curl --request PUT \
  --url https://api.example.com/v1/reference-types/{type} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": [],
  "sensitivity": "masked",
  "correlation": "exact",
  "description": "Customer tax document (CPF or CNPJ), stored masked",
  "mask": "document"
}
'

{
  "type": "acme.order_id",
  "scope": [
    "storeId"
  ],
  "sensitivity": "none",
  "correlation": "exact",
  "searchable": true,
  "description": "Order number assigned by the checkout service, unique within a store",
  "ownerIdentity": "acme/platform-deployer",
  "createdAt": "2026-10-19T12:00:00Z"
}

{
  "type": "acme.order_id",
  "scope": [
    "storeId"
  ],
  "sensitivity": "none",
  "correlation": "exact",
  "searchable": true,
  "description": "Order number assigned by the checkout service, unique within a store",
  "ownerIdentity": "acme/platform-deployer",
  "createdAt": "2026-10-19T12:00:00Z"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "SF-0022",
  "detail": "Reference types are immutable: use a new type name for a new meaning.",
  "errors": [
    {
      "location": "body.scope",
      "message": "registered with scope [storeId]; this request declares []"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 409,
  "title": "Conflict",
  "type": "https://errors.lerian.studio/v1/SF-0022"
}

{
  "code": "SF-0023",
  "detail": "Use a name whose first dotted segment is a reserved prefix of the deployment.",
  "errors": [
    {
      "location": "path.type",
      "message": "name outside every reserved prefix: \"shop.order_id\" does not start with a reserved prefix (acme)"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.lerian.studio/v1/SF-0023"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Register a reference type

Registers a reference type: a kind of business identifier facts carry, such as an order number, with its scope keys, correlation and sensitivity. Every contract declaring the type inherits its scope and sensitivity, and may declare exact correlation only on an exact type, so register it from your deploy pipeline before any contract uses it.

Rules

Idempotent: equal content answers 200 as a replay, whoever sends it.
A registered type is immutable, with one exception: mask: document can be added once to a type that has no mask, every other member equal. Omitting mask on a type that has one is a replay showing the stored mask; a mask can never be removed.
mask accepts only document, and never with sensitivity none or hashed.
The first dotted segment of the name must be one of the deployment’s reserved prefixes, and the token needs catalog:reserved.
ownerIdentity is the authenticated caller, recorded for audit.

Responses

201 registered; 200 replay, or the mask added.
403 SF-0014 missing contracts:read, contracts:write or catalog:reserved.
409 SF-0022 different content: errors[] lists every differing member, and nothing changes.
422 SF-0023 name outside every reserved prefix; SF-0092 invalid member.
503 SF-0094 retry later.

PUT

reference-types

{type}

curl --request PUT \
  --url https://api.example.com/v1/reference-types/{type} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": [],
  "sensitivity": "masked",
  "correlation": "exact",
  "description": "Customer tax document (CPF or CNPJ), stored masked",
  "mask": "document"
}
'

{
  "type": "acme.order_id",
  "scope": [
    "storeId"
  ],
  "sensitivity": "none",
  "correlation": "exact",
  "searchable": true,
  "description": "Order number assigned by the checkout service, unique within a store",
  "ownerIdentity": "acme/platform-deployer",
  "createdAt": "2026-10-19T12:00:00Z"
}

{
  "type": "acme.order_id",
  "scope": [
    "storeId"
  ],
  "sensitivity": "none",
  "correlation": "exact",
  "searchable": true,
  "description": "Order number assigned by the checkout service, unique within a store",
  "ownerIdentity": "acme/platform-deployer",
  "createdAt": "2026-10-19T12:00:00Z"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "SF-0022",
  "detail": "Reference types are immutable: use a new type name for a new meaning.",
  "errors": [
    {
      "location": "body.scope",
      "message": "registered with scope [storeId]; this request declares []"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 409,
  "title": "Conflict",
  "type": "https://errors.lerian.studio/v1/SF-0022"
}

{
  "code": "SF-0023",
  "detail": "Use a name whose first dotted segment is a reserved prefix of the deployment.",
  "errors": [
    {
      "location": "path.type",
      "message": "name outside every reserved prefix: \"shop.order_id\" does not start with a reserved prefix (acme)"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.lerian.studio/v1/SF-0023"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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

type

string

required

Reference type name: a dotted name whose first segment is a reserved prefix.

Example:

"acme.order_id"

Body

application/json

correlation

string

required

Whether references of this type link facts into flows; a contract may declare exact only on an exact type. Allowed values: exact, none.

description

string

required

What the reference identifies: 1 to 512 UTF-8 bytes, no control characters.

Example:

"Order number assigned by the checkout service, unique within a store"

scope

string[] | null

required

Scope keys that complete the reference identity, such as storeId; a set, stored sorted, duplicates refused.

mask

string

Display format, only with sensitivity masked or encrypted; set once, never removed (omitting it later is a replay). Allowed values: document.

searchable

boolean

Whether listFlowsByReference may list facts by this type; defaults to false.

sensitivity

string

Protection of values at rest and on reads, inherited by every contract that declares the type; defaults to none. Allowed values: none, masked, hashed, encrypted.

Response

The reference type is already registered with this content: a replay, whoever sends it, or the one-way addition of mask: document to a type that had no mask. The body is the stored type.

correlation

enum<string>

required

Whether references of this type link facts into flows. Allowed values: exact, none.

Available options:

exact,

none

createdAt

string<date-time>

required

When the type was registered. RFC 3339, UTC.

description

string

required

What the reference identifies, as registered.

ownerIdentity

string

required

Verified identity that registered the type, in the form owner/sub; recorded for audit only.

Example:

"acme/platform-deployer"

scope

string[] | null

required

Scope keys that complete the reference identity, sorted.

searchable

boolean

required

Whether listFlowsByReference can list facts by this type.

sensitivity

enum<string>

required

Protection of values at rest and on reads; see Sensitivity and protected values. Allowed values: none, masked, hashed, encrypted.

Available options:

none,

masked,

hashed,

encrypted

type

string

required

Reference type name.

Example:

"acme.order_id"

mask

enum<string>

Display format of the type; omitted when it has none. Allowed values: document.

Available options:

document

Overview

Reference Types

Contracts

Facts

Flows

Error handling

Register a reference type

Authorizations

Path Parameters

Body

Response