{
  "openapi": "3.1.2",
  "info": {
    "title": "GovStack Digital Registries API",
    "version": "1.0.0-draft",
    "description": "This draft reference describes how clients read and change Registry Records through declared\ncollections. A deployment selects the operations it supports and publishes its own\nOpenAPI contract with concrete collection paths and schemas. The `records` collection\nand `https://registry.example/registries/records` Registry Identifier are generic\nreference values.\n\n### Understand the data\n\n- A **Registry** holds records for which a named authority accepts responsibility\n  within a declared scope.\n- A **Record** represents an entity, place, asset, or event within that Registry.\n- A **Collection** groups Records for API access and declares its Registry, membership,\n  supported operations, and representation schemas or views. It need not correspond\n  to a database table. One API can expose several collections.\n- A **permitted view** contains the Record data and metadata that the caller is\n  authorised to receive. It can be filtered or redacted.\n\nDeployments select at least one Consultation or Write capability. Consultation provides:\n\n| Capability | Use it to |\n| --- | --- |\n| Retrieve | Read one Record by its stable identifier. |\n| Lookup | Read one Record using a declared exact selector, such as a registration number. |\n| List | Read a page of Records in a declared order. |\n| Search | Run a declared typed search and read a page of results. |\n| Revision List | Read a page of retained source revisions for one Record. |\n| Revision Retrieve | Read one retained source revision by its identifier. |\n\nWrite independently provides direct Create, direct Update, named Transition, and governed\nChange Requests. Selecting one capability selects no other. A submitted Change Request is\nimmutable and non-authoritative until separately authorised application succeeds. A 202\nresponse identifies actual background work and never proves a Record commit, approval, or\napplication.\n\n### Find a deployed API\n\nStart with `/.well-known/api-catalog` at the API origin (scheme, host, and port, without\na path). This RFC 9727 linkset is a document containing links to the deployed OpenAPI\ncontract and Registry Core metadata. The metadata identifies the\nRegistry, its name, authority, authoritative scope, and specification version. It also\nassociates the service with its Registry, supported API families, endpoint, and deployed\ncontract. The contract declares the Registry Identifier from this metadata. An external\ncatalogue can repeat the metadata but does not replace the origin's linkset.\n\nUse the deployed contract to find typed data and input schemas, field meanings,\nauthorisation, pagination policy, and source currency. Source currency describes how\nup to date the returned information is, including any material replication or cache\ndelay. Where caller discovery is supported, it provides metadata about collections and\noperations visible to the authenticated caller. Discovery does not grant access to\nRecords; authorisation is evaluated on every read.\n\n### Read within the declared limits\n\nEach read applies the caller's permitted view. Only when Update or Transition designates the\ncanonical Retrieve through `companionRead` does that Retrieve become its current authoritative\nguard view. It returns a strong ETag without granting mutation authority or widening the\npermitted representation. Operations can additionally declare\n`conditional-read`, `field-selection`, `complete-traversal`, `snapshot-traversal`,\n`recorded-time`, `effective-time`, or `purpose-bound` features. Omission selects none.\nThis combined reference contract selects conditional-read on Retrieve. Read-only deployment\nprofiles can omit that feature and its validator. Ordinary pagination limits\nthe response size, with declared resource limits and source consistency. It does not\npromise exhaustive traversal, a snapshot, or bounded database work. Public operations\ndeclare `security: []`.\n\nTransport uses TLS 1.3 or later. The `/v1` paths identify this API compatibility line;\n`info.version` versions the draft HTTP contract.\n\nThe default response language is English (`en`). A deployment may select another default\nor localise Problem `title` and `detail`. It then declares that default and follows API\nDesign Guide section 19 for `Accept-Language`, `Content-Language`, and `Vary`.",
    "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": "Deployment root; registry.example is non-production. A deployment may add a stable routing prefix, such as /registry, before the versioned resource paths. Each collection's contract supplies its Registry association and selected view; callers do not repeat registryId on each request. API-family labels classify operations independently of paths.",
      "variables": {
        "gatewayHost": {
          "default": "registry.example",
          "description": "Deployment gateway hostname; registry.example is non-production."
        }
      }
    }
  ],
  "security": [
    {
      "citizenOAuth": [
        "bb:digital-registries:record:read"
      ]
    },
    {
      "serviceOAuth": [
        "bb:digital-registries:record:read"
      ]
    }
  ],
  "tags": [
    {
      "name": "Read",
      "description": "Read authorised Records from declared collections and their associated Registries."
    },
    {
      "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."
    },
    {
      "name": "Write",
      "description": "Authoritative Record mutations performed without a governed proposal."
    },
    {
      "name": "Change Requests",
      "description": "Immutable proposals, review decisions, and separately observable application state."
    },
    {
      "name": "Operations",
      "description": "Optional background execution tracking, independent of Change Request review."
    }
  ],
  "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/capabilities": {
      "get": {
        "operationId": "getCallerCapabilities",
        "summary": "Discover caller-visible Registry operations",
        "description": "Returns only Consultation, Write, and supporting operations discoverable to the\nauthenticated caller. Discovery requires authentication but no particular Record read or\nWrite scope; caller filtering evaluates the complete trusted authorisation context.\nThe document links the versioned OpenAPI contract and names operations by\noperationId. It describes operation families, capabilities, read-view metadata, Write\nmetadata, features, and purpose requirements; it never promises access to any particular\nRecord, field, or mutation. Authorisation is evaluated again on every operation request.\n\nCaller filtering uses the trusted authentication and authorisation context of this\ndiscovery request. No purpose value supplied to discovery grants visibility or access.\n\nIf generated capability metadata exceeds a published bound or contains contradictory\ncollection or operation identities, the operation returns `500 InternalError`. It\nnever truncates or silently deduplicates the metadata.\n\nCapability and feature annotations are advisory. Clients skip an operation whose\ncapability value they do not recognise and ignore feature values they do not\nrecognise. Neither behaviour grants authority, and current authorisation is still\nevaluated on every operation request. The response uses `Cache-Control: no-store`.",
        "tags": [
          "Discovery"
        ],
        "security": [
          {
            "citizenOAuth": []
          },
          {
            "serviceOAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded caller-filtered capability document.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CallerCapabilitiesCacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallerCapabilities"
                },
                "examples": {
                  "selectedOperations": {
                    "summary": "Caller can discover the reference Retrieve operation",
                    "value": {
                      "collections": [
                        {
                          "collectionId": "records",
                          "registry": "https://registry.example/registries/records",
                          "operations": [
                            {
                              "operationId": "retrieveRecord",
                              "family": "consultation",
                              "capability": "retrieve",
                              "view": "record-public",
                              "features": [
                                "conditional-read"
                              ],
                              "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml"
                            }
                          ]
                        }
                      ],
                      "operations": []
                    }
                  },
                  "noVisibleOperations": {
                    "summary": "Authenticated caller has no discoverable Registry operations",
                    "value": {
                      "collections": [],
                      "operations": []
                    }
                  }
                }
              }
            }
          },
          "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"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/collections/{collectionId}/records/{recordId}": {
      "get": {
        "operationId": "retrieveRecord",
        "summary": "Retrieve one Record by its stable identifier",
        "description": "Returns the permitted Record view for a stable identifier within this collection's\ndeclared membership. Encode `recordId` as one path segment.\n\nAn absent Record, a Record outside the collection, and a Record whose existence\ncannot be disclosed to the caller share the same `404` response. The response does\nnot reveal which condition applied. This baseline operation selects current state\nand no selectable temporal feature.\n\nWhen a Write operation selects this exact operation and view through `companionRead`,\nthe body and strong ETag come from one current authoritative guard evaluation. That\nconstraint applies only to the selected companion use, not to ordinary read-only\nprojections. The tag remains disclosure-controlled response metadata; a deployment\ncannot select this operation as a companion when revealing the tag or its change cadence\nis forbidden in the effective authorisation, disclosure, purpose, and field-selection\ncontext.",
        "tags": [
          "Read"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "retrieve",
          "view": "record-public",
          "features": [
            "conditional-read"
          ]
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/StrongRecord"
          },
          "304": {
            "$ref": "#/components/responses/StrongNotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`bad-request` identifies malformed or structurally invalid input, including invalid or unsupported query parameters. This operation has no request body or pagination controls."
          },
          "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"
          }
        }
      },
      "patch": {
        "operationId": "updateRecord",
        "summary": "Update one Record directly",
        "description": "Applies `UpdateInput` to the writable Record representation as an RFC 7396 JSON Merge Patch. Only `data` is writable. The closed schema rejects `recordId`, source evidence, authority-owned state, and other control members. This reference contract leaves domain members below `data` unconstrained; each deployment narrows them in its published contract. Under RFC 7396, a null domain member removes that member. Send the strong `ETag` from the companion read in `If-Match`; weak validators are not accepted. Authorisation, policy, target state, and the guard are re-evaluated atomically with commit. A mismatch returns generic `412` without identifying changed guard state. A synchronous commit returns bodyless `204` with the new strong `ETag`.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:record:update"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:record:update"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "update",
          "inputSchema": "#/components/schemas/UpdateInput",
          "inputMediaType": "application/merge-patch+json",
          "companionRead": {
            "operationId": "retrieveRecord",
            "view": "record-public"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateInput"
              },
              "example": {
                "data": {
                  "label": "Corrected label"
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "$ref": "#/components/responses/RecordUpdated"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteRecordNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "415": {
            "$ref": "#/components/responses/WriteUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/collections/{collectionId}/records": {
      "get": {
        "operationId": "listRecords",
        "summary": "List an authorised page of Records",
        "description": "Returns permitted Records from this collection in the deployment’s deterministic\ndefault order with a unique tie-breaker. Deployments offering `sort` declare its\nallowed fields and directions.\n\nEach declared equality filter is one query parameter for a non-personal field.\nA field named `pageSize`, `cursor`, `offset`, `limit`, `sort`, or `fields` uses another\ndeclared parameter name.\n\nEach request is authorised. Unsupported query parameters return `400`. Continuations\nfollow the Cursor and PageSize rules. Omit `cursor` for the first page. A request\nsample containing a cursor illustrates a continuation request.",
        "tags": [
          "Read"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "list",
          "view": "record-public"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Sort"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/RecordPage"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`bad-request` identifies invalid or unsupported query parameters or invalid pagination controls, including an out-of-range `pageSize`. `invalid-cursor` identifies a malformed, expired, or mismatched continuation. Keep the original path, filters, sort order, and effective `pageSize` when continuing."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/CollectionNotAvailable"
          },
          "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"
          }
        }
      },
      "post": {
        "operationId": "createRecord",
        "summary": "Create one Record directly",
        "description": "Creates one Record in the selected Collection. A synchronous `201` response means that the authoritative commit has completed and returns the new Record URI in `Location`. The operation returns `202` only when it accepts actual commit work for asynchronous execution. The deployment replaces `CreateInput.data` with its domain schema. Retries follow the shared `Idempotency-Key` contract.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:record:create"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:record:create"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "create",
          "inputSchema": "#/components/schemas/CreateInput"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInput"
              },
              "example": {
                "data": {
                  "label": "Reference record"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/RecordCreated"
          },
          "202": {
            "$ref": "#/components/responses/WriteAccepted"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteCollectionNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "415": {
            "$ref": "#/components/responses/WriteUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/collections/{collectionId}/lookup": {
      "post": {
        "operationId": "lookupRecord",
        "summary": "Look up one Record using a declared exact selector",
        "description": "Resolves one declared exact selector to a permitted Record in this collection. Each\nselector specifies typed key fields, normalisation, uniqueness scope, and permitted\ncallers. Matching respects the declared collection membership and uniqueness scope.\nKeys may be composite or derived from declared verified caller context.\n\nIf no matching Record can be disclosed to the caller, the operation uses `404`.\nA uniqueness violation uses generic `500`, subject to the policy on disclosing\nwhether a Record exists. Malformed or structurally invalid input uses `400`.\nStructurally valid input with an unknown selector or invalid domain values uses `422`.\n\nThis synchronous read is retryable without an `Idempotency-Key`. Selector values\nremain confined to the request body.",
        "tags": [
          "Read"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "lookup",
          "view": "record-public"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$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/LookupRequest"
              },
              "examples": {
                "byRegistrationNumber": {
                  "summary": "Illustrative declared selector from the business binding",
                  "value": {
                    "selector": "byRegistrationNumber",
                    "values": {
                      "registrationNumber": "BR-000042"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Record"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`bad-request` identifies malformed JSON, missing or undeclared body members, incorrect JSON types, or invalid or unsupported query parameters. Structurally valid input with an unknown selector or invalid domain values uses `422` instead."
          },
          "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/{collectionId}/search": {
      "post": {
        "operationId": "searchRecords",
        "summary": "Run one declared search and return a page",
        "description": "Runs one declared typed search within this collection and returns a RecordPage.\nContinue with a `POST` request containing the same search, criteria, and any sort\nvalues, plus the returned cursor. Criteria equality follows declared type semantics,\nindependent of JSON property order.\n\nMalformed or structurally invalid input and invalid pagination controls use `400`.\nStructurally valid input with an unknown search or invalid domain values uses `422`.\nInvalid continuations use `400 invalid-cursor`.\n\nThis synchronous read is retryable without an `Idempotency-Key`. Search values\nremain confined to the request body.",
        "tags": [
          "Read"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "search",
          "view": "record-public"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$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/SearchRequest"
              },
              "examples": {
                "byRegistrationStatus": {
                  "summary": "First page using the business binding's status search",
                  "value": {
                    "search": "byRegistrationStatus",
                    "criteria": {
                      "registrationStatus": "DISSOLVED"
                    },
                    "pageSize": 20
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/RecordPage"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`bad-request` identifies malformed JSON, missing or undeclared body members, incorrect JSON types, invalid or unsupported query parameters, or invalid body-carried pagination controls, including an out-of-range `pageSize`. `invalid-cursor` identifies a malformed, expired, or mismatched continuation. Repeat the original search, criteria, any sort values, and effective `pageSize` when continuing. Structurally valid input with an unknown search or invalid domain values uses `422` instead."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/CollectionNotAvailable"
          },
          "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/{collectionId}/records/{recordId}/revisions": {
      "get": {
        "operationId": "listRecordRevisions",
        "summary": "List disclosed retained revisions for one Record",
        "description": "Returns a bounded page of retained source revisions for the identified Record in the\ndeployment's declared stable source revision order, newest first, with a documented\nunique tie-breaker. Clients follow that order without interpreting opaque `revisionId`\nvalues as timestamps or sequence numbers, or assuming `recordedAt` is always available.\n\nEach item is evaluated under current authorisation and disclosure policy. The cursor\nis bound to this path's parent `recordId` and every other request selector. Replay\nagainst a different parent Record or changed selector returns `400 invalid-cursor`.\nThe operation neither fabricates history nor implies that revisions absent from the\nsource were retained.\n\nAn absent parent Record, a Record outside this collection, and a parent Record whose\nexistence cannot be disclosed to the caller use the same generic `404` response.\nOnly after authorisation and checks on whether existence can be disclosed may source\ninability to return retained history use `409 history-not-available`.",
        "tags": [
          "Read"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "revision-list",
          "view": "record-history"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/RevisionPage"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`bad-request` identifies invalid or unsupported query parameters or invalid pagination controls, including an out-of-range `pageSize`. `invalid-cursor` identifies a malformed, expired, or mismatched continuation, including reuse under a different parent `recordId`. Keep the original path, request selectors, and effective `pageSize` when continuing."
          },
          "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/{collectionId}/records/{recordId}/revisions/{revisionId}": {
      "get": {
        "operationId": "retrieveRecordRevision",
        "summary": "Retrieve one disclosed retained Record revision",
        "description": "Returns one retained source revision under current authorisation and disclosure\npolicy. `revisionId` is opaque and source-backed.\n\nAn unavailable or protected revision, absent or protected parent Record, or parent\nRecord outside the collection uses the same `404` response. The API does not reveal\nwhich condition applied.\n\nOnly after authorisation and checks on whether existence can be disclosed may source\ninability to return known retained history use `409 history-not-available`. The\noperation never reconstructs or fabricates a missing historical state.",
        "tags": [
          "Read"
        ],
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "revision-retrieve",
          "view": "record-history"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/RevisionId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/RecordRevision"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`bad-request` identifies malformed or structurally invalid input, including invalid or unsupported query parameters. This operation has no request body or pagination controls."
          },
          "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/{collectionId}/records/{recordId}/transition": {
      "post": {
        "operationId": "applyRecordTransition",
        "summary": "Apply the published Record transition",
        "description": "Applies the named transition profile published for this operation. This reference fixes the action path as `transition`. A deployment narrows `TransitionInput.name` to a constant or closed enumeration and publishes closed, typed parameters instead of accepting an arbitrary action or workflow expression. `If-Match` guards the source Record. At commit, the service atomically rechecks current authorisation, trusted purpose, grants, target state, and the source guard. A mismatch returns generic `412` without identifying changed guard state. Unknown and protected Records both return `404`. The operation returns `202` only for actual asynchronous transition work.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:record:transition"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:record:transition"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "collection": "records",
          "capability": "transition",
          "inputSchema": "#/components/schemas/TransitionInput",
          "action": "transition",
          "transitionProfile": "record-transition",
          "companionRead": {
            "operationId": "retrieveRecord",
            "view": "record-public"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/CollectionId"
          },
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransitionInput"
              },
              "example": {
                "name": "transition",
                "parameters": {
                  "reason": "verified-source"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/TransitionApplied"
          },
          "202": {
            "$ref": "#/components/responses/WriteAccepted"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteRecordNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "415": {
            "$ref": "#/components/responses/WriteUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/change-requests": {
      "post": {
        "operationId": "submitChangeRequest",
        "summary": "Submit an immutable change proposal",
        "description": "Creates one immutable, non-authoritative proposal in pending review, with no Record side effect. It uses the corresponding direct operation's typed `CreateInput`, `UpdateInput`, or `TransitionInput`. Update and transition proposals bind the source Record's strong validator in `baseETag`; update also declares `inputMediaType`. Trusted actor and purpose come from verified authorisation context, never client-supplied actor, approval, decision, or review-state fields. Completed creation returns `201` with `Location`; waiting for review is not asynchronous execution.",
        "tags": [
          "Change Requests"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:change-request:submit"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:change-request:submit"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "capability": "change-requests",
          "inputSchema": "#/components/schemas/CreateChangeRequest"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateChangeRequest"
              },
              "example": {
                "kind": "update",
                "target": {
                  "collectionId": "records",
                  "recordId": "r_42"
                },
                "baseETag": "\"record-7fa9\"",
                "inputMediaType": "application/merge-patch+json",
                "input": {
                  "data": {
                    "label": "Corrected label"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/ChangeRequestCreated"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/TargetNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "415": {
            "$ref": "#/components/responses/WriteUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      },
      "get": {
        "operationId": "listChangeRequests",
        "summary": "List caller-visible change requests",
        "description": "Returns a bounded page of Change Requests visible to the current caller and context. Empty results return `200` with an empty `items` array. Order is ascending `submittedAt`, with `changeRequestId` as the unique tie-breaker. The integrity-protected cursor binds the authenticated actor and tenant partition, trusted purpose, Registry and Collection scope, filters, order, and effective page size; it expires under `changeRequestCursorLifetime`. Malformed, expired, tampered, or context-mismatched cursors return `400` and never restart traversal. Every page is reauthorised under current policy. Traversal reads current state, not a snapshot: new requests can appear later in order, but state changes do not reorder an existing request. The deployment publishes `changeRequestResultWindow` and a processing-time bound; exceeding the latter returns `503` with `Retry-After`. A null `nextCursor` marks completion. Responses use `no-store` and disclose no protected requests through counts, ordering, or errors.",
        "tags": [
          "Change Requests"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:change-request:read"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:change-request:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/ChangeRequestPageSize"
          },
          {
            "$ref": "#/components/parameters/ChangeRequestCursor"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ChangeRequestPage"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest",
            "description": "Malformed or structurally invalid request, including invalid pagination controls or a malformed, expired, tampered, or context-mismatched cursor. This read does not require `Idempotency-Key`."
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "406": {
            "$ref": "#/components/responses/WriteNotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/change-requests/{changeRequestId}": {
      "get": {
        "operationId": "getChangeRequest",
        "summary": "Retrieve one change request",
        "description": "Returns one caller-visible Change Request. Unknown and protected requests both return `404`. Its strong `ETag` identifies the immutable proposal version with current review and application state. `If-None-Match` enables conditional reading but does not replace the strong `If-Match` required for review.",
        "tags": [
          "Change Requests"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:change-request:read"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:change-request:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ChangeRequestId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ChangeRequest"
          },
          "304": {
            "$ref": "#/components/responses/WriteNotModified"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest",
            "description": "Malformed or structurally invalid request. This read has no request body and does not require `Idempotency-Key`."
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ChangeRequestNotAvailable"
          },
          "406": {
            "$ref": "#/components/responses/WriteNotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/change-requests/{changeRequestId}/approve": {
      "post": {
        "operationId": "approveChangeRequest",
        "summary": "Approve the exact proposal version",
        "description": "Approves the proposal version selected by the request resource's strong `If-Match`. `If-Match` guards the Change Request representation; the stored `baseETag` independently guards the source Record at commit. Approval cannot create trusted purpose, extend grants, or bypass current authorisation. This review-only operation returns `200` with approval recorded and application `not-started`. An internal worker with the independent `bb:digital-registries:change-request:apply` grant can later attempt application; review authority alone cannot. Optional `ReviewDecisionInput` can retain a human comment as governance context, not Record data, authority, purpose, or a decision selector.",
        "tags": [
          "Change Requests"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:change-request:review"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:change-request:review"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "capability": "change-requests"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ChangeRequestId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewDecisionInput"
              },
              "example": {
                "comment": "Reviewed against the submitted evidence."
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ChangeRequestApproved"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ChangeRequestNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/change-requests/{changeRequestId}/reject": {
      "post": {
        "operationId": "rejectChangeRequest",
        "summary": "Reject the exact proposal version",
        "description": "Rejects the pending proposal version selected by the request resource's strong `If-Match`. Optional `ReviewDecisionInput` can retain a comment but cannot alter the proposal or supply authority. Unknown and protected requests both return `404`.",
        "tags": [
          "Change Requests"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:change-request:review"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:change-request:review"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "capability": "change-requests"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ChangeRequestId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewDecisionInput"
              },
              "example": {
                "comment": "Submitted evidence does not support the proposed change."
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ChangeRequestRejected"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ChangeRequestNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/change-requests/{changeRequestId}/withdraw": {
      "post": {
        "operationId": "withdrawChangeRequest",
        "summary": "Withdraw the exact proposal version",
        "description": "Withdraws the pending proposal version selected by the request resource's strong `If-Match`. Current policy must authorise the caller; the request identifier or an earlier proposal grant confers no authority. Optional `ReviewDecisionInput` can retain a governance comment but cannot alter the proposal.",
        "tags": [
          "Change Requests"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:change-request:withdraw"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:change-request:withdraw"
            ]
          }
        ],
        "x-govstack-digital-registries-write": {
          "registry": "https://registry.example/registries/records",
          "capability": "change-requests"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ChangeRequestId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewDecisionInput"
              },
              "example": {
                "comment": "Proposal withdrawn before review."
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ChangeRequestWithdrawn"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ChangeRequestNotAvailable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    },
    "/v1/operations/{operationId}": {
      "get": {
        "operationId": "getOperation",
        "summary": "Retrieve asynchronous write status",
        "description": "Available only with background processing. Returns execution work accepted with `202`; `operationId` identifies a background job, not an OpenAPI operation name. `pending` means queued execution, not pending approval. Review and application states remain on the Change Request. A successful `GET` can report failed work; failure of this `GET` uses HTTP Problem Details. Non-terminal responses can include `Retry-After`. Unknown and protected Operations both return `404`. Published `operationRetention` controls result retention.",
        "tags": [
          "Operations"
        ],
        "security": [
          {
            "citizenOAuth": [
              "bb:digital-registries:operation:read"
            ]
          },
          {
            "serviceOAuth": [
              "bb:digital-registries:operation:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/OperationId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Operation"
          },
          "400": {
            "$ref": "#/components/responses/WriteBadRequest",
            "description": "Malformed or structurally invalid request. This supporting read has no request body and does not require `Idempotency-Key`."
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/OperationNotAvailable"
          },
          "406": {
            "$ref": "#/components/responses/WriteNotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/WriteTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteServiceUnavailable"
          }
        }
      }
    }
  },
  "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": {
      "CollectionId": {
        "name": "collectionId",
        "in": "path",
        "required": true,
        "description": "Collection selected by this reference catalogue. A deployed contract replaces the enum with its declared literal collection identifiers. In example URLs such as `/collections/records/records/r_42`, the first `records` is the collection identifier; the second names the Record resource within that collection.",
        "schema": {
          "$ref": "#/components/schemas/CollectionId"
        }
      },
      "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"
        }
      },
      "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"
        }
      },
      "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"
        }
      },
      "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"
        }
      },
      "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"
        }
      },
      "EffectiveAt": {
        "name": "effectiveAt",
        "in": "query",
        "required": false,
        "description": "Selects source state applicable at this calendar date or RFC 3339 instant. Omission selects the currently applicable state unless another temporal coordinate is supplied. Declare only when effective-time is selected.",
        "schema": {
          "$ref": "#/components/schemas/EffectiveAt"
        }
      },
      "Sort": {
        "name": "sort",
        "in": "query",
        "required": false,
        "description": "Fields to sort by. Omit to use the deployment's default order; keep the same sort\ninput on continuation requests.",
        "schema": {
          "$ref": "#/components/schemas/Sort"
        }
      },
      "Fields": {
        "name": "fields",
        "in": "query",
        "required": false,
        "style": "form",
        "explode": false,
        "description": "Deployments declare this parameter only when `field-selection` is selected. It accepts comma-separated top-level data field names, narrowed to the deployment's supported enum. Omission uses the declared default field set; `recordId`, `data`, and documented mandatory data fields remain present. Disclosure policy governs every selected field.",
        "schema": {
          "$ref": "#/components/schemas/FieldSelection"
        }
      },
      "ChangeRequestId": {
        "name": "changeRequestId",
        "in": "path",
        "required": true,
        "description": "Opaque change-request identifier encoded as one path segment.",
        "schema": {
          "$ref": "#/components/schemas/OpaqueId"
        }
      },
      "OperationId": {
        "name": "operationId",
        "in": "path",
        "required": true,
        "description": "Opaque asynchronous Operation identifier encoded as one path segment.",
        "schema": {
          "$ref": "#/components/schemas/OpaqueId"
        }
      },
      "IfMatch": {
        "name": "If-Match",
        "in": "header",
        "required": true,
        "description": "One strong `ETag` for the target representation; weak validators and wildcards are not accepted. For a Record mutation, the service compares the companion guard atomically with commit and returns generic `412` on mismatch without disclosing which guard state changed. For review, it guards the Change Request, not the proposal's `baseETag`, which guards the source Record at commit.",
        "schema": {
          "$ref": "#/components/schemas/StrongETag"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Opaque, client-generated, high-entropy Structured Field String, including quotation marks, with at most 200 characters inside them; UUID values are recommended. Replay lookup binds the method, canonical target URI, authenticated client, tenant or equivalent authorisation partition, and effective trusted purpose. The fingerprint binds the method, canonical target URI, content type, canonical body, and every declared semantic header. A missing, malformed, or oversized key returns `400` before processing. The deployment publishes `idempotencyReplayWindow`; after expiry, it may process the key as new only if its profile permits. Within the window, a completed matching retry returns the original status, body, `Content-Type`, and `Location`, with per-attempt headers regenerated. Fingerprint mismatch returns `422`; a matching in-flight retry returns `409`. Before disclosing a stored result, the service rechecks current authorisation, effective trusted purpose, and disclosure policy. A purpose change cannot select the stored result because purpose is in the lookup scope. The key never preserves or creates a grant.",
        "schema": {
          "type": "string",
          "minLength": 3,
          "maxLength": 202,
          "pattern": "^\"(?:[\\x20-\\x21\\x23-\\x5B\\x5D-\\x7E]|\\\\[\"\\\\]){1,200}\"$"
        },
        "example": "\"018f47d2-4c42-7ca4-bf47-2bd31f88b922\""
      },
      "ChangeRequestPageSize": {
        "name": "pageSize",
        "in": "query",
        "required": false,
        "description": "Maximum items in this bounded page; default 20 and maximum 100.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "ChangeRequestCursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "Opaque, integrity-protected continuation from the preceding Change Request page; omit it for the first page. It binds caller context, trusted purpose, Registry and Collection scope, filters, deterministic order, and effective page size, and expires under `changeRequestCursorLifetime`. Invalid continuation returns `400` and never restarts traversal.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2048
        }
      }
    },
    "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"
        }
      },
      "WriteCacheControl": {
        "description": "Required no-store policy for protected Write and workflow responses.",
        "required": true,
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      },
      "CallerCapabilitiesCacheControl": {
        "description": "Required no-store policy for the authenticated, caller-filtered capability document.",
        "required": true,
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      },
      "ETag": {
        "description": "HTTP representation validator, which may be omitted; it is not a source revision identifier.",
        "schema": {
          "type": "string"
        },
        "example": "W/\"representation-7fa9\""
      },
      "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\""
      },
      "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\""
      },
      "RetryAfter": {
        "description": "Delay in seconds or HTTP-date before retrying; authoritative over any advisory quota fields.",
        "schema": {
          "type": "string"
        },
        "example": "30"
      },
      "WwwAuthenticate": {
        "description": "Bearer authentication challenge, with no record-specific facts.",
        "schema": {
          "type": "string"
        },
        "example": "Bearer"
      },
      "StrongETag": {
        "description": "Strong validator suitable for If-Match; weak validators are forbidden. On a selected Record companion read it is also an opaque mutation guard, without encoded source values or any grant of authority.",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/StrongETag"
        },
        "example": "\"record-7fa9\""
      },
      "Location": {
        "description": "URI of the created Record, change request, or asynchronous Operation.",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uri-reference"
        }
      }
    },
    "schemas": {
      "CollectionId": {
        "type": "string",
        "enum": [
          "records"
        ],
        "description": "Canonical reference collection identifier. Deployment bindings define their own bounded collection identifier enum and use literal values in concrete paths."
      },
      "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"
        ]
      },
      "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"
        ]
      },
      "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"
        ]
      },
      "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"
          }
        ]
      },
      "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"
          }
        ]
      },
      "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."
          }
        }
      },
      "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"
            }
          }
        ]
      },
      "TemporalRecord": {
        "description": "Record wrapper for an operation that selected temporal coordinates. The source-backed temporal metadata echoes the effective selection.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Record"
          },
          {
            "type": "object",
            "description": "A temporally selected Record requires top-level temporal metadata.",
            "required": [
              "temporal"
            ],
            "properties": {
              "temporal": {
                "$ref": "#/components/schemas/TemporalMetadata"
              }
            }
          }
        ]
      },
      "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
            }
          }
        ]
      },
      "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"
          }
        ]
      },
      "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"
          }
        },
        "examples": [
          {
            "items": [],
            "pageInfo": {
              "nextCursor": null
            }
          }
        ]
      },
      "TemporalRecordPage": {
        "description": "RecordPage wrapper for a request that selected temporal coordinates. Metadata remains present when the page has no items.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RecordPage"
          },
          {
            "type": "object",
            "description": "A temporally selected page requires top-level temporal metadata.",
            "required": [
              "temporal"
            ],
            "properties": {
              "temporal": {
                "$ref": "#/components/schemas/TemporalMetadata"
              }
            }
          }
        ]
      },
      "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
        ]
      },
      "PageInfo": {
        "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-2"
          },
          {
            "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"
          }
        ]
      },
      "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"
        ]
      },
      "Sort": {
        "type": "string",
        "minLength": 1,
        "pattern": "^-?[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)*(,-?[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)*)*(?![\\s\\S])",
        "description": "Comma-separated field names using the schema's spelling; prefix `-` for descending\norder, and use `.` between nested fields. Deployments narrow this schema to supported\nfields and directions, publish a unique tie-breaker, and omit the input when only\ndefault ordering is available.",
        "examples": [
          "recordId"
        ]
      },
      "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"
          ]
        ]
      },
      "LookupRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "One declared exact selector with its typed key values. Deployments bind each selector name to a closed values schema, such as oneOf branches with const names. Context-only selectors use an empty values object; other selectors require their declared client-supplied fields.",
        "required": [
          "selector",
          "values"
        ],
        "properties": {
          "selector": {
            "type": "string",
            "minLength": 1,
            "description": "Name of a deployment-declared exact key selector."
          },
          "values": {
            "type": "object",
            "description": "All declared client-supplied key fields, or an empty object for a context-only selector."
          }
        },
        "examples": [
          {
            "selector": "byRegistrationNumber",
            "values": {
              "registrationNumber": "BR-000042"
            }
          }
        ]
      },
      "SearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "One declared search with typed criteria and continuation controls. Deployments bind each name to a closed criteria schema and declare sort when supported.",
        "required": [
          "search",
          "criteria"
        ],
        "properties": {
          "search": {
            "type": "string",
            "minLength": 1,
            "description": "Name of a deployment-declared search."
          },
          "criteria": {
            "type": "object",
            "description": "The closed typed criteria for this search, repeated on continuation."
          },
          "pageSize": {
            "$ref": "#/components/schemas/PageSize"
          },
          "cursor": {
            "$ref": "#/components/schemas/Cursor"
          },
          "sort": {
            "$ref": "#/components/schemas/Sort"
          }
        },
        "examples": [
          {
            "search": "byRegistrationStatus",
            "criteria": {
              "registrationStatus": "DISSOLVED"
            },
            "pageSize": 20
          }
        ]
      },
      "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."
          }
        }
      },
      "SearchSet": {
        "type": "array",
        "minItems": 1,
        "maxItems": 100,
        "uniqueItems": true,
        "description": "Reusable non-empty set-membership shape. A deployment narrows item types and matching semantics independently for each named search.",
        "items": {
          "description": "One typed member accepted by the named search."
        }
      },
      "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."
      },
      "PurposeAccessTokenClaimBinding": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "required",
          "binding",
          "claim",
          "allowedPurposes"
        ],
        "description": "Purpose is derived from a trusted access-token claim and checked against a closed allowed set.",
        "properties": {
          "required": {
            "type": "boolean",
            "const": true,
            "description": "Purpose evaluation is mandatory for this operation."
          },
          "binding": {
            "type": "string",
            "const": "access-token-claim",
            "description": "Purpose is read from the named verified access-token claim."
          },
          "claim": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z][A-Za-z0-9._:-]{0,127}(?![\\s\\S])",
            "description": "Verified access-token claim carrying the caller's declared purpose."
          },
          "allowedPurposes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "uniqueItems": true,
            "description": "Purpose values accepted by this operation after policy evaluation.",
            "items": {
              "description": "Controlled purpose code or absolute purpose URI accepted by policy.",
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}(?![\\s\\S])",
                  "description": "Bounded controlled purpose code."
                },
                {
                  "type": "string",
                  "format": "uri",
                  "minLength": 1,
                  "maxLength": 2048,
                  "pattern": "^\\S+(?![\\s\\S])",
                  "description": "Absolute purpose URI."
                }
              ]
            }
          }
        }
      },
      "PurposeRequirement": {
        "description": "Trusted purpose binding for a purpose-bound operation. Purpose never arrives in a URI, query parameter, request body, or ad hoc header, and does not itself grant access.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/PurposeAccessTokenClaimBinding"
          },
          {
            "type": "object",
            "description": "Purpose supplied by a governed trusted authorisation context.",
            "additionalProperties": false,
            "required": [
              "required",
              "binding",
              "allowedPurposes"
            ],
            "properties": {
              "required": {
                "type": "boolean",
                "const": true,
                "description": "Purpose evaluation is mandatory for this operation."
              },
              "binding": {
                "type": "string",
                "const": "trusted-authorization-context",
                "description": "Purpose is supplied by a separately governed trusted authorisation context."
              },
              "allowedPurposes": {
                "type": "array",
                "minItems": 1,
                "maxItems": 32,
                "uniqueItems": true,
                "description": "Purpose values accepted from the trusted authorisation context.",
                "items": {
                  "description": "Controlled purpose code or absolute purpose URI accepted by policy.",
                  "anyOf": [
                    {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128,
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}(?![\\s\\S])",
                      "description": "Bounded controlled purpose code."
                    },
                    {
                      "type": "string",
                      "format": "uri",
                      "minLength": 1,
                      "maxLength": 2048,
                      "pattern": "^\\S+(?![\\s\\S])",
                      "description": "Absolute purpose URI."
                    }
                  ]
                }
              }
            }
          }
        ]
      },
      "CompanionReadIdentity": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operationId",
          "view"
        ],
        "description": "Machine-readable identity of the one GET and view whose body and strong ETag come from the same current authoritative guard evaluation for a separately authorised Update or Transition. A deployment cannot designate the read when its effective disclosure policy forbids revealing the tag or its change cadence.",
        "properties": {
          "operationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z][A-Za-z0-9]{0,127}(?![\\s\\S])",
            "description": "operationId of the companion GET in the linked contract."
          },
          "view": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[a-z][a-z0-9-]{0,127}(?![\\s\\S])",
            "description": "Exact permitted Record view returned by that GET. In companion use, its writable data and guard-relevant state are evaluated at the same current authoritative point as the strong ETag."
          }
        }
      },
      "DiscoveredWriteMetadata": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Advisory Write metadata copied from the linked operation contract.",
        "properties": {
          "companionRead": {
            "$ref": "#/components/schemas/CompanionReadIdentity"
          }
        }
      },
      "CapabilityOperation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operationId",
          "contract",
          "capability"
        ],
        "description": "One operation visible to the caller; this is not permission for any particular Record. A client skips the complete entry when capability is unknown and ignores unknown feature annotations on a recognised capability. Discovery metadata never creates authority, and current authorisation applies to every operation request.",
        "properties": {
          "operationId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z][A-Za-z0-9]{0,127}(?![\\s\\S])",
            "description": "Stable operationId in the linked versioned contract."
          },
          "contract": {
            "type": "string",
            "format": "uri",
            "minLength": 1,
            "maxLength": 2048,
            "pattern": "^https://\\S+(?![\\s\\S])",
            "description": "Absolute URI of the versioned OpenAPI contract containing operationId."
          },
          "family": {
            "type": "string",
            "enum": [
              "consultation",
              "write"
            ],
            "description": "API family of the linked operation."
          },
          "capability": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[a-z][a-z0-9-]{0,127}(?![\\s\\S])",
            "x-extensible-enum": [
              "retrieve",
              "lookup",
              "list",
              "search",
              "revision-list",
              "revision-retrieve",
              "create",
              "update",
              "transition",
              "change-requests",
              "change-request-list",
              "change-request-retrieve",
              "change-request-approve",
              "change-request-reject",
              "change-request-withdraw",
              "operation-retrieve"
            ],
            "description": "Consultation, Write, or supporting capability implemented by the linked operation. The listed values are known to this contract version; clients skip an operation entry with an unknown value."
          },
          "view": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[a-z][a-z0-9-]{0,127}(?![\\s\\S])",
            "description": "Record view returned by the linked operation."
          },
          "features": {
            "type": "array",
            "maxItems": 8,
            "uniqueItems": true,
            "description": "Selectable features selected by this operation.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[a-z][a-z0-9-]{0,127}(?![\\s\\S])",
              "x-extensible-enum": [
                "conditional-read",
                "field-selection",
                "complete-traversal",
                "snapshot-traversal",
                "recorded-time",
                "effective-time",
                "purpose-bound"
              ],
              "description": "Advisory selectable feature known to this contract version. Clients ignore unknown feature values. conditional-read uses representation validators; field-selection projects declared fields; complete- and snapshot-traversal add traversal guarantees; recorded-time and effective-time select temporal state; purpose-bound requires the declared trusted purpose binding."
            }
          },
          "purpose": {
            "$ref": "#/components/schemas/PurposeRequirement"
          },
          "write": {
            "$ref": "#/components/schemas/DiscoveredWriteMetadata"
          },
          "readableFields": {
            "type": "array",
            "maxItems": 128,
            "uniqueItems": true,
            "description": "Field names this caller may request from the operation. Names refer to the linked contract and do not promise access for any particular Record.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "description": "Declared response field name visible to this caller."
            }
          },
          "searches": {
            "type": "array",
            "maxItems": 64,
            "uniqueItems": true,
            "description": "Named searches visible to the caller and declared by the linked operation.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,127}(?![\\s\\S])",
              "description": "Named search from the linked contract."
            }
          },
          "selectors": {
            "type": "array",
            "maxItems": 64,
            "uniqueItems": true,
            "description": "Exact selector names visible to the caller and declared by the linked operation.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,127}(?![\\s\\S])",
              "description": "Exact selector name from the linked contract."
            }
          }
        },
        "allOf": [
          {
            "description": "Recognised Consultation operations declare the Record view they return.",
            "if": {
              "description": "Match capabilities recognised as Consultation by this contract version.",
              "required": [
                "capability"
              ],
              "properties": {
                "capability": {
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ],
                  "description": "Capability recognised as Consultation by this contract version."
                }
              }
            },
            "then": {
              "description": "Require a read view and preserve legacy family omission.",
              "required": [
                "view"
              ],
              "allOf": [
                {
                  "anyOf": [
                    {
                      "description": "Accept a legacy Consultation entry without family.",
                      "not": {
                        "required": [
                          "family"
                        ],
                        "description": "Legacy Consultation entries may omit family."
                      }
                    },
                    {
                      "description": "Accept an explicitly classified Consultation entry.",
                      "properties": {
                        "family": {
                          "const": "consultation",
                          "description": "Explicit family for a Consultation operation."
                        }
                      }
                    }
                  ]
                },
                {
                  "not": {
                    "required": [
                      "write"
                    ],
                    "description": "Consultation discovery does not carry Write metadata."
                  }
                }
              ]
            }
          },
          {
            "description": "Recognised Write and supporting operations declare their family explicitly.",
            "if": {
              "description": "Match capabilities recognised as Write or supporting operations.",
              "required": [
                "capability"
              ],
              "properties": {
                "capability": {
                  "enum": [
                    "create",
                    "update",
                    "transition",
                    "change-requests",
                    "change-request-list",
                    "change-request-retrieve",
                    "change-request-approve",
                    "change-request-reject",
                    "change-request-withdraw",
                    "operation-retrieve"
                  ],
                  "description": "Capability recognised as Write or supporting by this contract version."
                }
              }
            },
            "then": {
              "description": "Require the explicit Write family classification.",
              "required": [
                "family"
              ],
              "properties": {
                "family": {
                  "const": "write",
                  "description": "Explicit family for a Write or supporting operation."
                }
              }
            }
          },
          {
            "description": "Write operations do not present read-view annotations as mutation authority.",
            "if": {
              "description": "Match entries explicitly classified in the Write family.",
              "required": [
                "family"
              ],
              "properties": {
                "family": {
                  "const": "write",
                  "description": "Match Write and supporting operations."
                }
              }
            },
            "then": {
              "description": "Forbid Consultation-only annotations on Write entries.",
              "not": {
                "anyOf": [
                  {
                    "required": [
                      "view"
                    ],
                    "description": "Write operations do not return a Record read view."
                  },
                  {
                    "required": [
                      "features"
                    ],
                    "description": "Read features belong to Consultation operations."
                  },
                  {
                    "required": [
                      "purpose"
                    ],
                    "description": "Read purpose metadata belongs to Consultation operations."
                  },
                  {
                    "required": [
                      "readableFields"
                    ],
                    "description": "Readable fields belong to Consultation operations."
                  },
                  {
                    "required": [
                      "searches"
                    ],
                    "description": "Search names belong to Consultation operations."
                  },
                  {
                    "required": [
                      "selectors"
                    ],
                    "description": "Selector names belong to Consultation operations."
                  }
                ]
              }
            }
          },
          {
            "description": "Update and Transition discovery identify their exact strong-validator read.",
            "if": {
              "description": "Match guarded mutation capabilities in the Write family.",
              "required": [
                "family",
                "capability"
              ],
              "properties": {
                "family": {
                  "const": "write",
                  "description": "Match Write operations."
                },
                "capability": {
                  "enum": [
                    "update",
                    "transition"
                  ],
                  "description": "Match guarded mutations."
                }
              }
            },
            "then": {
              "description": "Require metadata identifying the exact companion read.",
              "required": [
                "write"
              ],
              "properties": {
                "write": {
                  "description": "Write metadata required for a guarded mutation.",
                  "required": [
                    "companionRead"
                  ]
                }
              }
            }
          },
          {
            "description": "Conditional-read is available only on Retrieve.",
            "if": {
              "description": "Detect conditional-read on a recognised capability.",
              "required": [
                "capability",
                "features"
              ],
              "properties": {
                "capability": {
                  "description": "Capability recognised by this contract version.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ]
                },
                "features": {
                  "description": "Selected features tested for conditional-read.",
                  "contains": {
                    "description": "Conditional-read feature marker.",
                    "const": "conditional-read"
                  }
                }
              }
            },
            "then": {
              "description": "Restrict the operation capability to Retrieve.",
              "properties": {
                "capability": {
                  "description": "Retrieve is the only capability supporting conditional-read.",
                  "const": "retrieve"
                }
              }
            }
          },
          {
            "description": "Traversal guarantees are available only on List and Search.",
            "if": {
              "description": "Detect complete- or snapshot-traversal on a recognised capability.",
              "required": [
                "capability",
                "features"
              ],
              "properties": {
                "capability": {
                  "description": "Capability recognised by this contract version.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ]
                },
                "features": {
                  "description": "Selected features tested for traversal guarantees.",
                  "contains": {
                    "description": "Complete- or snapshot-traversal feature marker.",
                    "enum": [
                      "complete-traversal",
                      "snapshot-traversal"
                    ]
                  }
                }
              }
            },
            "then": {
              "description": "Restrict traversal guarantees to collection-returning operations.",
              "properties": {
                "capability": {
                  "description": "List and Search are the collection-returning capabilities.",
                  "enum": [
                    "list",
                    "search"
                  ]
                }
              }
            }
          },
          {
            "description": "Snapshot traversal depends on complete traversal.",
            "if": {
              "description": "Detect snapshot-traversal on a recognised capability.",
              "required": [
                "capability",
                "features"
              ],
              "properties": {
                "capability": {
                  "description": "Capability recognised by this contract version.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ]
                },
                "features": {
                  "description": "Selected features tested for snapshot-traversal.",
                  "contains": {
                    "description": "Snapshot-traversal feature marker.",
                    "const": "snapshot-traversal"
                  }
                }
              }
            },
            "then": {
              "description": "Require complete-traversal in the same feature set.",
              "properties": {
                "features": {
                  "description": "Snapshot traversal's required companion feature.",
                  "contains": {
                    "description": "Complete-traversal feature marker.",
                    "const": "complete-traversal"
                  }
                }
              }
            }
          },
          {
            "description": "Temporal selection is limited to ordinary reads, not revision reads.",
            "if": {
              "description": "Detect temporal selection on a recognised capability.",
              "required": [
                "capability",
                "features"
              ],
              "properties": {
                "capability": {
                  "description": "Capability recognised by this contract version.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ]
                },
                "features": {
                  "description": "Selected features tested for temporal selection.",
                  "contains": {
                    "description": "Recorded-time or effective-time feature marker.",
                    "enum": [
                      "recorded-time",
                      "effective-time"
                    ]
                  }
                }
              }
            },
            "then": {
              "description": "Restrict temporal selection to ordinary read capabilities.",
              "properties": {
                "capability": {
                  "description": "Ordinary read capability supporting temporal selection.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search"
                  ]
                }
              }
            }
          },
          {
            "description": "Purpose-bound selection requires a trusted purpose declaration.",
            "if": {
              "description": "Detect purpose-bound on a recognised capability.",
              "required": [
                "capability",
                "features"
              ],
              "properties": {
                "capability": {
                  "description": "Capability recognised by this contract version.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ]
                },
                "features": {
                  "description": "Selected features tested for purpose binding.",
                  "contains": {
                    "description": "Purpose-bound feature marker.",
                    "const": "purpose-bound"
                  }
                }
              }
            },
            "then": {
              "description": "Require the trusted purpose declaration.",
              "required": [
                "purpose"
              ]
            }
          },
          {
            "description": "A purpose declaration is valid only with purpose-bound selected.",
            "if": {
              "description": "Detect a purpose declaration on a recognised capability.",
              "required": [
                "capability",
                "purpose"
              ],
              "properties": {
                "capability": {
                  "description": "Capability recognised by this contract version.",
                  "enum": [
                    "retrieve",
                    "lookup",
                    "list",
                    "search",
                    "revision-list",
                    "revision-retrieve"
                  ]
                }
              }
            },
            "then": {
              "description": "Require purpose-bound in the same feature set.",
              "required": [
                "features"
              ],
              "properties": {
                "features": {
                  "description": "Selected features tested for the purpose-bound marker.",
                  "contains": {
                    "description": "Purpose-bound feature marker.",
                    "const": "purpose-bound"
                  }
                }
              }
            }
          }
        ]
      },
      "RootCapabilityOperation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "registry",
          "operation"
        ],
        "description": "Caller-visible Registry operation that is not scoped beneath one Collection path, such as a cross-Collection Change Request or asynchronous Operation resource.",
        "properties": {
          "registry": {
            "type": "string",
            "format": "iri",
            "minLength": 1,
            "maxLength": 2048,
            "description": "Registry Identifier governed by this operation."
          },
          "operation": {
            "$ref": "#/components/schemas/CapabilityOperation"
          }
        }
      },
      "CapabilityCollection": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collectionId",
          "registry",
          "operations"
        ],
        "description": "Caller-visible operations for one declared collection.",
        "properties": {
          "collectionId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[a-z][a-z0-9-]{0,127}(?![\\s\\S])",
            "description": "Literal collection identifier used by the linked contract."
          },
          "registry": {
            "type": "string",
            "format": "iri",
            "minLength": 1,
            "maxLength": 2048,
            "description": "Stable Registry Identifier associated with this collection."
          },
          "operations": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "uniqueItems": true,
            "description": "Bounded caller-visible operation catalogue for this collection. Each (contract, operationId) pair is unique; contradictory duplicates are an error and are never silently deduplicated.",
            "items": {
              "$ref": "#/components/schemas/CapabilityOperation"
            }
          }
        }
      },
      "CallerCapabilities": {
        "type": "object",
        "required": [
          "collections"
        ],
        "description": "Caller-filtered discovery document. It is a bounded catalogue of selectable operations, not a promise of per-Record, per-field, or future authorisation. When the complete caller-visible result exceeds any declared bound, the operation fails with its declared error response and never silently truncates the catalogue. Clients skip entries with an unknown capability and ignore unknown feature annotations on recognised capabilities; current authorisation remains authoritative for every request.",
        "properties": {
          "collections": {
            "type": "array",
            "maxItems": 64,
            "uniqueItems": true,
            "description": "Caller-visible collections; an empty array reveals no collection operations. collectionId values are unique; contradictory duplicates are an error and are never silently deduplicated.",
            "items": {
              "$ref": "#/components/schemas/CapabilityCollection"
            }
          },
          "operations": {
            "type": "array",
            "maxItems": 64,
            "uniqueItems": true,
            "description": "Caller-visible operations outside a Collection resource path. An empty array reveals none; omission has the same meaning and does not change the meaning of collections.",
            "items": {
              "$ref": "#/components/schemas/RootCapabilityOperation"
            }
          }
        },
        "examples": [
          {
            "collections": [
              {
                "collectionId": "records",
                "registry": "https://registry.example/registries/records",
                "operations": [
                  {
                    "operationId": "retrieveRecord",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "consultation",
                    "capability": "retrieve",
                    "view": "record-public",
                    "features": [
                      "conditional-read"
                    ]
                  },
                  {
                    "operationId": "listRecords",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "consultation",
                    "capability": "list",
                    "view": "record-public"
                  },
                  {
                    "operationId": "lookupRecord",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "consultation",
                    "capability": "lookup",
                    "view": "record-public"
                  },
                  {
                    "operationId": "searchRecords",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "consultation",
                    "capability": "search",
                    "view": "record-public"
                  },
                  {
                    "operationId": "listRecordRevisions",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "consultation",
                    "capability": "revision-list",
                    "view": "record-history"
                  },
                  {
                    "operationId": "retrieveRecordRevision",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "consultation",
                    "capability": "revision-retrieve",
                    "view": "record-history"
                  },
                  {
                    "operationId": "createRecord",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "write",
                    "capability": "create"
                  },
                  {
                    "operationId": "updateRecord",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "write",
                    "capability": "update",
                    "write": {
                      "companionRead": {
                        "operationId": "retrieveRecord",
                        "view": "record-public"
                      }
                    }
                  },
                  {
                    "operationId": "applyRecordTransition",
                    "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                    "family": "write",
                    "capability": "transition",
                    "write": {
                      "companionRead": {
                        "operationId": "retrieveRecord",
                        "view": "record-public"
                      }
                    }
                  }
                ]
              }
            ],
            "operations": [
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "submitChangeRequest",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "change-requests"
                }
              },
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "listChangeRequests",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "change-request-list"
                }
              },
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "getChangeRequest",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "change-request-retrieve"
                }
              },
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "approveChangeRequest",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "change-request-approve"
                }
              },
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "rejectChangeRequest",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "change-request-reject"
                }
              },
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "withdrawChangeRequest",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "change-request-withdraw"
                }
              },
              {
                "registry": "https://registry.example/registries/records",
                "operation": {
                  "operationId": "getOperation",
                  "contract": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                  "family": "write",
                  "capability": "operation-retrieve"
                }
              }
            ]
          },
          {
            "collections": [],
            "operations": []
          }
        ]
      },
      "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."
          }
        }
      },
      "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"
                }
              }
            }
          }
        ]
      },
      "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"
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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."
          }
        }
      },
      "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"
          }
        ]
      },
      "OpaqueId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}(?![\\s\\S])",
        "description": "Opaque, non-personal identifier with no client-inferred internal format.",
        "examples": [
          "op_7"
        ]
      },
      "StrongETag": {
        "type": "string",
        "minLength": 3,
        "maxLength": 258,
        "pattern": "^\"[\\x21\\x23-\\x7E]{1,256}\"(?![\\s\\S])",
        "description": "GovStack Write profile of one quoted strong entity tag using bounded visible ASCII opaque-tag characters. Weak W/ validators, wildcard, lists, spaces, controls, non-ASCII, and trailing input are not admitted.",
        "examples": [
          "\"record-7fa9\""
        ]
      },
      "SourceReference": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "system",
          "revision"
        ],
        "description": "Optional source-backed audit reference supplied with a mutation. Its presence does not require event sourcing or a history API, and the server validates it under source policy.",
        "properties": {
          "system": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Stable identifier of the source system or authority."
          },
          "revision": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Source-backed revision identifier."
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "description": "UTC instant at which the source recorded this revision, when supplied."
          }
        },
        "examples": [
          {
            "system": "https://source.example/systems/register",
            "revision": "source-revision-17",
            "recordedAt": "2026-11-04T08:00:00Z"
          }
        ]
      },
      "CreateInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data"
        ],
        "description": "Semantic input shared by direct and governed creation. Deployments replace or narrow `data` with their domain schema; this reference contract defines no domain fields.",
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Typed domain data in a concrete deployment contract."
          },
          "source": {
            "$ref": "#/components/schemas/SourceReference"
          }
        },
        "examples": [
          {
            "data": {
              "label": "Reference record"
            }
          }
        ]
      },
      "UpdateInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data"
        ],
        "description": "RFC 7396 JSON Merge Patch shared by direct and governed update. It applies to the writable Record representation. Only `data` is mutable; the closed schema rejects `recordId`, source evidence, and authority-owned control fields. Null domain members are removed.",
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": true,
            "minProperties": 1,
            "description": "Domain merge patch, narrowed by the concrete deployment's domain schema."
          }
        },
        "examples": [
          {
            "data": {
              "label": "Corrected label"
            }
          }
        ]
      },
      "TransitionInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name"
        ],
        "description": "Input shared by direct and governed transition. Concrete profiles narrow `name` to a constant or closed enumeration, narrow `parameters` to a closed typed schema, and publish allowed names. This is not an arbitrary runtime action selector.",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[a-z][a-z0-9-]{0,127}(?![\\s\\S])",
            "description": "Catalog transition identifier. A concrete operation narrows this property to a const or closed enum of names it publishes; arbitrary runtime action names are forbidden."
          },
          "parameters": {
            "type": "object",
            "additionalProperties": true,
            "description": "Transition-profile parameters, closed and typed by a concrete contract."
          },
          "source": {
            "$ref": "#/components/schemas/SourceReference"
          }
        },
        "examples": [
          {
            "name": "transition",
            "parameters": {
              "reason": "verified-source"
            }
          }
        ]
      },
      "CreateTarget": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collectionId"
        ],
        "properties": {
          "collectionId": {
            "$ref": "#/components/schemas/CollectionId"
          }
        },
        "description": "Target Collection for creation. recordId is forbidden by the closed shape.",
        "examples": [
          {
            "collectionId": "records"
          }
        ]
      },
      "RecordTarget": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collectionId",
          "recordId"
        ],
        "properties": {
          "collectionId": {
            "$ref": "#/components/schemas/CollectionId"
          },
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          }
        },
        "description": "Existing source Record targeted by update or transition.",
        "examples": [
          {
            "collectionId": "records",
            "recordId": "r_42"
          }
        ]
      },
      "CreateChangeRequest": {
        "description": "Immutable submitted proposal. Closed shapes reject client-supplied actor, purpose, review state, approval, and decision fields. Update and transition bind a strong source `baseETag`.",
        "oneOf": [
          {
            "type": "object",
            "description": "Create proposal with no client-selected Record identifier.",
            "additionalProperties": false,
            "required": [
              "kind",
              "target",
              "input"
            ],
            "properties": {
              "kind": {
                "const": "create",
                "description": "Proposal to create a server-identified Record."
              },
              "target": {
                "$ref": "#/components/schemas/CreateTarget"
              },
              "input": {
                "$ref": "#/components/schemas/CreateInput"
              }
            }
          },
          {
            "type": "object",
            "description": "Update proposal bound to a source Record validator and merge-patch media type.",
            "additionalProperties": false,
            "required": [
              "kind",
              "target",
              "baseETag",
              "inputMediaType",
              "input"
            ],
            "properties": {
              "kind": {
                "const": "update",
                "description": "Proposal to apply a merge patch to an existing Record."
              },
              "target": {
                "$ref": "#/components/schemas/RecordTarget"
              },
              "baseETag": {
                "$ref": "#/components/schemas/StrongETag"
              },
              "inputMediaType": {
                "type": "string",
                "const": "application/merge-patch+json",
                "description": "Registered patch format governing UpdateInput.data."
              },
              "input": {
                "$ref": "#/components/schemas/UpdateInput"
              }
            }
          },
          {
            "type": "object",
            "description": "Named transition proposal bound to a source Record validator.",
            "additionalProperties": false,
            "required": [
              "kind",
              "target",
              "baseETag",
              "input"
            ],
            "properties": {
              "kind": {
                "const": "transition",
                "description": "Proposal to apply one published named transition."
              },
              "target": {
                "$ref": "#/components/schemas/RecordTarget"
              },
              "baseETag": {
                "$ref": "#/components/schemas/StrongETag"
              },
              "input": {
                "$ref": "#/components/schemas/TransitionInput"
              }
            }
          }
        ],
        "examples": [
          {
            "kind": "update",
            "target": {
              "collectionId": "records",
              "recordId": "r_42"
            },
            "baseETag": "\"record-7fa9\"",
            "inputMediaType": "application/merge-patch+json",
            "input": {
              "data": {
                "label": "Corrected label"
              }
            }
          }
        ]
      },
      "ReviewDecisionInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "comment"
        ],
        "description": "Optional body for a review action. `comment` is retained governance context only, not authoritative Record data, actor identity, trusted purpose, approval state, or a substitute for the operation selected by the request URI and current authorisation.",
        "properties": {
          "comment": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000,
            "description": "Human review note safe for the Change Request's authorised audience."
          }
        },
        "examples": [
          {
            "comment": "Reviewed against the submitted evidence."
          }
        ]
      },
      "WriteResult": {
        "type": "object",
        "required": [
          "collectionId",
          "recordId",
          "etag"
        ],
        "description": "Receipt for an authoritative Record mutation, not a domain Record representation. Readers accept additive response-envelope fields.",
        "properties": {
          "collectionId": {
            "$ref": "#/components/schemas/CollectionId"
          },
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "etag": {
            "$ref": "#/components/schemas/StrongETag"
          },
          "source": {
            "$ref": "#/components/schemas/SourceReference"
          }
        },
        "examples": [
          {
            "collectionId": "records",
            "recordId": "r_42",
            "etag": "\"record-7fa9\""
          }
        ]
      },
      "WritableRecord": {
        "type": "object",
        "required": [
          "recordId",
          "data"
        ],
        "description": "Companion representation used to obtain a strong write validator. Readers accept additive response-envelope fields.",
        "properties": {
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Caller-authorised domain data, narrowed by the concrete deployment."
          },
          "source": {
            "$ref": "#/components/schemas/SourceReference"
          }
        },
        "examples": [
          {
            "recordId": "r_42",
            "data": {
              "label": "Reference record"
            }
          }
        ]
      },
      "ProcessingError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "traceId"
        ],
        "description": "Transport-neutral failure summary stored in a domain-state representation.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "Stable absolute error type."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "description": "Short human-readable failure summary."
          },
          "detail": {
            "type": "string",
            "description": "Failure detail safe to disclose to this caller."
          },
          "traceId": {
            "type": "string",
            "pattern": "^(?!0{32}$)[\\da-f]{32}$",
            "description": "W3C trace identifier associated with the failed application attempt."
          }
        },
        "examples": [
          {
            "type": "https://govstack.global/problems/digital-registries/source-precondition-failed",
            "title": "Source Record changed",
            "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
          }
        ]
      },
      "ChangeRequest": {
        "type": "object",
        "required": [
          "changeRequestId",
          "proposalVersion",
          "kind",
          "target",
          "input",
          "reviewState",
          "applicationState",
          "submittedAt",
          "updatedAt"
        ],
        "description": "Immutable proposal with independently observable review and application states. `pending` has no Record side effect; `approved` does not imply `applied`. `result` appears only for `applied`, and `error` is required for `blocked` or `failed`. Readers accept additive envelope fields.",
        "properties": {
          "changeRequestId": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "proposalVersion": {
            "type": "integer",
            "minimum": 1,
            "description": "Immutable proposal version to which review If-Match is bound."
          },
          "kind": {
            "type": "string",
            "enum": [
              "create",
              "update",
              "transition"
            ],
            "description": "Proposed semantic change: create adds a Record, update applies a merge patch, and transition applies one published named action.",
            "examples": [
              "update"
            ]
          },
          "target": {
            "description": "Target Collection and, for update or transition, stable Record identifier."
          },
          "input": {
            "description": "Typed input matching the corresponding direct operation contract."
          },
          "baseETag": {
            "$ref": "#/components/schemas/StrongETag"
          },
          "inputMediaType": {
            "type": "string",
            "const": "application/merge-patch+json",
            "description": "Registered patch media type required for update proposals."
          },
          "reviewState": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "withdrawn"
            ],
            "description": "Governance state: `pending` awaits review, `approved` records approval, `rejected` records rejection, and `withdrawn` records authorised withdrawal.",
            "examples": [
              "pending"
            ]
          },
          "applicationState": {
            "type": "string",
            "enum": [
              "not-started",
              "applying",
              "applied",
              "blocked",
              "failed"
            ],
            "description": "Authoritative application state: `not-started` has no commit work, `applying` is non-terminal, `applied` succeeded, `blocked` needs changed precondition or authority, and `failed` is terminal processing failure.",
            "examples": [
              "not-started"
            ]
          },
          "result": {
            "$ref": "#/components/schemas/WriteResult"
          },
          "error": {
            "$ref": "#/components/schemas/ProcessingError"
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "description": "UTC instant at which the immutable proposal resource was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "description": "UTC instant at which review or application state last changed."
          }
        },
        "allOf": [
          {
            "if": {
              "description": "Select the create proposal branch.",
              "properties": {
                "kind": {
                  "const": "create",
                  "description": "Create proposal discriminator."
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "description": "Create uses a Collection target and CreateInput without source preconditions.",
              "properties": {
                "target": {
                  "$ref": "#/components/schemas/CreateTarget"
                },
                "input": {
                  "$ref": "#/components/schemas/CreateInput"
                }
              },
              "not": {
                "description": "Creation has neither a source validator nor patch media type.",
                "anyOf": [
                  {
                    "description": "baseETag is forbidden for creation.",
                    "required": [
                      "baseETag"
                    ]
                  },
                  {
                    "description": "inputMediaType is forbidden for creation.",
                    "required": [
                      "inputMediaType"
                    ]
                  }
                ]
              }
            }
          },
          {
            "if": {
              "description": "Select the update proposal branch.",
              "properties": {
                "kind": {
                  "const": "update",
                  "description": "Update proposal discriminator."
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "description": "Update requires an existing target, source validator, media type, and UpdateInput.",
              "required": [
                "baseETag",
                "inputMediaType"
              ],
              "properties": {
                "target": {
                  "$ref": "#/components/schemas/RecordTarget"
                },
                "input": {
                  "$ref": "#/components/schemas/UpdateInput"
                }
              }
            }
          },
          {
            "if": {
              "description": "Select the named transition proposal branch.",
              "properties": {
                "kind": {
                  "const": "transition",
                  "description": "Transition proposal discriminator."
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "description": "Transition requires an existing target, source validator, and TransitionInput.",
              "required": [
                "baseETag"
              ],
              "properties": {
                "target": {
                  "$ref": "#/components/schemas/RecordTarget"
                },
                "input": {
                  "$ref": "#/components/schemas/TransitionInput"
                }
              },
              "not": {
                "description": "Named transitions do not carry update patch media type.",
                "required": [
                  "inputMediaType"
                ]
              }
            }
          },
          {
            "if": {
              "description": "Match review states that cannot begin authoritative application.",
              "properties": {
                "reviewState": {
                  "enum": [
                    "pending",
                    "rejected",
                    "withdrawn"
                  ],
                  "description": "Review states with no Record side effect."
                }
              },
              "required": [
                "reviewState"
              ]
            },
            "then": {
              "description": "Non-approved proposals remain not-started.",
              "properties": {
                "applicationState": {
                  "const": "not-started",
                  "description": "No application work has started."
                }
              }
            }
          },
          {
            "if": {
              "description": "Match successfully applied proposals.",
              "properties": {
                "applicationState": {
                  "const": "applied",
                  "description": "Authoritative application succeeded."
                }
              },
              "required": [
                "applicationState"
              ]
            },
            "then": {
              "description": "Applied proposals are approved and carry a result but no error.",
              "required": [
                "result"
              ],
              "properties": {
                "reviewState": {
                  "const": "approved",
                  "description": "Application requires prior approval."
                }
              },
              "not": {
                "description": "Applied proposals do not carry an application error.",
                "required": [
                  "error"
                ]
              }
            }
          },
          {
            "if": {
              "description": "Match blocked or failed application attempts.",
              "properties": {
                "applicationState": {
                  "enum": [
                    "blocked",
                    "failed"
                  ],
                  "description": "Application stopped without an authoritative result."
                }
              },
              "required": [
                "applicationState"
              ]
            },
            "then": {
              "description": "Blocked and failed application states require an error and no result.",
              "required": [
                "error"
              ],
              "properties": {
                "reviewState": {
                  "const": "approved",
                  "description": "Application requires prior approval."
                }
              },
              "not": {
                "description": "Unsuccessful application has no WriteResult.",
                "required": [
                  "result"
                ]
              }
            }
          },
          {
            "if": {
              "description": "Match application states without a terminal outcome.",
              "properties": {
                "applicationState": {
                  "enum": [
                    "not-started",
                    "applying"
                  ],
                  "description": "No terminal application outcome is available."
                }
              },
              "required": [
                "applicationState"
              ]
            },
            "then": {
              "description": "Non-terminal application has neither result nor stored error.",
              "not": {
                "description": "Terminal outcome members are forbidden until application terminates.",
                "anyOf": [
                  {
                    "description": "Result is forbidden before applied.",
                    "required": [
                      "result"
                    ]
                  },
                  {
                    "description": "Error is forbidden before blocked or failed.",
                    "required": [
                      "error"
                    ]
                  }
                ]
              }
            }
          }
        ]
      },
      "ChangeRequestPage": {
        "type": "object",
        "required": [
          "items",
          "page"
        ],
        "description": "Bounded page of visible change requests. Readers accept additive response-envelope fields.",
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "description": "Caller-visible change requests in deterministic page order.",
            "items": {
              "$ref": "#/components/schemas/ChangeRequest"
            }
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo-2"
          }
        }
      },
      "ApprovedChangeRequest": {
        "description": "Approved review decision with no authoritative application started.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ChangeRequest"
          },
          {
            "type": "object",
            "description": "Constrain the approval response to its exact review-only outcome.",
            "required": [
              "reviewState",
              "applicationState"
            ],
            "properties": {
              "reviewState": {
                "const": "approved",
                "description": "The exact proposal version was approved."
              },
              "applicationState": {
                "const": "not-started",
                "description": "Approval did not start application."
              }
            }
          }
        ]
      },
      "RejectedChangeRequest": {
        "description": "Rejected review decision with no authoritative application started.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ChangeRequest"
          },
          {
            "type": "object",
            "description": "Constrain the rejection response to its exact review-only outcome.",
            "required": [
              "reviewState",
              "applicationState"
            ],
            "properties": {
              "reviewState": {
                "const": "rejected",
                "description": "The exact proposal version was rejected."
              },
              "applicationState": {
                "const": "not-started",
                "description": "Rejection has no application effect."
              }
            }
          }
        ]
      },
      "WithdrawnChangeRequest": {
        "description": "Authorised withdrawal with no authoritative application started.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ChangeRequest"
          },
          {
            "type": "object",
            "description": "Constrain the withdrawal response to its exact review-only outcome.",
            "required": [
              "reviewState",
              "applicationState"
            ],
            "properties": {
              "reviewState": {
                "const": "withdrawn",
                "description": "The exact proposal version was withdrawn."
              },
              "applicationState": {
                "const": "not-started",
                "description": "Withdrawal has no application effect."
              }
            }
          }
        ]
      },
      "Operation": {
        "type": "object",
        "required": [
          "operationId",
          "status",
          "createdAt",
          "updatedAt"
        ],
        "description": "Optional background execution state, separate from Change Request governance. `pending` means queued execution, not pending approval; `running` means execution is in progress. Neither grants approval or implies a committed Record. `succeeded` and `failed` are terminal; only `succeeded` has `result`, and `failed` requires `error`. Review and application states remain on the Change Request. Readers accept additive envelope fields.",
        "properties": {
          "operationId": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "succeeded",
              "failed"
            ],
            "description": "Operation lifecycle: pending and running are non-terminal; succeeded and failed are terminal.",
            "examples": [
              "running"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "description": "UTC instant at which the Operation resource was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "Z(?![\\s\\S])",
            "description": "UTC instant at which Operation state last changed."
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Optional approximate completion percentage for non-terminal work."
          },
          "result": {
            "$ref": "#/components/schemas/WriteResult"
          },
          "error": {
            "$ref": "#/components/schemas/ProcessingError"
          }
        },
        "examples": [
          {
            "operationId": "op_7",
            "status": "running",
            "createdAt": "2026-11-04T08:00:00Z",
            "updatedAt": "2026-11-04T08:00:05Z",
            "progress": 40
          }
        ],
        "allOf": [
          {
            "if": {
              "description": "Match successful terminal Operations.",
              "properties": {
                "status": {
                  "const": "succeeded",
                  "description": "Work completed successfully."
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "description": "Successful Operations carry a result and no error.",
              "required": [
                "result"
              ],
              "not": {
                "description": "Successful Operations do not carry an error.",
                "required": [
                  "error"
                ]
              }
            }
          },
          {
            "if": {
              "description": "Match failed terminal Operations.",
              "properties": {
                "status": {
                  "const": "failed",
                  "description": "Work completed unsuccessfully."
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "description": "Failed Operations carry an error and no result.",
              "required": [
                "error"
              ],
              "not": {
                "description": "Failed Operations do not carry a result.",
                "required": [
                  "result"
                ]
              }
            }
          },
          {
            "if": {
              "description": "Match non-terminal Operations.",
              "properties": {
                "status": {
                  "enum": [
                    "pending",
                    "running"
                  ],
                  "description": "Work has not reached a terminal state."
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "description": "Non-terminal Operations carry neither result nor error.",
              "not": {
                "description": "Terminal outcome members are forbidden before completion.",
                "anyOf": [
                  {
                    "description": "Result is forbidden before success.",
                    "required": [
                      "result"
                    ]
                  },
                  {
                    "description": "Error is forbidden before failure.",
                    "required": [
                      "error"
                    ]
                  }
                ]
              }
            }
          }
        ]
      },
      "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."
              }
            }
          }
        ]
      },
      "CollectionNotAvailableProblem": {
        "description": "A Collection is absent or protected from disclosure.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind every concealed or absent Collection outcome to one stable identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/collection-not-available",
                "description": "Stable Collection-unavailable problem type."
              },
              "status": {
                "const": 404,
                "description": "HTTP Not Found status."
              }
            }
          }
        ]
      },
      "BadRequestProblem": {
        "description": "Malformed non-field input or request-body field validation failure.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/ValidationProblem"
              },
              {
                "type": "object",
                "description": "Bind field validation failure to the 400 invalid-request problem type.",
                "required": [
                  "type",
                  "title",
                  "status",
                  "traceId"
                ],
                "properties": {
                  "type": {
                    "const": "https://govstack.global/problems/digital-registries/invalid-request",
                    "description": "Stable invalid-request problem type."
                  },
                  "status": {
                    "const": 400,
                    "description": "HTTP Bad Request status."
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "type": "object",
                "description": "Bind non-field request failure to the 400 bad-request problem type.",
                "required": [
                  "type",
                  "title",
                  "status",
                  "traceId"
                ],
                "properties": {
                  "type": {
                    "const": "https://govstack.global/problems/digital-registries/bad-request",
                    "description": "Stable bad-request problem type."
                  },
                  "status": {
                    "const": 400,
                    "description": "HTTP Bad Request status."
                  }
                },
                "not": {
                  "required": [
                    "errors"
                  ],
                  "description": "Non-field failure omits body-relative errors."
                }
              }
            ]
          }
        ]
      },
      "UnauthorizedProblem": {
        "description": "Authentication failed for the current HTTP request.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind authentication failure to the 401 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/unauthorized",
                "description": "Stable unauthorized problem type."
              },
              "status": {
                "const": 401,
                "description": "HTTP Unauthorized status."
              }
            }
          }
        ]
      },
      "ForbiddenProblem": {
        "description": "Current authenticated context lacks the required grant.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind authorisation failure to the 403 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/forbidden",
                "description": "Stable forbidden problem type."
              },
              "status": {
                "const": 403,
                "description": "HTTP Forbidden status."
              }
            }
          }
        ]
      },
      "NotAvailableProblem": {
        "description": "Resource is absent, out of scope, or protected from existence disclosure.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind concealed or absent resource outcomes to one 404 identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/not-available",
                "description": "Stable not-available problem type."
              },
              "status": {
                "const": 404,
                "description": "HTTP Not Found status."
              }
            }
          }
        ]
      },
      "NotAcceptableProblem": {
        "description": "No response representation satisfies the request Accept header.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind representation negotiation failure to the 406 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/not-acceptable",
                "description": "Stable not-acceptable problem type."
              },
              "status": {
                "const": 406,
                "description": "HTTP Not Acceptable status."
              }
            }
          }
        ]
      },
      "ConflictProblem": {
        "description": "State conflict or matching idempotent request still in flight.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "type": "object",
                "description": "Bind a resource or workflow state conflict to its 409 identity.",
                "required": [
                  "type",
                  "title",
                  "status",
                  "traceId"
                ],
                "properties": {
                  "type": {
                    "const": "https://govstack.global/problems/digital-registries/state-conflict",
                    "description": "Stable state-conflict problem type."
                  },
                  "status": {
                    "const": 409,
                    "description": "HTTP Conflict status."
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "type": "object",
                "description": "Bind a matching in-flight retry to its distinct 409 identity.",
                "required": [
                  "type",
                  "title",
                  "status",
                  "traceId"
                ],
                "properties": {
                  "type": {
                    "const": "https://govstack.global/problems/digital-registries/idempotency-in-flight",
                    "description": "Stable in-flight idempotency problem type."
                  },
                  "status": {
                    "const": 409,
                    "description": "HTTP Conflict status."
                  }
                }
              }
            ]
          }
        ]
      },
      "PreconditionFailedProblem": {
        "description": "A supplied strong If-Match validator did not match current state.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind a failed If-Match comparison to the 412 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/precondition-failed",
                "description": "Stable precondition-failed problem type."
              },
              "status": {
                "const": 412,
                "description": "HTTP Precondition Failed status."
              }
            }
          }
        ]
      },
      "UnsupportedMediaTypeProblem": {
        "description": "Request Content-Type is not supported by the operation.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind request media-type rejection to the 415 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/unsupported-media-type",
                "description": "Stable unsupported-media-type problem type."
              },
              "status": {
                "const": 415,
                "description": "HTTP Unsupported Media Type status."
              }
            }
          }
        ]
      },
      "UnprocessableContentProblem": {
        "description": "Semantic body validation failure or idempotency fingerprint mismatch.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/ValidationProblem"
              },
              {
                "type": "object",
                "description": "Bind semantic field validation failure to its 422 identity.",
                "required": [
                  "type",
                  "title",
                  "status",
                  "traceId"
                ],
                "properties": {
                  "type": {
                    "const": "https://govstack.global/problems/digital-registries/invalid-content",
                    "description": "Stable invalid-content problem type."
                  },
                  "status": {
                    "const": 422,
                    "description": "HTTP Unprocessable Content status."
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "type": "object",
                "description": "Bind idempotency fingerprint mismatch to its distinct 422 identity.",
                "required": [
                  "type",
                  "title",
                  "status",
                  "traceId"
                ],
                "properties": {
                  "type": {
                    "const": "https://govstack.global/problems/digital-registries/idempotency-fingerprint-mismatch",
                    "description": "Stable fingerprint-mismatch problem type."
                  },
                  "status": {
                    "const": 422,
                    "description": "HTTP Unprocessable Content status."
                  }
                },
                "not": {
                  "required": [
                    "errors"
                  ],
                  "description": "Fingerprint mismatch has no body-relative field errors."
                }
              }
            ]
          }
        ]
      },
      "PreconditionRequiredProblem": {
        "description": "Required If-Match header was absent.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind missing required If-Match to the 428 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/precondition-required",
                "description": "Stable precondition-required problem type."
              },
              "status": {
                "const": 428,
                "description": "HTTP Precondition Required status."
              }
            }
          }
        ]
      },
      "TooManyRequestsProblem": {
        "description": "Caller-visible rate limit was exceeded.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind rate-limit rejection to the 429 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/too-many-requests",
                "description": "Stable too-many-requests problem type."
              },
              "status": {
                "const": 429,
                "description": "HTTP Too Many Requests status."
              }
            }
          }
        ]
      },
      "InternalErrorProblem": {
        "description": "Unexpected server failure with no internal details.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind unexpected server failure to the 500 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/internal-error",
                "description": "Stable internal-error problem type."
              },
              "status": {
                "const": 500,
                "description": "HTTP Internal Server Error status."
              }
            }
          }
        ]
      },
      "ServiceUnavailableProblem": {
        "description": "Service temporarily cannot accept work.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "description": "Bind temporary service unavailability to the 503 problem identity.",
            "required": [
              "type",
              "title",
              "status",
              "traceId"
            ],
            "properties": {
              "type": {
                "const": "https://govstack.global/problems/digital-registries/service-unavailable",
                "description": "Stable service-unavailable problem type."
              },
              "status": {
                "const": 503,
                "description": "HTTP Service Unavailable status."
              }
            }
          }
        ]
      },
      "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."
          }
        }
      },
      "PageInfo-2": {
        "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."
          }
        }
      }
    },
    "responses": {
      "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"
                    }
                  ]
                }
              ]
            }
          }
        }
      },
      "ApiCatalogHeaders": {
        "description": "The API catalog response headers, without a body.",
        "headers": {
          "Link": {
            "$ref": "#/components/headers/ApiCatalogLink"
          },
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        }
      },
      "ApiCatalogNotModified": {
        "description": "The API catalog validator matches; the response is bodyless.",
        "headers": {
          "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"
          }
        }
      },
      "Record": {
        "description": "One permitted Record in the published view. Retrieve and Lookup share this envelope. ETag is not required unless conditional-read is selected by Retrieve.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "ETag": {
            "$ref": "#/components/headers/ETag"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Record"
            }
          }
        }
      },
      "StrongRecord": {
        "description": "The permitted Record view used by the canonical companion read. Its body and required strong ETag come from one current authoritative guard evaluation in the effective authorisation, disclosure, purpose, and field-selection context. The tag is a valid strong validator for the selected representation and also invalidates when any authoritative field or source condition changes in a way that can alter that mutation's validation, mapping, or committed effect. Unrelated hidden state need not invalidate it. The opaque tag encodes no source value; receiving the representation, the tag, or a change in the tag grants no mutation authority and identifies no changed state. A shared view name alone does not make this tag equal to a mutation success tag. Equality is meaningful only when the read observes that exact committed guard state with no intervening mutation-relevant change, and uses the same effective context.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Record"
            }
          }
        }
      },
      "RecordPage": {
        "description": "One bounded page, which may be empty and still have a continuation cursor.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RecordPage"
            }
          }
        }
      },
      "RecordRevision": {
        "description": "One retained source revision disclosed under current authorisation.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RecordRevision"
            }
          }
        }
      },
      "RevisionPage": {
        "description": "One bounded page of retained source revisions under current disclosure policy.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RevisionPage"
            }
          }
        }
      },
      "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"
          }
        }
      },
      "StrongNotModified": {
        "description": "The authorised canonical companion read matched its strong current-view validator; the response is bodyless and grants no Write authority.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "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"
            }
          }
        }
      },
      "CollectionNotAvailable": {
        "description": "The collection is unavailable to this caller. Unknown collections and protected collection visibility use the same status, problem type and public detail.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/CollectionNotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/collection-not-available",
              "title": "Collection not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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."
                }
              ]
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "RecordCreated": {
        "description": "Record created and authoritatively committed. Location identifies the same Record as the response body and the createdRecord link. Reading it remains separately authorised and follows the declared source-currency contract. The body etag equals the ETag header. A later companion GET returns that same new guard only when it observes that exact committed guard state with no intervening mutation-relevant change, has reached companion currency, and uses the same effective authorisation, disclosure, purpose, and field selection.",
        "headers": {
          "Location": {
            "$ref": "#/components/headers/Location"
          },
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteResult"
            },
            "example": {
              "collectionId": "records",
              "recordId": "r_42",
              "etag": "\"record-7fa9\""
            }
          }
        },
        "links": {
          "createdRecord": {
            "operationId": "retrieveRecord",
            "description": "Retrieve the created Record when the current caller is separately authorised.",
            "parameters": {
              "collectionId": "$response.body#/collectionId",
              "recordId": "$response.body#/recordId"
            }
          }
        }
      },
      "RecordUpdated": {
        "description": "Record updated and authoritatively committed; response is bodyless. The ETag is the new guard. A later companion GET returns the same value only when it observes that exact committed guard state with no intervening mutation-relevant change, has reached companion currency, and uses the same effective authorisation, disclosure, purpose, and field selection.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "links": {
          "updatedRecord": {
            "operationId": "retrieveRecord",
            "description": "Retrieve the updated Record under separate read authorisation and source currency.",
            "parameters": {
              "collectionId": "$request.path.collectionId",
              "recordId": "$request.path.recordId"
            }
          }
        }
      },
      "TransitionApplied": {
        "description": "Transition applied and authoritatively committed. The body etag equals the ETag header. A later companion GET returns that same new guard only when it observes that exact committed guard state with no intervening mutation-relevant change, has reached companion currency, and uses the same effective authorisation, disclosure, purpose, and field selection.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteResult"
            },
            "example": {
              "collectionId": "records",
              "recordId": "r_42",
              "etag": "\"record-7faa\""
            }
          }
        },
        "links": {
          "transitionedRecord": {
            "operationId": "retrieveRecord",
            "description": "Retrieve the transitioned Record under separate read authorisation and source currency.",
            "parameters": {
              "collectionId": "$request.path.collectionId",
              "recordId": "$request.path.recordId"
            }
          }
        }
      },
      "WriteAccepted": {
        "description": "Optional background execution has been accepted; authoritative commit is not implied. Location identifies the Operation to poll. Waiting for manual approval alone does not produce this response; completed Change Request creation returns 201 instead.",
        "headers": {
          "Location": {
            "$ref": "#/components/headers/Location"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Operation"
            },
            "example": {
              "operationId": "op_7",
              "status": "running",
              "createdAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:00:05Z",
              "progress": 40
            }
          }
        }
      },
      "WritableRecord": {
        "description": "Caller-authorised writable Record representation with a strong validator.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WritableRecord"
            },
            "example": {
              "recordId": "r_42",
              "data": {
                "label": "Reference record"
              }
            }
          }
        }
      },
      "ChangeRequestCreated": {
        "description": "Immutable pending change request created; no Record side effect has occurred.",
        "headers": {
          "Location": {
            "$ref": "#/components/headers/Location"
          },
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ChangeRequest"
            },
            "example": {
              "changeRequestId": "cr_7",
              "proposalVersion": 1,
              "kind": "update",
              "target": {
                "collectionId": "records",
                "recordId": "r_42"
              },
              "baseETag": "\"record-7fa9\"",
              "inputMediaType": "application/merge-patch+json",
              "input": {
                "data": {
                  "label": "Corrected label"
                }
              },
              "reviewState": "pending",
              "applicationState": "not-started",
              "submittedAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:00:00Z"
            }
          }
        }
      },
      "ChangeRequest": {
        "description": "One caller-visible change request.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ChangeRequest"
            },
            "example": {
              "changeRequestId": "cr_7",
              "proposalVersion": 1,
              "kind": "update",
              "target": {
                "collectionId": "records",
                "recordId": "r_42"
              },
              "baseETag": "\"record-7fa9\"",
              "inputMediaType": "application/merge-patch+json",
              "input": {
                "data": {
                  "label": "Corrected label"
                }
              },
              "reviewState": "pending",
              "applicationState": "not-started",
              "submittedAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:00:00Z"
            }
          }
        }
      },
      "ChangeRequestPage": {
        "description": "Bounded page of caller-visible change requests.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ChangeRequestPage"
            },
            "example": {
              "items": [
                {
                  "changeRequestId": "cr_7",
                  "proposalVersion": 1,
                  "kind": "update",
                  "target": {
                    "collectionId": "records",
                    "recordId": "r_42"
                  },
                  "baseETag": "\"record-7fa9\"",
                  "inputMediaType": "application/merge-patch+json",
                  "input": {
                    "data": {
                      "label": "Corrected label"
                    }
                  },
                  "reviewState": "pending",
                  "applicationState": "not-started",
                  "submittedAt": "2026-11-04T08:00:00Z",
                  "updatedAt": "2026-11-04T08:00:00Z"
                }
              ],
              "page": {
                "nextCursor": null
              }
            }
          }
        }
      },
      "ChangeRequestApproved": {
        "description": "Exact proposal version approved; application has not started.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApprovedChangeRequest"
            },
            "example": {
              "changeRequestId": "cr_7",
              "proposalVersion": 1,
              "kind": "update",
              "target": {
                "collectionId": "records",
                "recordId": "r_42"
              },
              "baseETag": "\"record-7fa9\"",
              "inputMediaType": "application/merge-patch+json",
              "input": {
                "data": {
                  "label": "Corrected label"
                }
              },
              "reviewState": "approved",
              "applicationState": "not-started",
              "submittedAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:03:00Z"
            }
          }
        }
      },
      "ChangeRequestRejected": {
        "description": "Exact proposal version rejected; application has not started.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RejectedChangeRequest"
            },
            "example": {
              "changeRequestId": "cr_7",
              "proposalVersion": 1,
              "kind": "update",
              "target": {
                "collectionId": "records",
                "recordId": "r_42"
              },
              "baseETag": "\"record-7fa9\"",
              "inputMediaType": "application/merge-patch+json",
              "input": {
                "data": {
                  "label": "Corrected label"
                }
              },
              "reviewState": "rejected",
              "applicationState": "not-started",
              "submittedAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:03:00Z"
            }
          }
        }
      },
      "ChangeRequestWithdrawn": {
        "description": "Exact proposal version withdrawn; application has not started.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WithdrawnChangeRequest"
            },
            "example": {
              "changeRequestId": "cr_7",
              "proposalVersion": 1,
              "kind": "update",
              "target": {
                "collectionId": "records",
                "recordId": "r_42"
              },
              "baseETag": "\"record-7fa9\"",
              "inputMediaType": "application/merge-patch+json",
              "input": {
                "data": {
                  "label": "Corrected label"
                }
              },
              "reviewState": "withdrawn",
              "applicationState": "not-started",
              "submittedAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:03:00Z"
            }
          }
        }
      },
      "Operation": {
        "description": "Current asynchronous write state.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Operation"
            },
            "example": {
              "operationId": "op_7",
              "status": "running",
              "createdAt": "2026-11-04T08:00:00Z",
              "updatedAt": "2026-11-04T08:00:05Z",
              "progress": 40
            }
          }
        }
      },
      "WriteNotModified": {
        "description": "Conditional GET validator matched; response is bodyless.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/StrongETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        }
      },
      "WriteBadRequest": {
        "description": "Malformed input, including missing or malformed required Idempotency-Key.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/BadRequestProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/bad-request",
              "title": "Bad request",
              "status": 400,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteUnauthorized": {
        "description": "Missing or invalid access token.",
        "headers": {
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WwwAuthenticate"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/UnauthorizedProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/unauthorized",
              "title": "Authentication required",
              "status": 401,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteForbidden": {
        "description": "Authenticated caller is not authorised for this operation.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ForbiddenProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/forbidden",
              "title": "Not authorised",
              "status": 403,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteRecordNotAvailable": {
        "description": "Record is absent, outside the collection, or its existence is protected. This is the same stable public Record-not-available outcome used by the companion read.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "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"
            }
          }
        }
      },
      "WriteCollectionNotAvailable": {
        "description": "Collection is absent or its existence is protected. This is the same stable public Collection-not-available outcome used by Read operations.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/CollectionNotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/collection-not-available",
              "title": "Collection not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "ChangeRequestNotAvailable": {
        "description": "Change request is absent or its existence is protected.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/NotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/not-available",
              "title": "Resource not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "TargetNotAvailable": {
        "description": "Proposal target is absent, outside the allowed Registry context, or protected from existence disclosure.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/NotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/not-available",
              "title": "Resource not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "OperationNotAvailable": {
        "description": "Operation is absent or its existence is protected.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/NotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/not-available",
              "title": "Resource not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteNotAcceptable": {
        "description": "No response representation matches Accept.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/NotAcceptableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/not-acceptable",
              "title": "Representation not available",
              "status": 406,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "Conflict": {
        "description": "Current state conflicts with the operation, or a matching idempotent retry remains in flight. Failed If-Match uses 412 instead.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ConflictProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/state-conflict",
              "title": "Current state conflicts with the request",
              "status": 409,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "PreconditionFailed": {
        "description": "If-Match did not match the current strong validator.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/PreconditionFailedProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/precondition-failed",
              "title": "Source state changed",
              "status": 412,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteUnsupportedMediaType": {
        "description": "Request Content-Type is not supported by this operation.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/UnsupportedMediaTypeProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/unsupported-media-type",
              "title": "Unsupported media type",
              "status": 415,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "UnprocessableContent": {
        "description": "Well-formed input violates semantics, or Idempotency-Key is reused in the same scope with a different request fingerprint.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/UnprocessableContentProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/idempotency-fingerprint-mismatch",
              "title": "Idempotency key fingerprint mismatch",
              "status": 422,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "PreconditionRequired": {
        "description": "Required If-Match was absent.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/PreconditionRequiredProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/precondition-required",
              "title": "If-Match is required",
              "status": 428,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteTooManyRequests": {
        "description": "Caller-visible rate limit exceeded.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/TooManyRequestsProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/too-many-requests",
              "title": "Rate limit exceeded",
              "status": 429,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteInternalError": {
        "description": "Unexpected server failure with no internal detail.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/InternalErrorProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/internal-error",
              "title": "Internal server error",
              "status": 500,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "WriteServiceUnavailable": {
        "description": "Service temporarily unavailable.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/WriteCacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ServiceUnavailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/service-unavailable",
              "title": "Service unavailable",
              "status": 503,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      }
    }
  }
}