> ## 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 Overview

> How AIR Credential schemas work — JSON Schema structure, JSON-LD context, field types, and validation rules that define a credential template.

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

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

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