Moca Network Docs

Appearance

Schema Management and Versioning ​

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
{
  "@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
{
  "@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
{
  "@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: