feat(typescript): validate request parameters against schema patterns
Why
TypeScript SDKs ignore pattern on parameter schemas, so an API author has no way to stop an SDK from sending a path, query or header value the API never accepts. For path parameters this matters beyond input hygiene. A spec that declares pattern: '^[a-z0-9_]+$' on an ID should stop a caller from passing arbitrary input, such as .., ABC or an untrusted value from an end user or a model tool call, before the SDK builds the URL.
The CLI and Terraform targets already enforce pattern. This brings TypeScript in line for request parameters. It complements #211, which rejects . and .. path segments by default whether or not a spec declares a pattern.
What changed
-
Operation parameters (
in: path,queryandheader) oftype: stringthat declare a portablepatternnow get a refinement in the operation's request schema. The SDK already parses every request through that schema before building the URL, so a mismatch fails withSDKValidationError("Input validation failed") and no request is sent:storeId: z.string().refine(matchesPattern$("^[a-z0-9_]+$"), { message: "Use lowercase letters, digits or underscores.", }), -
Only portable patterns are enforced. The generator reuses the CLI's portable-subset check, now shared as
isPortablePatternincommon/common/patterns.ts. A pattern qualifies when Go's regexp and ECMA-262 Unicode mode (the JSON Schema dialect) read it the same way. Anything else, such as\p{L},\A...\z,[[:alnum:]],\sor lookaheads, is left to the server, matching the CLI. The runtime helpermatchesPatterninlib/primitives.tscompiles with theuflag and has no fallback mode. -
Only the operation's own parameters are constrained. Properties of an object parameter (for example a
deepObjectquery parameter) carry a parameter annotation too, and their model can be shared with a request body. Those properties are not refined, so a schema used both as a query parameter and as a body is never validated when sent as a body. -
A default that violates its own pattern disables the refinement for that parameter. On zod
v3a refinement also runs on the default, so every call omitting the parameter would otherwise fail. The parameter is still sent with its default, as before. -
Generated examples match the pattern. When a patterned parameter has no explicit example and the usual faked value doesn't match, the TypeScript example is now built from the pattern by a small deterministic generator for the portable subset (
exampleForPortablePatternincommon/common/patterns.ts): the first alternation branch, three items for unbounded repetition, and characters from a printable pool (for examplestoreId: "abc"rather than"<id>"). README snippets, docs and generated tests therefore call the SDK with values it accepts. Other targets' examples are unchanged. -
x-speakeasy-pattern-error-messageis used as the error message when present, matching the CLI. Otherwise the message isValue must match pattern <pattern>. -
Works with zod
v3,v4andv4-minithrough the existingz.refinehelper. Thenone(no-zod) runtime has no schemas, so it is unchanged.
Out of scope: request body properties, properties of object parameters, response parsing, and string items of array parameters. Body and response schemas are unchanged, so a spec whose pattern is stricter than real data can't make an existing call fail when its response is parsed.
Review notes
- This changes behaviour for existing SDKs whose specs declare portable parameter patterns: a value that doesn't match is now rejected client-side instead of sent. That is the intent, and it matches the CLI.
oneOfstring parameters that the generator collapses into a single string get the merged pattern (for example(^[a-z]+$|^[0-9]+$)).- A default that violates its own pattern is a spec error. A validation-time lint rule would be the better place to report it. This PR only keeps such SDKs working.
Testing
TARGET=primary make test-typescriptv2(zodv4-mini): 54 files, 819 tests passing.tests/primary/parameter_patterns_additional.test.tsuses the existingcli-pattern-error-message.yamlfragment to check that path, query and header mismatches are rejected before any request is sent, custom and default messages, valid values being sent, a lookahead pattern being left to the server, and body properties staying unconstrained.TARGET=tertiary make test-typescriptv2(zodv3): 29 files, 426 tests passing. A newtertiary/parameter-pattern-validation.yamlfragment andtests/tertiary/parameter_patterns_additional.test.tscover rejection onv3, an omitted patterned parameter sending its default, and a component used as both adeepObjectquery parameter and the request body being sent unchanged. The generated example for its unexampled path parameter matches the pattern.TARGET=reviewandTARGET=no-zodfortypescriptv2,TARGET=review make test-cli(854 tests, CLI output unchanged by the shared helper move), andmake check-template-typescriptv2pass.- Not run:
TARGET=quaternary(zodv4), because the local environment has nopnpmversion configured. make lint: golangci-lint's gofmt check reports an alignment finding on an unrelatedtemplates/perms.goentry; localgofmtmakes no changes to the file.
Public-safety check
- This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
- Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (
.claude/skills/public-repo-communication/SKILL.md). - Generated fixtures and review SDK changes are public-safe.
- I reviewed
git diff --check.
Summary by cubic
TypeScript SDKs now validate path, query, and header string parameters against schema pattern declarations before building the request, and generate examples that match those patterns. Previously those values were sent unchecked, so a caller could pass input like .. that the API never accepts; a mismatch now raises SDKValidationError and no request is sent, aligning TypeScript with the CLI and Terraform targets.
- Enforces only patterns deemed portable, meaning they behave identically in Go's regexp and ECMA-262 Unicode mode; patterns that can't be confirmed portable, such as lookaheads, are left to the server.
- Uses
x-speakeasy-pattern-error-messagefor the error message when declared, otherwise defaults toValue must match pattern <pattern>. - Applies only to string parameters in the operation's own request model in path, query, and header positions; request body properties and object parameter properties shared with the body are unchanged.
- Rejects values exceeding a declared
maxLengthbefore the pattern runs (including for defaults and generated examples), so the regex never sees arbitrarily long input and the default is still sent when it matches. - Replaces generated examples that would violate a pattern with a matching one, covering the full portable subset including alternation, character classes, anchors, escapes, and quantifiers.
- Tests cover Unicode mode, uncompilable patterns, merged
oneOfpatterns, lookahead syntax, maxLength bounds, and rejection before a request is sent across all parameter positions.