Link Search Menu Expand Document
tsrct documentation

DDX Body Specification

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 

{
  "ddx": {
    "spec":         { ... },
    "data":         { ... },
    "entitlements": [ ... ]
  },
  "keys": [ ... ]
}

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

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

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

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 

"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

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

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

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)

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 

"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 keys entries 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

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