{
  "openapi": "3.1.2",
  "info": {
    "title": "Birth-registration registry Consultation: recorded-parent view",
    "version": "1.0.0-draft",
    "description": "Illustrative birth-registrations collection for Registry https://registry.example/registries/birth-registrations. Its membership is all birth registration Records in that Registry. Retrieve selects the birth-registration-with-recorded-parents view. BirthRegistrationRecord is defined in relationship-examples.schema.json, published with dependencies at https://registry.example/contracts/1.0.0-draft/examples/relationship-examples.schema.json. Reads synchronously query the authoritative registration source and authorise all released fields and components. The source retains revisions and can select a state by recording instant and Record applicability. dateOfBirth is the civil-registration event date; effectiveAt instead accepts a calendar date selecting the applicability of the registry Record and is echoed in top-level temporal metadata. This profile rejects instant values for effectiveAt and performs no timezone conversion. registrationEffectiveFrom is the inclusive first applicable calendar date. recordedAsOf remains a UTC instant serialised with Z. recordedAsOf alone applies the declared knowledge cut without an effective-time filter; effectiveAt alone selects the applicable state using the latest recorded knowledge; both coordinates intersect. Omission of both selects current state. Retained source revisions are normalised into the declared birth-registration-history view using published schema-version mappings. Normalisation preserves recorded values and never overwrites them with current values. If a retained revision cannot be represented without invention or loss, history returns history-not-available rather than a fabricated revision. This profile returns the complete permitted parent view in source order, bounded to four components. Overflow uses generic 500, subject to protected-existence policy. The individualRef, when supplied, targets the Individuals Registry; IndividualReference declares its target collection, Retrieve binding and identifier mapping. Access tokens use issuer https://identity.example, the stable logical service audience https://registry.example/birth-registrations and the declared read scope. Example endpoints are non-production. TLS is 1.3 or later; the gateway allows 60 requests per authenticated client per minute. Responses use no-store. Unsupported query parameters use 400. Every Consultation operation is purpose-bound. Purpose is accepted only from the verified access-token claim named purpose, with the value benefit-eligibility; it is not accepted from a URI, query parameter, request body or ad hoc header and never grants access by itself.",
    "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 birth-registrations collection declares its Registry, membership and representation.",
      "variables": {
        "gatewayHost": {
          "default": "registry.example",
          "description": "Reserved non-production documentation-domain default."
        }
      }
    }
  ],
  "security": [
    {
      "citizenOAuth": [
        "bb:digital-registries:record:read"
      ]
    },
    {
      "serviceOAuth": [
        "bb:digital-registries:record:read"
      ]
    }
  ],
  "tags": [
    {
      "name": "Consultation",
      "description": "Retrieve a permitted birth-registration view with recorded parent components."
    }
  ],
  "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/birth-registrations/records/{recordId}": {
      "get": {
        "operationId": "retrieveBirthRegistration",
        "summary": "Retrieve a birth registration with its recorded parent data",
        "description": "Retrieve a Record in the birth-registrations collection with its permitted view. Parent components preserve nameAtRegistration as recorded; individualRef supplies related Record identity when present. When the source evaluates the requested temporal coordinates and proves that no Record state exists at that point, absent Records, Records outside this collection, and protected existence share 404 record-not-available. A 409 is reserved for source inability to evaluate the requested temporal state. The service never falls back to current state.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-pii": true,
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/birth-registrations",
          "collection": "birth-registrations",
          "capability": "retrieve",
          "view": "birth-registration-with-recorded-parents",
          "features": [
            "recorded-time",
            "effective-time",
            "purpose-bound"
          ],
          "purpose": {
            "required": true,
            "binding": "access-token-claim",
            "claim": "purpose",
            "allowedPurposes": [
              "benefit-eligibility"
            ]
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/RecordedAsOf"
          },
          {
            "$ref": "#/components/parameters/EffectiveAt"
          }
        ],
        "responses": {
          "200": {
            "description": "Complete permitted birth-registration view within its published profile bound.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthRegistrationTemporalRecord"
                },
                "examples": {
                  "current": {
                    "summary": "Current state, with no temporal selection or temporal metadata",
                    "value": {
                      "recordId": "birth_19",
                      "data": {
                        "dateOfBirth": "2020-06-12",
                        "placeOfBirth": "Example Town",
                        "registrationEffectiveFrom": "2020-07-01",
                        "parents": [
                          {
                            "nameAtRegistration": "Alex Example"
                          },
                          {
                            "nameAtRegistration": "Robin Example",
                            "individualRef": {
                              "recordId": "person_57"
                            }
                          }
                        ]
                      }
                    }
                  },
                  "selectedState": {
                    "summary": "Source state selected by recording instant and Record applicability",
                    "value": {
                      "recordId": "birth_19",
                      "temporal": {
                        "recordedAsOf": "2026-06-03T00:00:00Z",
                        "effectiveAt": "2020-07-15"
                      },
                      "data": {
                        "dateOfBirth": "2020-06-12",
                        "placeOfBirth": "Corrected Town",
                        "registrationEffectiveFrom": "2020-07-01",
                        "parents": [
                          {
                            "nameAtRegistration": "Alex Example"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "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"
          },
          "409": {
            "$ref": "#/components/responses/TemporalStateNotAvailable"
          },
          "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/birth-registrations/search": {
      "post": {
        "operationId": "searchBirthRegistrations",
        "summary": "Search by occurrence period and place",
        "description": "Execute the declared byOccurrencePeriodAndPlace search. occurrencePeriod bounds dateOfBirth, while placePrefix matches placeOfBirth using case-sensitive Unicode scalar prefix comparison. temporal independently selects source recording time and Record applicability. recordedAsOf-only, effectiveAt-only, combined, and omitted selections use the defaults declared in this contract. Repeat search, criteria and temporal unchanged with a cursor. A successfully evaluated search with no permitted matches returns 200 with an empty Page, including when matching Records are protected and therefore filtered. A 409 is reserved for source inability to evaluate the requested temporal state. The service never falls back to current state.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-pii": true,
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/birth-registrations",
          "collection": "birth-registrations",
          "capability": "search",
          "view": "birth-registration-with-recorded-parents",
          "features": [
            "recorded-time",
            "effective-time",
            "purpose-bound"
          ],
          "purpose": {
            "required": true,
            "binding": "access-token-claim",
            "claim": "purpose",
            "allowedPurposes": [
              "benefit-eligibility"
            ]
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Typed named search, temporal selection and pagination controls.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BirthRegistrationSearchRequest"
              },
              "example": {
                "search": "byOccurrencePeriodAndPlace",
                "criteria": {
                  "occurrencePeriod": {
                    "from": "2020-06-01",
                    "to": "2020-06-30"
                  },
                  "placePrefix": "Example"
                },
                "temporal": {
                  "recordedAsOf": "2026-06-03T00:00:00Z",
                  "effectiveAt": "2020-07-15"
                },
                "pageSize": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A bounded page of authorised current or temporally selected birth registrations. When the request selects temporal coordinates, top-level page temporal metadata echoes them even when items is empty; individual item metadata is not mandatory.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthRegistrationPage"
                },
                "example": {
                  "items": [],
                  "temporal": {
                    "recordedAsOf": "2026-06-03T00:00:00Z",
                    "effectiveAt": "2020-07-15"
                  },
                  "pageInfo": {
                    "nextCursor": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "409": {
            "$ref": "#/components/responses/TemporalStateNotAvailable"
          },
          "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/birth-registrations/records/{recordId}/revisions": {
      "get": {
        "operationId": "listBirthRegistrationRevisions",
        "summary": "List retained birth-registration revisions",
        "description": "Return retained source revisions in the declared stable source acceptance order, newest first, with a documented unique tie-breaker. Clients follow that order without interpreting opaque revisionId values as timestamps or sequence numbers or assuming that recordedAt is always present. The cursor is bound to this path's parent recordId and all other request selectors; replay against another parent Record or changed selector returns 400 invalid-cursor. Each retained source schema version is mapped into the declared birth-registration-history view without overwriting recorded values. No missing history is reconstructed. A mapping that cannot preserve the revision returns history-not-available only after authorisation and protected-existence checks. An absent parent Record, a parent outside this collection, and protected parent existence use the same generic 404 response.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-pii": true,
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/birth-registrations",
          "collection": "birth-registrations",
          "capability": "revision-list",
          "view": "birth-registration-history",
          "features": [
            "purpose-bound"
          ],
          "purpose": {
            "required": true,
            "binding": "access-token-claim",
            "claim": "purpose",
            "allowedPurposes": [
              "benefit-eligibility"
            ]
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A bounded page of retained, currently disclosable revisions.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthRegistrationRevisionPage"
                },
                "example": {
                  "items": [
                    {
                      "recordId": "birth_19",
                      "revision": {
                        "revisionId": "rev-2",
                        "recordedAt": "2026-05-02T09:00:00Z"
                      },
                      "data": {
                        "dateOfBirth": "2020-06-12",
                        "placeOfBirth": "Example Town",
                        "registrationEffectiveFrom": "2020-07-01",
                        "parents": []
                      }
                    }
                  ],
                  "pageInfo": {
                    "nextCursor": null
                  }
                }
              }
            }
          },
          "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"
          },
          "409": {
            "$ref": "#/components/responses/HistoryNotAvailable"
          },
          "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/birth-registrations/records/{recordId}/revisions/{revisionId}": {
      "get": {
        "operationId": "retrieveBirthRegistrationRevision",
        "summary": "Retrieve one retained birth-registration revision",
        "description": "Return one retained source revision normalised into the declared history view without overwriting recorded values. A source version that cannot be mapped without invention or loss returns history-not-available only after authorisation and protected-existence checks. An unavailable or protected revision, absent or protected parent Record, or parent Record outside this collection uses the same 404 response.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-pii": true,
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/birth-registrations",
          "collection": "birth-registrations",
          "capability": "revision-retrieve",
          "view": "birth-registration-history",
          "features": [
            "purpose-bound"
          ],
          "purpose": {
            "required": true,
            "binding": "access-token-claim",
            "claim": "purpose",
            "allowedPurposes": [
              "benefit-eligibility"
            ]
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/RevisionId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "description": "One retained, currently disclosable birth-registration revision.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthRegistrationRevision"
                },
                "example": {
                  "recordId": "birth_19",
                  "revision": {
                    "revisionId": "rev-2",
                    "recordedAt": "2026-05-02T09:00:00Z"
                  },
                  "data": {
                    "dateOfBirth": "2020-06-12",
                    "placeOfBirth": "Example Town",
                    "registrationEffectiveFrom": "2020-07-01",
                    "parents": []
                  }
                }
              }
            }
          },
          "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"
          },
          "409": {
            "$ref": "#/components/responses/HistoryNotAvailable"
          },
          "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": {
    "parameters": {
      "EffectiveAt": {
        "name": "effectiveAt",
        "in": "query",
        "required": false,
        "description": "Calendar date selecting Record applicability, with registrationEffectiveFrom inclusive. Instant values are rejected; this profile performs no timezone conversion.",
        "schema": {
          "$ref": "#/components/schemas/BirthRegistrationEffectiveAt"
        }
      },
      "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"
        }
      },
      "RecordedAsOf": {
        "name": "recordedAsOf",
        "in": "query",
        "required": false,
        "description": "Selects source state recorded no later than this RFC 3339 instant. Omission selects the current recorded state unless another temporal coordinate is supplied. Declare only when recorded-time is selected.",
        "schema": {
          "$ref": "#/components/schemas/RecordedAsOf"
        }
      },
      "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"
        }
      },
      "RevisionId": {
        "name": "revisionId",
        "in": "path",
        "required": true,
        "description": "Opaque identifier of one retained source revision, encoded as one path segment.",
        "schema": {
          "$ref": "#/components/schemas/RevisionId"
        }
      }
    },
    "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."
            }
          }
        }
      }
    },
    "schemas": {
      "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"
        ]
      },
      "RecordedAsOf": {
        "type": "string",
        "format": "date-time",
        "pattern": "Z(?![\\s\\S])",
        "minLength": 20,
        "maxLength": 35,
        "description": "RFC 3339 UTC instant serialised with Z, bounding source recording time for a read.",
        "examples": [
          "2026-03-01T12:00:00Z"
        ]
      },
      "BirthRegistrationEffectiveAt": {
        "type": "string",
        "format": "date",
        "minLength": 10,
        "maxLength": 10,
        "description": "Calendar date selecting Record applicability. registrationEffectiveFrom is inclusive; instant values and implicit timezone conversion are not supported."
      },
      "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"
            }
          }
        ]
      },
      "RecordReference": {
        "type": "object",
        "description": "Identity of a related Record. The field or deployment schema fixes the target Registry; otherwise registryId is required. An explicit registryId must agree with the fixed target. Concrete fields encode these constraints. When a target read is offered, the field binding identifies the target collection, contract and operation, and maps the referenced identifier to its input. Target reads follow the target Registry's published capabilities and access policy. Profiles declare any referential-integrity guarantees. Adopted domain reference forms may be used with declared target semantics.",
        "required": [
          "recordId"
        ],
        "properties": {
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "registryId": {
            "type": "string",
            "format": "iri",
            "minLength": 1,
            "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:",
            "description": "Stable absolute IRI of the target Registry; service endpoints are discovered separately."
          }
        },
        "examples": [
          {
            "recordId": "person_42",
            "registryId": "https://registry.example/registries/individuals"
          }
        ]
      },
      "IndividualReference": {
        "type": "object",
        "additionalProperties": false,
        "description": "Related Record in the fixed target Registry https://registry.example/registries/individuals. registryId may be omitted; an explicit value must match that target. This illustrative field binding resolves through the individuals collection: operation retrieveIndividual in https://registry.example/contracts/1.0.0-draft/examples/individual-registry.openapi.yaml, GET https://registry.example/v1/collections/individuals/records/{recordId}. Supply the referenced recordId as the path parameter, encoded as one segment. The illustrative target contract is not included in these artifacts; target access is evaluated separately.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RecordReference"
          }
        ],
        "properties": {
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "registryId": {
            "type": "string",
            "const": "https://registry.example/registries/individuals",
            "description": "The same target Registry already fixed by this field's schema."
          }
        },
        "examples": [
          {
            "recordId": "person_42"
          },
          {
            "recordId": "person_42",
            "registryId": "https://registry.example/registries/individuals"
          }
        ]
      },
      "ParentAtRegistration": {
        "type": "object",
        "additionalProperties": false,
        "description": "Parent details captured by the birth registration. nameAtRegistration retains its recorded meaning. individualRef is not required and supplies related Record identity when available.",
        "required": [
          "nameAtRegistration"
        ],
        "properties": {
          "nameAtRegistration": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "Parent name captured at registration, preserved as a historical fact."
          },
          "individualRef": {
            "$ref": "#/components/schemas/IndividualReference"
          }
        },
        "examples": [
          {
            "nameAtRegistration": "Alex Example"
          },
          {
            "nameAtRegistration": "Robin Example",
            "individualRef": {
              "recordId": "person_57"
            }
          }
        ]
      },
      "BirthRegistrationData": {
        "type": "object",
        "additionalProperties": false,
        "description": "Recorded birth event and parent details in the fixed registration view.",
        "required": [
          "dateOfBirth",
          "placeOfBirth",
          "parents"
        ],
        "properties": {
          "dateOfBirth": {
            "type": "string",
            "format": "date",
            "description": "Calendar date of birth as recorded by this registration."
          },
          "placeOfBirth": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "Place of birth label captured by the registration."
          },
          "registrationEffectiveFrom": {
            "type": "string",
            "format": "date",
            "description": "First calendar date on which this registry Record version is applicable. This Record-applicability coordinate is distinct from dateOfBirth, which describes the civil-registration event."
          },
          "parents": {
            "type": "array",
            "maxItems": 4,
            "description": "Complete permitted parent components in source registration order. This profile accepts up to four components; overflow fails the read.",
            "items": {
              "$ref": "#/components/schemas/ParentAtRegistration"
            }
          }
        },
        "examples": [
          {
            "dateOfBirth": "2020-06-12",
            "placeOfBirth": "Example Town",
            "registrationEffectiveFrom": "2020-07-01",
            "parents": [
              {
                "nameAtRegistration": "Alex Example"
              },
              {
                "nameAtRegistration": "Robin Example",
                "individualRef": {
                  "recordId": "person_57"
                }
              }
            ]
          }
        ]
      },
      "BirthRegistrationRecord": {
        "description": "Record in https://registry.example/registries/birth-registrations with recorded parent data and any related Record references.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Record"
          },
          {
            "type": "object",
            "description": "Concrete birth-registration data binding.",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/BirthRegistrationData"
              }
            }
          }
        ],
        "examples": [
          {
            "recordId": "birth_19",
            "data": {
              "dateOfBirth": "2020-06-12",
              "placeOfBirth": "Example Town",
              "registrationEffectiveFrom": "2020-07-01",
              "parents": [
                {
                  "nameAtRegistration": "Alex Example"
                },
                {
                  "nameAtRegistration": "Robin Example",
                  "individualRef": {
                    "recordId": "person_57"
                  }
                }
              ]
            }
          }
        ]
      },
      "EffectiveAt": {
        "type": "string",
        "minLength": 10,
        "maxLength": 35,
        "description": "Calendar date or RFC 3339 UTC instant serialised with Z at which the requested state applies.",
        "oneOf": [
          {
            "format": "date",
            "minLength": 10,
            "maxLength": 10,
            "description": "Calendar-date applicability coordinate."
          },
          {
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "minLength": 20,
            "maxLength": 35,
            "description": "UTC instant applicability coordinate serialised with Z."
          }
        ],
        "examples": [
          "2026-02-15"
        ]
      },
      "TemporalMetadata": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "maxProperties": 2,
        "description": "Source-backed temporal coordinates actually used to produce this representation. It echoes every requested temporal coordinate after validation and is omitted only for a current-state request with no temporal selection.",
        "properties": {
          "recordedAsOf": {
            "$ref": "#/components/schemas/RecordedAsOf"
          },
          "effectiveAt": {
            "$ref": "#/components/schemas/EffectiveAt"
          }
        },
        "examples": [
          {
            "recordedAsOf": "2026-03-01T12:00:00Z",
            "effectiveAt": "2026-02-15"
          }
        ]
      },
      "BirthRegistrationTemporalMetadata": {
        "description": "Source-backed temporal echo for the birth profile, preserving UTC recording instants and date-only applicability coordinates.",
        "allOf": [
          {
            "$ref": "#/components/schemas/TemporalMetadata"
          },
          {
            "type": "object",
            "description": "Returned effectiveAt coordinates are calendar dates without timezone conversion.",
            "properties": {
              "effectiveAt": {
                "$ref": "#/components/schemas/BirthRegistrationEffectiveAt"
              }
            }
          }
        ]
      },
      "BirthRegistrationTemporalRecord": {
        "description": "Temporal-capable birth-registration Record. temporal is omitted for current state and present with source-backed echoed coordinates when temporal selection is used.",
        "allOf": [
          {
            "$ref": "#/components/schemas/BirthRegistrationRecord"
          },
          {
            "type": "object",
            "description": "Top-level temporal metadata, when supplied, is typed by the shared temporal contract.",
            "properties": {
              "temporal": {
                "$ref": "#/components/schemas/BirthRegistrationTemporalMetadata"
              }
            }
          }
        ]
      },
      "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."
              }
            }
          }
        ]
      },
      "SearchRange": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "maxProperties": 2,
        "description": "Reusable inclusive or exclusive range shape. A deployment narrows bound value schemas to one comparable domain type and requires at least one bound.",
        "properties": {
          "from": {
            "description": "Lower bound, with type and inclusion semantics declared by the named search."
          },
          "to": {
            "description": "Upper bound, with type and inclusion semantics declared by the named search."
          }
        }
      },
      "OccurrencePeriod": {
        "description": "Inclusive range of birth-event dates. At least one date bound is required.",
        "allOf": [
          {
            "$ref": "#/components/schemas/SearchRange"
          },
          {
            "type": "object",
            "description": "This named search narrows both reusable range bounds to calendar dates.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date",
                "description": "Inclusive earliest dateOfBirth."
              },
              "to": {
                "type": "string",
                "format": "date",
                "description": "Inclusive latest dateOfBirth."
              }
            }
          }
        ]
      },
      "SearchPrefix": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "description": "Reusable string-prefix value. A deployment declares normalisation, collation, and case handling for each named search. This shape does not define a query language."
      },
      "OccurrencePeriodAndPlaceCriteria": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "occurrencePeriod",
          "placePrefix"
        ],
        "description": "Typed civil-registration event criteria: an inclusive date-of-birth range and a declared place-label prefix.",
        "properties": {
          "occurrencePeriod": {
            "$ref": "#/components/schemas/OccurrencePeriod"
          },
          "placePrefix": {
            "$ref": "#/components/schemas/SearchPrefix"
          }
        }
      },
      "TemporalSelection": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "maxProperties": 2,
        "description": "Temporal coordinates, when supplied, for a declared recorded-time or effective-time read.\nAt least one coordinate is required when the object is present. Omission selects the\noperation's documented current state.\n\n- `recordedAsOf` alone applies a knowledge cut with no effective-time filter.\n- `effectiveAt` alone selects the state applicable then using the latest recorded knowledge.\n- Both coordinates intersect those selections.",
        "properties": {
          "recordedAsOf": {
            "$ref": "#/components/schemas/RecordedAsOf"
          },
          "effectiveAt": {
            "$ref": "#/components/schemas/EffectiveAt"
          }
        },
        "examples": [
          {
            "recordedAsOf": "2026-03-01T12:00:00Z"
          },
          {
            "effectiveAt": "2026-02-15"
          },
          {
            "recordedAsOf": "2026-03-01T12:00:00Z",
            "effectiveAt": "2026-02-15"
          }
        ]
      },
      "BirthRegistrationTemporalSelection": {
        "description": "Birth-profile temporal selection: recordedAsOf is a UTC instant with Z, while effectiveAt is a calendar date only.",
        "allOf": [
          {
            "$ref": "#/components/schemas/TemporalSelection"
          },
          {
            "type": "object",
            "description": "The birth profile narrows effective-time selection to calendar dates.",
            "properties": {
              "effectiveAt": {
                "$ref": "#/components/schemas/BirthRegistrationEffectiveAt"
              }
            }
          }
        ]
      },
      "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"
        ]
      },
      "BirthRegistrationSearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "search",
          "criteria"
        ],
        "description": "Named typed search by occurrence period and place, with temporal selection (when declared) and continuation controls.",
        "properties": {
          "search": {
            "const": "byOccurrencePeriodAndPlace",
            "description": "Published named search for occurrence-period and place-prefix criteria."
          },
          "criteria": {
            "$ref": "#/components/schemas/OccurrencePeriodAndPlaceCriteria"
          },
          "temporal": {
            "$ref": "#/components/schemas/BirthRegistrationTemporalSelection"
          },
          "pageSize": {
            "$ref": "#/components/schemas/PageSize"
          },
          "cursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "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
            }
          }
        ]
      },
      "BirthRegistrationPage": {
        "description": "A bounded current or temporally selected page. Page-level temporal metadata echoes a selection even when items is empty; item metadata remains not required.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RecordPage"
          },
          {
            "type": "object",
            "description": "Current and temporally selected results share the same birth-registration Record view.",
            "properties": {
              "temporal": {
                "$ref": "#/components/schemas/BirthRegistrationTemporalMetadata"
              },
              "items": {
                "type": "array",
                "maxItems": 100,
                "description": "Birth-registration Records in the declared search order.",
                "items": {
                  "$ref": "#/components/schemas/BirthRegistrationTemporalRecord"
                }
              }
            }
          }
        ]
      },
      "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"
                }
              }
            }
          }
        ]
      },
      "RevisionId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}(?![\\s\\S])",
        "description": "Opaque source-backed identifier for one retained revision of a Record.",
        "examples": [
          "rev_2024_07"
        ]
      },
      "RevisionMetadata": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "revisionId"
        ],
        "description": "Source-backed identity and, when supplied, recording instant for one retained revision.",
        "properties": {
          "revisionId": {
            "$ref": "#/components/schemas/RevisionId"
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "minLength": 20,
            "maxLength": 35,
            "description": "RFC 3339 UTC instant serialised with Z at which the source recorded this revision, when available."
          }
        }
      },
      "RecordRevision": {
        "description": "One retained source revision disclosed under current authorisation. revision is always present. Revision operations do not accept temporal selection.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Record"
          },
          {
            "type": "object",
            "description": "Revision metadata required in addition to the common Record envelope.",
            "required": [
              "revision"
            ],
            "properties": {
              "revision": {
                "$ref": "#/components/schemas/RevisionMetadata"
              }
            }
          }
        ],
        "examples": [
          {
            "recordId": "r_42",
            "revision": {
              "revisionId": "rev_2024_07",
              "recordedAt": "2024-07-01T09:30:00Z"
            },
            "data": {
              "legalName": "Example Ltd"
            }
          }
        ]
      },
      "RevisionPage": {
        "description": "Bounded page of retained revisions under current disclosure policy.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RecordPage"
          },
          {
            "type": "object",
            "description": "Revision pages narrow each item to the RecordRevision schema.",
            "properties": {
              "items": {
                "type": "array",
                "maxItems": 100,
                "description": "Retained revisions in the operation's declared deterministic order.",
                "items": {
                  "$ref": "#/components/schemas/RecordRevision"
                }
              }
            }
          }
        ],
        "examples": [
          {
            "items": [],
            "pageInfo": {
              "nextCursor": null
            }
          }
        ]
      },
      "BirthRegistrationRevision": {
        "description": "One retained source revision of a birth-registration Record under current disclosure policy.",
        "allOf": [
          {
            "$ref": "#/components/schemas/BirthRegistrationRecord"
          },
          {
            "type": "object",
            "description": "Retained history requires source-backed revision identity.",
            "required": [
              "revision"
            ],
            "properties": {
              "revision": {
                "$ref": "#/components/schemas/RevisionMetadata"
              }
            }
          }
        ]
      },
      "BirthRegistrationRevisionPage": {
        "description": "A bounded page of retained birth-registration revisions.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RevisionPage"
          },
          {
            "type": "object",
            "description": "Revision pages narrow each item to a birth-registration revision.",
            "properties": {
              "items": {
                "type": "array",
                "maxItems": 100,
                "description": "Retained birth-registration revisions in descending recording order.",
                "items": {
                  "$ref": "#/components/schemas/BirthRegistrationRevision"
                }
              }
            }
          }
        ]
      }
    },
    "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\""
      },
      "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"
          }
        }
      },
      "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"
            }
          }
        }
      },
      "TemporalStateNotAvailable": {
        "description": "The authorised source cannot evaluate the requested temporal state because retention, source-history gaps, or unavailable temporal capability prevents a source-backed result. It never reconstructs a state or substitutes current state.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/temporal-state-not-available",
              "title": "Temporal state not available",
              "status": 409,
              "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."
                }
              ]
            }
          }
        }
      },
      "HistoryNotAvailable": {
        "description": "After authorisation and protected-existence checks, the source cannot return known source-backed retained history because retention, mapping, or source-history gaps make it unavailable. The service does not reconstruct missing revisions or substitute current state.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/history-not-available",
              "title": "Retained history not available",
              "status": 409,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      }
    }
  }
}