curl --request PUT \
  --url https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}"

	payload := strings.NewReader("{\n  \"team\": \"checkout-squad\",\n  \"schema\": {\n    \"$id\": \"urn:acme:checkout:checkout.order_placed:1.0.0\",\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\": \"Order placed\",\n    \"type\": \"object\",\n    \"additionalProperties\": false,\n    \"required\": [\n      \"amount\",\n      \"currency\",\n      \"customerDocument\"\n    ],\n    \"properties\": {\n      \"amount\": {\n        \"type\": \"string\",\n        \"pattern\": \"^(0|[1-9][0-9]*)\\\\.[0-9]{2}$\"\n      },\n      \"currency\": {\n        \"type\": \"string\",\n        \"pattern\": \"^[A-Z]{3}$\"\n      },\n      \"customerDocument\": {\n        \"type\": \"string\",\n        \"x-sensitivity\": \"masked\",\n        \"x-mask\": \"document\"\n      }\n    },\n    \"$defs\": {\n      \"decimalAmount\": {\n        \"type\": \"string\",\n        \"pattern\": \"^(0|[1-9][0-9]*)\\\\.[0-9]{2}$\"\n      }\n    }\n  },\n  \"references\": [\n    {\n      \"type\": \"acme.order_id\",\n      \"cardinality\": \"one\",\n      \"required\": true,\n      \"correlation\": \"exact\"\n    },\n    {\n      \"type\": \"acme.customer_document\",\n      \"cardinality\": \"zero_or_one\",\n      \"required\": false,\n      \"correlation\": \"none\"\n    }\n  ],\n  \"compatibilityPolicy\": \"TRANSITIVE\",\n  \"hash\": \"sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

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.

PUT

contracts

{producer}

{namespace}

{type}

{schemaVersion}

curl --request PUT \
  --url https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}"

	payload := strings.NewReader("{\n  \"team\": \"checkout-squad\",\n  \"schema\": {\n    \"$id\": \"urn:acme:checkout:checkout.order_placed:1.0.0\",\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\": \"Order placed\",\n    \"type\": \"object\",\n    \"additionalProperties\": false,\n    \"required\": [\n      \"amount\",\n      \"currency\",\n      \"customerDocument\"\n    ],\n    \"properties\": {\n      \"amount\": {\n        \"type\": \"string\",\n        \"pattern\": \"^(0|[1-9][0-9]*)\\\\.[0-9]{2}$\"\n      },\n      \"currency\": {\n        \"type\": \"string\",\n        \"pattern\": \"^[A-Z]{3}$\"\n      },\n      \"customerDocument\": {\n        \"type\": \"string\",\n        \"x-sensitivity\": \"masked\",\n        \"x-mask\": \"document\"\n      }\n    },\n    \"$defs\": {\n      \"decimalAmount\": {\n        \"type\": \"string\",\n        \"pattern\": \"^(0|[1-9][0-9]*)\\\\.[0-9]{2}$\"\n      }\n    }\n  },\n  \"references\": [\n    {\n      \"type\": \"acme.order_id\",\n      \"cardinality\": \"one\",\n      \"required\": true,\n      \"correlation\": \"exact\"\n    },\n    {\n      \"type\": \"acme.customer_document\",\n      \"cardinality\": \"zero_or_one\",\n      \"required\": false,\n      \"correlation\": \"none\"\n    }\n  ],\n  \"compatibilityPolicy\": \"TRANSITIVE\",\n  \"hash\": \"sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

producer

string

required

Producer service that owns the fact type.

Example:

"checkout-api"

namespace

string

required

Namespace of the fact type.

Example:

"acme.checkout"

type

string

required

Fact type name.

Example:

"checkout.order_placed"

schemaVersion

string

required

Semantic version of the contract (major.minor.patch).

Example:

"1.0.0"

Body

application/json

hash

string

required

Content hash computed by the producer (the prefix sha256: plus 64 lowercase hex characters), verified by the server against the content sent.

Example:

"sha256:0000000000000000000000000000000000000000000000000000000000000000"

references

object[] | null

required

References facts of this type carry; scope and sensitivity come from each reference type and cannot be declared here.

Show child attributes

schema

any

required

Self-contained JSON Schema 2020-12 document that every fact payload of this type must satisfy.

team

string

required

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.

Example:

"checkout-squad"

compatibilityPolicy

string

How a new version is checked against the earlier versions of its major; optional, defaults to TRANSITIVE. Allowed values: TRANSITIVE.

Response

Identical content is already registered under this identity: a replay that changes nothing. The body is the stored contract version.

createdAt

string<date-time>

required

When this version was registered. RFC 3339, UTC.

hash

string

required

Content hash verified at registration (the prefix sha256: plus 64 hex characters); the authoritative integrity value of this version.

namespace

string

required

Namespace of the fact type, bound to the producer that registered in it first.

Example:

"acme.checkout"

producer

string

required

Producer service that owns the fact type.

Example:

"checkout-api"

references

object[] | null

required

References facts of this type carry, each with the scope and sensitivity its reference type had at registration.

Show child attributes

schema

any

required

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

string

required

Semantic version of this contract (major.minor.patch).

Example:

"1.0.0"

status

enum<string>

required

Lifecycle status: a DEPRECATED version refuses new facts and never returns to ACTIVE. Allowed values: ACTIVE, DEPRECATED.

Available options:

ACTIVE,

DEPRECATED

team

string

required

Owning team or squad, as registered; informational and audited, never an identity.

Example:

"checkout-squad"

type

string

required

Fact type name, chosen by the producer.

Example:

"checkout.order_placed"

compatibilityPolicy

enum<string>

How a new version is checked against the earlier versions of its major. Allowed values: TRANSITIVE.

Available options:

TRANSITIVE

Overview

Reference Types

Contracts

Facts

Flows

Error handling

Register a contract version

Authorizations

Path Parameters

Body

Response