What is a Credential Schema?

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

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 are a crucial component that allows for the interoperable use of VCs across different services. Just by parsing a schema, any program can interpret the content of a Verifiable Credential without having to interact with the Issuer Party.

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

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