A DDX document (cls: ddx) is a signed tdoc whose body carries the credential’s visual presentation, notarized claims, delegation entitlements, and the public key used to countersign challenge-responses.
The body is a JSON object with two top-level fields:
| Field | Required | Description |
|---|---|---|
ddx |
yes | The credential payload — spec, data, and optionally entitlements |
keys |
yes | JWKS array of public keys registered to this credential |
Top-level structure
Section titled “Top-level structure”{ "ddx": { "spec": { ... }, "data": { ... }, "entitlements": [ ... ] }, "keys": [ ... ]}ddx.spec — Visual Specification
Section titled “ddx.spec — Visual Specification”spec defines the credential’s identity and visual design. It controls how the credential card is rendered in wallets and verification UIs.
| Field | Required | Type | Description |
|---|---|---|---|
category |
yes | string | Semantic type of the credential (e.g. "card", "agent") |
name |
yes | string | Internal name of this credential template |
design |
yes | object | Visual design parameters (see below) |
agentId |
no | string | For agent credentials — the agent’s functional identifier |
scope |
no | string | For agent credentials — comma-delimited list of permitted actions |
a2a_endpoint |
no | string | For agent credentials — the A2A endpoint URL |
spec.design
Section titled “spec.design”| Field | Required | Type | Description |
|---|---|---|---|
title |
yes | string | Issuer display name (shown in card header) |
subtitle |
yes | string | Credential purpose or type (shown in card header) |
primaryTitle |
yes | string | Holder’s name or primary identifier |
primarySubtitle |
no | string | Holder’s role, title, or secondary label |
primaryImage |
no | string | tsrct uid of the holder’s portrait image document |
logo |
no | string | tsrct uid of the issuer’s logo image document |
backgroundColor |
yes | string | Card background — hex color (e.g. "#fcbc05") or CSS gradient |
foregroundColor |
yes | string | Card foreground text color (e.g. "#303030") |
Example — spec
Section titled “Example — spec”From 2222222222222222222222222.9000990009900099000990009.20241231124933-ddx-name-saurabh-gupta:
"spec": { "category": "card", "name": "tsrct official person card", "design": { "logo": "2222222222222222222222222.20240114-01-tsrct-logo", "title": "tsrct", "subtitle": "Personnel Identification", "primaryImage": "2222222222222222222222222.202401150816-sg-profile-pic-small", "primaryTitle": "Saurabh Gupta", "primarySubtitle": "Founder & CEO, tsrct", "backgroundColor": "#fcbc05", "foregroundColor": "#303030" }}ddx.data — Notarized Claims
Section titled “ddx.data — Notarized Claims”data contains the factual claims that the issuing organization is asserting about the credential holder. These claims are cryptographically bound to the credential and cannot be altered without invalidating the signature.
The keys and values are defined by the issuer. Common conventions:
| Field | Type | Description |
|---|---|---|
startDate |
string (ISO 8601) | Date the relationship or role began |
jobDescription |
string or array of strings | Role description or responsibilities |
location |
string | Geographic location of the holder or role |
description |
string | Free-form attestation about the holder |
Any additional key-value pairs are valid. The schema is issuer-defined; tsrct does not validate claim semantics.
Example — data
Section titled “Example — data”"data": { "startDate": "2023-08-01", "jobDescription": [ "As CEO and Founder of tsrct, Saurabh has the following responsibilities:", "* Establish the product and commercial vision for tsrct", "* Build the initial prototype to launch the product in the market", "* Recruit initial customer base to test and establish product market fit" ], "location": "New York City, NY"}ddx.entitlements — Delegation Entitlements
Section titled “ddx.entitlements — Delegation Entitlements”entitlements is an optional array. Each entry grants the credential holder the authority to issue further credentials of a defined shape on behalf of the issuing organization.
An entitlement of type grant_delegate means: “the holder of this DDX may issue new DDX credentials, with the structure and constraints specified here.”
Entitlement fields
Section titled “Entitlement fields”| Field | Required | Type | Description |
|---|---|---|---|
cls |
yes | string | Entitlement class — currently "grant_delegate" |
scm |
yes | string | tsrct uid of the schema document defining this entitlement format |
ver |
yes | string | Schema version (e.g. "v7") |
description |
yes | string | Human-readable description of the authority being granted |
hdr.fixed |
no | object | Header fields that must be fixed in any credential issued under this entitlement |
hdr.inputs |
no | array | Header fields the issuing holder may supply when creating a delegated credential |
subjects |
yes | array | Allowed target src values — ["*"] means any tsrct src |
allow_delegation |
yes | boolean | Whether the holder may issue further delegated credentials |
allow_sub_delegation |
yes | boolean | Whether credentials issued under this entitlement may themselves delegate |
depth.max |
yes | integer | Maximum delegation depth from the root issuer |
depth.current |
yes | integer | Current depth of this entitlement in the delegation chain |
allow_peer_revoke |
yes | boolean | Whether a peer credential holder may revoke credentials issued by the holder |
allow_sub_revoke |
yes | boolean | Whether the holder may revoke credentials issued by sub-delegates |
spec.fixed |
no | object | spec fields that are fixed in any credential issued under this entitlement |
spec.inputs |
no | array | spec.design fields the issuing holder may supply |
data.fixed |
no | object | data fields that are fixed in any credential issued under this entitlement |
data.inputs |
no | array | data fields the issuing holder may supply |
Example — entitlements
Section titled “Example — entitlements”From 7890078900789007890078909.9000990009900099000990009.202505222315-ddx-name-saurabh-gupta-with-ent-v6:
"entitlements": [ { "cls": "grant_delegate", "scm": "2222222222222222222222222.grant-delegate-schema-v7", "ver": "v7", "description": "Authority to grant identification to others",
"hdr.fixed": { "cid": "apptanium.com:delegated-grant", "sub": "apptanium.com:groups" }, "hdr.inputs": ["exp"],
"subjects": ["*"], "allow_delegation": true, "allow_sub_delegation": true, "depth.max": 5, "depth.current": 1, "allow_peer_revoke": true, "allow_sub_revoke": true,
"spec.fixed": { "category": "card", "name": "Apptanium official group membership", "design": { "logo": "7890078900789007890078909.apptanium-com-logo-image-001", "title": "Apptanium", "subtitle": "Group Membership ID", "backgroundColor": "#2271a1", "foregroundColor": "#f7f7f7" } }, "spec.inputs": [ "design.primaryImage", "design.primaryTitle", "design.primarySubtitle" ],
"data.fixed": {}, "data.inputs": ["location", "description"] }]In this example, the holder (9000990009900099000990009) may issue Apptanium Group Membership cards to any tsrct src. The issuer fixes the card template (logo, colors, category) but the holder supplies the portrait image, name, role, location, and description for each individual they credential. The holder may sub-delegate up to 4 more levels deep (depth.max: 5, depth.current: 1).
keys — Public Keys (JWKS)
Section titled “keys — Public Keys (JWKS)”keys is an array of JSON Web Key (JWK) objects. These are the public keys associated with this credential. The corresponding private keys are held exclusively by the issuer’s DDX node and are never transmitted.
Each key object follows the RFC 7517 JWK format:
| Field | Description |
|---|---|
kty |
Key type — always "RSA" for tsrct credentials |
kid |
Key identifier — follows the pattern {ddx-uid}-sig or {ddx-uid}-enc |
alg |
Algorithm — always "RS256" |
use |
Key usage — "sig" for signing, "enc" for encryption |
n |
RSA modulus (base64url-encoded) |
e |
RSA public exponent (base64url-encoded) |
Example — keys
Section titled “Example — keys”"keys": [ { "kty": "RSA", "kid": "2222222222222222222222222.9000990009900099000990009.20241231124933-ddx-name-saurabh-gupta-sig", "alg": "RS256", "use": "sig", "n": "ANvTsjmiFQ2qtQe03NvkUBlfOb1gHj6wPKPZeISHJfcZHYWFICEnyoyBavGZgv2K...", "e": "AQAB" }]Note: Private keys corresponding to
keysentries are held exclusively by the issuing DDX node. They are used to countersign challenge-responses during real-time verification (see DDX Request-Response Flow) and are never stored in or transmitted by tsrct.
Complete body example
Section titled “Complete body example”A minimal credential with no entitlements (2222222222222222222222222.9000990009900099000990009.20241231124933-ddx-name-saurabh-gupta):
{ "ddx": { "spec": { "category": "card", "name": "tsrct official person card", "design": { "logo": "2222222222222222222222222.20240114-01-tsrct-logo", "title": "tsrct", "subtitle": "Personnel Identification", "primaryImage": "2222222222222222222222222.202401150816-sg-profile-pic-small", "primaryTitle": "Saurabh Gupta", "primarySubtitle": "Founder & CEO, tsrct", "backgroundColor": "#fcbc05", "foregroundColor": "#303030" } }, "data": { "startDate": "2023-08-01", "jobDescription": [ "As CEO and Founder of tsrct, Saurabh has the following responsibilities:", "* Establish the product and commercial vision for tsrct", "* Build the initial prototype to launch the product in the market" ], "location": "New York City, NY" } }, "keys": [ { "kty": "RSA", "kid": "2222222222222222222222222.9000990009900099000990009.20241231124933-ddx-name-saurabh-gupta-sig", "alg": "RS256", "use": "sig", "n": "ANvTsjmiFQ2qtQe03NvkUBlfOb1gHj6wPKPZeISHJfcZHYWFICEnyoyBavGZgv2K...", "e": "AQAB" } ]}A credential with delegation entitlements (7890078900789007890078909.9000990009900099000990009.202505222315-ddx-name-saurabh-gupta-with-ent-v6) follows the same structure with a populated entitlements array inside ddx, as shown in the entitlements section above.
See also
Section titled “See also”- DDX Overview — what DDX is and how issuers set it up
- DDX Request-Response Flow — the cryptographic countersigning handshake
- tsrct Doc Spec — the full
tdocwire format that wraps a DDX body