{
  "openapi": "3.1.2",
  "info": {
    "title": "Household registry Consultation: nested fixed-view example",
    "version": "1.0.0-draft",
    "description": "Illustrative households collection for Registry https://registry.example/registries/households. Its membership is all household Records in that Registry. Retrieve selects the household-with-memberships view. HouseholdRecord is defined in relationship-examples.schema.json, published with dependencies at https://registry.example/contracts/1.0.0-draft/examples/relationship-examples.schema.json. Reads synchronously query the authoritative household source and authorise all released fields and components. This profile returns complete permitted arrays within bounds of 20 memberships and three address lines. Overflow uses generic 500, subject to protected-existence policy. individualRef targets the Individuals Registry; IndividualReference declares its target collection, Retrieve binding and identifier mapping. Access tokens use issuer https://identity.example, the stable logical service audience https://registry.example/households and the declared read scope. Example endpoints are non-production. TLS is 1.3 or later; the gateway allows 60 requests per authenticated client per minute. Responses use no-store. Unsupported query parameters use 400.",
    "contact": {
      "name": "GovStack Digital Registries Working Group",
      "url": "https://github.com/GovStackWorkingGroup/bb-digital-registries"
    },
    "x-govstack-api-guide": {
      "version": "0.3.0-draft",
      "rulesetVersion": "0.3.0-draft"
    }
  },
  "servers": [
    {
      "url": "https://{gatewayHost}",
      "description": "Non-production deployment root. The households collection declares its Registry, membership and representation.",
      "variables": {
        "gatewayHost": {
          "default": "registry.example",
          "description": "Reserved non-production documentation-domain default."
        }
      }
    }
  ],
  "security": [
    {
      "citizenOAuth": [
        "bb:digital-registries:record:read"
      ]
    },
    {
      "serviceOAuth": [
        "bb:digital-registries:record:read"
      ]
    }
  ],
  "tags": [
    {
      "name": "Consultation",
      "description": "Retrieve a permitted household view with embedded components."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check service liveness",
        "description": "Returns HTTP `200` when the service can accept work and `503` otherwise. This bounded, unauthenticated check exposes only a public service label. Dependency checks are limited to those that determine service availability.",
        "tags": [
          "Health"
        ],
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "description": "The service is healthy and able to accept work.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "servers": [
        {
          "url": "https://{gatewayHost}",
          "description": "Origin root. RFC 8615 fixes well-known URIs at the origin, so a deployment routing prefix does not apply to this path.",
          "variables": {
            "gatewayHost": {
              "default": "registry.example",
              "description": "Deployment gateway hostname; registry.example is non-production."
            }
          }
        }
      ],
      "get": {
        "operationId": "getApiCatalog",
        "summary": "Get the API catalog",
        "description": "Returns the RFC 9727 API catalog for this origin as an RFC 9264 linkset. For each\nDigital Registries API at the origin, a `service-desc` link targets its OpenAPI\ncontract and a `service-meta` link, typed `application/ld+json`, targets the Registry\nmetadata document.\n\nA deployment that restricts the catalog to an intended audience declares that access\nrequirement instead of `security: []`.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ApiCatalog"
          },
          "304": {
            "$ref": "#/components/responses/ApiCatalogNotModified"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      },
      "head": {
        "operationId": "headApiCatalog",
        "summary": "Check the API catalog",
        "description": "Returns the API catalog response headers without a body, including the `Link` header with the `api-catalog` relation that RFC 9727 requires for `HEAD` requests.",
        "tags": [
          "Discovery"
        ],
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ApiCatalogHeaders"
          },
          "500": {
            "$ref": "#/components/responses/InternalErrorHeaders"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailableHeaders"
          }
        }
      }
    },
    "/v1/collections/households/records/{recordId}": {
      "get": {
        "operationId": "retrieveHousehold",
        "summary": "Retrieve a household with its declared embedded components",
        "description": "Retrieve a Record in the households collection with its permitted embedded address and membership components. individualRef identifies the related Individual Record. Absent Records, Records outside this collection and protected existence share 404 record-not-available.",
        "tags": [
          "Consultation"
        ],
        "x-govstack-pii": true,
        "x-govstack-digital-registries": {
          "registry": "https://registry.example/registries/households",
          "collection": "households",
          "capability": "retrieve",
          "view": "household-with-memberships"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/RecordId"
          },
          {
            "$ref": "#/components/parameters/Traceparent"
          }
        ],
        "responses": {
          "200": {
            "description": "Complete permitted household view within its published profile bounds.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HouseholdRecord"
                },
                "example": {
                  "recordId": "household_8",
                  "data": {
                    "address": {
                      "addressLines": [
                        "12 Example Street"
                      ],
                      "locality": "Example Town",
                      "postalCode": "00120"
                    },
                    "memberships": [
                      {
                        "membershipId": "membership_1",
                        "role": "REFERENCE_PERSON",
                        "individualRef": {
                          "recordId": "person_42"
                        }
                      },
                      {
                        "membershipId": "membership_2",
                        "role": "MEMBER",
                        "individualRef": {
                          "recordId": "person_57",
                          "registryId": "https://registry.example/registries/individuals"
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/RecordNotAvailable"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        }
      }
    }
  },
  "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": {
      "Traceparent": {
        "name": "traceparent",
        "in": "header",
        "required": false,
        "description": "W3C Trace Context. Propagate valid context; create context when absent or invalid. Problem traceId is the effective trace-id. Trace metadata excludes personal data.",
        "schema": {
          "type": "string"
        }
      },
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "Conditional request against the selected representation's ETag. Authorisation precedes evaluation of the validator.",
        "schema": {
          "type": "string"
        }
      },
      "RecordId": {
        "name": "recordId",
        "in": "path",
        "required": true,
        "description": "Stable opaque identifier within the selected registry, encoded as one path segment.",
        "schema": {
          "$ref": "#/components/schemas/RecordId"
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "description": "Informational body, which may be omitted; only the HTTP status determines liveness.",
        "properties": {
          "description": {
            "type": "string",
            "description": "Public human-readable service label with no internal details."
          }
        },
        "examples": [
          {
            "description": "Digital Registries API"
          }
        ]
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details with one stable machine identifier in type and a trace identifier for correlation. Error text contains no personal data or system-internal detail.",
        "required": [
          "type",
          "title",
          "status",
          "traceId"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://govstack\\.global/problems/[a-z][a-z0-9-]{1,30}/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
            "description": "Stable GovStack problem-type URI and machine identifier in the form https://govstack.global/problems/{bb-code}/{problem-slug}, where the problem slug uses kebab-case."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "description": "Short human-readable summary of the problem type."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "HTTP status code for this occurrence."
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "URI reference identifying this problem occurrence."
          },
          "traceId": {
            "type": "string",
            "pattern": "^(?!0{32}$)[\\da-f]{32}$",
            "description": "The 32-hex-digit trace-id component of the effective request traceparent."
          }
        }
      },
      "LinkTarget": {
        "type": "object",
        "description": "One RFC 9264 target link; further target attributes follow RFC 9264.",
        "required": [
          "href"
        ],
        "properties": {
          "href": {
            "type": "string",
            "format": "uri-reference",
            "description": "The target URI."
          },
          "type": {
            "type": "string",
            "description": "Media type hint for the target."
          },
          "title": {
            "type": "string",
            "description": "Human-readable target label."
          }
        }
      },
      "LinkContext": {
        "type": "object",
        "description": "One RFC 9264 link context. Members other than anchor are link relation types, such as item, service-desc and service-meta.",
        "properties": {
          "anchor": {
            "type": "string",
            "format": "uri-reference",
            "description": "The link context URI."
          }
        },
        "additionalProperties": {
          "type": "array",
          "minItems": 1,
          "description": "Target links for one relation type.",
          "items": {
            "$ref": "#/components/schemas/LinkTarget"
          }
        }
      },
      "ApiCatalog": {
        "type": "object",
        "description": "RFC 9264 linkset listing the APIs at this origin. Each Digital Registries API has a service-desc link to its OpenAPI contract and a service-meta link to its Registry metadata document.",
        "required": [
          "linkset"
        ],
        "properties": {
          "linkset": {
            "type": "array",
            "minItems": 1,
            "description": "Link context objects, such as one per API anchor.",
            "items": {
              "$ref": "#/components/schemas/LinkContext"
            }
          }
        }
      },
      "RecordId": {
        "type": "string",
        "minLength": 1,
        "description": "Stable opaque identifier unique across all collections in the selected Registry, unchanged throughout the Record's lifecycle and never reassigned to a different Record. The same Record retains its identifier across collections and views. Suitable source identifiers are retained. Exposed identifiers are non-personal and safe for URL references. Collection actions occupy a separate namespace, so source identifiers such as lookup and search remain valid Record Identifiers.",
        "examples": [
          "r_42"
        ]
      },
      "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"
            }
          }
        ]
      },
      "Address": {
        "type": "object",
        "additionalProperties": false,
        "description": "Current address embedded in and owned by the household Record.",
        "required": [
          "addressLines",
          "locality"
        ],
        "properties": {
          "addressLines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 3,
            "description": "Complete ordered address lines, bounded to three in this profile.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "One non-empty address line."
            }
          },
          "locality": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Locality label recorded for this household address."
          },
          "postalCode": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32,
            "description": "Postal code as a string; leading zeroes are retained. Omitted when not recorded for this view."
          }
        },
        "examples": [
          {
            "addressLines": [
              "12 Example Street"
            ],
            "locality": "Example Town",
            "postalCode": "00120"
          }
        ]
      },
      "RecordReference": {
        "type": "object",
        "description": "Identity of a related Record. The field or deployment schema fixes the target Registry; otherwise registryId is required. An explicit registryId must agree with the fixed target. Concrete fields encode these constraints. When a target read is offered, the field binding identifies the target collection, contract and operation, and maps the referenced identifier to its input. Target reads follow the target Registry's published capabilities and access policy. Profiles declare any referential-integrity guarantees. Adopted domain reference forms may be used with declared target semantics.",
        "required": [
          "recordId"
        ],
        "properties": {
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "registryId": {
            "type": "string",
            "format": "iri",
            "minLength": 1,
            "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:",
            "description": "Stable absolute IRI of the target Registry; service endpoints are discovered separately."
          }
        },
        "examples": [
          {
            "recordId": "person_42",
            "registryId": "https://registry.example/registries/individuals"
          }
        ]
      },
      "IndividualReference": {
        "type": "object",
        "additionalProperties": false,
        "description": "Related Record in the fixed target Registry https://registry.example/registries/individuals. registryId may be omitted; an explicit value must match that target. This illustrative field binding resolves through the individuals collection: operation retrieveIndividual in https://registry.example/contracts/1.0.0-draft/examples/individual-registry.openapi.yaml, GET https://registry.example/v1/collections/individuals/records/{recordId}. Supply the referenced recordId as the path parameter, encoded as one segment. The illustrative target contract is not included in these artifacts; target access is evaluated separately.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RecordReference"
          }
        ],
        "properties": {
          "recordId": {
            "$ref": "#/components/schemas/RecordId"
          },
          "registryId": {
            "type": "string",
            "const": "https://registry.example/registries/individuals",
            "description": "The same target Registry already fixed by this field's schema."
          }
        },
        "examples": [
          {
            "recordId": "person_42"
          },
          {
            "recordId": "person_42",
            "registryId": "https://registry.example/registries/individuals"
          }
        ]
      },
      "HouseholdMembership": {
        "type": "object",
        "additionalProperties": false,
        "description": "Household-owned membership component. membershipId identifies it within the household; role describes the relationship to the referenced individual.",
        "required": [
          "membershipId",
          "role",
          "individualRef"
        ],
        "properties": {
          "membershipId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Stable component identifier unique within its household."
          },
          "role": {
            "type": "string",
            "enum": [
              "REFERENCE_PERSON",
              "MEMBER"
            ],
            "description": "REFERENCE_PERSON identifies the administrative reference person; MEMBER identifies another recorded member. This profile uses a closed vocabulary."
          },
          "individualRef": {
            "$ref": "#/components/schemas/IndividualReference"
          }
        },
        "examples": [
          {
            "membershipId": "membership_1",
            "role": "REFERENCE_PERSON",
            "individualRef": {
              "recordId": "person_42"
            }
          }
        ]
      },
      "HouseholdData": {
        "type": "object",
        "additionalProperties": false,
        "description": "Current household view with an embedded address and complete permitted membership components. Individual identities are carried as references.",
        "required": [
          "address",
          "memberships"
        ],
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "memberships": {
            "type": "array",
            "maxItems": 20,
            "description": "Complete permitted memberships ordered by membershipId in Unicode scalar order. This profile accepts up to 20 components; overflow fails the read.",
            "items": {
              "$ref": "#/components/schemas/HouseholdMembership"
            }
          }
        },
        "examples": [
          {
            "address": {
              "addressLines": [
                "12 Example Street"
              ],
              "locality": "Example Town"
            },
            "memberships": [
              {
                "membershipId": "membership_1",
                "role": "REFERENCE_PERSON",
                "individualRef": {
                  "recordId": "person_42"
                }
              }
            ]
          }
        ]
      },
      "HouseholdRecord": {
        "description": "Record in https://registry.example/registries/households with the typed household view and an extensible envelope.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Record"
          },
          {
            "type": "object",
            "description": "Concrete household data binding.",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/HouseholdData"
              }
            }
          }
        ],
        "examples": [
          {
            "recordId": "household_8",
            "data": {
              "address": {
                "addressLines": [
                  "12 Example Street"
                ],
                "locality": "Example Town"
              },
              "memberships": [
                {
                  "membershipId": "membership_1",
                  "role": "REFERENCE_PERSON",
                  "individualRef": {
                    "recordId": "person_42"
                  }
                }
              ]
            }
          }
        ]
      },
      "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."
              }
            }
          }
        ]
      }
    },
    "headers": {
      "CacheControl": {
        "description": "Protected reads and errors use no-store. Deployments may publish another caching policy for public or properly isolated representations while preserving authorisation.",
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      },
      "RetryAfter": {
        "description": "Delay in seconds or HTTP-date before retrying; authoritative over any advisory quota fields.",
        "schema": {
          "type": "string"
        },
        "example": "30"
      },
      "ApiCatalogLink": {
        "description": "Web Link with the api-catalog relation. Its target is this well-known URI or the publisher's API catalog document location.",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": ";\\s*rel\\s*=\\s*(?:api-catalog|\"(?:[^\"]*\\s)?api-catalog(?:\\s[^\"]*)?\")\\s*(?:[;,]|(?![\\s\\S]))"
        },
        "example": "</.well-known/api-catalog>; rel=\"api-catalog\""
      },
      "ApiCatalogETag": {
        "description": "Required HTTP representation validator for the API catalog linkset.",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "W/\"representation-7fa9\""
      },
      "WwwAuthenticate": {
        "description": "Bearer authentication challenge, with no record-specific facts.",
        "schema": {
          "type": "string"
        },
        "example": "Bearer"
      }
    },
    "responses": {
      "InternalError": {
        "description": "Request failure, including a source contract violation. Protected-existence policy precedes Record-specific diagnostics. Problem text excludes personal data, source counts and internal details; type is the sole machine identifier, with code and timestamp omitted.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/internal-error",
              "title": "Request could not be completed",
              "status": 500,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The service temporarily cannot accept work; no dependency topology is exposed.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/service-unavailable",
              "title": "Service temporarily unavailable",
              "status": 503,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "ApiCatalog": {
        "description": "The API catalog linkset. RFC 9727 recommends the Content-Type profile parameter \"https://www.rfc-editor.org/info/rfc9727\".",
        "headers": {
          "Link": {
            "$ref": "#/components/headers/ApiCatalogLink"
          },
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        },
        "content": {
          "application/linkset+json": {
            "schema": {
              "$ref": "#/components/schemas/ApiCatalog"
            },
            "example": {
              "linkset": [
                {
                  "anchor": "https://registry.example/",
                  "service-desc": [
                    {
                      "href": "https://registry.example/contracts/1.0.0-draft/openapi.yaml",
                      "type": "application/vnd.oai.openapi",
                      "title": "Digital Registries API"
                    }
                  ],
                  "service-meta": [
                    {
                      "href": "https://registry.example/catalog",
                      "type": "application/ld+json",
                      "title": "Registry metadata for the records Registry"
                    }
                  ]
                }
              ]
            }
          }
        }
      },
      "ApiCatalogNotModified": {
        "description": "The API catalog validator matches; the response is bodyless.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        }
      },
      "ApiCatalogHeaders": {
        "description": "The API catalog response headers, without a body.",
        "headers": {
          "Link": {
            "$ref": "#/components/headers/ApiCatalogLink"
          },
          "ETag": {
            "$ref": "#/components/headers/ApiCatalogETag"
          }
        }
      },
      "InternalErrorHeaders": {
        "description": "HEAD form of InternalError: the request could not be completed; the response is bodyless.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "ServiceUnavailableHeaders": {
        "description": "HEAD form of ServiceUnavailable: the service temporarily cannot accept work; the response is bodyless.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "BadRequest": {
        "description": "`bad-request` identifies malformed or structurally invalid input, including malformed\nJSON, missing or undeclared body members, and incorrect JSON types. It also identifies\ninvalid or unsupported query parameters or invalid pagination controls, such as an\nout-of-range `pageSize`. When `field-selection` is selected, empty, duplicate,\nincorrectly typed or out-of-bounds selections and unsupported `fields` query values\nuse `400`.\n\n`invalid-cursor` identifies a malformed, expired, or mismatched continuation,\nincluding changed path selectors such as a `revision-list` parent `recordId`, request\ncriteria, ordering, effective `pageSize`, field or temporal selection, or trusted purpose.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "malformed": {
                "value": {
                  "type": "https://govstack.global/problems/digital-registries/bad-request",
                  "title": "Invalid request",
                  "status": 400,
                  "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
                }
              },
              "structure": {
                "summary": "A required request member is missing",
                "value": {
                  "type": "https://govstack.global/problems/digital-registries/bad-request",
                  "title": "Invalid request",
                  "status": 400,
                  "detail": "The request is missing a required member.",
                  "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
                }
              },
              "cursor": {
                "value": {
                  "type": "https://govstack.global/problems/digital-registries/invalid-cursor",
                  "title": "Invalid continuation",
                  "status": 400,
                  "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid access token; the problem reveals no record existence.",
        "headers": {
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WwwAuthenticate"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/unauthorized",
              "title": "Authentication required",
              "status": 401,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Access to the operation or view is denied. Protected Record existence uses the 404 response.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/forbidden",
              "title": "Operation not permitted",
              "status": 403,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "RecordNotAvailable": {
        "description": "Absent Records, Records outside the declared collection and protected existence return the same status, problem type and public detail. Record-specific counts and hints are withheld.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/RecordNotAvailableProblem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/record-not-available",
              "title": "Record not available",
              "status": 404,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "NotAcceptable": {
        "description": "The requested response media type is not supported.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/not-acceptable",
              "title": "Response media type not supported",
              "status": 406,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "The gateway enforces its published quota scope and supplies Retry-After. Advisory RateLimit headers are gateway-owned.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/too-many-requests",
              "title": "Request rate exceeded",
              "status": 429,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "BadGateway": {
        "description": "The registry adapter received an unusable upstream response; no upstream details are exposed.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/bad-gateway",
              "title": "Upstream request failed",
              "status": 502,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      },
      "GatewayTimeout": {
        "description": "The upstream read exceeded its time budget; no partial or fabricated record is returned.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://govstack.global/problems/digital-registries/gateway-timeout",
              "title": "Upstream request timed out",
              "status": 504,
              "traceId": "6f1c3f0e2a9b4c8d7e6f5a4b3c2d1e0f"
            }
          }
        }
      }
    }
  }
}