HTTP Parser contracts¶

Reference: installed TypeScript Parser v2.35.0 with Zod v4.1.12. This implementation covers all eighteen runtime schema exports from eight HTTP-related source families and five body envelopes. It validates event shapes and payloads; routing, authorization decisions, response validation and OpenAPI belong to the separate Event Handler/Validation work.

Schema export mapping¶

These names are exported from the Go parser/schemas package with their reference spelling.

The implementation reuses shared fields, dictionaries, method enums and certificates where the reference contracts agree. Differences are preserved:

• REST query dictionaries and body permit explicit null but are required; several other REST dictionaries are optional and nullable.
• HTTP API v2 body is optional but not nullable. Its version is a string; the REQUEST authorizer event specifically requires 2.0.
• REST identity permits test-invoke-source-ip and an absent sourceIp. HTTP API v2 requires a valid IPv4/IPv6 address. WebSocket identity only requires a string.
• REST request context permits a nonempty messageId only when eventType is MESSAGE.
• ALB permits an arbitrary method string, while API Gateway and VPC Lattice use the reference seven-method enum.
• VPC Lattice v2 timeEpoch is a string. Identity field casing, including X509SubjectCn and x509SanDns, is retained.

Body envelopes¶

Each envelope replaces the base body's schema with the application schema and validates the whole event. Metadata and payload issues can therefore appear together, in schema field order. Payload issue paths start with body. The application schema controls whether an absent/null body is accepted, independently of the base event body's optional/nullable policy.

No automatic JSON or Base64 decoding occurs. Use JSONStringified or Base64Encoded explicitly as appropriate for the input. A true isBase64Encoded/is_base64_encoded flag alone leaves the body unchanged. There is no ALB envelope in the pinned reference; use AlbSchema extension or explicit body parsing.

payload := parser.Typed[Order](parser.Object(
    parser.Field{Name: "id", Schema: parser.String()},
    parser.Field{Name: "amount", Schema: parser.Number()},
))
schema := envelopes.APIGatewayV2(parser.JSONStringified(payload))
result, err := parser.SafeParse(ctx, event, schema)

See the complete HTTP Lambda example for safe parsing and HTTP 400 handling. It keeps operational errors/cancellation distinct from validation failures.

EventBridge and the HTTP envelopes share a private object-field validator. It preserves an application schema's safe-mode interface, returns a zero value for accepted absence and does not store per-request results in shared state. Extending the selected payload rule leaves the exported base model unchanged.

Evidence and remaining boundaries¶

Local acceptance on 2026-09-15 passed all eighteen packaged modules, fifteen standalone consumers, both CGO-disabled Lambda architecture builds, 226/226 Docker assertions and 14/14 Batch artifact checks. Runtime checks execute all five new body envelopes, ALB multi-value headers and combined metadata/body failures. Disposable containers and their internal network were removed. See MODULE_ACCEPTANCE.json, LOCAL_ACCEPTANCE.json and BATCH_ACCEPTANCE.json; no AWS deployment was performed.

generate-parser-http.mjs runs the actual pinned packages and writes 458 cases to parser/testdata/http-v2.35.0.json. Cases include valid/missing/null schemas, individual top-level field omission/type mutations, nested certificates/identity variants, IPv4/IPv6 and invalid addresses, REST messageId refinement, ordinary/safe envelopes, combined metadata/payload errors, missing/null bodies, application object bodies and explicit no-decoding behavior. Existing core/stream cases remain part of the same Parser regression suite (604 cases total).

Additional Go tests cover accepted absence, concurrent schema reuse, unchanged base schemas, safe versus ordinary payload modes, cancellation, nil schemas and operational error identity. The shared field extractor also fixes absent EventBridge unknown detail returning an internal absence value.

Full inferred-type/export mapping, nested Zod error trees, exception-class identity, every IP/encoding/type edge and performance budgets remain open. REST request-context refinement is a composed Go Schema interface; it does not expose Zod-specific refinement/extension methods. HTTP models and envelopes do not constitute an implemented Event Handler router or JSON Schema Validation module.