feat(typescript): validate request parameters against schema patterns

TR
12h ago
+714-77

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, query and header) of type: string that declare a portable pattern now 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 with SDKValidationError ("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 isPortablePattern in common/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:]], \s or lookaheads, is left to the server, matching the CLI. The runtime helper matchesPattern in lib/primitives.ts compiles with the u flag and has no fallback mode.

  • Only the operation's own parameters are constrained. Properties of an object parameter (for example a deepObject query 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 v3 a 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 (exampleForPortablePattern in common/common/patterns.ts): the first alternation branch, three items for unbounded repetition, and characters from a printable pool (for example storeId: "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-message is used as the error message when present, matching the CLI. Otherwise the message is Value must match pattern <pattern>.

  • Works with zod v3, v4 and v4-mini through the existing z.refine helper. The none (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.
  • oneOf string 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 (zod v4-mini): 54 files, 819 tests passing. tests/primary/parameter_patterns_additional.test.ts uses the existing cli-pattern-error-message.yaml fragment 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 (zod v3): 29 files, 426 tests passing. A new tertiary/parameter-pattern-validation.yaml fragment and tests/tertiary/parameter_patterns_additional.test.ts cover rejection on v3, an omitted patterned parameter sending its default, and a component used as both a deepObject query parameter and the request body being sent unchanged. The generated example for its unexampled path parameter matches the pattern.
  • TARGET=review and TARGET=no-zod for typescriptv2, TARGET=review make test-cli (854 tests, CLI output unchanged by the shared helper move), and make check-template-typescriptv2 pass.
  • Not run: TARGET=quaternary (zod v4), because the local environment has no pnpm version configured.
  • make lint: golangci-lint's gofmt check reports an alignment finding on an unrelated templates/perms.go entry; local gofmt makes 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-message for the error message when declared, otherwise defaults to Value 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 maxLength before 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 oneOf patterns, lookahead syntax, maxLength bounds, and rejection before a request is sent across all parameter positions.