Conceptos clave

Antes de emitir o verificar credenciales en ISBE conviene entender los siguientes conceptos.

Verifiable Credential (VC)

Una VC es un conjunto de claims sobre un sujeto, firmado por un emisor y expresado en formato JSON. En ISBE se usa el VC Data Model v2 del W3C. La estructura básica es:

{
  "@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": "<url-del-schema>", "type": "FullJsonSchemaValidator2021" },
  "termsOfUse": { "type": "IsbeIssuanceCertificate", "id": "<url-tir>" },
  "proof": { ... }
}

Campos obligatorios vs. opcionales

Campo	Obligatorio	Descripción
`@context`	✅	Debe incluir `https://www.w3.org/ns/credentials/v2` como primer elemento.
`id`	✅	Identificador único de la VC. En ISBE se usa el formato `urn:uuid:<uuid>`.
`type`	✅	Array con la cadena de tipos. Siempre incluye `VerifiableCredential` e `IsbeAttestation`.
`issuer`	✅	DID del emisor registrado en el TIR para el tipo de VC emitido.
`validFrom`	✅	Fecha de inicio de validez (ISO 8601).
`validUntil`	⚠️ recomendado	Fecha de expiración. Obligatorio en acreditaciones (`IsbeAccreditation`).
`credentialSubject`	✅	Objeto con los claims del sujeto. Debe incluir `id` (DID del sujeto).
`credentialSchema`	✅	Referencia al JSON Schema del tipo de VC.
`termsOfUse`	✅ para VCs de dominio	Referencia a la entrada del TIR que acredita al emisor.
`credentialStatus`	❌ opcional	Referencia al mecanismo de revocación. Presente en acreditaciones (`IsbeAccreditationEntry`).
`evidence`	❌ opcional	Información sobre el proceso que originó la VC.
`proof`	✅ en serialización JSON-LD	En serialización JWT, la prueba va en el propio envelope JWT.

credentialSubject como array

El esquema base IsbeAttestation permite credentialSubject como objeto o como array. Sin embargo, dentro del ecosistema ISBE credentialSubject no puede ser un array. Los servicios de emisión y verificación de ISBE siempre usan un único sujeto por VC.

Jerarquía de tipos de VC

ISBE define una jerarquía de tipos de VC basada en herencia de esquemas JSON Schema. Cada tipo incluye en su array type todos los tipos de su cadena de herencia:

VerifiableCredential
  └── IsbeAttestation                        (base de todas las VCs ISBE)
       ├── IsbeAccreditation                  (acredita emisores en el TIR)
       └── IsbeDomainCredential               (credencial de dominio para un caso de uso)
            └── IsbePortalLearCredential      (acceso al portal ISBE)

`IsbeAttestation`

Schema base del que heredan todos los tipos de VC ISBE. Define la estructura mínima (campos @context, id, type, issuer, validFrom, credentialSubject, credentialSchema) y los $defs reutilizables (credentialStatus, credentialSchema, termsOfUse).

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

`IsbeAccreditation`

Extiende IsbeAttestation con la estructura de autorización delegada. Una VC de tipo IsbeAccreditation registrada en el TIR certifica que su emisor tiene potestad para emitir uno o más tipos de VC dentro de un dominio. Se emite de TAO a TI (o de RTAO a TAO).

El credentialSubject de una IsbeAccreditation tiene:

{
  "id": "did:isbe:uc:<identifier-del-emisor-acreditado>",
  "domain": "ISBE",
  "accreditedFor": [
    {
      "schemaId": "https://raw.githubusercontent.com/alastria/.../portalLear-schema.json",
      "types": ["VerifiableCredential", "IsbeAttestation", "IsbeDomainCredential", "ISBE", "IsbePortalLearCredential"]
    }
  ],
  "reservedAttributeId": "<hash-del-atributo-en-TIR>"
}

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

`IsbeDomainCredential`

Extiende IsbeAttestation con la obligatoriedad del campo termsOfUse (que debe apuntar a la entrada del TIR que acredita al emisor). Este tipo actúa como clase abstracta de la que heredan las credenciales de casos de uso específicos.

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

`IsbePortalLearCredential`

La primera credencial de dominio de ISBE. Permite al portador autenticarse en el portal ISBE como LEAR (Legal Entity Appointed Representative) de su organización.

El credentialSubject de una IsbePortalLearCredential contiene un objeto mandate con tres partes:

{
  "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"]
      }
    ]
  }
}

Campos del mandator: el representante legal de la organización que concede el mandato. organization y organizationIdentifier son obligatorios; country, commonName y email son opcionales.

Campos del mandatee: el empleado que recibe el mandato. Todos los campos son obligatorios: employeeId, email, firstName, lastName.

Campos de power: array de poderes concedidos. Cada poder define type, domain, function y action (array con al menos un elemento). El array power debe tener al menos un elemento.

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

Formato de prueba (proof)

Las VCs en ISBE se emiten como JWT firmados (Verifiable Credential JWT, VC-JWT). La prueba criptográfica no va en el campo proof del payload sino en la firma del JWT.

Cuando una VC se codifica en formato JWT:

El payload del JWT contiene el campo vc con la VC sin el campo proof.
El header del JWT incluye kid apuntando al vMethodId del assertionMethod del emisor en su DID Document.
El algoritmo (alg) es ES256 (P-256) o ES256K (secp256k1) según la clave del assertionMethod.

Cuando la VC se serializa como JSON-LD (p. ej. en el repositorio de acreditaciones o en respuestas de la API del TIR), el campo proof tiene la siguiente estructura:

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

Tipos de `credentialSchema`

El campo credentialSchema puede usar dos tipos:

Valor de `type`	Semántica
`JsonSchema`	Referencia a un JSON Schema estándar para validación básica.
`FullJsonSchemaValidator2021`	Validación completa del schema incluyendo la evaluación de herencia `allOf`. El tipo usado en ISBE para todas las VCs de producción.

Identificador de VC (`id`)

El campo id de una VC en ISBE usa el formato URN con UUID v4:

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

Este identificador debe ser globalmente único. Los servicios de emisión de ISBE lo generan automáticamente.

`termsOfUse` y el TIR

El campo termsOfUse vincula la VC a la acreditación que autoriza al emisor en el TIR:

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

El valor de id apunta al endpoint del TIR donde está registrada la acreditación del emisor. Un verificador puede seguir ese URL y comprobar que la acreditación está vigente y que el emisor está autorizado para el tipo de VC contenido en el array type.

Repositorio de esquemas

Los JSON Schemas de ISBE están publicados en:

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

Los esquemas commons son referencias abstractas que no deben usarse directamente en nuevas VCs de casos de uso, sino extenderse mediante allOf. Los esquemas de use-cases son los que se referencian desde el campo credentialSchema de una VC concreta.

Verifiable Credential (VC)​

Campos obligatorios vs. opcionales​

Jerarquía de tipos de VC​

IsbeAttestation​

IsbeAccreditation​

IsbeDomainCredential​

IsbePortalLearCredential​

Formato de prueba (proof)​

Tipos de credentialSchema​

Identificador de VC (id)​

termsOfUse y el TIR​

Repositorio de esquemas​