Registry Notary reference

Use this page to look up the Registry Notary config schema, HTTP routes, federation config, disclosure modes, source connector options, and audit event fields. This reference is hand-maintained; the authoritative contract is the upstream repo. The OpenAPI contract is generated: cargo run -p registry-notary-bin -- openapi. (README)

HTTP routes

/healthz and /ready are public probe routes. Other routes require authentication through static API-key/bearer-token mode or OIDC mode.

Method	Path	Purpose
GET	/healthz	Return the liveness probe. Public.
GET	/ready	Return the readiness probe. Public.
POST	/admin/reload	Admin-scoped no-op reload endpoint. Returns reloaded: false in the standalone router.
GET	/openapi.json	Return the Registry Notary OpenAPI 3.1.0 document.
GET	/.well-known/evidence-service	Return the service capabilities document.
GET	/.well-known/evidence/jwks.json	Return the public issuer verification keys as a JWKS.
GET	/claims	List claim definitions visible to the authenticated principal.
GET	/claims/{claim_id}	Return one claim definition by ID. Returns 404 if not found.
GET	/formats	List supported output format media types.
POST	/claims/evaluate	Evaluate one or more claims for a single subject.
POST	/claims/batch-evaluate	Evaluate one or more claims for multiple subjects inline. Accepts Idempotency-Key header.
POST	/evidence/render	Render a stored evaluation in a requested format and disclosure level.
POST	/credentials/issue	Issue an SD-JWT VC credential from a stored evaluation.
GET	/.well-known/openid-credential-issuer	Return the OID4VCI Credential Issuer Metadata document.
GET	/oid4vci/credential-offer	Return a CredentialOffer for one or more configured credential configurations.
POST	/oid4vci/nonce	Mint a fresh c_nonce for the holder proof of possession JWT.
POST	/oid4vci/credential	Issue an SD-JWT VC credential bound to the holder’s did:jwk.
POST	/federation/v1/evaluations	Evaluate one configured federation profile for a trusted peer. Mounted only when federation.enabled is true.

HTTP status codes used across routes:

• 200: success.
• 400: invalid request body or a disclosure widening attempt.
• 401: missing or invalid credential.
• 403: principal is not authorized for the requested claim, purpose, disclosure mode, or format.
• 404: claim ID or evaluation ID not found.
• 503: a source registry is unreachable. POST /claims/evaluate returns this with code: source.unavailable in the application/problem+json body.

Federated evaluation uses application/jwt request and response bodies on success. Transport denials use application/problem+json.

Example response body for POST /claims/evaluate (200):

{
  "results": [
    {
      "claim_id": "farmer-under-4ha",
      "claim_version": "2026-05",
      "subject_ref": "person-1",
      "subject_type": "person",
      "satisfied": true,
      "value": true,
      "disclosure": "predicate",
      "format": "application/vnd.registry-notary.claim-result+json",
      "evaluation_id": "01HX7Y5F2WAJ7ZP0Q4M5K9E8NC",
      "issued_at": "2026-05-24T12:00:00Z",
      "expires_at": "2026-05-25T12:00:00Z",
      "provenance": {
        "computed_by": "demo.registry-notary",
        "source_count": 1,
        "source_versions": {}
      }
    }
  ]
}

POST /claims/batch-evaluate wraps each subject’s evaluations in an items[].claim_results[] envelope; the per-claim entries follow the same shape.

Claim config schema

Fields of ClaimDefinition.

Field	Required	Type	Default	Notes
id	Yes	string	None	Stable claim identifier. Must not be empty.
title	Yes	string	None	Human-readable label.
version	Yes	string	None	API version string (for example, 2026-05).
subject_type	Yes	string	None	Kind of entity (for example, person).
value.type	No	string	""	Value type: date, number, boolean, or string.
value.unit	No	string	None	Optional unit (for example, hectare).
inputs	No	array	[]	Named parameters the caller must supply. Each has name and type.
depends_on	No	array	[]	IDs of claims that must be evaluated before this one. Must form a DAG.
source_bindings	No	map	{}	Map of binding name to SourceBindingConfig. Required if rule reads a source.
rule	Yes	object	None	Evaluation rule. See Rule types.
operations.evaluate.enabled	No	bool	true	Whether POST /claims/evaluate is enabled for this claim.
operations.batch_evaluate.enabled	No	bool	false	Whether POST /claims/batch-evaluate is enabled.
operations.batch_evaluate.max_subjects	No	number	100	Per-claim subject limit for batch evaluation.
disclosure.default	No	string	redacted	Default disclosure mode.
disclosure.allowed	No	array	["redacted"]	Modes the caller may request.
disclosure.downgrade	No	string	deny	Action when caller requests a disallowed mode.
formats	No	array	[]	Allowed output media types.
credential_profiles	No	array	[]	Credential profile IDs that may issue from this claim.
cccev.requirement_type	No	string	None	CCCEV requirement type annotation for JSON-LD rendering.
oots.enabled	No	bool	None	Once-Only Technical System config. Serves as metadata annotations only; not yet enforced.

ClaimDefinition fields, narrative form

The same fields described in prose. Use this form when reading the YAML config side by side with the evaluation engine section of the overview.

• id: stable string identifier used in API requests.
• title: human-readable label.
• version: a date-based API version string (for example, 2026-05).
• subject_type: the kind of entity being evaluated (for example, person).
• value: the type and optional unit of the claim’s raw value (for example, type: number, unit: hectare).
• inputs: named parameters the caller must supply (for example, a subject_id string).
• depends_on: ordered list of claim IDs whose results must be available before this claim evaluates. The config validator rejects dependency cycles at startup.
• source_bindings: a map of binding names to source binding entries, each specifying which connector and connection to use, the dataset and entity name, a lookup strategy, and the fields to extract.
• rule: the evaluation rule. See Rule types.
• disclosure: the per-claim disclosure policy. See Disclosure policy modes.
• formats: the output media types this claim can produce.
• credential_profiles: which credential profiles may issue a credential from this claim.
• cccev: optional Core Criterion and Core Evidence Vocabulary (CCCEV) annotation (for example, requirement_type: InformationRequirement).
• oots: optional Once-Only Technical System (OOTS) annotation. Fields include enabled, requirement (an IRI), reference_framework, evidence_type_classification, evidence_type_list, languages, and authentication_level_of_assurance. When oots.enabled is true, the claim summary API publishes the block and the CCCEV renderer uses oots.requirement as the cccev:supportsRequirement IRI. There is no dedicated OOTS transport or external OOTS endpoint at this version; the fields serve as metadata annotations only; not yet enforced.

Rule types

Type	Required fields	Behavior
extract	source, field	Reads field from the source binding named source. Returns the raw value.
exists	source	Returns true if the source binding found at least one record, false otherwise.
cel	expression, optionally bindings	Evaluates a CEL expression. bindings.claims maps variable names to upstream claim IDs. bindings.vars supplies static values.
plugin	plugin	Declares an external plugin name. Not yet implemented at reviewed commit.

Source binding config

Fields of SourceBindingConfig.

Field	Required	Notes
connector	Yes	registry_data_api or dci.
connection	Yes	Key in evidence.source_connections.
required_scope	No	Scope the authenticated principal must carry to use this binding.
dataset	Yes	Logical dataset name passed to the source connector.
entity	Yes	Logical entity name passed to the source connector.
lookup.input	Yes	Name from inputs used as the lookup key value.
lookup.field	Yes	Field name on the source entity to match against.
lookup.op	No	Comparison operator. Default: eq.
lookup.cardinality	No	Expected record count. Default: one.
fields.<name>.field	Yes	Source field name to extract.
fields.<name>.type	No	Expected type: date, number, boolean, string.
fields.<name>.unit	No	Optional unit.
fields.<name>.required	No	If true, evaluation fails when the field is absent.

Source connector types

Registry Data API

• Kind: Registry Data API
• YAML value: registry_data_api
• Protocol: HTTP POST to {base_url}/{dataset}/{entity} with query parameters
• Request shape: Standard Registry Data API query body

SP DCI

• Kind: SP DCI
• YAML value: dci
• Protocol: HTTP POST to {base_url}{dci.search_path}
• Request shape: DCI registry/sync/search-shaped request body with query_type and subject ID

SP DCI connector config fields under source_connections.<id>.dci:

Field	Default
search_path	/registry/sync/search
sender_id	registry-notary
query_type	idtype-value
records_path	/message/search_response/0/data/reg_records
max_results	2
registry_type	None
record_type	None
field_paths	{} (map of local field name to JSON path in record)

Disclosure policy modes

Mode	YAML value	What the caller receives
Full value	value	The evaluated claim value (date, number, boolean, or string).
Predicate	predicate	Boolean satisfaction result only. The underlying value is not returned.
Redacted	redacted	No value and no predicate. The result slot is present but carries no data.

Downgrade strategies (disclosure.downgrade):

Strategy	YAML value	Behavior when disallowed mode is requested
Deny	deny	Returns DisclosureNotAllowed error. Default.
Default	default	Falls back to disclosure.default.
Redacted	redacted	Forces the result to Redacted.

Output media types

Registry Notary supports three output media types: native claim result JSON (application/vnd.registry-notary.claim-result+json), CCCEV JSON-LD (application/ld+json; profile="cccev"), and SD-JWT VC (application/dc+sd-jwt, only via /credentials/issue).

Credential profile config

Fields of CredentialProfileConfig.

Field	Required	Default	Notes
format	Yes	None	Must be application/dc+sd-jwt.
issuer	Yes	None	Issuer DID (for example, did:web:example.gov).
issuer_key_env	Yes	None	Name of the environment variable holding the Ed25519 OKP JWK.
issuer_kid	No	None	Key ID to include in the credential header.
vct	Yes	None	Verifiable Credential Type URI.
validity_seconds	No	7776000 (90 days)	Credential validity window.
holder_binding.mode	No	None	Binding mode. Currently did.
holder_binding.proof_of_possession	No	None	required enforces holder proof. Only did:jwk is supported when set to required.
holder_binding.allowed_did_methods	No	[]	Permitted DID methods for holder binding.
allowed_claims	No	[]	Claim IDs that this profile may issue.
disclosure.allowed	No	None	Disclosure modes permitted in issued credentials.

OID4VCI routes

Registry Notary emits OpenID for Verifiable Credential Issuance (OID4VCI) Draft 13 compatible routes when oid4vci.enabled is true in config. The wider OID4VCI spec alignment is aligns_with; the four routes below emit the wire shapes the spec defines.

GET /.well-known/openid-credential-issuer

Returns the Credential Issuer Metadata document.

• Auth: public.
• Response media type: application/json.
• Response body fields: credential_issuer, credential_endpoint, nonce_endpoint (optional), authorization_servers (optional), credential_configurations_supported (map of configuration id to metadata, including format, scope, cryptographic_binding_methods_supported, credential_signing_alg_values_supported, proof_types_supported, display, vct).

GET /oid4vci/credential-offer

Returns a CredentialOffer for one or all configured credential configurations.

• Auth: public.
• Query parameter: credential_configuration_id (optional). If omitted, the offer lists every configuration the server knows about.
• Response media type: application/json.
• Response body fields: credential_issuer, credential_configuration_ids, grants (currently the authorization_code grant with an issuer_state nonce).

POST /oid4vci/nonce

Mints a fresh c_nonce used by the holder when signing the proof-of-possession JWT.

• Auth: public. Only enabled when oid4vci.nonce.enabled is true.
• Request media type: application/json (body may be empty).
• Request body fields: credential_configuration_id (optional).
• Response media type: application/json.
• Response body fields: c_nonce, c_nonce_expires_in (seconds).

POST /oid4vci/credential

Issues an SD-JWT VC credential bound to the holder’s did:jwk.

• Auth: bearer access token sourced from the configured authorization server (for example, eSignet). Self-attestation principals only.
• Request media type: application/json.
• Request body fields: format (must be dc+sd-jwt), credential_configuration_id or credential_identifier, proof.proof_type (must be jwt), proof.jwt (signed with the holder’s did:jwk; aud equals the configured credential_issuer; nonce is the value from POST /oid4vci/nonce).
• Response media type: application/json.
• Response body fields: credential (the SD-JWT VC as a single compact-serialization string), c_nonce (next nonce, optional), c_nonce_expires_in (optional).

Proof JWT validation comes from Registry Platform OID4VCI helpers; the credential signing key is the same Ed25519 OKP JWK loaded by the credential profile that backs the configuration. Holder binding requires did:jwk; other DID methods are rejected at config validation.

Federated evaluation route

POST /federation/v1/evaluations accepts one compact JWS request and returns one signed evaluation response. The route is not mounted unless federation.enabled is true.

Request requirements:

• Request media type: application/jwt.
• Compact JWS serialization only.
• Header fields: typ = registry-notary-request+jwt, alg = EdDSA, and a kid found in the configured peer JWKS.
• Required payload claims: iss, sub, aud, iat, nbf, exp, jti, protocol, action, profile, purpose, and request.
• protocol must be registry-notary-federation/v0.1.
• action must be evaluate.
• purpose must be an HTTPS URI allowed by the peer policy.
• jti must be a ULID string and is retained in the replay store until exp + clock_leeway.

Response shape:

• Success media type: application/jwt.
• Header fields: typ = registry-notary-response+jwt, alg = EdDSA, and serving Notary kid.
• Payload fields include iss, sub, aud, iat, nbf, exp, jti, request_jti, protocol, action, profile, and either result or error.
• result.subject_ref.hash is a pairwise hmac-sha256: handle. The raw subject identifier is not returned.
• Stale source observations return HTTP 200 with a signed top-level error object.
• Replay, policy, signature, body-limit, and audience failures return unsigned RFC 7807-style denial bodies.

The serving Notary validates the request before source reads. Audit write failure prevents a successful signed response.

Audit event shape

EvidenceAuditEvent fields. Events are serialized as Registry Platform audit envelopes in JSON Lines (JSONL) to stdout or a file.

Field	Type	Notes
event_id	string	Unique identifier for this audit record.
occurred_at	string	RFC 3339 timestamp.
principal_id	string	Identifier of the authenticated caller.
decision	string	Outcome of the request.
method	string	HTTP method.
path	string	Request path.
status	number	HTTP response status code.
verification_id	string or null	Verification context identifier. May be omitted for redacted results.
claim_hash	string or null	Hash of the evaluated claim set. May be omitted for redacted results.
row_count	number or null	Number of source records read.
error_code	string or null	Error code if the request failed.
federation_peer_id_hash	string or null	Hashed peer node id for federated evaluation audit records.
federation_issuer	string or null	Requesting peer issuer for federated evaluation audit records.
federation_profile	string or null	Evaluation profile id used for federated evaluation.
federation_purpose	string or null	Purpose URI accepted for federated evaluation.
federation_request_jti	string or null	Request JWT jti for replay and audit correlation.
federation_subject_ref_hash	string or null	Pairwise subject reference hash emitted in the signed response.

Top-level config sections

StandaloneRegistryNotaryConfig top-level keys.

server

Default bind: 127.0.0.1:8081. The standalone demo config in demo/config/registry-notary.yaml overrides this to 127.0.0.1:4255. The Lab topology overrides it to 0.0.0.0:8080 inside the container (mapped to host ports 4321-4324).

auth

Key	Default	Notes
mode	api_key	api_key for static API key and bearer-token lists, or oidc for inbound bearer JWT verification.
api_keys	[]	Static credentials array of {id, hash_env, scopes}. hash_env names an env var containing a sha256:<64 hex> fingerprint.
bearer_tokens	[]	Static bearer credentials array of {id, hash_env, scopes}.
oidc	None	Required when mode: oidc; see OIDC auth config.

OIDC auth config

Fields under auth.oidc.

Key	Default	Notes
issuer	None	Expected JWT iss. Required.
jwks_uri	None	JWKS endpoint used by the platform OIDC verifier. Required.
audiences	[]	Accepted JWT audiences. At least one is required.
allowed_clients	[]	Optional allowed azp/client identifiers.
allowed_algorithms	["EdDSA"]	Accepted JOSE algorithms.
allowed_typ	["JWT"]	Accepted JOSE typ headers.
scope_claim	scope	Claim used to extract scopes.
scope_separator	space	Single-character scope separator.
scope_map	{}	Optional mapping from incoming scopes to Notary scopes.
principal_claim	sub	Claim used as the Notary principal ID.
leeway_seconds	60	Clock skew tolerance.
allow_insecure_localhost	false	Allows local insecure JWKS URLs for development.

audit

Key	Default	Notes
sink	stdout	stdout, file, or jsonl.
path	None	Required when sink: file or sink: jsonl.
hash_secret_env	None	Required. Names an env var containing deployment-specific audit hash secret material.

evidence

Key	Default	Notes
enabled	false	Must be true. Config validation fails otherwise.
service_id	registry-notary	Service identity string in responses.
api_version	2026-05	API version label.
api_base_url	/	Base URL for self-links in the service document.
inline_batch_limit	100	Global maximum subjects per batch request.
claims	[]	Array of claim definitions.
credential_profiles	{}	Map of profile ID to CredentialProfileConfig.
source_connections	{}	Map of connection ID to SourceConnectionConfig.

federation

Fields of FederationConfig.

Key	Default	Notes
enabled	false	When true, mounts /federation/v1/evaluations.
node_id	""	Serving Notary node id. MVP requires did:web.
issuer	""	Serving Notary HTTPS issuer. Host must bind to node_id.
jwks_uri	""	HTTPS JWKS URL for this Notary federation signing keys.
federation_api	""	Public federation API base URL.
supported_protocol_versions	[]	Must include registry-notary-federation/v0.1 when enabled.
inbound_body_limit_bytes	16384	Maximum compact JWS request body size.
max_request_lifetime_seconds	300	Maximum exp - iat for request JWTs.
clock_leeway_seconds	60	Clock skew tolerance for time checks and replay retention.
signing.kid	""	Key id placed in signed response JWT headers.
signing.key_env	""	Env var containing the Ed25519 OKP JWK used to sign responses.
signing.alg	EdDSA	Only EdDSA is accepted for the MVP.
pairwise_subject_hash.secret_env	""	Dedicated secret for pairwise subject handles. Do not reuse audit or signing secrets.
replay.storage	in_process_single_instance_only	MVP replay store. Not safe for active-active serving deployments.
replay.max_entries	10000	Maximum in-process replay entries before oldest-entry eviction.
replay.eviction	expire_oldest	Expires old entries, then evicts oldest inserted entries when full.
response_shaping.minimum_denial_latency_ms	250	Minimum latency floor for denied federation requests.
emergency_denylist.node_ids	[]	Locally denied peer node ids.
emergency_denylist.kids	[]	Locally denied request signing key ids.
peers	[]	Static trusted peer policies. At least one is required when enabled.
evaluation_profiles	[]	Local evaluation profiles. At least one is required when enabled.

Fields of FederationPeerConfig.

Key	Notes
node_id	Trusted peer node id. MVP requires did:web.
issuer	Trusted peer HTTPS issuer. Host must bind to node_id.
jwks_uri	Peer JWKS URL used by the request verifier.
allow_insecure_localhost	Development-only opt-in for local JWKS URLs.
allowed_protocol_versions	Must include registry-notary-federation/v0.1.
allowed_purposes	HTTPS purpose URI allowlist.
allowed_profiles	Evaluation profile IDs this peer may request.
source_scopes	Internal source scopes granted to this peer after policy passes.

Fields of FederationEvaluationProfileConfig.

Key	Notes
id	Local profile id referenced by peer allowed_profiles and request profile.
ruleset	Public ruleset id that can match Registry Manifest evaluation_profiles[].ruleset.
claim_id	Evidence claim evaluated for this profile.
subject_id_type	Required request subject id type.
max_source_observed_age_seconds	Optional freshness limit; stale source observations return a signed evaluation error.

evidence.source_connections

Fields of SourceConnectionConfig.

Key	Default	Notes
base_url	None	Upstream source registry base URL. Required.
allow_insecure_localhost	false	Development-only opt-in for HTTP localhost source registries.
allow_insecure_private_network	false	Development/demo opt-in for HTTP private-network source registries, while cloud metadata endpoints remain blocked.
token_env	None	Environment variable containing the outbound bearer token used when Notary calls the source registry. Required.
dci	DCI defaults	Optional DCI connector settings such as search_path, query_type, records_path, and field_paths.
max_in_flight	8	Per-connection cap on concurrent outbound source requests.
bulk_mode	none	Connector-specific bulk-read mode. Values include none, rda_in_filter, and dci_batched_search.
bulk_mode_lookup_unique	false	Required operator attestation for rda_in_filter.
bulk_timeout_max_ms	30000	Upper bound on the per-call timeout for bulk source reads.