> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moca.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Management & Versioning

> Evolve AIR Credential schemas safely with backward-compatible versioning — strategies for adding fields, deprecation, and migrating existing credentials.

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:**

```json theme={null}
{
  "@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:**

```json theme={null}
{
  "@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:**

```json theme={null}
{
  "@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](/airkit/quickstart/issue-credentials)
* **Verify Credentials** - Learn how to verify credentials in the [Credential Verification Quickstart](/airkit/quickstart/verify-credentials)
* **Explore Schema Registry** - Browse and reuse existing schemas in the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/issuer/schemas)
* **Advanced Schema Design** - Learn about complex schema patterns and advanced use cases