ak.schema.did_binding_contracts.v1

Arkret Verified DID Binding Contracts

ak.schema.did_binding_contracts.v1 · file: schemas/did-binding-contracts.schema.json

Canonical shapes behind identity/did-usage-and-verification.md section 5: the retained evidence receipt whose digest is the binding's evidence_digest, the resolver policy snapshot whose digest is the binding's policy_digest, the mechanically extracted evidence dependency record used for selective invalidation, the limited-trust pin record, and the freshness profile row every authority call site references. These objects are trust-domain-local: the contracts guarantee recomputability and change-sensitivity, not cross-deployment digest equality.

* $ · anyOf[6]

anyOf · anyOf[0] · object · $ref #/$defs/normalized_did_document

The sole canonical normalized DID Document projection used by document_digest. It retains every v1-normative member, including also_known_as and metadata.primary_handle, and losslessly retains unknown extensions. contexts preserves source order because JSON-LD context order can affect interpretation; every other set-like array is sorted in unsigned UTF-8 order with duplicates rejected. Duplicate/conflicting source properties, ids, relationship entries, services, metadata keys, or extension names fail before digesting. document_digest is exactly sha256:lowercase_hex(SHA-256(RFC8785_JCS(this object))); raw resolver bytes use raw_document_digest and no third DID-document digest name exists.

* did · string · $ref #/$defs/did

Canonical bare DID used for registration, DID method resolution and owner-published current resolution. It contains no path, query or fragment and MUST project through the registered method adapter to exactly one did_core_id.

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* contexts · array<oneOf[2]>

items · oneOf[2]

oneOf · oneOf[0] · string

oneOf · oneOf[1] · object

* controller_dids · array<$ref #/$defs/did>

items · string · $ref #/$defs/did

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* also_known_as · array<string>

items · string

Canonical URI validated by the DID resolver before projection; this array may contain non-network schemes such as acct: and therefore is not a URL field.

pattern: ^[A-Za-z][A-Za-z0-9+.-]*:[^\s]+$

* verification_methods · array<$ref #/$defs/normalized_did_verification_method>

items · object · $ref #/$defs/normalized_did_verification_method

Canonical Arkret projection of one DID verification method. public_key_material is the lossless canonical JSON object containing the registered method-specific public-key members; extensions retains every other member. Rows are sorted by verification_method and duplicate or conflicting verification methods are rejected before projection.

* verification_method · string · $ref ./common-ids.schema.json#/$defs/did_url

Arkret verification-method DID URL profile (identity/did-usage-and-verification.md section 2.2): lowercase method name, no query, required fragment, fragment limited to ASCII [A-Za-z0-9._:-]. Every verification_method-family field and every kid/key_ref a schema declares to be a DID URL MUST resolve to exactly this definition; values compare byte-for-byte with no URI normalization or percent-decoding.

pattern: ^did:[a-z0-9]+:[^\s#?]+#[A-Za-z0-9._:-]+$

* controller_did · string · $ref #/$defs/did

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* verification_method_suite · string

* public_key_material · object

* extensions · array<$ref #/$defs/normalized_did_document_extension>

items · object · $ref #/$defs/normalized_did_document_extension

One lossless extension property from the verified DID Document. Rows are sorted by name in unsigned UTF-8 byte order and duplicate names are rejected. A name that collides with a registered known member is invalid rather than shadowing that member.

* name · string

* value · ?

* authentication · array<$ref #/$defs/normalized_did_relationship_entry> · $ref #/$defs/normalized_did_relationship

Sorted duplicate-free relationship references. Every entry must identify a method present in verification_methods; embedded W3C methods are first hoisted into verification_methods and then referenced here.

items · object · $ref #/$defs/normalized_did_relationship_entry

* verification_method · string · $ref ./common-ids.schema.json#/$defs/did_url

pattern: ^did:[a-z0-9]+:[^\s#?]+#[A-Za-z0-9._:-]+$

* assertion_methods · array<$ref #/$defs/normalized_did_relationship_entry> · $ref #/$defs/normalized_did_relationship

items · object · $ref #/$defs/normalized_did_relationship_entry

* verification_method · string · $ref ./common-ids.schema.json#/$defs/did_url

pattern: ^did:[a-z0-9]+:[^\s#?]+#[A-Za-z0-9._:-]+$

* key_agreements · array<$ref #/$defs/normalized_did_relationship_entry> · $ref #/$defs/normalized_did_relationship

items · object · $ref #/$defs/normalized_did_relationship_entry

* verification_method · string · $ref ./common-ids.schema.json#/$defs/did_url

pattern: ^did:[a-z0-9]+:[^\s#?]+#[A-Za-z0-9._:-]+$

* capability_invocations · array<$ref #/$defs/normalized_did_relationship_entry> · $ref #/$defs/normalized_did_relationship

items · object · $ref #/$defs/normalized_did_relationship_entry

* verification_method · string · $ref ./common-ids.schema.json#/$defs/did_url

pattern: ^did:[a-z0-9]+:[^\s#?]+#[A-Za-z0-9._:-]+$

* capability_delegations · array<$ref #/$defs/normalized_did_relationship_entry> · $ref #/$defs/normalized_did_relationship

items · object · $ref #/$defs/normalized_did_relationship_entry

* verification_method · string · $ref ./common-ids.schema.json#/$defs/did_url

pattern: ^did:[a-z0-9]+:[^\s#?]+#[A-Za-z0-9._:-]+$

* services · array<$ref #/$defs/normalized_did_service>

items · object · $ref #/$defs/normalized_did_service

Canonical Arkret projection of one DID service entry. uri preserves the W3C service id as a generic URI (not an Arkret stable object id); protocol_names is the sorted, duplicate-free projection of the W3C type set; endpoint retains its complete canonical JSON value. Arkret-defined names and endpoint shapes are closed by did-document-contract-registry.json.

* uri · string (uri) · format=uri

* protocol_names · array<string>

items · string

* endpoint · ?

* extensions · array<$ref #/$defs/normalized_did_document_extension>

items · object · $ref #/$defs/normalized_did_document_extension

* name · string

* value · ?

* metadata · object · $ref #/$defs/normalized_did_document_metadata

Closed Arkret metadata projection. primary_handle is a holder preference pointer only; it never creates a handle claim or authorization.

primary_handle · string (arkret-canonical-handle) · format=arkret-canonical-handle · $ref ./string-profiles.schema.json#/$defs/canonical_handle

Canonical <prepared-localpart>:<lowercase-A-label-domain> handle or realm alias. The prepared localpart maximum is 128 Unicode code points; the domain maximum is 253 ASCII octets.

pattern: ^(?!ak:)[^\s:@/#?\\]+:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$

* extensions · array<$ref #/$defs/normalized_did_document_extension>

items · object · $ref #/$defs/normalized_did_document_extension

* name · string

* value · ?

anyOf · anyOf[1] · object · $ref #/$defs/evidence_receipt

Canonical evidence receipt. evidence_digest = "sha256:" + lowercase_hex(SHA-256(RFC8785_JCS(evidence_receipt))). The receipt MUST be retained so an auditor can recompute the digest; a method without proofs degrades to an empty method_proofs array (a document-bound receipt), never to an implementation-invented placeholder. Unknown method or proof kinds fail closed.

* kind · const "ak.did.binding_evidence.v1"

enum: "ak.did.binding_evidence.v1"

* method · string · $ref #/$defs/method_token

Canonical lowercase DID method token (W3C DID 1.0 method-name), e.g. key, web, webvh.

pattern: ^[a-z0-9]+$

* document_digest · string · $ref #/$defs/digest

Typed lowercase-hex SHA-256 digest.

pattern: ^sha256:[0-9a-f]{64}$

* method_proofs · array<$ref #/$defs/webvh_log_evidence>

Closed per-method proof rows; empty for proofless methods (did:key, bare did:web). v1 registers exactly one row kind (webvh_log); receiving any unregistered proof kind fails closed. Rows never reuse resolver response order: each row kind registers its own canonical sort and duplicate-rejection rules.

items · object · $ref #/$defs/webvh_log_evidence

did:webvh method evidence row. witnesses are sorted by witness_did (UTF-8 byte order) with duplicates rejected; witness_proofs_digest commits to the canonical raw witness proof set so the receipt stays change-sensitive to any witness signature change.

* kind · const "webvh_log"

enum: "webvh_log"

* history_head · string

The verified webvh log head (versionId / entry-hash form) this binding pinned.

* witnesses · array<object>

Sorted by witness_did, UTF-8 byte order; duplicates rejected. These rows double as the evidence dependency coordinates for selective invalidation.

items · object

* witness_did · string · $ref #/$defs/did

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* controlling_organization_did · string · $ref #/$defs/did

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* witness_proofs_digest · string · $ref #/$defs/digest

Typed lowercase-hex SHA-256 digest.

pattern: ^sha256:[0-9a-f]{64}$

anyOf · anyOf[2] · object · $ref #/$defs/resolver_policy_snapshot

Canonical resolver policy snapshot. policy_digest = "sha256:" + lowercase_hex(SHA-256(RFC8785_JCS(policy_snapshot))). The snapshot MUST be retainable and rebuildable so auditors can recompute the digest and verify that any security-relevant configuration change necessarily changes it. Enum values MUST use the registered wire tokens below; language-native debug formats are forbidden. accepted_did_methods and trust_roots are sorted by UTF-8 byte order with duplicates rejected; strings receive no Unicode normalization.

allOf · allOf[0] · ?

* kind · const "ak.did.resolver_policy.v1"

enum: "ak.did.resolver_policy.v1"

* policy_profile · string

Registered resolver policy profile id; the schema discriminator for profile_policy. v1 registers ak.did_resolver_policy_profile.base.v1 (empty closed profile_policy). A deployment introducing extra policy dimensions MUST register its own profile with an additionalProperties:false schema listing every configuration field that changes resolution, verification, network boundaries, size limits or degradation behavior as required. Unknown profiles, unknown fields, and missing registered fields all fail closed.

pattern: ^ak\.did_resolver_policy_profile\.[a-z0-9_]+\.v[0-9]+$

* accepted_did_methods · array<string>

Normalized did:<method>: prefixes, sorted, deduplicated.

items · string

pattern: ^did:[a-z0-9]+:$

* fail_mode · string (enum)

enum: "fail_closed" "allow_cached_on_error"

* trust_roots · array<string>

Sorted, deduplicated; may be empty.

items · string

* profile_policy · object

Profile-specific dimensions validated by the closed schema the policy_profile registers; the base profile requires exactly the empty object. Any change here changes the digest, so section 5 invalidation obligations are preserved for deployment-specific knobs.

anyOf · anyOf[3] · object · $ref #/$defs/evidence_dependencies

Structured dependency record mechanically extracted from the evidence receipt (did-usage-and-verification.md section 5.6). It answers 'which bindings depend on witness X / log head H' — a mapping a digest cannot provide because digests are one-way. Proofless methods produce the empty record.

* witness_dids · array<$ref #/$defs/did>

Sorted, deduplicated; empty for proofless methods.

items · string · $ref #/$defs/did

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* witness_controlling_organization_dids · array<$ref #/$defs/did>

Sorted, deduplicated; empty for proofless methods.

items · string · $ref #/$defs/did

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* history_heads · array<string>

Sorted, deduplicated; empty for proofless methods.

items · string

anyOf · anyOf[4] · object · $ref #/$defs/limited_trust

Per-pin limited-trust record (did-usage-and-verification.md section 5.5). Omitted entirely when both pins are present; when present, each state MUST be consistent with the actual presence of the corresponding pin field. method_unsupported is a legitimate terminal state (did:key has no history); not_surfaced marks a resolver that failed to surface evidence its method supports and is treated as a failure state, not a normal audit note.

* history_head_status · string (enum)

enum: "pinned" "method_unsupported" "not_surfaced"

* version_id_status · string (enum)

enum: "pinned" "method_unsupported" "not_surfaced"

anyOf · anyOf[5] · object · $ref #/$defs/freshness_profile

One registered freshness profile row (did-usage-and-verification.md section 5.4). Every DID authority call site references exactly one freshness_profile_id through its operation/action registration; natural-language tier guessing is forbidden. Deployments declare their rows in machine-readable form and the declared snapshot enters profile_policy of the resolver policy snapshot, so changing any number structurally invalidates existing bindings. Tier constraints (finite windows, ordering, stale behavior) are normative in section 5.4.

* freshness_profile_id · string

pattern: ^ak\.did_freshness\.[a-z0-9_]+\.v[0-9]+$

* risk_tier · string (enum)

enum: "low" "medium" "high"

* did_method_selector · array<string>

did:<method>: prefixes this row applies to, or the single wildcard "*".

items · string

pattern: ^(\*|did:[a-z0-9]+:)$

* fresh_for_seconds · integer | null

The single freshness threshold: refresh_after = verified_at + fresh_for_seconds, and the authority call's max_age MUST equal the same value — two separately maintained constants are forbidden.

* stale_grace_seconds · integer | null

* hard_expiry_seconds · integer | null

* stale_behavior · string (enum)

enum: "accepted_without_network" "accepted_and_background_refresh" "synchronous_refresh_or_fail_closed"

Source

registry row: spec/v1/artifacts/registry/schema-registry.json
schema document: spec/v1/artifacts/schemas/did-binding-contracts.schema.json