Key Concepts

Before issuing or verifying credentials in ISBE it is useful to understand the following concepts.

Verifiable Credential (VC)

A VC is a set of claims about a subject, signed by an issuer and expressed in JSON format. ISBE uses the W3C VC Data Model v2. The basic structure is:

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "id": "urn:uuid:<uuid>",
  "type": ["VerifiableCredential", "IsbeAttestation", "..."],
  "issuer": "did:isbe:uc:<identifier>",
  "validFrom": "2026-01-01T00:00:00.000Z",
  "validUntil": "2036-01-01T00:00:00.000Z",
  "credentialSubject": { "id": "did:isbe:uc:<identifier>", ... },
  "credentialSchema": { "id": "<schema-url>", "type": "FullJsonSchemaValidator2021" },
  "termsOfUse": { "type": "IsbeIssuanceCertificate", "id": "<tir-url>" },
  "proof": { ... }
}

Mandatory vs. optional fields

Field	Mandatory	Description
@context	✅	Must include https://www.w3.org/ns/credentials/v2 as the first element.
id	✅	Unique VC identifier. ISBE uses the format urn:uuid:<uuid>.
type	✅	Array with the type chain. Always includes VerifiableCredential and IsbeAttestation.
issuer	✅	DID of the issuer registered in the TIR for the issued VC type.
validFrom	✅	Validity start date (ISO 8601).
validUntil	⚠️ recommended	Expiry date. Mandatory for accreditations (IsbeAccreditation).
credentialSubject	✅	Object with the subject's claims. Must include id (subject's DID).
credentialSchema	✅	Reference to the JSON Schema of the VC type.
termsOfUse	✅ for domain VCs	Reference to the TIR entry that accredits the issuer.
credentialStatus	❌ optional	Reference to the revocation mechanism. Present in accreditations (IsbeAccreditationEntry).
evidence	❌ optional	Information about the process that originated the VC.
proof	✅ in JSON-LD serialization	In JWT serialization, the proof is in the JWT envelope itself.

credentialSubject as an array

The base schema IsbeAttestation allows credentialSubject as an object or as an array. However, within the ISBE ecosystem credentialSubject cannot be an array. ISBE's issuance and verification services always use a single subject per VC.

VC type hierarchy

ISBE defines a VC type hierarchy based on JSON Schema inheritance. Each type includes in its type array all the types in its inheritance chain:

VerifiableCredential
  └── IsbeAttestation                        (base for all ISBE VCs)
       ├── IsbeAccreditation                  (accredits issuers in the TIR)
       └── IsbeDomainCredential               (domain credential for a use case)
            └── IsbePortalLearCredential      (ISBE portal access)

IsbeAttestation

Base schema from which all ISBE VC types inherit. Defines the minimum structure (fields @context, id, type, issuer, validFrom, credentialSubject, credentialSchema) and the reusable $defs (credentialStatus, credentialSchema, termsOfUse).

• Schema URL: https://raw.githubusercontent.com/alastria/isbe-identity-schemas-repository/main/commons/isbe-attestation-schema.json

IsbeAccreditation

Extends IsbeAttestation with the delegated authorization structure. A VC of type IsbeAccreditation registered in the TIR certifies that its issuer has authority to issue one or more VC types within a domain. Issued from TAO to TI (or from RTAO to TAO).

The credentialSubject of an IsbeAccreditation contains:

{
  "id": "did:isbe:uc:<identifier-of-accredited-issuer>",
  "domain": "ISBE",
  "accreditedFor": [
    {
      "schemaId": "https://raw.githubusercontent.com/alastria/.../portalLear-schema.json",
      "types": ["VerifiableCredential", "IsbeAttestation", "IsbeDomainCredential", "ISBE", "IsbePortalLearCredential"]
    }
  ],
  "reservedAttributeId": "<attribute-hash-in-TIR>"
}

• Schema URL: https://raw.githubusercontent.com/alastria/isbe-identity-schemas-repository/main/commons/isbe-accreditation-schema.json

IsbeDomainCredential

Extends IsbeAttestation with the mandatory termsOfUse field (which must point to the TIR entry that accredits the issuer). This type acts as an abstract class from which specific use-case credentials inherit.

• Schema URL: https://raw.githubusercontent.com/alastria/isbe-identity-schemas-repository/main/commons/isbe-domain-credential-schema.json

IsbePortalLearCredential

The first ISBE domain credential. It allows the holder to authenticate in the ISBE portal as a LEAR (Legal Entity Appointed Representative) of their organization.

The credentialSubject of an IsbePortalLearCredential contains a mandate object with three parts:

{
  "mandate": {
    "mandator": {
      "organization": "Empresa S.A.",
      "organizationIdentifier": "ES-B12345678",
      "country": "ES",
      "commonName": "Juan García Martínez",
      "email": "j.garcia@empresa.es"
    },
    "mandatee": {
      "employeeId": "E-00123",
      "email": "empleado@empresa.es",
      "firstName": "Ana",
      "lastName": "López Fernández"
    },
    "power": [
      {
        "type": "domain",
        "domain": "ISBE",
        "function": "onboarding",
        "action": ["execute"]
      }
    ]
  }
}

mandator fields: the legal representative of the organization granting the mandate. organization and organizationIdentifier are mandatory; country, commonName, and email are optional.

mandatee fields: the employee receiving the mandate. All fields are mandatory: employeeId, email, firstName, lastName.

power fields: array of granted powers. Each power defines type, domain, function, and action (array with at least one element). The power array must have at least one element.

• Schema URL: https://raw.githubusercontent.com/alastria/isbe-identity-schemas-repository/main/use-cases/isbe/portal/lear/portalLear-schema.json

Proof format

VCs in ISBE are issued as signed JWTs (Verifiable Credential JWT, VC-JWT). The cryptographic proof is not in the proof field of the payload but in the JWT signature itself.

When a VC is encoded in JWT format:

• The JWT payload contains the vc field with the VC without the proof field.
• The JWT header includes kid pointing to the vMethodId of the issuer's assertionMethod in its DID Document.
• The algorithm (alg) is ES256 (P-256) or ES256K (secp256k1) depending on the assertionMethod key.

When the VC is serialized as JSON-LD (e.g. in the accreditations repository or in TIR API responses), the proof field has the following structure:

{
  "proof": {
    "type": "JsonWebSignature2020",
    "proofPurpose": "assertionMethod",
    "created": "2026-01-15T10:00:00.000Z",
    "verificationMethod": "did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV#<vMethodId>",
    "jws": "<base64url-header>..<base64url-signature>"
  }
}

credentialSchema types

The credentialSchema field can use two types:

type value	Semantics
JsonSchema	Reference to a standard JSON Schema for basic validation.
FullJsonSchemaValidator2021	Full schema validation including allOf inheritance evaluation. The type used in ISBE for all production VCs.

VC identifier (id)

The id field of a VC in ISBE uses the URN format with UUID v4:

urn:uuid:8d475485-1617-42f3-b402-9c95117ad72b

This identifier must be globally unique. ISBE's issuance services generate it automatically.

termsOfUse and the TIR

The termsOfUse field links the VC to the accreditation that authorizes the issuer in the TIR:

{
  "termsOfUse": {
    "type": "IsbeIssuanceCertificate",
    "id": "https://tir.portal.redisbe.com/trusted-issuers-registry/v1/issuers/did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV/attributes/<hash>"
  }
}

The id value points to the TIR endpoint where the issuer's accreditation is registered. A verifier can follow that URL and check that the accreditation is current and that the issuer is authorized for the VC type in the type array.

Schema repository

ISBE's JSON Schemas are published at:

https://github.com/alastria/isbe-identity-schemas-repository

The commons schemas are abstract references that must not be used directly in new use-case VCs, but extended via allOf. The use-cases schemas are the ones referenced from the credentialSchema field of a concrete VC.