Base/Core Credential Schema

Naming Conventions

All fields use snake_case naming convention. Fields governed by Ayra Association use the ayra_ prefix.

• Use _did suffix when the field contains a DID (not _id)

• Use snake_case with underscores (not camelCase)

• Ayra-governed fields: ayra_ prefix (e.g., ayra_card_type)

• Non-Ayra fields: no prefix (e.g., ecosystem_id, issuer_id)

Mandatory Fields

All Ayra Card credentials MUST include the following fields in credentialSubject:

Ayra Trust Network Fields

Fields governed by Ayra Association for trust network integration:

• ayra_trust_network_did (string, URI format, REQUIRED)

  • DID for the Ayra Trust Network ecosystem

  • Must be a valid DID URI

• ayra_assurance_level (string or integer, REQUIRED)

  • Assurance level under which credential was issued

  • Values: "0", 0, or blank are acceptable

  • Higher numbers indicate higher assurance

• ayra_card_type (string, REQUIRED)

  • Type of Ayra Card from Ayra Type Catalog

  • Examples: businesscard", "staffpass", "membercard"

  • Managed in Ayra Type Catalogue

• ayra_card_version (string, REQUIRED)

  • Semantic version of Ayra Card protocol

  • Format: Semantic Versioning (e.g., "1.0.1")

  • Pattern: ^\d+\.\d+\.\d+$

• ayra_card_type_version (string, REQUIRED)

  • Version number for the specific Ayra Card type

  • Allows versioning of individual card types

  • Format: Semantic Versioning (e.g., "1.0.0")

Trust Registry Integration Fields

Required for TRQP validation:

• authority_trust_registry (string, URI format, REQUIRED)

  • URI of the Trust Registry used for validation

  • Used in TRQP queries

• ecosystem_id (string, URI format, REQUIRED)

  • DID of the ecosystem under which this credential was issued

  • Used in TRQP authority_id queries

  • Note: Somewhat duplicative with TRQP authority_id but required for Ayra Card

• issuer_id (string, URI format, REQUIRED)

  • DID of the issuer

  • Must map to a supported DID Method

  • Note: Duplicates top-level issuer.id but included in credentialSubject for convenience

  • Used in TRQP entity_id queries

• action + resource pairs

  • action+resource for the Issuer test

    • action: issue

    • resource: ayracard:businesscard

  • action+resource for the Ayra Trust Network + Ecosystem /recognition test

    • action: manage-issues

    • resource: ayracard:businesscard

Payload Structure

• payloads (array, OPTIONAL)

  • Array of payload objects

  • Minimum 1 item if present

  • Each payload object contains:

    • id (string, REQUIRED) - Unique identifier, pattern: ^[a-zA-Z0-9_-]+$

    • type (string, REQUIRED) - Payload type (max 255 chars), examples: "phone", "social", "credential"

    • format (string, REQUIRED) - Format/encoding (max 255 chars), examples: "text", "url", "image/png;base64", "dcql"

    • data (string, REQUIRED) - Payload data content

    • description (string, OPTIONAL) - Human-readable description

Business Card Specific Fields

For ayra_card_type: "businesscard" credentials:

Employer-Issued Business Card

• display_name (string, RECOMMENDED)

  • Display name shown to Holder or Verifier

  • Full name of the credential holder

• company_display_name (string, RECOMMENDED)

  • Display name of the issuing company/organization

• email (string, email format, OPTIONAL)

  • Email address of the credential holder

  • Must be valid email format

• phone (string, OPTIONAL)

  • Phone number of the credential holder

  • Note: Can also be included as a payload

• person_name (string, OPTIONAL)

  • Full name of the person

  • Consider using structured format (given_name, family_name) in future versions

• title (string, OPTIONAL)

  • Job title or role

  • Example: "Solutions Architect", "CEO"

Note on Expiration:

• Use W3C VCDM top-level field validUntil (ISO 8601 date-time format)

• Do NOT use expire_datetime in credentialSubject

Note on Deep Links:

• Deep links (Signal, WhatsApp, etc.) should be in payloads, NOT credentialSubject

• Use payload type: "social" or type: "deeplink"

Self-Issued Business Card

Same fields as employer-issued, but:

• Issuer and subject DIDs are the same

• May not be First Person Project compatible (due to self-issuance)

Staff Pass Specific Fields

NOTE: This Ayra Card Type (ayra_card_type: "staffpass") is NOTIONAL. Schema not finalized.

Proposed additional fields for Staff Pass:

• photo (string, OPTIONAL)

  • Base64-encoded photo (PNG format preferred)

  • Consider ISO/IEC 19794-5 compliance for biometric photos

  • Alternative: Include as payload with type: "photo", format: "image/png;base64"

• person_binding (string, OPTIONAL)

  • Describes how the pass is bound to the person

  • Examples: "biometric", "photo", "did🔑abc123"

---

W3C VCDM 2.0 Mapping

Ayra Card credentials are compliant with W3C Verifiable Credentials Data Model 2.0. Key field mappings:

Ayra Card Concept	W3C VCDM 2.0 Field	Location	Type	Notes
Credential ID	id	Top-level	URI	Unique identifier for the credential
Context	@context	Top-level	Array	Must include W3C VC context + Ayra context
Credential Types	type	Top-level	Array	Must include "VerifiableCredential" + "AyraBusinessCard"
Issuer DID	issuer or issuer.id	Top-level	URI	DID of the issuer
Issue Date	validFrom	Top-level	datetime	ISO 8601 format
Expiration Date	validUntil	Top-level	datetime	ISO 8601 format (OPTIONAL)
Subject DID	credentialSubject.id	credentialSubject	URI	DID of the credential holder
Schema Reference	credentialSchema.id	credentialSchema	URI	Points to JSON schema
Schema Type	credentialSchema.type	credentialSchema	string	Usually "JsonSchemaValidator2018"
Ayra-specific fields	Various	credentialSubject	Various	All ayra_* fields and business data
Cryptographic Proof	proof	Top-level	Object	Signature/proof information

Example Structure:

{
  "@context": ["https://www.w3.org/ns/credentials/v2", "https://schema.ayra.forum/..."],
  "type": ["VerifiableCredential", "AyraBusinessCard"],
  "id": "urn:uuid:...",
  "issuer": {"id": "did:web:example.com"},
  "validFrom": "2025-01-15T00:00:00Z",
  "validUntil": "2026-01-15T00:00:00Z",
  "credentialSubject": {
    "id": "did:key:z...",
    "ayra_trust_network_did": "did:web:ayra.forum",
    "ayra_card_type": "businesscard",
    // ... other Ayra fields
  },
  "credentialSchema": {
    "id": "https://schema.ayra.forum/ayra-card-schema.json",
    "type": "JsonSchemaValidator2018"
  },
  "proof": { /* ... */ }
}

---

Optional Fields

All Ayra Card credentials MAY include additional fields beyond the required set. Business Card and Staff Pass specific fields listed above are OPTIONAL unless marked REQUIRED or RECOMMENDED.

Guidelines for Optional Fields:

• Keep optional fields minimal to maintain simplicity

• Consider using payloads for extensibility

• Document any optional fields added to specific card types

---

Discussion Points & Future Considerations

Under Consideration

• Logos/Icons/Overlays

  • Consider OCA (Overlays Capture Architecture) for branding

  • Could be payload-based

• Consent Management

  • Consent Required (Y|N)?

  • May be ecosystem-centric / geo-centric

  • Consider GDPR and other regulatory requirements

Decisions Made

• Naming Convention: Use _did suffix when field contains a DID (not _id)

• Field Separator: Use _ (underscore) with all lowercase (snake_case)

• Field Name: ecosystem_id - Using ecosystem_id in documentation and guidance for Ayra Card

  • Used for TRQP authority_id queries

  • Note: An ecosystem may be registered in multiple TRs

  • Note: A TR may be authoritative for multiple ecosystems

Ties to Ayra Trust Network

• Issuer Registration: Issuer MUST be registered in Ayra Trust Network

• Verifier Registration: Verifier MAY need to be registered (depending on use case)

• Trust Registry: authority_trust_registry points to the authoritative TR

TRQP Implementation Detail

PRECONDITION: Ties to Trust Registry

• Issuer MUST be registered in a Trust Registry

  • authority_trust_registry:

  • issued_under_authority_id: the authority_id that the credential was issued under. MUST be recognized in the trust registry indicated by authority_trust_registry

• Trust Registry MUST be available for a particular ecosystem

Authorization Check

The values for the TRQP queries are:

• TRQP entity_id is the value in issuer_id

• TRQP authority_id is the value in ecosystem_id

• TRQP action is issue. This value does not vary for the Authorization Check.

• TRQP resource is the value in ayra_card_type

Ayra Trust Network Check

The values for the TRQP /recognition query are:

• TRQP entity_id is the ecosystem_id

• TRQP authority_id is the atn_registry (i.e. the Ayra Trust Network Registry)

• TRQP action is manage-issuers. This value does not vary for the Authorization Check.

• TRQP resource is the value in ayra_card_type

Scope of Verifiability

The Verifier is taking on the risks (per GF). Issuer is attesting to the claims provided. How they got to that is ...

LIMITS

• We are NOT sharing transitive proof/transitive trust.

Conformance Test Suite

The focus of the CTS is:

• Testing the Verifier/Wallet interaction

  • DIDComm v2.0 with OOBI and PresentProof 2.0

• Validating the credential contents

  • schema validation

  • data validation (light - mandatory fields present, etc.)

• Ecosystem Issuer /authorization test (is authorized)

• Ayra Trust Network /recognition test