Skip to main content
As your application evolves, you may need to update your credential schemas. Understanding how to manage schema changes is crucial for maintaining compatibility and ensuring smooth operations.

​
Schema Versioning Strategy

When you need to modify a schema, consider these approaches:

​
Backward Compatible Changes

These changes don’t break existing credentials:
  • Adding new optional attributes
  • Updating descriptions or metadata
  • Adding new schema versions

​
Breaking Changes

These changes require careful planning:
  • Removing attributes
  • Changing attribute data types
  • Making optional attributes required
  • Renaming attributes

​
Best Practices for Schema Evolution

​
1. Plan for Growth

JSON-LD Context v1.0: 
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v1.0.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v1.0#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}

​
2. Add New Fields Gradually

JSON-LD Context v1.1: 
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v1.1.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v1.1#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          },
          "phoneNumber": {
            "@id": "vocab:phoneNumber",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}

​
3. Deprecate Fields Carefully

JSON-LD Context v2.0: 
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v2.0.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v2.0#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          },
          "phoneNumber": {
            "@id": "vocab:phoneNumber",
            "@type": "xsd:string"
          },
          "fullName": {
            "@id": "vocab:fullName",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}

​
Managing Schema Updates in Production

​
1. Gradual Migration Strategy

  • Keep old schemas active during transition periods
  • Issue new credentials with updated schemas
  • Gradually phase out old schema versions
  • Monitor credential usage patterns

​
2. Communication with Users

  • Notify users about schema changes
  • Provide migration guides for credential holders
  • Maintain backward compatibility for verification

​
3. Testing Schema Changes

  • Test new schemas in development environment
  • Validate credential issuance with new schemas
  • Ensure verification still works with old credentials
  • Test selective disclosure with updated schemas

​
Schema Registry and Discovery

The AIR Kit provides a schema registry where you can:
  • Browse Available Schemas: Discover schemas created by other developers
  • Reuse Existing Schemas: Use well-established schemas for common use cases
  • Contribute Schemas: Share your schemas with the community

​
Next Steps

Now that you understand schema creation and JSON-LD implementation, you can: