{
  "openapi": "3.1.2",
  "info": {
    "title": "Business registry Consultation: concrete illustrative binding",
    "version": "1.0.0-draft",
    "description": "Illustrative businesses collection for Registry https://registry.example/registries/business. Its membership is all business registration Records in that Registry, including dissolved registrations. Operations select the business-public view. Record.data follows business-registry.schema.json, published with dependencies at https://registry.example/contracts/1.0.0-draft/examples/business-registry.schema.json. Retrieve, Lookup, List, and Search are selected; Revision List and Revision Retrieve are not. Reads synchronously query the authoritative source and apply the caller’s permitted view. Access tokens use issuer https://identity.example, the stable logical service audience https://registry.example/business and the declared read scope. TLS is 1.3 or later. Example endpoints are non-production. The gateway allows 60 requests per authenticated client per minute and an 8 KiB request body. The published field-selection set is legalName and registrationStatus, with both returned by default. Pages use live ascending ASCII recordId order. The initial pageSize defaults to 20, maximum 100; continuations retain that effective value. Cursors expire 15 minutes after traversal creation and bind the effective field selection. List and Search declare complete-traversal: while source data and access remain unchanged, every permitted match is returned exactly once. This deployment additionally limits each page to scanning 1000 candidates or two seconds of source work; its cursor advances beyond the last scanned candidate, so a non-final page can be short or empty. Disclosure policy permits these progress patterns. The service never reports completion merely because it reaches an internal result window. If a resource limit prevents progress or complete traversal, it returns the declared 503 failure. total is exact for permitted matches at page evaluation and is omitted when unavailable within budget. Typed request schemas declare accepted inputs. Malformed or structurally invalid input, unsupported query parameters and invalid pagination controls use 400. Structurally valid bodies with unknown selector, search, or field names, or invalid domain values use 422.",
    "contact": {
      "name": "GovStack Digital Registries Working Group",
      "url": "https://github.com/GovStackWorkingGroup/bb-digital-registries"
    },
    "x-govstack-api-guide": {
      "version": "0.3.0-draft",
      "rulesetVersion": "0.3.0-draft"
    }
  },
  "servers": [
    {
      "url": "https://{gatewayHost}",
      "description": "Non-production deployment root. The businesses collection declares its Registry association, membership and representation independently of this root.",
      "variables": {
        "gatewayHost": {
          "default": "registry.example",
          "description": "Non-production reserved documentation-domain default."
        }
      }
    }
  ],
  "security": [
    {
      "citizenOAuth": [
        "bb:digital-registries:record:read"
      ]
    },
    {
      "serviceOAuth": [
        "bb:digital-registries:record:read"
      ]
    }
  ],
  "tags": [
    {
      "name": "Consultation",
      "description": "Read authorised Records from the businesses collection."
    },
    {
      "name": "Health",
      "description": "Bounded operational liveness without registry information."
    },
    {
      "name": "Discovery",
      "description": "Locate the origin's API contracts and Registry metadata through the RFC 9727 API catalog."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check service liveness",
        "description": "Returns HTTP `200` when the service can accept work and `503` otherwise. This bounded, unauthenticated check exposes only a public service label. Dependency checks are limited to those that determine service availability.",
        "tags": [
          "Health"
        ],
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "description": "The service is healthy and able to accept work.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "servers": [
        {
          "url": "https://{gatewayHost}",
          "description": "Origin root. RFC 8615 fixes well-known URIs at the origin, so a deployment routing prefix does not apply to this path.",
          "variables": {
            "gatewayHost": {
              "default": "registry.example",
              "description": "Deployment gateway hostname; registry.example is non-production."
            }
          }
        }
      ],
      "get": {
        "operationId": "getApiCatalog",
        "summary": "Get the API catalog",
        "description": "Returns the RFC 9727 API catalog for this origin as an RFC 9264 linkset. For each\nDigital Registries API at the origin, a `service-desc` link targets its OpenAPI\ncontract and a `service-meta` link, typed `application/ld+json`, targets the Registry\nmetadata document.\n\nA deployment that restricts the catalog to an intended audience declares that access\nrequirement instead of `security: []`.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ApiCatalog"
          },
          "304": {
            "$ref": "#/components/responses/ApiCatalogNotModified"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      },
      "head": {
        "operationId": "headApiCatalog",
        "summary": "Check the API catalog",
        "description": "Returns the API catalog response headers without a body, including the `Link` header with the `api-catalog` relation that RFC 9727 requires for `HEAD` requests.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ApiCatalogHeaders"
          },
          "500": {
            "$ref": "#/components/responses/InternalErrorHeaders"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailableHeaders"
          }
        }
      }
    },
    "/v1/collections/businesses/records/{recordId}": {
      "get": {
        "operationId": "retrieveBusiness",
        "summary": "Retrieve one record by its stable identifier",
        "description": "Retrieve the permitted business-public view by source recordId within the businesses collection. Absent Records, Records outside this collection and protected existence share 404 record-not-available. The response uses no-store. Conditional retrieval uses the representation’s ETag after authorisation. Empty, duplicate, unknown, or incorrectly typed fields query values use 400.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/business",
          "collection": "businesses",
          "capability": "retrieve",
          "view": "business-public",
          "features": [
            "conditional-read",
            "field-selection"
          ]
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/BusinessFields"
          }
        ],
        "responses": {
          "200": {
            "description": "One authorised business-public record.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "ETag": {
                "$ref": "#/components/headers/ConditionalETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessRecord"
                },
                "example": {
                  "recordId": "r_42",
                  "data": {
                    "legalName": "Example Ltd"
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/RecordNotAvailable"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    },
    "/v1/collections/businesses/records": {
      "get": {
        "operationId": "listBusinesses",
        "summary": "List an authorised page of records",
        "description": "Return permitted Records from the businesses collection in ascending ASCII recordId order using the declared live pagination policy. Continue with cursor and the retained effective pageSize and field selection. Only nextCursor null ends traversal. Empty, duplicate, unknown, or incorrectly typed fields query values use 400.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/business",
          "collection": "businesses",
          "capability": "list",
          "view": "business-public",
          "features": [
            "field-selection",
            "complete-traversal"
          ]
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/BusinessFields"
          }
        ],
        "responses": {
          "200": {
            "description": "A bounded page of business-public records in ascending ASCII recordId order.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessPage"
                },
                "example": {
                  "items": [
                    {
                      "recordId": "r_42",
                      "data": {
                        "registrationStatus": "DISSOLVED"
                      }
                    }
                  ],
                  "pageInfo": {
                    "nextCursor": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    },
    "/v1/collections/businesses/lookup": {
      "post": {
        "operationId": "lookupBusiness",
        "summary": "Look up one record using a declared exact selector",
        "description": "Resolve byRegistrationNumber or the composite byJurisdictionNumber key within the businesses collection using byte-for-byte string matching. BusinessLookupRequest defines their fields and uniqueness scopes. Return the permitted Record, 404 for an unavailable match, or generic 500 for a uniqueness violation. Malformed or structurally invalid input uses 400; structurally valid input with an unknown selector, unknown field name, or invalid domain value uses 422. Protected-existence policy applies before Record-specific diagnostics.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/business",
          "collection": "businesses",
          "capability": "lookup",
          "view": "business-public",
          "features": [
            "field-selection"
          ]
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "One published exact selector and all its typed key values.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BusinessLookupRequest"
              },
              "examples": {
                "byRegistrationNumber": {
                  "summary": "Declared selector requesting only the legal name",
                  "value": {
                    "selector": "byRegistrationNumber",
                    "values": {
                      "registrationNumber": "BR-000042"
                    },
                    "fields": [
                      "legalName"
                    ]
                  }
                },
                "composite": {
                  "summary": "Exact composite key",
                  "value": {
                    "selector": "byJurisdictionNumber",
                    "values": {
                      "jurisdictionCode": "AA",
                      "localNumber": "00000042"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One authorised business-public record.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessRecord"
                },
                "example": {
                  "recordId": "r_42",
                  "data": {
                    "legalName": "Example Ltd"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/RecordNotAvailable"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "413": {
            "$ref": "#/components/responses/ContentTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/InvalidField"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    },
    "/v1/collections/businesses/search": {
      "post": {
        "operationId": "searchBusinesses",
        "summary": "Execute one declared search and return a page",
        "description": "Search the businesses collection byRegistrationStatus, or byFields with any non-empty combination of legalName and registrationStatus, using exact equality. Repeat search and criteria with cursor on continuation; pageSize may be omitted to retain its bound value. Apply the declared live pagination policy. Malformed or structurally invalid input and invalid pagination controls use 400. Structurally valid input with an unknown search, unknown field name, or invalid domain value uses 422; malformed, expired or mismatched continuations use 400 invalid-cursor.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/business",
          "collection": "businesses",
          "capability": "search",
          "view": "business-public",
          "features": [
            "field-selection",
            "complete-traversal"
          ]
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "One declared search with criteria and body-carried pagination controls.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BusinessSearchRequest"
              },
              "examples": {
                "byRegistrationStatus": {
                  "summary": "First page using the business binding's status search",
                  "value": {
                    "search": "byRegistrationStatus",
                    "criteria": {
                      "registrationStatus": "DISSOLVED"
                    },
                    "fields": [
                      "legalName"
                    ],
                    "pageSize": 20
                  }
                },
                "byFields": {
                  "summary": "Equality on a combination of declared fields",
                  "value": {
                    "search": "byFields",
                    "criteria": {
                      "legalName": "Example Ltd",
                      "registrationStatus": "DISSOLVED"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A bounded page of business-public records in ascending ASCII recordId order.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessPage"
                },
                "example": {
                  "items": [
                    {
                      "recordId": "r_42",
                      "data": {
                        "legalName": "Example Ltd"
                      }
                    }
                  ],
                  "pageInfo": {
                    "nextCursor": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "413": {
            "$ref": "#/components/responses/ContentTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/InvalidField"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "citizenOAuth": {
        "type": "oauth2",
        "description": "Citizen access-token authorisation backed by OpenID Connect. Authorization-code clients use PKCE S256. Deployments publish issuer and audience. ID Tokens are rejected.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://identity.example/authorize",
            "tokenUrl": "https://identity.example/token",
            "scopes": {
              "bb:digital-registries:record:read": "Read an authorised write-capable Record view.",
              "bb:digital-registries:record:create": "Attempt authorised direct Record creation.",
              "bb:digital-registries:record:update": "Attempt authorised direct Record update.",
              "bb:digital-registries:record:transition": "Attempt an authorised named Record transition.",
              "bb:digital-registries:change-request:submit": "Submit an authorised immutable proposal.",
              "bb:digital-registries:change-request:read": "Read caller-visible proposals and states.",
              "bb:digital-registries:change-request:review": "Approve or reject an exact proposal version.",
              "bb:digital-registries:change-request:withdraw": "Withdraw a proposal when policy permits.",
              "bb:digital-registries:change-request:apply": "Execute an approved proposal under current policy.",
              "bb:digital-registries:operation:read": "Read caller-visible asynchronous operation state."
            }
          }
        }
      },
      "serviceOAuth": {
        "type": "oauth2",
        "description": "Confidential inter-BB client credentials. Tokens are audience- and scope-restricted; sender-constrained access tokens are recommended.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://identity.example/token",
            "scopes": {
              "bb:digital-registries:record:read": "Read an authorised write-capable Record view.",
              "bb:digital-registries:record:create": "Attempt authorised direct Record creation.",
              "bb:digital-registries:record:update": "Attempt authorised direct Record update.",
              "bb:digital-registries:record:transition": "Attempt an authorised named Record transition.",
              "bb:digital-registries:change-request:submit": "Submit an authorised immutable proposal.",
              "bb:digital-registries:change-request:read": "Read caller-visible proposals and states.",
              "bb:digital-registries:change-request:review": "Approve or reject an exact proposal version.",
              "bb:digital-registries:change-request:withdraw": "Withdraw a proposal when policy permits.",
              "bb:digital-registries:change-request:apply": "Execute an approved proposal under current policy.",
              "bb:digital-registries:operation:read": "Read caller-visible asynchronous operation state."
            }
          }
        }
      }
    },
    "parameters": {
      "BusinessFields": {
        "name": "fields",
        "in": "query",
        "required": false,
        "style": "form",
        "explode": false,
        "description": "Comma-separated top-level business-public fields. Omission selects both legalName and registrationStatus. Continuations repeat the effective selection unchanged.",
        "schema": {
          "$ref": "#/components/schemas/BusinessFields"
        }
      },
      "Traceparent": {
        "name": "traceparent",
        "in": "header",
        "required": false,
        "description": "W3C Trace Context. Propagate valid context; create context when absent or invalid. Problem traceId is the effective trace-id. Trace metadata excludes personal data.",
        "schema": {
          "type": "string"
        }
      },
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "Conditional request against the selected representation's ETag. Authorisation precedes evaluation of the validator.",
        "schema": {
          "type": "string"
        }
      },
      "RecordId": {
        "name": "recordId",
        "in": "path",
        "required": true,
        "description": "Stable opaque identifier within the selected registry, encoded as one path segment.",
        "schema": {
          "$ref": "#/components/schemas/RecordId"
        }
      },
      "PageSize": {
        "name": "pageSize",
        "in": "query",
        "required": false,
        "description": "Maximum number of items returned in a page.",
        "schema": {
          "$ref": "#/components/schemas/PageSize"
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "Continuation from the previous page. Omit for the first page.",
        "schema": {
          "$ref": "#/components/schemas/Cursor"
        }
      }
    },
    "schemas": {
      "BusinessFields": {
        "description": "Non-empty field selection supported by this deployment. Omission selects both legalName and registrationStatus.",
        "type": "array",
        "maxItems": 2,
        "allOf": [
          {
            "$ref": "#/components/schemas/FieldSelection"
          },
          {
            "type": "array",
            "description": "Selection of literal camelCase property names from the BusinessData response object.",
            "items": {
              "type": "string",
              "enum": [
                "legalName",
                "registrationStatus"
              ],
              "description": "Literal response property name: legalName is the registered business name; registrationStatus is the domain registration status. Casing is significant."
            }
          }
        ],
        "examples": [
          [
            "legalName"
          ],
          [
            "legalName",
            "registrationStatus"
          ]
        ]
      },
      "BusinessRecord": {
        "description": "The shared record envelope bound to the business-public view; additive envelope metadata remains permitted.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Record"
          },
          {
            "type": "object",
            "description": "Concrete identity and view constraints for this example.",
            "properties": {
              "recordId": {
                "type": "string",
                "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}(?![\\s\\S])",
                "description": "Existing non-personal source identifier. Records are ordered by ascending ASCII bytes of this value, which is also the unique tie-breaker. Collection actions occupy a separate path namespace, so source identifiers such as lookup and search remain valid."
              },
              "data": {
                "$ref": "#/components/schemas/BusinessData"
              }
            }
          }
        ],
        "examples": [
          {
            "recordId": "r_42",
            "data": {
              "legalName": "Example Ltd",
              "registrationStatus": "DISSOLVED"
            }
          }
        ]
      },
      "BusinessPage": {
        "description": "A typed business record page; total, when supplied, is exact for authorised matching records at evaluation of this page.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RecordPage"
          },
          {
            "type": "object",
            "description": "Every item uses the same declared business-public view.",
            "properties": {
              "items": {
                "type": "array",
                "maxItems": 100,
                "description": "At most the effective pageSize business records, in ascending ASCII recordId order.",
                "items": {
                  "$ref": "#/components/schemas/BusinessRecord"
                }
              }
            }
          }
        ],
        "examples": [
          {
            "items": [],
            "pageInfo": {
              "nextCursor": null,
              "total": 0
            }
          }
        ]
      },
      "BusinessLookupRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "One of two typed exact-key selectors. Selector names determine their complete accepted key fields.",
        "required": [
          "selector",
          "values"
        ],
        "properties": {
          "selector": {
            "type": "string",
            "description": "Published exact selector name, constrained together with its values by oneOf."
          },
          "values": {
            "type": "object",
            "description": "The complete typed key associated with the chosen selector."
          },
          "fields": {
            "$ref": "#/components/schemas/BusinessFields"
          }
        },
        "oneOf": [
          {
            "description": "Registry-wide registration-number lookup.",
            "properties": {
              "selector": {
                "const": "byRegistrationNumber"
              },
              "values": {
                "$ref": "#/components/schemas/RegistrationNumberValues"
              }
            }
          },
          {
            "description": "Jurisdiction and local-number composite lookup.",
            "properties": {
              "selector": {
                "const": "byJurisdictionNumber"
              },
              "values": {
                "$ref": "#/components/schemas/JurisdictionNumberValues"
              }
            }
          }
        ],
        "examples": [
          {
            "selector": "byRegistrationNumber",
            "values": {
              "registrationNumber": "BR-000042"
            },
            "fields": [
              "legalName"
            ]
          },
          {
            "selector": "byJurisdictionNumber",
            "values": {
              "jurisdictionCode": "AA",
              "localNumber": "00000042"
            }
          }
        ]
      },
      "BusinessSearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "One of two typed equality searches with continuation controls. Search names determine their accepted criteria. Repeat search and criteria on continuation.",
        "required": [
          "search",
          "criteria"
        ],
        "properties": {
          "search": {
            "type": "string",
            "description": "Published search name, constrained together with its criteria by oneOf."
          },
          "criteria": {
            "type": "object",
            "description": "The typed criteria associated with the chosen search."
          },
          "fields": {
            "$ref": "#/components/schemas/BusinessFields"
          },
          "pageSize": {
            "$ref": "#/components/schemas/PageSize"
          },
          "cursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        },
        "oneOf": [
          {
            "description": "Registration-status equality search.",
            "properties": {
              "search": {
                "const": "byRegistrationStatus"
              },
              "criteria": {
                "$ref": "#/components/schemas/RegistrationStatusCriteria"
              }
            }
          },
          {
            "description": "Equality search over the declared business-public fields.",
            "properties": {
              "search": {
                "const": "byFields"
              },
              "criteria": {
                "$ref": "#/components/schemas/FieldEqualityCriteria"
              }
            }
          }
        ],
        "examples": [
          {
            "search": "byRegistrationStatus",
            "criteria": {
              "registrationStatus": "DISSOLVED"
            },
            "fields": [
              "legalName"
            ],
            "pageSize": 20
          },
          {
            "search": "byRegistrationStatus",
            "criteria": {
              "registrationStatus": "DISSOLVED"
            },
            "fields": [
              "legalName"
            ],
            "cursor": "pgn_7JpQ9m2W4xK8fR3cT6vN1"
          },
          {
            "search": "byFields",
            "criteria": {
              "legalName": "Example Ltd",
              "registrationStatus": "DISSOLVED"
            }
          }
        ]
      },
      "Health": {
        "type": "object",
        "description": "Informational body, which may be omitted; only the HTTP status determines liveness.",
        "properties": {
          "description": {
            "type": "string",
            "description": "Public human-readable service label with no internal details."
          }
        },
        "examples": [
          {
            "description": "Digital Registries API"
          }
        ]
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details with one stable machine identifier in type and a trace identifier for correlation. Error text contains no personal data or system-internal detail.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://govstack\\.global/problems/[a-z][a-z0-9-]{1,30}/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
            "description": "Stable GovStack problem-type URI and machine identifier in the form https://govstack.global/problems/{bb-code}/{problem-slug}, where the problem slug uses kebab-case."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "description": "Short human-readable summary of the problem type."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "HTTP status code for this occurrence."
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "URI reference identifying this problem occurrence."
          },
          "traceId": {
            "type": "string",
            "pattern": "^(?!0{32}$)[\\da-f]{32}$",
            "description": "The 32-hex-digit trace-id component of the effective request traceparent."
          }
        }
      },
      "LinkTarget": {
        "type": "object",
        "description": "One RFC 9264 target link; further target attributes follow RFC 9264.",
        "required": [
          "href"
        ],
        "properties": {
          "href": {
            "type": "string",
            "format": "uri-reference",
            "description": "The target URI."
          },
          "type": {
            "type": "string",
            "description": "Media type hint for the target."
          },
          "title": {
            "type": "string",
            "description": "Human-readable target label."
          }
        }
      },
      "LinkContext": {
        "type": "object",
        "description": "One RFC 9264 link context. Members other than anchor are link relation types, such as item, service-desc and service-meta.",
        "properties": {
          "anchor": {
            "type": "string",
            "format": "uri-reference",
            "description": "The link context URI."
          }
        },
        "additionalProperties": {
          "type": "array",
          "minItems": 1,
          "description": "Target links for one relation type.",
          "items": {
            "$ref": "#/components/schemas/LinkTarget"
          }
        }
      },
      "ApiCatalog": {
        "type": "object",
        "description": "RFC 9264 linkset listing the APIs at this origin. Each Digital Registries API has a service-desc link to its OpenAPI contract and a service-meta link to its Registry metadata document.",
        "required": [
          "linkset"
        ],
        "properties": {
          "linkset": {
            "type": "array",
            "minItems": 1,
            "description": "Link context objects, such as one per API anchor.",
            "items": {
              "$ref": "#/components/schemas/LinkContext"
            }
          }
        }
      },
      "RecordId": {
        "type": "string",
        "minLength": 1,
        "description": "Stable opaque identifier unique across all collections in the selected Registry, unchanged throughout the Record's lifecycle and never reassigned to a different Record. The same Record retains its identifier across collections and views. Suitable source identifiers are retained. Exposed identifiers are non-personal and safe for URL references. Collection actions occupy a separate namespace, so source identifiers such as lookup and search remain valid Record Identifiers.",
        "examples": [
          "r_42"
        ]
      },
      "FieldSelection": {
        "type": "array",
        "minItems": 1,
        "uniqueItems": true,
        "description": "Non-empty set of declared selectable top-level data field names. A deployment narrows items to its supported enum, declares bounds and a default field set, and makes selectable fields not required in its response schema. No nested query or expansion syntax is implied. Always retain recordId and data.",
        "items": {
          "type": "string",
          "minLength": 1,
          "description": "A selectable top-level data property name published by the contract."
        },
        "examples": [
          [
            "legalName"
          ]
        ]
      },
      "Record": {
        "type": "object",
        "description": "Record identity and its typed, permitted domain view. Registry identity, data schema and field meanings are supplied by the collection and operation binding. data may include nested objects, embedded relationship components, references and predefined related-data views with declared ownership and temporal semantics. Revision, lifecycle and provenance fields, when supplied, are source-backed. Readers accept additive envelope fields.",
        "required": [
          "recordId",
          "data"
        ],
        "properties": {
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "data": {
            "type": "object",
            "description": "Caller-authorised domain view. A field-selection operation admits omission of selectable fields within this same schema and always retains recordId and data. Deployments should reuse suitable established domain schemas and vocabularies, including national or sector schemas. The contract identifies adopted models and versions and binds their concepts to a concrete JSON Schema, documenting mappings, local constraints and extensions. The view may contain typed nested structures and relationships."
          }
        },
        "examples": [
          {
            "recordId": "r_42",
            "data": {
              "legalName": "Example Ltd",
              "registrationStatus": "DISSOLVED"
            }
          }
        ]
      },
      "RegistrationStatus": {
        "type": "string",
        "pattern": "^[A-Z][A-Z0-9_]*(?![\\s\\S])",
        "x-extensible-enum": [
          "ACTIVE",
          "DISSOLVED"
        ],
        "description": "ACTIVE means registered and not dissolved; DISSOLVED means registration has ended. The registry can add statuses; clients handle unrecognised values.",
        "examples": [
          "DISSOLVED"
        ]
      },
      "BusinessData": {
        "type": "object",
        "additionalProperties": false,
        "description": "Business-public view fields. Both fields are returned by default; a field-selection request can project either field, so each property is not required in the response schema.",
        "properties": {
          "legalName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "Current legal name recorded by the business registry; no assertion about a person's identity is made."
          },
          "registrationStatus": {
            "$ref": "#/components/schemas/RegistrationStatus"
          }
        },
        "examples": [
          {
            "legalName": "Example Ltd",
            "registrationStatus": "DISSOLVED"
          }
        ]
      },
      "RecordNotAvailableProblem": {
        "description": "A Record is absent, outside the selected Collection, or protected from disclosure.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind every concealed or absent Record outcome to the stable read identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/record-not-available",
                "description": "Stable Record-unavailable problem type."
              },
              "status": {
                "const": 404,
                "description": "HTTP Not Found status."
              }
            }
          }
        ]
      },
      "PageSize": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20,
        "description": "Defaults to 20 on the first request. Values outside the declared bounds return\n`400 bad-request`. With a cursor, omit `pageSize` to keep its bound value or repeat\nthat value; changing it returns `400 invalid-cursor`.",
        "examples": [
          20
        ]
      },
      "Cursor": {
        "type": "string",
        "minLength": 1,
        "maxLength": 4096,
        "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])",
        "description": "Return this URL-safe, opaque, integrity-protected token unchanged. It contains no\npersonal data and is bound to:\n\n- Service, Registry, collection, selected view, applicable access context, and operation.\n- All path selectors, including the parent `recordId` for `revision-list`.\n- Search name, criteria, ordering, effective field and temporal selection, effective\n  trusted purpose, and `pageSize`.\n\nRepeat the same path and request selectors. Malformed, expired, or mismatched cursors,\nincluding reuse for another parent Record, return `400 invalid-cursor`.\n\nThe service rechecks current authorisation for every page; the cursor grants no authority.\nSource-metadata\nfallback never changes the effective purpose. Deployments publish expiry.\n\nA cursor can wrap a source offset, page number, or token without strengthening the source's\nguarantees.",
        "examples": [
          "pgn_7JpQ9m2W4xK8fR3cT6vN1"
        ]
      },
      "PageInfo": {
        "type": "object",
        "description": "Cursor metadata for a bounded collection response.",
        "required": [
          "nextCursor"
        ],
        "properties": {
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Opaque non-empty cursor for the next page, or null on the final page."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of matching resources, supplied when inexpensive to compute. Each BB use must document whether the value is exact or estimated and whether it describes the current collection or the snapshot used to produce the first page."
          }
        }
      },
      "PageInfo-2": {
        "description": "Continuation metadata. Returned cursors satisfy the Cursor input constraints.\nWhen supplied, `total` is exact for the full permitted query at the declared evaluation\npoint, before applying the continuation boundary:\n\n- Current page evaluation for live reads.\n- The fixed source snapshot evaluated under current rights for `snapshot-traversal`.",
        "allOf": [
          {
            "$ref": "#/components/schemas/PageInfo"
          },
          {
            "type": "object",
            "description": "The continuation obeys the same length and alphabet constraints as the request cursor.",
            "properties": {
              "nextCursor": {
                "description": "Opaque continuation accepted by the next request, or null on the final page.",
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Cursor"
                  },
                  {
                    "type": "null",
                    "description": "No continuation remains for this traversal."
                  }
                ]
              }
            }
          }
        ],
        "examples": [
          {
            "nextCursor": null
          },
          {
            "nextCursor": "pgn_7JpQ9m2W4xK8fR3cT6vN1"
          }
        ]
      },
      "RecordPage": {
        "type": "object",
        "description": "Response-bounded page in the declared deterministic order. Baseline traversal follows\nthe published source consistency, result limits, and resource policy. It does not\nestablish an exhaustive export, snapshot, or bound on database work.\n\n`complete-traversal` additionally returns each permitted match once under unchanged\ndata and access. `snapshot-traversal` fixes source membership, order, and data at one\nevaluation point.\n\nEvery page applies current authorisation and disclosure. A short or empty page may\ncontinue; `nextCursor` set to `null` ends the declared traversal. When present, `total`\nis exact for the full permitted query at its declared evaluation point, before the\ncontinuation boundary.",
        "required": [
          "items",
          "pageInfo"
        ],
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "description": "Authorised records in the deployment's declared deterministic order.",
            "items": {
              "$ref": "#/components/schemas/Record"
            }
          },
          "pageInfo": {
            "$ref": "#/components/schemas/PageInfo-2"
          }
        },
        "examples": [
          {
            "items": [],
            "pageInfo": {
              "nextCursor": null
            }
          }
        ]
      },
      "RegistrationNumberValues": {
        "type": "object",
        "additionalProperties": false,
        "description": "Complete exact key, unique throughout this Registry, matched byte for byte.",
        "required": [
          "registrationNumber"
        ],
        "properties": {
          "registrationNumber": {
            "type": "string",
            "pattern": "^BR-[0-9]{6}(?![\\s\\S])",
            "description": "Registry-assigned registration number, including the uppercase prefix and all six digits."
          }
        },
        "examples": [
          {
            "registrationNumber": "BR-000042"
          }
        ]
      },
      "JurisdictionNumberValues": {
        "type": "object",
        "additionalProperties": false,
        "description": "Composite exact key whose pair is unique in this Registry. Both fields are matched byte for byte.",
        "required": [
          "jurisdictionCode",
          "localNumber"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "pattern": "^[A-Z]{2}(?![\\s\\S])",
            "description": "Two-letter registry-owned jurisdiction code, not asserted to be an ISO country code."
          },
          "localNumber": {
            "type": "string",
            "pattern": "^[0-9]{8}(?![\\s\\S])",
            "description": "Eight-digit identifier within the jurisdiction; leading zeroes are significant."
          }
        },
        "examples": [
          {
            "jurisdictionCode": "AA",
            "localNumber": "00000042"
          }
        ]
      },
      "FieldError": {
        "type": "object",
        "description": "Human-readable failure associated with one request field.",
        "required": [
          "pointer",
          "message"
        ],
        "properties": {
          "pointer": {
            "type": "string",
            "format": "json-pointer",
            "description": "JSON Pointer identifying the invalid request field."
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "description": "Human-readable explanation of the field failure."
          }
        }
      },
      "ValidationProblem": {
        "description": "Problem details for a request containing one or more invalid fields.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Field-level validation details.",
            "required": [
              "errors"
            ],
            "properties": {
              "errors": {
                "type": "array",
                "minItems": 1,
                "description": "One entry for each request field that failed validation.",
                "items": {
                  "$ref": "#/components/schemas/FieldError"
                }
              }
            }
          }
        ]
      },
      "RegistrationStatusCriteria": {
        "type": "object",
        "additionalProperties": false,
        "description": "One equality predicate over the declared business registration status, with no implicit case conversion.",
        "required": [
          "registrationStatus"
        ],
        "properties": {
          "registrationStatus": {
            "$ref": "#/components/schemas/RegistrationStatus"
          }
        },
        "examples": [
          {
            "registrationStatus": "DISSOLVED"
          }
        ]
      },
      "legalName": {
        "type": "string",
        "minLength": 1,
        "maxLength": 300,
        "description": "Current legal name recorded by the business registry; no assertion about a person's identity is made."
      },
      "FieldEqualityCriteria": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Equality predicates over any non-empty combination of the declared business-public fields. Every supplied field must match exactly; omitted fields do not constrain the result.",
        "properties": {
          "legalName": {
            "$ref": "#/components/schemas/legalName"
          },
          "registrationStatus": {
            "$ref": "#/components/schemas/RegistrationStatus"
          }
        },
        "examples": [
          {
            "legalName": "Example Ltd",
            "registrationStatus": "DISSOLVED"
          }
        ]
      }
    },
    "headers": {
      "CacheControl": {
        "description": "Protected reads and errors use no-store. Deployments may publish another caching policy for public or properly isolated representations while preserving authorisation.",
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      },
      "RetryAfter": {
        "description": "Delay in seconds or HTTP-date before retrying; authoritative over any advisory quota fields.",
        "schema": {
          "type": "string"
        },
        "example": "30"
      },
      "ApiCatalogLink": {
        "description": "Web Link with the api-catalog relation. Its target is this well-known URI or the publisher's API catalog document location.",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": ";\\s*rel\\s*=\\s*(?:api-catalog|\"(?:[^\"]*\\s)?api-catalog(?:\\s[^\"]*)?\")\\s*(?:[;,]|(?![\\s\\S]))"
        },
        "example": "</.well-known/api-catalog>; rel=\"api-catalog\""
      },
      "ApiCatalogETag": {
        "description": "Required HTTP representation validator for the API catalog linkset.",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "W/\"representation-7fa9\""
      },
      "ConditionalETag": {
        "description": "Required representation validator on 200 and 304 responses of Retrieve selecting conditional-read. It identifies the permitted representation, effective field and temporal selection, and effective trusted purpose context, not a source revision.",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "W/\"representation-7fa9\""
      },
      "WwwAuthenticate": {
        "description": "Bearer authentication challenge, with no record-specific facts.",
        "schema": {
          "type": "string"
        },
        "example": "Bearer"
      }
    },
    "responses": {
      "InternalError": {
        "description": "Request failure, including a source contract violation. Protected-existence policy precedes Record-specific diagnostics. Problem text excludes personal data, source counts and internal details; type is the sole machine identifier, with code and timestamp omitted.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/internal-error",
              "title": "Request could not be completed",
              "status": 500,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The service temporarily cannot accept work; no dependency topology is exposed.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/service-unavailable",
              "title": "Service temporarily unavailable",
              "status": 503,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "ApiCatalog": {
        "description": "The API catalog linkset. RFC 9727 recommends the Content-Type profile parameter \"https://www.rfc-editor.org/info/rfc9727\".",
        "headers": {
          "Link": {
            "$ref": "#/components/headers/ApiCatalogLink"
          },
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        },
        "content": {
          "application/linkset+json": {
            "schema": {
              "$ref": "#/components/schemas/ApiCatalog"
            },
            "example": {
              "linkset": [
                {
                  "anchor": "https://registry.example/",
                  "service-desc": [
                    {
                      "href": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                      "type": "application/vnd.oai.openapi",
                      "title": "Digital Registries API"
                    }
                  ],
                  "service-meta": [
                    {
                      "href": "https://registry.example/catalog",
                      "type": "application/ld+json",
                      "title": "Registry metadata for the records Registry"
                    }
                  ]
                }
              ]
            }
          }
        }
      },
      "ApiCatalogNotModified": {
        "description": "The API catalog validator matches; the response is bodyless.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        }
      },
      "ApiCatalogHeaders": {
        "description": "The API catalog response headers, without a body.",
        "headers": {
          "Link": {
            "$ref": "#/components/headers/ApiCatalogLink"
          },
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        }
      },
      "InternalErrorHeaders": {
        "description": "HEAD form of InternalError: the request could not be completed; the response is bodyless.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "ServiceUnavailableHeaders": {
        "description": "HEAD form of ServiceUnavailable: the service temporarily cannot accept work; the response is bodyless.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "NotModified": {
        "description": "A Retrieve selecting conditional-read matches its representation validator after authorisation; the response is bodyless.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ConditionalETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "BadRequest": {
        "description": "`bad-request` identifies malformed or structurally invalid input, including malformed\nJSON, missing or undeclared body members, and incorrect JSON types. It also identifies\ninvalid or unsupported query parameters or invalid pagination controls, such as an\nout-of-range `pageSize`. When `field-selection` is selected, empty, duplicate,\nincorrectly typed or out-of-bounds selections and unsupported `fields` query values\nuse `400`.\n\n`invalid-cursor` identifies a malformed, expired, or mismatched continuation,\nincluding changed path selectors such as a `revision-list` parent `recordId`, request\ncriteria, ordering, effective `pageSize`, field or temporal selection, or trusted purpose.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "malformed": {
                "value": {
                  "type": "https://govstack.global/problems/digital-registries/bad-request",
                  "title": "Invalid request",
                  "status": 400,
                  "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
                }
              },
              "structure": {
                "summary": "A required request member is missing",
                "value": {
                  "type": "https://govstack.global/problems/digital-registries/bad-request",
                  "title": "Invalid request",
                  "status": 400,
                  "detail": "The request is missing a required member.",
                  "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
                }
              },
              "cursor": {
                "value": {
                  "type": "https://govstack.global/problems/digital-registries/invalid-cursor",
                  "title": "Invalid continuation",
                  "status": 400,
                  "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid access token; the problem reveals no record existence.",
        "headers": {
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WwwAuthenticate"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/unauthorized",
              "title": "Authentication required",
              "status": 401,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Access to the operation or view is denied. Protected Record existence uses the 404 response.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/forbidden",
              "title": "Operation not permitted",
              "status": 403,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "RecordNotAvailable": {
        "description": "Absent Records, Records outside the declared collection and protected existence return the same status, problem type and public detail. Record-specific counts and hints are withheld.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/RecordNotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/record-not-available",
              "title": "Record not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "NotAcceptable": {
        "description": "The requested response media type is not supported.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/not-acceptable",
              "title": "Response media type not supported",
              "status": 406,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "The gateway enforces its published quota scope and supplies Retry-After. Advisory RateLimit headers are gateway-owned.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/too-many-requests",
              "title": "Request rate exceeded",
              "status": 429,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "BadGateway": {
        "description": "The registry adapter received an unusable upstream response; no upstream details are exposed.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/bad-gateway",
              "title": "Upstream request failed",
              "status": 502,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "GatewayTimeout": {
        "description": "The upstream read exceeded its time budget; no partial or fabricated record is returned.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/gateway-timeout",
              "title": "Upstream request timed out",
              "status": 504,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "ContentTooLarge": {
        "description": "The request exceeds the deployment's published body-size limit.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/content-too-large",
              "title": "Request body too large",
              "status": 413,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "This read operation accepts application/json request bodies only.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/unsupported-media-type",
              "title": "Request media type not supported",
              "status": 415,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "InvalidField": {
        "description": "A structurally valid Lookup or Search body names an unknown selector, search or\nselectable field, or supplies domain values that violate declared format,\nenumeration, or semantic constraints.\n\nStructural input and pagination-control errors use `400`. Field errors use JSON\nPointers and messages that exclude submitted values and internal details.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/invalid-field",
              "title": "Request validation failed",
              "status": 422,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f",
              "errors": [
                {
                  "pointer": "/values/registrationNumber",
                  "message": "The registration number does not match the declared format."
                }
              ]
            }
          }
        }
      }
    }
  }
}