> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Register a contract version > Registers one version of a fact contract: the JSON Schema its facts must satisfy and the references they carry. Call it from your deploy pipeline, before the producer rolls out: the registration must succeed before facts are accepted. **Rules** - Idempotent: the same identity and content hash is a replay. - Published versions are immutable; a new minor or patch version must stay compatible. - The namespace starts with a reserved prefix, so every registration needs `catalog:reserved`. - The first registration binds the namespace to the calling producer service, recorded for audit. In multi-tenant mode the owner is the producer's service credential for the tenant. - Every declared reference type must be registered first. A reference declares only `type`, `cardinality`, `required` and `correlation`; scope and sensitivity come from the reference type and appear in the response. `exact` is refused on a `correlation: none` type. - `x-sensitivity` (`masked`, `hashed` or `encrypted`) only on a `type: string` property reached through `properties`; `x-mask: document` only beside `masked` or `encrypted`. **Responses** - `201` registered and `ACTIVE`; `200` identical replay. - `403` `SF-0005` the namespace is bound to another producer service; `SF-0014`, `SF-0027`, `SF-0028`. - `409` `SF-0002` same version, different content (`errors[]` lists differences and the bump); `SF-0003` incompatible minor or patch. - `422` `SF-0004`, `SF-0018`, `SF-0021`, `SF-0023`, `SF-0025`, `SF-0092`. - `503` `SF-0094` retry later. ## OpenAPI ````yaml /pt/openapi/v3-current/system-facts.yaml put /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion} openapi: 3.1.0 info: description: > ## What System Facts does System Facts is the shared record of what happened in your business flows. Each service that takes part in a flow (a producer) sends an immutable fact when a business moment happens, such as an order placed or a payment settled. System Facts validates every fact against the contract its producer registered, stores it once, and links the facts that share a reference into one flow. A reader can then ask what happened to order `ORD-2026-000123` and get every fact of that flow, from every producer, in one answer. A stored fact never changes: System Facts records and correlates, it does not edit history. ## Concepts - **Producer**: a service that sends facts, such as `checkout-api` or `payments-api`. - **Namespace**: the dotted name a producer sends its facts under, such as `acme.checkout`; the first service that registers a contract for a producer and namespace becomes their owner. - **Fact type**: the name of one kind of business moment, such as `checkout.order_placed`. - **Contract**: one semantic version of a fact type, with the JSON Schema of its payload and the references its facts carry. - **Reference type**: a named kind of business identifier, such as `acme.order_id`, registered once with its scope, correlation, sensitivity and searchable settings. - **Reference**: one identifier a fact carries: a reference type, a value and a scope, such as `acme.order_id` `ORD-2026-000123` with scope `storeId: store-sp-01`. - **Subject**: the business entity a fact is about, given as a type and an id, such as `checkout.order` `ORD-2026-000123`. - **Fact**: one immutable record that a business moment happened, sent as an envelope with its subject, its references and its payload (`data`). - **Flow**: the group of facts linked by their references, identified by a `flowAggregationId`. - **Correlation and merge**: a reference whose type has `correlation: exact` links its fact to every fact carrying the same reference, and when one fact links two flows they merge into one, the absorbed flow id still resolving to the surviving flow. - **Sensitivity**: how a reference value or a payload field is stored and shown: `none`, `masked`, `hashed` or `encrypted`. - **Searchable**: a reference type registered with `searchable: true` can be used to list every fact that carries it. ## Integrate in four steps 1. **Register the reference types** your facts carry with `registerReferenceType`, such as `acme.order_id` and `acme.payment_id`. 2. **Register a contract version** of each fact type with `registerContract` from your deploy pipeline, before the producer rolls out: the registration must succeed before facts are accepted. 3. **Send facts** with `ingestFact`, one envelope per business moment, using the producer's service credential for the tenant. 4. **Read the flows** with `getFlow` (by flow id), `findFlowByReference` (the one flow of a reference) or `listFlowsByReference` (every fact carrying a searchable reference). Every write is idempotent, so a producer can safely resend after a timeout. ## Authentication and permissions Every request except the public health probes sends `Authorization: Bearer `. Facts and flows belong to the tenant of the token; the reference-type and contract catalogs are shared by every tenant of the deployment. | Operation | Permission | |-----------|------------| | `getReferenceType`, `listReferenceTypes`, `getContract`, `listContractVersions`, `listContracts` | `contracts:read` | | `registerReferenceType`, `registerContract` | `contracts:read`, `contracts:write` and `catalog:reserved` (every catalog name sits under a reserved prefix) | | `deprecateContract` | `contracts:read` and `contracts:write`, plus `catalog:deprecate` for a version whose namespace you do not own | | `ingestFact` | `facts:read` and `facts:write` | | `getFlow`, `findFlowByReference`, `listFlowsByReference` | `facts:read`; with `facts:reveal`, encrypted values come back in clear form | ## Conventions - **Tenant**: always taken from the token, never from a path, a query parameter or a body. - **Idempotent writes**: a first registration or ingest answers `201`; the same request again answers `200` and changes nothing (`ingestFact` adds `duplicate: true`). - **Immutability**: a contract version, a reference type and a fact never change; different content under the same identity answers `409` (a reference type may only gain a display `mask`, once). - **Pagination**: a list answers one page and a `nextCursor`; send it back as the page's cursor parameter to read the next page, treat it as opaque, and stop when it is omitted. - **Timestamps**: RFC 3339 in UTC, such as `2026-10-19T14:32:10Z`. - **Size**: a fact envelope is at most 256 KiB by default; a larger one answers `413` SF-0012. - **Names**: the first dotted segment of every namespace and reference-type name must be one of the deployment's reserved prefixes (`REFERENCE_TYPE_RESERVED_PREFIXES`, default `lerian`); this document uses `acme`. - **Errors**: every error is `application/problem+json` (RFC 9457) with a stable `code`; the table below lists every code, when it answers and whether to retry. ## Sensitivity and protected values A reference type's `sensitivity` decides how its values are shown on reads, and a contract can mark payload fields the same way with `x-sensitivity`. - `none`: returned as sent. - `masked`: returned as `****` plus the last 4 characters of a value of 12 or more (`****` alone otherwise), and never in clear form. With `mask: document` it shows `***.456.789-**` for 11 digits and `**.345.678/0001-**` for 14; any other digit count is refused at ingest. - `hashed`: returned as the keyed digest `hmac-sha256:v1:`, and never in clear form. - `encrypted`: also stored sealed (AES-256-GCM); returned masked, or in clear form to a caller holding `facts:reveal`. Every class correlates exactly as `none` does, because matching starts from the clear value, and every stored digest is keyed, never a plain hash. A protected value comes back flagged `protected: true`, and protected payload fields are listed in `protectedFields`. To find a flow by a protected reference, always send the clear value: System Facts digests it and matches the stored digest. ## Error codes | Code | HTTP | Name | When | What to do | Retry | |------|------|------|------|------------|-------| | SF-0001 | 422 | Contract Not Registered | No contract version is registered for the producer, namespace, fact type and schema version the request names (a deprecated version answers SF-0019). | Register the contract version from your deploy pipeline, before the producer rolls out, then send the request again. | After a fix | | SF-0002 | 409 | Contract Content Conflict | A contract version with the same identity is already registered with different content. | Published versions are immutable: bump the schema version, using the differences listed in errors[] to choose the bump. | No | | SF-0003 | 409 | Incompatible Contract Change | The new minor or patch version is not compatible with the versions already registered for the fact type. | Fix the schema so it stays compatible, or register the change as a new major version. | No | | SF-0004 | 422 | Invalid Contract Schema | The contract schema is not a valid, self-contained JSON Schema, or a declared reference asks for a correlation its reference type does not allow. | Give the schema an absolute $id, keep every $ref inside the document (#/$defs), and fix the members listed in errors[]. | No | | SF-0005 | 403 | Namespace Not Owned | The namespace is bound to another producer service, or the fact is sent for a producer and namespace your service did not register. | Register and send only under a namespace your service owns, with the service credential of the owning producer. | No | | SF-0006 | 422 | Invalid Envelope | The fact envelope or the query is malformed: a member is missing, has the wrong format or is not part of the envelope, or a listing period is empty. | Fix the members listed in errors[] and send the request again. | No | | SF-0007 | 422 | Payload Contract Violation | The fact payload (data) does not validate against the JSON Schema of the registered contract. | Fix the payload fields listed in errors[] so they match the contract. | No | | SF-0008 | 422 | Reference Violation | The fact carries a reference the contract does not declare, a scope key its reference type does not declare, or more than five distinct exact-correlation references. | Send only the references and scope keys that the contract and its reference types declare. | No | | SF-0009 | 404 | Flow Not Found | No flow exists with the given flow identifier. | Verify the identifier: an identifier absorbed by a merge still resolves, an unknown one does not. | No | | SF-0010 | 404 | Reference Not Found | No flow carries a reference with the given type, value and scope. | Verify the reference type, the value and every scope key of the query. | No | | SF-0011 | 409 | Ambiguous Reference | More than one flow carries the reference, so the lookup cannot choose one. | Pick a flow from candidates[] and read it by its flowAggregationId. | No | | SF-0012 | 413 | Payload Too Large | The request body is larger than the configured size limit (256 KiB by default for a fact envelope). | Reduce the request body; for a fact, send a statement about an occurrence, not a document. | No | | SF-0013 | 401 | Unauthenticated | The request carries no valid bearer token. | Send a valid bearer token issued for the tenant; a producer uses its service credential. | After a fix | | SF-0014 | 403 | Unauthorized | The token is valid but lacks a permission the operation requires, such as catalog:reserved, which every catalog registration needs because every catalog name sits under a reserved prefix. | Ask the tenant administrator to grant the permission the operation lists, then send the request again. | After a fix | | SF-0015 | 500 | Internal Error | The service failed for a reason the request did not cause. | Retry later with the same request; writes are idempotent, so a retry is safe. | Yes, later | | SF-0016 | 409 | Fact Content Conflict | A fact with the same factId is already stored with different content. | Facts are immutable: send a changed occurrence as a new fact with a new factId, and check the producer that reused the identifier. | No | | SF-0017 | 404 | Contract Version Not Found | The catalog holds no contract version with the given producer, namespace, fact type and schema version. | Verify the four path segments, and register the version from your deploy pipeline if it is missing. | No | | SF-0018 | 422 | Contract Hash Mismatch | The content hash sent with the contract does not match the content it accompanies. | Recompute the content hash over the same content you are sending. | No | | SF-0019 | 422 | Contract Version Not Active | The contract version is deprecated and no longer accepts facts. | Send the fact against an active version of the same fact type. | No | | SF-0020 | 403 | Emission Not Enabled | An operator has disabled fact emission for this tenant. | Keep the fact pending and retry later; facts are accepted again once an operator enables emission. | Yes, later | | SF-0021 | 422 | Reference Type Not Registered | The contract declares a reference type the reference-type catalog does not hold; errors[] lists every missing type. | Have the owner register each reference type before you register the contract that uses it. | After a fix | | SF-0022 | 409 | Reference Type Conflict | A reference type with the same name is already registered with a different definition. | Reference types are immutable: use a new type name for a new meaning. | No | | SF-0023 | 422 | Name Outside Reserved Prefix | The namespace or reference-type name does not start with one of the reserved prefixes of the deployment. | Use a name whose first dotted segment is a reserved prefix of the deployment. | No | | SF-0024 | 422 | Reference Type Not Searchable | Flows are listed by a reference type that is not registered, or is registered with searchable: false. | List flows only by a reference type registered with searchable: true, or read the one flow of an exact reference with findFlowByReference. | No | | SF-0025 | 422 | Invalid Payload Field Sensitivity | An x-sensitivity or x-mask annotation in the contract schema is misplaced or carries an unknown value. | Declare x-sensitivity (masked, hashed or encrypted) only on a string property reached through properties, and x-mask only next to masked or encrypted. | No | | SF-0026 | 422 | Payload Protection Unavailable | The contract version the fact names carries malformed sensitivity annotations, so its payload cannot be protected and nothing is stored. | Register a corrected contract version and send the fact against it. | After a fix | | SF-0027 | 403 | Producer Credential Required | In multi-tenant mode, the credential does not name a producer service, so namespace ownership cannot be decided. | Use the service credential of the producer for the tenant, and rotate a credential issued before it carried the producer name. | After a fix | | SF-0028 | 403 | Undeclared Source Service | In multi-tenant mode, the service credential of the producer was created without naming its producer service. | Ask the tenant administrator to recreate the credential with its producer service set; rotating the same credential does not fix this. | After a fix | | SF-0090 | 400 | Invalid Request | The request is malformed, such as a body that is not valid JSON. | Fix the request syntax and send it again. | No | | SF-0091 | 404 | Not Found | The requested resource does not exist, such as an unknown reference type or path. | Verify the path and the resource name; a reference type exists only after its owner registers it. | No | | SF-0092 | 422 | Unprocessable Request | The request does not match the request schema of the operation, such as an unexpected member or an invalid cursor. | Fix the members listed in errors[] so the request matches the schema of the operation. | No | | SF-0093 | 409 | Conflict | The request conflicts with the current state of a resource. | Read the resource again and send a request consistent with its current state. | No | | SF-0094 | 503 | Service Unavailable | The service cannot answer right now: it is starting, the authorization service is temporarily unavailable, or the correlation keys of the fact stayed busy. | Retry later with the same request, honoring Retry-After when the response carries it. | Yes, later | | SF-0095 | 429 | Rate Limit Exceeded | The caller sent more requests than the rate limit allows. | Wait for the Retry-After delay before the next request. | Yes, later | | SF-0096 | 400 | Request Failed | The request was refused for a client-side reason no more specific code describes; the response keeps the HTTP status of that reason, such as 405 or 415. | Read the detail member, fix the request and send it again. | No | title: System Facts API version: v1.0.1 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- The catalog of business identifiers a fact can carry, such as `acme.order_id`. Register each type once, before any contract declares it: its scope, correlation and sensitivity apply to every contract that uses it. name: Reference Types - description: >- Versioned contracts of each fact type: the payload JSON Schema and the references its facts carry. Register a version from your deploy pipeline before the producer rolls out, read it back, list the catalog, and deprecate a version you no longer send. name: Contracts - description: >- Send one immutable fact per business moment. Each fact is validated against its active contract version and linked to a flow through its references. name: Facts - description: >- Read what happened: one flow by its id, the flow of one reference, or every fact carrying a searchable reference. Protected values come back in their protected form unless you hold `facts:reveal`. name: Flows paths: /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}: put: tags: - Contracts summary: Register a contract version description: >- Registers one version of a fact contract: the JSON Schema its facts must satisfy and the references they carry. Call it from your deploy pipeline, before the producer rolls out: the registration must succeed before facts are accepted. **Rules** - Idempotent: the same identity and content hash is a replay. - Published versions are immutable; a new minor or patch version must stay compatible. - The namespace starts with a reserved prefix, so every registration needs `catalog:reserved`. - The first registration binds the namespace to the calling producer service, recorded for audit. In multi-tenant mode the owner is the producer's service credential for the tenant. - Every declared reference type must be registered first. A reference declares only `type`, `cardinality`, `required` and `correlation`; scope and sensitivity come from the reference type and appear in the response. `exact` is refused on a `correlation: none` type. - `x-sensitivity` (`masked`, `hashed` or `encrypted`) only on a `type: string` property reached through `properties`; `x-mask: document` only beside `masked` or `encrypted`. **Responses** - `201` registered and `ACTIVE`; `200` identical replay. - `403` `SF-0005` the namespace is bound to another producer service; `SF-0014`, `SF-0027`, `SF-0028`. - `409` `SF-0002` same version, different content (`errors[]` lists differences and the bump); `SF-0003` incompatible minor or patch. - `422` `SF-0004`, `SF-0018`, `SF-0021`, `SF-0023`, `SF-0025`, `SF-0092`. - `503` `SF-0094` retry later. operationId: registerContract parameters: - description: Producer service that owns the fact type. in: path name: producer required: true schema: description: Producer service that owns the fact type. examples: - checkout-api type: string - description: Namespace of the fact type. in: path name: namespace required: true schema: description: Namespace of the fact type. examples: - acme.checkout type: string - description: Fact type name. in: path name: type required: true schema: description: Fact type name. examples: - checkout.order_placed type: string - description: Semantic version of the contract (major.minor.patch). in: path name: schemaVersion required: true schema: description: Semantic version of the contract (major.minor.patch). examples: - 1.0.0 type: string requestBody: content: application/json: examples: orderPlaced: summary: checkout-api registers checkout.order_placed 1.0.0 value: team: checkout-squad schema: $id: urn:acme:checkout:checkout.order_placed:1.0.0 $schema: https://json-schema.org/draft/2020-12/schema title: Order placed type: object additionalProperties: false required: - amount - currency - customerDocument properties: amount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ currency: type: string pattern: ^[A-Z]{3}$ customerDocument: type: string x-sensitivity: masked x-mask: document $defs: decimalAmount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ references: - type: acme.order_id cardinality: one required: true correlation: exact - type: acme.customer_document cardinality: zero_or_one required: false correlation: none compatibilityPolicy: TRANSITIVE hash: >- sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c schema: $ref: '#/components/schemas/ContractRegistrationBody' required: true responses: '200': content: application/json: examples: replay: summary: >- The same content sent again on the next rollout changes nothing value: producer: checkout-api namespace: acme.checkout type: checkout.order_placed schemaVersion: 1.0.0 team: checkout-squad schema: $id: urn:acme:checkout:checkout.order_placed:1.0.0 $schema: https://json-schema.org/draft/2020-12/schema title: Order placed type: object additionalProperties: false required: - amount - currency - customerDocument properties: amount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ currency: type: string pattern: ^[A-Z]{3}$ customerDocument: type: string x-sensitivity: masked x-mask: document $defs: decimalAmount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ references: - type: acme.order_id cardinality: one required: true correlation: exact scope: - storeId sensitivity: none - type: acme.customer_document cardinality: zero_or_one required: false correlation: none scope: [] sensitivity: masked mask: document compatibilityPolicy: TRANSITIVE hash: >- sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c status: ACTIVE createdAt: '2026-10-19T12:00:00Z' schema: $ref: '#/components/schemas/ContractBody' description: >- Identical content is already registered under this identity: a replay that changes nothing. The body is the stored contract version. '201': content: application/json: examples: firstRegistration: summary: The order placed contract is registered and ACTIVE value: producer: checkout-api namespace: acme.checkout type: checkout.order_placed schemaVersion: 1.0.0 team: checkout-squad schema: $id: urn:acme:checkout:checkout.order_placed:1.0.0 $schema: https://json-schema.org/draft/2020-12/schema title: Order placed type: object additionalProperties: false required: - amount - currency - customerDocument properties: amount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ currency: type: string pattern: ^[A-Z]{3}$ customerDocument: type: string x-sensitivity: masked x-mask: document $defs: decimalAmount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ references: - type: acme.order_id cardinality: one required: true correlation: exact scope: - storeId sensitivity: none - type: acme.customer_document cardinality: zero_or_one required: false correlation: none scope: [] sensitivity: masked mask: document compatibilityPolicy: TRANSITIVE hash: >- sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c status: ACTIVE createdAt: '2026-10-19T12:00:00Z' schema: $ref: '#/components/schemas/ContractBody' description: >- The contract version is registered and `ACTIVE`: facts can be sent against it. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: '`SF-0013` The request carries no valid bearer token.' '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0005` The namespace is bound to another producer service. `SF-0014` The token lacks `contracts:read` or `contracts:write`, or lacks `catalog:reserved`, which every registration needs. `SF-0027` In multi-tenant mode, the credential is not the producer's service credential for the tenant. `SF-0028` That credential was created without naming its producer service. '409': content: application/problem+json: examples: contentConflict: description: >- Sent: the orderPlaced request body with the `pattern` of `$defs/decimalAmount` changed to `^(0|[1-9][0-9]*)\.[0-9]{1,2}$` and its hash recomputed over that content. summary: Version 1.0.0 sent again with a different amount pattern value: code: SF-0002 detail: >- Published versions are immutable: bump the schema version, using the differences listed in errors[] to choose the bump. errors: - location: body.hash message: >- published sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c / submitted sha256:eac98ee058f9be8cbce25cdd94e99e06d39f8a4bf013843c1fc745dc19bcc435 - location: body.schema/$defs/decimalAmount/pattern message: >- the value changed from "^(0|[1-9][0-9]*)\\.[0-9]{2}$" to "^(0|[1-9][0-9]*)\\.[0-9]{1,2}$" - location: body message: 'incompatible difference: register it as a new MAJOR' instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 409 title: Conflict type: https://errors.lerian.studio/v1/SF-0002 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0002` This identity is registered with different content: `errors[]` lists the published and submitted hashes at `body.hash`, then each structural difference at its pointer (at most 50, then a count of the rest), then the bump to make: a new major for an incompatible difference, a new minor for an addition, a patch or a deterministic build when only annotations or number spelling differ. `SF-0003` The new minor or patch version is incompatible with the previous one: fix the schema or bump the major version. '422': content: application/problem+json: examples: hashMismatch: description: >- Sent: the orderPlaced request body with its hash set to sha256:3f786850e387550fdab836ed7e6dc881de23001b8f5d8a2f1c0f3c9d2a4e5b67, a digest of another content. The answer names the digest that content hashes to. summary: The hash sent does not describe the content sent value: code: SF-0018 detail: >- Recompute the content hash over the same content you are sending. errors: - location: body.hash message: >- content hash does not match contract content: the submitted content hashes to sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0018 referenceTypeMissing: summary: >- The customer document type is declared before it is registered value: code: SF-0021 detail: >- Have the owner register each reference type before you register the contract that uses it. errors: - location: body.references[1].type message: >- reference type "acme.customer_document" is not registered in the reference-type catalog; its owner registers it before any contract declares it instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0021 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0004` The schema is not a valid, self-contained JSON Schema 2020-12 document (such as a missing absolute `$id`, an external `$ref` or a schema over the size limit), or a reference declares `exact` correlation on a `correlation: none` type (at `body.references[i].correlation`). `SF-0018` The content hash does not match the content sent. `SF-0021` A declared reference type is not registered; every missing type is listed. `SF-0023` The namespace does not start with a reserved prefix (at `path.namespace`). `SF-0025` An `x-sensitivity` or `x-mask` annotation is misplaced or has an unsupported value; one `errors[]` entry per location, at most 50 listed, then one entry counting the rest. `SF-0092` A path segment or body member is malformed, such as a schema version that is not `major.minor.patch`, a hash that is not `sha256:` plus 64 hex characters, or a repeated reference type; or the body does not match the request schema, such as a reference still sending `scope`, `sensitivity` or `normalization`. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0015` The service failed for a reason the request did not cause: retry later. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0094` The service is starting, the authorization service is temporarily unavailable, or it could not answer the `catalog:reserved` check: retry later. security: - BearerAuth: [] components: schemas: ContractRegistrationBody: additionalProperties: false properties: compatibilityPolicy: description: >- How a new version is checked against the earlier versions of its major; optional, defaults to `TRANSITIVE`. Allowed values: `TRANSITIVE`. type: string hash: description: >- Content hash computed by the producer (the prefix sha256: plus 64 lowercase hex characters), verified by the server against the content sent. examples: - >- sha256:0000000000000000000000000000000000000000000000000000000000000000 type: string references: description: >- References facts of this type carry; scope and sensitivity come from each reference type and cannot be declared here. items: $ref: '#/components/schemas/ReferenceDeclarationBody' type: - array - 'null' schema: description: >- Self-contained JSON Schema 2020-12 document that every fact payload of this type must satisfy. team: description: >- Owning team or squad, audited, never an identity: 1 to 128 UTF-8 bytes (accented letters take two or more), no surrounding whitespace or control characters. examples: - checkout-squad type: string required: - team - schema - references - hash type: object ContractBody: additionalProperties: false properties: compatibilityPolicy: description: >- How a new version is checked against the earlier versions of its major. Allowed values: `TRANSITIVE`. enum: - TRANSITIVE type: string createdAt: description: When this version was registered. RFC 3339, UTC. format: date-time type: string hash: description: >- Content hash verified at registration (the prefix sha256: plus 64 hex characters); the authoritative integrity value of this version. type: string namespace: description: >- Namespace of the fact type, bound to the producer that registered in it first. examples: - acme.checkout type: string producer: description: Producer service that owns the fact type. examples: - checkout-api type: string references: description: >- References facts of this type carry, each with the scope and sensitivity its reference type had at registration. items: $ref: '#/components/schemas/ReferenceSpecBody' type: - array - 'null' schema: description: >- Payload schema as stored: member order, whitespace and number spelling may differ from what was sent, so check integrity with `hash`, never by rehashing this. schemaVersion: description: Semantic version of this contract (major.minor.patch). examples: - 1.0.0 type: string status: description: >- Lifecycle status: a `DEPRECATED` version refuses new facts and never returns to `ACTIVE`. Allowed values: `ACTIVE`, `DEPRECATED`. enum: - ACTIVE - DEPRECATED type: string team: description: >- Owning team or squad, as registered; informational and audited, never an identity. examples: - checkout-squad type: string type: description: Fact type name, chosen by the producer. examples: - checkout.order_placed type: string required: - producer - namespace - type - schemaVersion - team - schema - references - hash - status - createdAt type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- Identifier of this occurrence of the problem: the request's trace id (32 lowercase hex characters), to quote when asking for support. examples: - 0199c1f07a3e7b219d443c1f8e2a9b01 type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ReferenceDeclarationBody: additionalProperties: false properties: cardinality: description: >- How many times the reference may appear on one fact. Allowed values: `one`, `zero_or_one`, `one_or_many`, `zero_or_many`. type: string correlation: description: >- Whether the reference creates and merges flows (`exact`) or is only recorded (`none`); `exact` needs an `exact` reference type. Allowed values: `exact`, `none`. type: string required: description: Whether every fact of this type must carry the reference. type: boolean type: description: Name of a registered reference type that facts of this type carry. examples: - acme.order_id type: string required: - type - cardinality - required - correlation type: object ReferenceSpecBody: additionalProperties: false properties: cardinality: description: >- How many times the reference may appear on one fact. Allowed values: `one`, `zero_or_one`, `one_or_many`, `zero_or_many`. enum: - one - zero_or_one - one_or_many - zero_or_many type: string correlation: description: >- Whether the reference creates and merges flows (`exact`) or is only recorded (`none`). Allowed values: `exact`, `none`. enum: - exact - none type: string mask: description: >- Display format of a `masked` or `encrypted` type, frozen when this version was registered; omitted when the type had none. Allowed values: `document`. enum: - document type: string required: description: Whether every fact of this type must carry the reference. type: boolean scope: description: >- Scope keys that complete the reference identity, sorted, as the reference type's owner fixed them. items: type: string type: - array - 'null' sensitivity: description: >- Protection of values at rest and on reads, fixed by the type's owner; see Sensitivity and protected values. Allowed values: `none`, `masked`, `hashed`, `encrypted`. enum: - none - masked - hashed - encrypted type: string type: description: Name of the reference type. examples: - acme.order_id type: string required: - type - cardinality - required - correlation - scope - sensitivity type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: >- JWT issued by the identity provider. A producer calls with a service credential issued for the tenant it sends facts for; a reader calls with a user token or a service credential. The tenant is always taken from the token, never from the request path, query or body. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.