{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schema.beltic.com/developer/v2/developer-credential-v2.schema.json", "title": "DeveloperCredential v2", "description": "W3C Verifiable Credential schema for Beltic DeveloperCredential v2. Aligned with VC Data Model 2.0.", "type": "object", "additionalProperties": false, "required": [ "@context", "type", "id", "issuer", "validFrom", "validUntil", "credentialSubject", "credentialStatus", "proof" ], "$defs": { "uuid": { "type": "string", "format": "uuid" }, "isoCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code" }, "jurisdiction": { "type": "object", "required": ["country"], "additionalProperties": false, "properties": { "country": { "$ref": "#/$defs/isoCountry" }, "region": { "type": "string", "pattern": "^[A-Z0-9]{1,5}$", "description": "Subdivision code (without country prefix)" } } }, "emailAddress": { "type": "string", "format": "email", "maxLength": 254 }, "phoneNumber": { "type": "string", "pattern": "^\\+?[0-9][0-9 ()-]{6,19}$", "maxLength": 25, "description": "Phone number in E.164 or common formats" }, "riskLevel": { "type": "string", "enum": ["none", "low", "medium", "high", "not_assessed"] }, "overallRiskLevel": { "type": "string", "enum": ["low", "medium", "high", "prohibited", "not_assessed"] }, "screeningStatus": { "type": "string", "enum": ["clear", "potential_match", "confirmed_match", "not_screened", "screening_error"] }, "assuranceLevel": { "type": "string", "enum": ["self_attested", "beltic_verified", "third_party_verified"] }, "didIdentifier": { "type": "string", "pattern": "^did:(web|key|ion|pkh|ethr):[a-zA-Z0-9._%-]+", "minLength": 10, "maxLength": 500, "description": "Decentralized Identifier (DID)" }, "verificationMethodRef": { "type": "string", "pattern": "^did:(web|key|ion|pkh|ethr):[a-zA-Z0-9._%-]+#[a-zA-Z0-9_-]+$", "minLength": 15, "maxLength": 600, "description": "DID verification method reference (DID#keyId format)" }, "proofObject": { "type": "object", "description": "W3C VC Data Integrity Proof", "required": ["type", "created", "verificationMethod", "proofPurpose", "proofValue"], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": ["Ed25519Signature2020", "JsonWebSignature2020", "EcdsaSecp256k1Signature2019"] }, "created": { "type": "string", "format": "date-time" }, "verificationMethod": { "$ref": "#/$defs/verificationMethodRef" }, "proofPurpose": { "type": "string", "enum": ["assertionMethod", "authentication", "keyAgreement"] }, "proofValue": { "type": "string", "minLength": 40, "maxLength": 2000 }, "challenge": { "type": "string", "maxLength": 256 }, "domain": { "type": "string", "format": "uri" } } }, "publicKeyObject": { "type": "object", "description": "Subject public key material", "required": ["type"], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": ["Ed25519VerificationKey2020", "JsonWebKey2020", "EcdsaSecp256k1VerificationKey2019", "X25519KeyAgreementKey2020"] }, "publicKeyMultibase": { "type": "string", "pattern": "^z[1-9A-HJ-NP-Za-km-z]+$", "minLength": 40, "maxLength": 200 }, "publicKeyJwk": { "type": "object", "properties": { "kty": { "type": "string", "enum": ["EC", "OKP", "RSA"] }, "crv": { "type": "string" }, "x": { "type": "string" }, "y": { "type": "string" } }, "required": ["kty"] } }, "oneOf": [ { "required": ["type", "publicKeyMultibase"] }, { "required": ["type", "publicKeyJwk"] } ] }, "bitstringStatusListEntry": { "type": "object", "description": "W3C Bitstring Status List Entry for credential revocation/suspension", "required": ["id", "type", "statusPurpose", "statusListIndex", "statusListCredential"], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uri", "description": "URL to the specific status entry" }, "type": { "type": "string", "const": "BitstringStatusListEntry" }, "statusPurpose": { "type": "string", "enum": ["revocation", "suspension"], "description": "Purpose of the status check" }, "statusListIndex": { "type": "string", "pattern": "^[0-9]+$", "description": "Index position in the status list bitstring" }, "statusListCredential": { "type": "string", "format": "uri", "description": "URL to the status list credential" } } } }, "properties": { "@context": { "type": "array", "items": { "type": "string" }, "minItems": 2, "description": "W3C VC context URIs. Must include base VC context and Beltic context.", "contains": { "const": "https://www.w3.org/ns/credentials/v2" } }, "type": { "type": "array", "items": { "type": "string" }, "minItems": 2, "allOf": [ { "contains": { "const": "VerifiableCredential" } }, { "contains": { "const": "DeveloperCredential" } } ], "description": "Credential types. Must include VerifiableCredential and DeveloperCredential." }, "id": { "type": "string", "format": "uri", "description": "Unique identifier for the credential (URN or URL)" }, "issuer": { "$ref": "#/$defs/didIdentifier", "description": "DID of the credential issuer" }, "validFrom": { "type": "string", "format": "date-time", "description": "Date and time when the credential becomes valid" }, "validUntil": { "type": "string", "format": "date-time", "description": "Date and time when the credential expires" }, "credentialSubject": { "type": "object", "description": "Developer/organization-specific claims", "additionalProperties": false, "required": [ "id", "schemaVersion", "legalName", "entityType", "incorporationJurisdiction", "businessRegistrationStatus", "website", "businessEmail", "taxIdExists", "kybTier", "sanctionsScreeningStatus", "overallRiskRating", "publicKey", "lastUpdatedDate" ], "properties": { "id": { "$ref": "#/$defs/didIdentifier", "description": "DID of the developer/organization (credential subject)" }, "schemaVersion": { "type": "string", "enum": ["2.0"], "description": "Schema version identifier." }, "assuranceMetadata": { "type": "object", "description": "Tracks the assurance level and verification details for each field in the credential.", "properties": { "globalAssuranceLevel": { "type": "string", "enum": ["self_attested", "beltic_verified", "third_party_verified"], "description": "Overall assurance level for the credential." }, "fieldAssurances": { "type": "object", "description": "Per-field assurance tracking.", "additionalProperties": { "type": "object", "properties": { "assuranceLevel": { "type": "string", "enum": ["self_attested", "beltic_verified", "third_party_verified"] }, "verificationDate": { "type": "string", "format": "date-time" }, "verificationSource": { "type": "string", "description": "Name or identifier of the verifying party or system." } }, "required": ["assuranceLevel"] } } }, "required": ["globalAssuranceLevel"] }, "legalName": { "type": "string", "minLength": 2, "maxLength": 500, "description": "Full legal name of the organization or individual." }, "entityType": { "type": "string", "enum": [ "corporation", "limited_liability_company", "partnership", "sole_proprietorship", "individual", "nonprofit_organization", "government_entity", "other" ], "description": "Legal entity type." }, "incorporationJurisdiction": { "$ref": "#/$defs/jurisdiction", "description": "Jurisdiction of incorporation" }, "incorporationDate": { "type": "string", "format": "date", "description": "Date of incorporation (required for organizations, optional for individuals)." }, "businessRegistrationNumber": { "type": "string", "description": "Tokenized/hashed registration number. MUST NOT contain raw registration numbers.", "minLength": 8, "maxLength": 128, "pattern": "^(hash_|tok_|hmac_)[A-Za-z0-9_-]+$" }, "businessRegistrationStatus": { "type": "string", "enum": [ "active_good_standing", "active_requires_attention", "inactive", "suspended", "not_applicable", "verification_pending" ], "description": "Registration status with authorities." }, "website": { "type": "string", "format": "uri", "description": "Primary website URL." }, "registeredAddress": { "type": "object", "properties": { "streetAddress": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": ["streetAddress", "city", "postalCode", "country"], "additionalProperties": false, "description": "Registered address (required for organizations).", "nullable": true }, "businessEmail": { "type": "string", "format": "email", "maxLength": 254, "description": "Business contact email." }, "businessPhone": { "$ref": "#/$defs/phoneNumber", "description": "Business phone number (restricted; recommended)." }, "securityEmail": { "$ref": "#/$defs/emailAddress", "description": "Security/incident response email." }, "taxIdExists": { "type": "boolean", "description": "Indicates whether the entity has a tax ID." }, "taxIdVerified": { "oneOf": [ { "type": "string", "enum": [ "verified", "not_verified", "verification_pending", "verification_failed", "not_applicable" ] }, { "type": "null" } ], "description": "Tax ID verification status (required when taxIdExists=true)." }, "taxIdJurisdiction": { "$ref": "#/$defs/jurisdiction", "description": "Jurisdiction of tax ID" }, "taxIdLastVerifiedDate": { "type": "string", "format": "date" }, "kybTier": { "type": "string", "enum": [ "tier_0_unverified", "tier_1_basic", "tier_2_standard", "tier_3_enhanced", "tier_4_maximum" ], "description": "KYB verification tier." }, "sanctionsScreeningStatus": { "$ref": "#/$defs/screeningStatus", "description": "Sanctions screening result" }, "sanctionsScreeningLastChecked": { "type": "string", "format": "date" }, "pepRiskLevel": { "$ref": "#/$defs/riskLevel", "description": "Politically Exposed Person risk level" }, "pepRiskLastAssessed": { "type": ["string", "null"], "format": "date" }, "adverseMediaRiskLevel": { "$ref": "#/$defs/riskLevel", "description": "Adverse media screening risk level" }, "adverseMediaLastAssessed": { "type": ["string", "null"], "format": "date" }, "overallRiskRating": { "$ref": "#/$defs/overallRiskLevel", "description": "Overall risk rating for the entity" }, "beneficialOwnersKycStatus": { "type": "string", "enum": [ "all_identified_and_kycd", "partially_identified", "identified_not_kycd", "unable_to_identify", "not_applicable", "not_assessed" ] }, "beneficialOwnersCount": { "type": "integer", "minimum": 0 }, "controlStructureComplexity": { "type": "string", "enum": ["simple", "moderate", "complex", "not_assessed"] }, "publicKey": { "$ref": "#/$defs/publicKeyObject" }, "lastUpdatedDate": { "type": "string", "format": "date-time" } } }, "credentialStatus": { "$ref": "#/$defs/bitstringStatusListEntry" }, "proof": { "$ref": "#/$defs/proofObject" } }, "allOf": [ { "$comment": "When taxIdExists is true, taxIdVerified and taxIdJurisdiction are required", "if": { "properties": { "credentialSubject": { "properties": { "taxIdExists": { "const": true } }, "required": ["taxIdExists"] } } }, "then": { "properties": { "credentialSubject": { "required": ["taxIdVerified", "taxIdJurisdiction"], "properties": { "taxIdVerified": { "not": { "type": "null" } } } } } } }, { "$comment": "When taxIdVerified is 'verified', taxIdLastVerifiedDate is required", "if": { "properties": { "credentialSubject": { "properties": { "taxIdVerified": { "const": "verified" } }, "required": ["taxIdVerified"] } } }, "then": { "properties": { "credentialSubject": { "required": ["taxIdLastVerifiedDate"] } } } }, { "$comment": "When entityType is 'individual', organization-only fields must NOT be present or should be null", "if": { "properties": { "credentialSubject": { "properties": { "entityType": { "const": "individual" } }, "required": ["entityType"] } } }, "then": { "properties": { "credentialSubject": { "properties": { "incorporationDate": false, "businessRegistrationNumber": false, "registeredAddress": { "type": "null" }, "beneficialOwnersKycStatus": { "enum": ["not_applicable"] } } } } } }, { "$comment": "When entityType is NOT 'individual' or 'sole_proprietorship', organization fields are required", "if": { "properties": { "credentialSubject": { "properties": { "entityType": { "enum": ["corporation", "limited_liability_company", "partnership", "nonprofit_organization", "government_entity", "other"] } }, "required": ["entityType"] } } }, "then": { "properties": { "credentialSubject": { "required": ["incorporationDate", "businessRegistrationNumber", "registeredAddress"] } } } }, { "$comment": "When kybTier is tier_2 or above, risk screening fields are required", "if": { "properties": { "credentialSubject": { "properties": { "kybTier": { "enum": ["tier_2_standard", "tier_3_enhanced", "tier_4_maximum"] } }, "required": ["kybTier"] } } }, "then": { "properties": { "credentialSubject": { "required": ["sanctionsScreeningStatus", "pepRiskLevel", "adverseMediaRiskLevel", "overallRiskRating"] } } } }, { "$comment": "When sanctionsScreeningStatus is set (not 'not_screened'), sanctionsScreeningLastChecked is required", "if": { "properties": { "credentialSubject": { "properties": { "sanctionsScreeningStatus": { "enum": ["clear", "potential_match", "confirmed_match", "screening_error"] } }, "required": ["sanctionsScreeningStatus"] } } }, "then": { "properties": { "credentialSubject": { "required": ["sanctionsScreeningLastChecked"] } } } }, { "$comment": "When pepRiskLevel is set (not 'not_assessed'), pepRiskLastAssessed is required", "if": { "properties": { "credentialSubject": { "properties": { "pepRiskLevel": { "enum": ["none", "low", "medium", "high"] } }, "required": ["pepRiskLevel"] } } }, "then": { "properties": { "credentialSubject": { "required": ["pepRiskLastAssessed"] } } } }, { "$comment": "When adverseMediaRiskLevel is set (not 'not_assessed'), adverseMediaLastAssessed is required", "if": { "properties": { "credentialSubject": { "properties": { "adverseMediaRiskLevel": { "enum": ["none", "low", "medium", "high"] } }, "required": ["adverseMediaRiskLevel"] } } }, "then": { "properties": { "credentialSubject": { "required": ["adverseMediaLastAssessed"] } } } }, { "$comment": "When sanctionsScreeningStatus is 'confirmed_match', overallRiskRating must be 'high' or 'prohibited'", "if": { "properties": { "credentialSubject": { "properties": { "sanctionsScreeningStatus": { "const": "confirmed_match" } }, "required": ["sanctionsScreeningStatus"] } } }, "then": { "properties": { "credentialSubject": { "properties": { "overallRiskRating": { "enum": ["high", "prohibited"] } } } } } }, { "$comment": "When overallRiskRating is 'prohibited', credential should be revoked or suspended", "if": { "properties": { "credentialSubject": { "properties": { "overallRiskRating": { "const": "prohibited" } }, "required": ["overallRiskRating"] } } }, "then": { "properties": { "credentialStatus": { "properties": { "statusPurpose": { "enum": ["revocation", "suspension"] } } } } } }, { "$comment": "When pepRiskLevel is 'high', overallRiskRating must be at least 'high'", "if": { "properties": { "credentialSubject": { "properties": { "pepRiskLevel": { "const": "high" } }, "required": ["pepRiskLevel"] } } }, "then": { "properties": { "credentialSubject": { "properties": { "overallRiskRating": { "enum": ["high", "prohibited"] } } } } } }, { "$comment": "When adverseMediaRiskLevel is 'high', overallRiskRating must be at least 'high'", "if": { "properties": { "credentialSubject": { "properties": { "adverseMediaRiskLevel": { "const": "high" } }, "required": ["adverseMediaRiskLevel"] } } }, "then": { "properties": { "credentialSubject": { "properties": { "overallRiskRating": { "enum": ["high", "prohibited"] } } } } } }, { "$comment": "When beneficialOwnersKycStatus is 'unable_to_identify', overallRiskRating should be escalated", "if": { "properties": { "credentialSubject": { "properties": { "beneficialOwnersKycStatus": { "const": "unable_to_identify" } }, "required": ["beneficialOwnersKycStatus"] } } }, "then": { "properties": { "credentialSubject": { "properties": { "overallRiskRating": { "enum": ["medium", "high", "prohibited"] } } } } } }, { "$comment": "Sole proprietorship handling - similar to individual", "if": { "properties": { "credentialSubject": { "properties": { "entityType": { "const": "sole_proprietorship" } }, "required": ["entityType"] } } }, "then": { "properties": { "credentialSubject": { "properties": { "beneficialOwnersKycStatus": { "enum": ["not_applicable", "not_assessed"] } } } } } } ] }