Iden3 schema structure

Contact the AIR team to enable Iden3 for your account: Partner with us. For SD-JWT credentials, see What are schemas.

An Iden3 credential schema is a blueprint that defines the structure, data types, and validation rules for the credentials you issue. You create it with the Iden3 Schema Builder, which generates the documents described below.

Schema components

A Schema Type encodes the structure of a particular Verifiable Credential (VC) by defining the type, the fields that must be included inside the VC, and a description for these fields. Schemas let different services interpret the same credential consistently. A verifier that knows the schema can read the credential’s claims without contacting the issuer. A schema type is made of two separate documents:

1. JSON-LD context

The JSON-LD Context contains a description of the type and its fields, providing semantic meaning to your credential data by linking it to standardized vocabularies and ontologies.

Understanding JSON-LD context

JSON-LD context defines the vocabulary and data types used in your credentials. It maps local field names to globally unique identifiers (URIs) that have well-defined meanings. Here’s an example of a JSON-LD Context for a MembershipPointsCredential:

{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "MembershipPointsCredential": {
        "@id": "https://your-domain.com/schemas/membership-points.json-ld#MembershipPointsCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/membership-points#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "memberId": {
            "@id": "vocab:memberId",
            "@type": "xsd:string"
          },
          "totalPoints": {
            "@id": "vocab:totalPoints",
            "@type": "xsd:integer"
          },
          "tier": {
            "@id": "vocab:tier",
            "@type": "xsd:string"
          },
          "lastUpdated": {
            "@id": "vocab:lastUpdated",
            "@type": "xsd:dateTime"
          }
        }
      }
    }
  ]
}

Key JSON-LD context elements

@version: Specifies the JSON-LD version (typically 1.1)
@protected: Ensures that terms cannot be overridden
@id: Maps to globally unique identifiers
@type: Specifies the data type using XML Schema types
vocab: Custom vocabulary namespace for your specific fields
xsd: XML Schema Definition namespace for standard data types

2. JSON Schema

The JSON Schema contains the validation rules for the Issuer Node, defining the structure and constraints for the credential data. Here’s an example of a JSON Schema for the MembershipPointsCredential:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/membership-points.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/membership-points.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "memberId", "totalPoints", "tier"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "memberId": {
          "title": "Member ID",
          "type": "string",
          "description": "Unique member identifier"
        },
        "totalPoints": {
          "title": "Total Points",
          "type": "integer",
          "description": "Total accumulated membership points",
          "minimum": 0
        },
        "tier": {
          "title": "Membership Tier",
          "type": "string",
          "description": "Current membership tier based on points",
          "enum": ["bronze", "silver", "gold", "platinum"]
        },
        "lastUpdated": {
          "title": "Last Updated",
          "type": "string",
          "format": "date-time",
          "description": "When points were last updated"
        }
      }
    }
  }
}

Key JSON Schema elements

$metadata: Contains URIs linking to both the JSON-LD context and JSON schema
required: Lists all mandatory fields for the credential
properties: Defines the structure and validation rules for each field
credentialSubject: Contains the actual credential data fields
format: Specifies validation formats (uri, date-time, etc.)

Benefits of this two-document approach

Separation of Concerns: JSON-LD handles semantics, JSON Schema handles validation
Interoperability: Different systems can understand credentials using standard vocabularies
Validation: Issuer nodes can validate credential structure before issuance
Flexibility: Allows for complex validation rules while maintaining semantic clarity

AIR Identity

Overview

Working with Identity

Iden3 schema structure

Schema components

1. JSON-LD context

Understanding JSON-LD context

Key JSON-LD context elements

2. JSON Schema

Key JSON Schema elements

Benefits of this two-document approach

​Schema components

​1. JSON-LD context

​Understanding JSON-LD context

​Key JSON-LD context elements

​2. JSON Schema

​Key JSON Schema elements

​Benefits of this two-document approach

Schema components

1. JSON-LD context

Understanding JSON-LD context

Key JSON-LD context elements

2. JSON Schema

Key JSON Schema elements

Benefits of this two-document approach