Spec proposal: add optional response-level metadata to all Registry API responses

[thomas-sickert]

Problem

The Registry API response schemas are currently closed to additional properties. Implementations therefore cannot return service-specific, response-level information without violating the schema or placing it inside catalog entries, where it could be mistaken for information about the discovered resource. The proposed registry response metadata has a different scope and lifecycle: it is produced by the service handling a particular request and applies to the response as a whole, not to an individual catalog entry.

The metadata field would allow implementing services to provide data required by clients of that particular Registry implementation.

HTTP headers are not always an adequate substitute, especially for structured data.

Proposed approach

Add an optional top-level metadata object to every Registry API response body, including Search, Explore, List, and Error responses.

For example:

{
  "results": [],
  "metadata": {
    "com.example.requestId": "ABCDEFG1234567890",
    "com.example.scope": {
      "ruleSet": "enterprise",
      "name": "Enterprise 1",
      "appliedFilter": {
        "allowList": [
          "engineering"
         ]
       }
    }
  }
}

Proposed requirements:

• Implementations MAY include metadata in any response body.
• Metadata values MAY contain any valid JSON value, including nested objects and arrays.
• Clients MUST ignore unrecognized metadata members.
• Implementations MUST NOT use metadata to replace or redefine standard response fields.
• Implementation-defined keys SHOULD use a collision-resistant namespace, such as a reverse-DNS name or URL.