> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.adid.dev/llms.txt. > For full documentation content, see https://docs.adid.dev/llms-full.txt. # Credential Schemas Credential schemas define the structure and validation rules for Verifiable Credentials in IDA. Schemas are registered on the ADI blockchain via the Schema Registry smart contract and validated at issuance time. ## Schema Lifecycle ```mermaid graph LR D[Define Schema] --> R[Register On-Chain] R --> P[Published] P --> V[Version Update] V --> P P --> U[Used in VC Issuance] U --> Val[Schema Validation] ``` ## Schema Structure A credential schema in IDA follows the JSON Schema (draft 2020-12) format: ```json { "id": "urn:uuid:...", "type": "JsonSchema", "name": "UniversityDegree", "version": "1.0", "author": "did:adi:issuer001", "created": "2026-03-28T10:00:00Z", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": ["degree", "university", "graduationYear"], "properties": { "degree": { "type": "object", "required": ["type", "name"], "properties": { "type": { "type": "string", "enum": ["BachelorDegree", "MasterDegree", "DoctoralDegree"] }, "name": { "type": "string", "maxLength": 200 }, "university": { "type": "string" }, "graduationYear": { "type": "integer", "minimum": 1900, "maximum": 2100 }, "gpa": { "type": "number", "minimum": 0, "maximum": 4.0 } } } } } } ``` ## Built-in Schema Templates IDA ships with six built-in schema templates located in `packages/api/internal/schemas/`. ### Education Degree (`education_degree.json`) For university and educational institution credentials. | Attribute | Type | Required | Description | | --------------------- | ------------- | -------- | --------------------------------------------------------------------------------- | | `degree.type` | string (enum) | Yes | BachelorDegree, MasterDegree, DoctoralDegree, AssociateDegree, ProfessionalDegree | | `degree.name` | string | Yes | Full degree name | | `degree.fieldOfStudy` | string | No | Major or field of study | | `university` | string | Yes | Issuing institution name | | `graduationYear` | integer | Yes | Year of graduation (1900-2100) | | `gpa` | number | No | Grade point average (0-4.0) | | `honors` | string (enum) | No | summa cum laude, magna cum laude, cum laude | | `registrationNumber` | string | No | University registration or student ID | ### KYC Verification (`kyc_verification.json`) For Know Your Customer verification credentials. | Attribute | Type | Required | Description | | -------------------- | ------------- | -------- | ----------------------------------------------------------- | | `kycLevel` | string (enum) | Yes | basic, enhanced, full | | `verifiedAt` | datetime | Yes | When KYC was completed | | `institution` | string | Yes | Verifying institution | | `country` | string | Yes | ISO 3166-1 alpha-2 country code | | `expiresAt` | datetime | Yes | KYC expiration date | | `documentType` | string (enum) | No | passport, national\_id, drivers\_license, residence\_permit | | `amlScreening` | boolean | No | Whether AML screening was performed | | `sanctionsScreening` | boolean | No | Whether sanctions screening was performed | | `pepScreening` | boolean | No | Whether PEP screening was performed | | `riskRating` | string (enum) | No | low, medium, high | ### Vaccination Record (`vaccination_record.json`) For healthcare vaccination credentials. | Attribute | Type | Required | Description | | ------------------ | ------- | -------- | ------------------------------- | | `vaccine` | string | Yes | Vaccine name | | `manufacturer` | string | Yes | Manufacturer | | `batchNumber` | string | Yes | Batch/lot number | | `doseNumber` | integer | Yes | Dose sequence number (1-10) | | `totalDoses` | integer | No | Total doses in the series | | `dateAdministered` | date | Yes | Date of administration | | `provider` | string | Yes | Healthcare provider | | `providerDID` | string | No | DID of the healthcare provider | | `country` | string | No | ISO 3166-1 alpha-2 country code | | `disease` | string | No | Target disease | | `nextDoseDate` | date | No | Recommended date for next dose | ### Address Proof (`address_proof.json`) For address verification credentials. | Attribute | Type | Required | Description | | -------------------- | ------------- | -------- | ----------------------------------------------------------------------- | | `addressLine1` | string | Yes | Primary street address | | `addressLine2` | string | No | Secondary address line | | `city` | string | Yes | City or municipality | | `stateOrProvince` | string | No | State, province, or region | | `postalCode` | string | No | Postal or ZIP code | | `country` | string | Yes | ISO 3166-1 alpha-2 country code | | `verifiedAt` | datetime | Yes | When address was verified | | `verificationMethod` | string (enum) | No | utility\_bill, bank\_statement, government\_letter, in\_person, digital | | `verifier` | string | No | Entity that verified the address | | `validUntil` | datetime | No | Expiration of the proof | ### Agent Capability (`agent_capability.json`) For AI Agent capability attestation credentials. Attests that an agent possesses specific capabilities as evaluated by a trusted authority. | Attribute | Type | Required | Description | | -------------------- | ------------- | -------- | -------------------------------------------------------------- | | `agentDid` | string (DID) | Yes | The agent's DID | | `capabilities` | array | Yes | List of capability tags | | `modelInfo.provider` | string | Yes | Model provider (e.g., Anthropic) | | `modelInfo.name` | string | Yes | Model name (e.g., Claude) | | `modelInfo.version` | string | Yes | Model version | | `safetyRating` | string (enum) | No | A, B, C, D, unrated | | `evaluationReport` | string (URI) | No | Link to evaluation report | | `evaluationDate` | datetime | No | When evaluation was performed | | `evaluator` | string | No | DID or name of the evaluator | | `constraints` | object | No | Operational constraints (maxTokens, rateLimit, allowedDomains) | ### Agent Delegation (`agent_delegation.json`) For AI Agent delegation credentials. Grants specific permissions from a delegator to a delegate agent with constraints and chain-of-delegation support. | Attribute | Type | Required | Description | | ---------------------------------- | ------------- | -------- | --------------------------------- | | `delegator` | string (DID) | Yes | DID of the delegating entity | | `delegate` | string (DID) | Yes | DID of the receiving agent | | `scope` | array | Yes | List of permitted actions | | `constraints.maxBudget` | number | No | Maximum budget | | `constraints.currency` | string | No | Currency (ISO 4217) | | `constraints.allowedMerchants` | array | No | Allowed merchant DIDs/names | | `constraints.timeWindow` | object | No | Start/end time window | | `constraints.geofence` | object | No | Geographic constraints | | `constraints.maxTransactionAmount` | number | No | Max single transaction | | `attenuatedFrom` | string | No | Parent delegation credential ID | | `maxDepth` | integer | No | Max delegation chain depth (0-10) | | `currentDepth` | integer | No | Current chain depth | | `revocationPolicy` | string (enum) | No | immediate, graceful, cascading | | `notificationEndpoint` | string (URI) | No | Webhook for delegation events | ## Schema Registration ### Create Schema via API ```bash curl -X POST http://localhost:8080/api/v1/credentials/schemas \ -H "Content-Type: application/json" \ -H "Authorization: ApiKey dev-api-key" \ -d '{ "name": "EmploymentCredential", "version": "1.0", "author": "did:adi:issuer001", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": ["employer", "position", "startDate"], "properties": { "employer": { "type": "string" }, "position": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "salary": { "type": "number", "minimum": 0 } } } }' ``` ### List Schemas ```bash curl http://localhost:8080/api/v1/credentials/schemas?page=1&limit=20 \ -H "Authorization: ApiKey dev-api-key" ``` ### Get Schema by ID ```bash curl http://localhost:8080/api/v1/credentials/schemas/urn:uuid:schema-id \ -H "Authorization: ApiKey dev-api-key" ``` ## Schema Versioning Schemas are immutable once registered. To update a schema, create a new version: | Version | Changes | Backward Compatible | | ------- | --------------------- | ------------------- | | v1.0 | Initial schema | N/A | | v1.1 | Add optional field | Yes | | v2.0 | Remove required field | No | Version `1.1` credentials can be verified against `1.0` verifiers (optional fields ignored). Version `2.0` credentials require updated verifiers. ## Schema Validation When a VC is issued with a `schemaId`, IDA validates the `credentialSubject` against the declared schema: 1. All `required` attributes must be present 2. Attribute types must match the schema definition 3. Enum values must be in the allowed set 4. Numeric values must satisfy min/max constraints 5. String lengths must not exceed defined maximums 6. Nested objects are validated recursively Validation errors return a `422 Unprocessable Entity` with details: ```json { "error": { "code": "SCHEMA_VALIDATION_FAILED", "message": "schema validation failed: graduationYear: required field missing; gpa: value 5.0 exceeds maximum 4.0; " } } ``` ## Custom Schema Creation Organizations can define custom schemas for any use case. The schema must follow JSON Schema draft 2020-12 and include: * A `type` field (usually `"object"`) * A `properties` object defining each field's type and constraints * A `required` array listing mandatory fields The schema is validated at registration time and enforced at credential issuance time when the `schemaId` is provided in the issuance request.