What are schemas

A credential schema is a blueprint that defines the structure, data types, and validation rules for the credentials you want to issue. Think of it as a template that ensures all credentials of a particular type have consistent fields and data formats. Schemas serve several critical purposes:

Data Consistency: Ensures all credentials of the same type have identical field structures
Validation: Defines data types and constraints for each field
Interoperability: Allows different systems to understand and process your credentials
Privacy: Enables selective disclosure of specific fields within a credential

SD-JWT and Iden3 use schemas differently. For SD-JWT VC credentials, the default format, the schema defines the claim names and types, and the schema ID becomes the credential type (vct) unless your issuer sets its own. Which claims are selectively disclosable is set by the issuer’s disclosureFrame. The JSON-LD context and $metadata described below apply to Iden3 credentials.

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

What are schemas

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