Support for patternProperties in Signatures solves dynamic Transport Keys

[sebastiandemel]

Examples and discussion on how patternProperties (see example use here) support in Moonwalk signature objects solves the long-lasting problem of dynamic Headers, Query, Cookies and Path parameters.

Problem

The OpenAPI 3.x specification restricts transport blocks (headers, queries, cookies) to strict maps of explicitly named parameters. This limitation prevents the accurate description and validation of APIs utilizing dynamic, pattern-based keys.

Currently, API producers rely on out-of-band documentation, x- extensions, or serialization workarounds (like deepObject for queries) to describe these patterns.

Some real-world patterns:

• Headers: Cloud storage metadata (X-Amz-Meta-<Key>), gRPC transcoding metadata (Grpc-Metadata-<Key>), or multi-tenant routing (X-Tenant-<ID>).
• Query Parameters: Dynamic filtering (filter[<field>]=<value>), sorting (sort[<field>]=asc), or sparse fieldsets (fields[<resource>]=<field>).
• Cookies: Tenant-specific sessions (session_<tenant_id>) or partitioned analytics trackers (_tracker_<domain_hash>).
• Path Parameters: Matrix URIs (/map/lat=<val>;lon=<val>) or dynamic wildcard path segment mapping.

How patternProperties fixes this

Moonwalk's architecture separates pure data schemas from HTTP interactions. Because of this, we can treat incoming HTTP transport blocks (like headers, queries, and cookies) simply as JSON objects that are evaluated by JSON Schema.

By adopting standard JSON Schemas patternProperties we gain a native, canonical mechanism for validating dynamic transport keys.

Sample: Metadata with GET requests
In this sample, a client is fetching metadata via a GET request. Because GET requests should not have a body (RFC 9110), dynamic data such as custom metadata headers and dynamic query filters must be passed via the transport layer.

# 1. The pure schemas define the patterns
$defs:
  DynamicQueryFilters:
    patternProperties:
      '^filter\[[a-zA-Z0-9_]+\]$':
        type: string
        description: "Matches dynamic query filters like filter[department]=advertising"

  DynamicMetadataHeaders:
    patternProperties:
      "^x-object-meta-[a-z0-9\\-]+$":
        type: string
        description: "Matches dynamic headers like x-object-meta-owner"

# 2. The interaction block maps them to the transport layer
functions:
  getObjectMetadata:
    interaction:
      http:
        request:
          method: GET
          query:
            $ref: '#/$defs/DynamicQueryFilters'
          headers:
            $ref: '#/$defs/DynamicMetadataHeaders'

Sample: Stream upload
Sample shows a client is uploading a raw binary stream. Because the HTTP body is entirely occupied by the binary file, user-defined metadata must be passed dynamically via headers.

# 1. The pure schema defines the pattern
$defs:
  FileMetadataHeaders:
    patternProperties:
      "^x-file-meta-[a-z0-9\\-]+$":
        type: string
        description: "Dynamic metadata for binary streams (e.g., x-file-meta-checksum or x-file-meta-author)"

# 2. The interaction block maps it to the transport layer
functions:
  uploadFileStream:
    interaction:
      http:
        request:
          method: PUT
          # The body is a raw stream, forcing metadata into the headers
          body:
            contentType: application/octet-stream
          headers:
            $ref: '#/$defs/FileMetadataHeaders'

This approach requires no new custom x- extensions and naturally converges with ongoing Moonwalk efforts to model standard HTTP fields (Discussion #108) and adopt full RFC 6570 URI Templates for path routing (Discussion #127).

Full example: Storage Object Api

Here is a YAML schema that defines a Storage Object API as an example that combines URI Templating and other discussions with patternProperties

Combines the following discussions

• Adoption of full RFC 6570 URI Templates, Discussed in #127 and #23.
• Modeling of standard HTTP fields governed by RFC 9110. Proposed in #108 Modeling HTTP fields (headers/trailers)
• Parametric independence, Proposed in #98 Support for parameter interdependencies

Endpoint

# 1. Pure Data Signatures (No HTTP context)
$defs:
  # Integrates with the proposed adoption of full RFC 6570 URI Templates 
  # (e.g., the '+' expansion operator) as discussed in Discussion #127 and #23.
  ObjectPathParameters:
    type: object
    properties:
      bucketId:
        type: string
        pattern: "^[a-z0-9-]+$"
      objectPath:
        type: string
        description: "Greedy match for infinite-depth folder structures."
        pattern: "^([a-zA-Z0-9_-]+/?)+[a-zA-Z0-9_-]+\\.[a-z0-9]+$"
    required:
      - bucketId
      - objectPath
    additionalProperties: false

  # Includes the modeling of standard HTTP fields governed by RFC 9110.
  ObjectMetadataHeaders:
    type: object
    properties:
      # Normalized to lowercase to align with HTTP semantics
      if-match:
        type: string

    # Assumption: Tooling must normalize HTTP headers to lowercase before validation
    patternProperties:
      "^x-object-meta-[a-z0-9\\-]+$":
        type: string
        description: "Dynamic user-defined storage metadata (e.g., x-object-meta-author)"
    
    # Kept true to allow implicit headers like Host, User-Agent, etc.
    additionalProperties: true

  ObjectQueries:
    type: object
    properties:
      includeDeleted:
        type: boolean

    # This proposal: Applied against parsed, URL-decoded query keys
    patternProperties:
      '^filter\[[a-zA-Z0-9_]+\]$':
        type: string
        description: "Dynamic metadata filters (e.g., filter[created_after]=2026-01-01)"
    additionalProperties: false

  ObjectCookies:
    type: object
    patternProperties:
      "^cdn_edge_token_[a-f0-9]{32}$":
        type: string
        description: "Dynamic edge-caching authorization tokens"
    
    # Kept true to allow implicit domain-scoped cookies
    additionalProperties: true

# 2. HTTP Interaction Mapping
functions:
  getObjectMetadata:
    interaction:
      http:
        request:
          method: GET
          # RFC 6570 enables greedy routing for the objectPath
          path: /storage/buckets/{bucketId}/objects/{+objectPath}/metadata
          
          # Tooling applies the pure schemas to the parsed HTTP field maps.
          # This enables the evaluation of parameter interdependencies and dynamic keys via unified schemas.
          pathParams:
            $ref: '#/$defs/ObjectPathParameters'
          headers:
            $ref: '#/$defs/ObjectMetadataHeaders'
          query:
            $ref: '#/$defs/ObjectQueries'
          cookies:
            $ref: '#/$defs/ObjectCookies'

Valid Deep-Path Retrieval

In this scenario, a client is fetching metadata for a deeply nested file. The request includes dynamic metadata headers and a dynamic filter.

Request:

GET /storage/buckets/media-assets/objects/production/2026/marketing/banners/hero-v2.png/metadata?includeDeleted=false&filter[department]=advertising HTTP/1.1
Host: storage.example.com
If-Match: "v73b2-991"
X-Object-Meta-Owner: Team-Alpha
X-Object-Meta-Project-ID: 8821
Cookie: cdn_edge_token_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6=auth_valid; _ga=GA1.2.123456789.167890

How the Validator processes this:

1. Path:
   The RFC 6570 router extracts bucketId as media-assets and {+objectPath} as production/2026/marketing/banners/hero-v2.png. The regex in $defs/ObjectPathParameters confirms this is a valid nested string.

2. Headers:

   • The validator checks the fixed if-match property (case-insensitive mapping), then iterates through the remaining lowercase headers.
   • It confirms x-object-meta-owner and x-object-meta-project-id both match the patternProperties regex ^x-object-meta-[a-z0-9\-]+$.
   • Unmodeled headers like host pass through safely due to additionalProperties: true.

3. Query: The validator confirms the URL-decoded key filter[department] matches the query regex.

4. Cookies: The validator confirms cdn_edge_token_... matches the regex. The unmodeled _ga tracking cookie is ignored safely due to additionalProperties: true.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "v73b2-991"

{
  "bucketId": "media-assets",
  "objectPath": "production/2026/marketing/banners/hero-v2.png",
  "metadata": {
    "owner": "Team-Alpha",
    "project-id": "8821",
    "department": "advertising"
  },
  "lastModified": "2026-03-12T10:00:00Z"
}

Invalid Key Validation (Header & Cookie Fail)

This example demonstrates a request that fails because it uses keys that do not match the required patterns, even though the transport location is correct.

Request:

GET /storage/buckets/media-assets/objects/config.json/metadata HTTP/1.1
Host: storage.example.com
X-Meta-Author: JohnDoe
Cookie: cdn_token_123=invalid

The Resulting Error (Validation Rejection):

The API gateway or validator rejects this before it hits the application logic because the explicitly provided keys do not satisfy the patternProperties constraints.

Response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "title": "Constraint Violation",
  "status": 400,
  "errors": [
    {
      "location": "headers",
      "issue": "Property 'x-meta-author' is not allowed. It does not match the required pattern '^x-object-meta-[a-z0-9\\-]+$'."
    },
    {
      "location": "cookies",
      "issue": "Property 'cdn_token_123' is not allowed. It lacks the 'cdn_edge_token_' prefix and does not meet the 32-character hexadecimal requirement."
    }
  ]
}

Assumptions

URL-Decoding of Transport Keys

We assume that schema validation applies to the parsed and URL-decoded key-value pairs of the query string and cookies, not the raw HTTP string. This avoids the validation failures that percent-encoding would otherwise cause.

For example, while a dynamic query is transmitted as filter%5Bdepartment%5D, the schema validator evaluates the decoded filter[department].

Edge cases

1. The Case-Sensitivity Clash (Headers)

Problem: HTTP headers are strictly case-insensitive according to RFC 9110 (e.g., X-Object-Meta-Owner is identical to x-object-meta-owner). However, JSON Schema's patternProperties uses ECMA-262 regular expressions, which are case-sensitive by default, and standard JSON Schema does not natively support inline regex flags like (?i).

Solution: Tooling MUST normalize header keys to lowercase before applying the JSON Schema evaluation.

2. Support for additionalProperties: false

Problem: While not specifically a problem with patternProperties, it's worth mentioning that the use of additionalProperties: false in headers can cause unintended rejections as clients tend to send implicit headers (such as Host, User-Agent, Accept, etc.). Similarly, clients (especially browsers) automatically append all domain-scoped cookies (like analytics trackers or CSRF tokens), even if the specific API endpoint does not require them.

Solution: Tooling SHOULD warn of its use in headers and cookies, and the default value for additionalProperties should be true to allow unmodeled transport data to safely pass through.

[karenetheridge]

I have a few comments and questions from my brief skim:

• This is very long; was it AI-written? If this proposal was shorter and more succinct it could have a greater chance of seeing some useful discussion.
• I have never seen the term "transport blocks" before -- where is that from?
• many of your listed usecases can already be solved -- elegantly, not with a kludge -- using the existing parameter styles, such as dynamically-named cookies. You can easily extract all cookies into an object and apply the patternProperties keyword to the property names to specify constraints and also types; there is also the option of embedding a multi-layer data structure into a cookie parameter (or a header or query value) using some sort of encoding such as application/json.
• I do however see the potential use for dynamic header names, as there is no way presently for specifying a wildcard match or any other non-literal-string matching mechanism for headers in OpenAPI 3.x.