Managing your schemas

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:

Issue Credentials - Use your schemas to issue credentials in the Credential Issuance Quickstart
Verify Credentials - Learn how to verify credentials in the Credential Verification Quickstart
Explore Schema Registry - Browse and reuse existing schemas in the Developer Dashboard
Advanced Schema Design - Learn about complex schema patterns and advanced use cases

AIR Identity

Overview

Working with Identity

Managing your schemas

Schema versioning strategy

Backward-compatible changes

Breaking changes

Best practices for schema evolution

1. Plan for growth

2. Add new fields gradually

3. Deprecate fields carefully

Managing schema updates in production

1. Gradual migration strategy

2. Communication with users

3. Testing schema changes

Schema registry and discovery

Next steps

​Schema versioning strategy

​Backward-compatible changes

​Breaking changes

​Best practices for schema evolution

​1. Plan for growth

​2. Add new fields gradually

​3. Deprecate fields carefully

​Managing schema updates in production

​1. Gradual migration strategy

​2. Communication with users

​3. Testing schema changes

​Schema registry and discovery

​Next steps

Schema versioning strategy

Backward-compatible changes

Breaking changes

Best practices for schema evolution

1. Plan for growth

2. Add new fields gradually

3. Deprecate fields carefully

Managing schema updates in production

1. Gradual migration strategy

2. Communication with users

3. Testing schema changes

Schema registry and discovery

Next steps