Un esquema es el molde de todo lo que se emite. Así como un formulario en papel define qué casilleros tiene, un esquema define qué datos lleva una credencial o un documento, cuánto tiempo vale y en qué formato se firma. Sin esquema no se emite nada, y parte de lo que define queda firmado para siempre en cada credencial, así que conviene pensarlo antes de la primera emisión.
Cómo crear cada tipo, campo por campo, está en Esquema SD-JWT, Esquema mDoc y Crear un esquema de documento.
Qué define un esquema
- Un identificador (
schema_id), por ejemplolicencia_de_conducir. - Los campos (
claims): nombre, tipo, si es obligatorio y si el ciudadano puede elegir no mostrarlo. - La vigencia (
validity_period):1y,6m,30d, onullpara que no venza. - Qué es (
kind): una credencial (credential) o un documento (document). - El formato (
format):vc+sd-jwt(default) omso_mdoc.
Los esquemas se crean en el dashboard (Schemas → New schema) o por API (/api/create-schema/).
Todos los campos del esquema
| Campo | Qué es |
|---|---|
schema_id |
Tu identificador estable (ver los dos identificadores). |
credential_type |
El tipo de credencial: viaja como vct en un SD-JWT, en el namespace meta en un mDoc, y es lo que se registra on-chain. No se puede cambiar nunca más. |
name |
Nombre para mostrar. |
claims |
Los campos: cada uno con key, label, type, required y, en credenciales, disclosable. |
validity_period |
Cuánto vive lo emitido: 1y, 6m, 30d, o null para que no venza. |
kind |
credential (default) o document. |
format |
vc+sd-jwt (default) o mso_mdoc. Inmutable de por vida. |
doc_type, namespace |
Solo mso_mdoc: el docType y el namespace de los elementos. |
El diseño de la tarjeta en la wallet también tiene API; el layout de la hoja de un documento, en cambio, solo se diseña en el dashboard.
Los tipos de esquema
| Tipo | Para qué | Detalle |
|---|---|---|
| Credencial SD-JWT VC | Una credencial en la wallet del ciudadano. Admite diseño de tarjeta y adjuntos. | Esquema SD-JWT |
| Credencial mDoc | Una credencial en el formato ISO de la licencia de conducir móvil. | Esquema mDoc |
| Documento | Un documento firmado, sin wallet. Admite diseño de hoja. | Crear un esquema de documento |
Los tipos no son intercambiables: emitir una oferta con un esquema de documento, o un documento con un esquema de credencial, responde 422 wrong_schema_kind. Cuál formato de credencial conviene está en Tipos de credenciales.
Cómo se combinan kind y format
| Tipo | kind |
format |
|---|---|---|
| Credencial SD-JWT VC | credential |
vc+sd-jwt |
| Credencial mDoc | credential |
mso_mdoc |
| Documento | document |
vc+sd-jwt |
Un esquema de kind document no puede ser mDoc: mDoc admite únicamente credential.
Los dos identificadores
Un esquema tiene dos ids, y confundirlos es el error más común:
schema_id: tu nombre para el esquema, por ejemplolicencia_de_conducir. No cambia entre versiones. Es el que usás casi siempre: para emitir, diseñar y revisar.id: un UUID que identifica una versión concreta. Solo lo usás para borrar.
Desde el dashboard, el schema_id se deriva del nombre (“Licencia de Conducir” → licencia_de_conducir); confirmalo en el listado antes de escribirlo en tu código. Por API lo elegís vos.
Detalles del schema_id
- Desde el dashboard: se toma el name, se pasa a minúsculas, todo lo que no sea
a-z0-9se convierte en_, y se corta a 24 caracteres. - Por API: tiene que ser único en el workspace. Un duplicado se reporta como
validation_errorsobreissuer_id, conhas already been taken, no sobreschema_id, que es donde uno lo busca. - En un mDoc con docType generado, el
schema_idpasa a formar parte del docType (io.sovra.<dirección>.<schema_id>.1), así que también es irreversible ahí. POST /api/v1/issuer/schemasdevuelve el esquema con suid, pero sinversion; esa solo aparece en el listado (GET /api/v1/issuer/schemas).
El registro on-chain
Un esquema recién creado todavía no sirve para emitir. Primero se registra en SovraChain, en segundo plano. Mientras tanto está pending, y cuando termina pasa a registered: recién ahí podés emitir. Si el registro falla (failed), hay que crear el esquema de nuevo.
No hay webhook de registro. Consultá el listado hasta ver registered:
curl -s "$BASE_URL/api/v1/issuer/schemas" \
-H "Authorization: Bearer $SOVRA_API_KEY" \
| jq '.schemas[] | {schema_id, version, registration_status}'Los estados de registro y sus errores
registration_status |
Qué significa |
|---|---|
pending |
El registro está en curso. Emitir con él (una oferta o un documento) devuelve 409 schema_registration_pending. |
registered |
Listo: recién acá se puede emitir. |
failed |
El registro agotó sus reintentos. registration_error dice por qué, y con ese esquema no se puede emitir nada (409 schema_registration_failed): hay que crearlo de nuevo. |
Versionado
Editar un esquema no lo modifica: crea una versión nueva (v1 → v2). Lo ya emitido sigue siendo válido con la versión con la que se emitió, y lo nuevo se emite siempre con la más reciente. En el dashboard es el botón Revise; por API, PUT /api/v1/issuer/schemas/{schema_id}.
Hay cosas que no se pueden cambiar nunca, porque quedan firmadas en cada credencial: schema_id, credential_type, kind, format, doc_type y namespace. Si van en una revisión, se ignoran en silencio.
Revisar un esquema por API
curl -s -X PUT "$BASE_URL/api/v1/issuer/schemas/licencia_de_conducir" \
-H "Authorization: Bearer $SOVRA_API_KEY" -H 'Content-Type: application/json' \
-d '{
"name": "Licencia de Conducir",
"base_version": 1,
"validity_period": "10y",
"claims": [ "…la lista completa, no un parche…" ]
}'claims va entero |
Es la lista nueva completa, no un parche. Lo que no mandes desaparece de la versión nueva. |
base_version |
La versión desde la que empezaste a editar. Si mientras tanto alguien publicó otra desde el dashboard, la llamada devuelve 409 schema_revision_conflict en vez de pisarla: releé y rebasá tus cambios. |
| Lo que se hereda | El diseño, el layout y el estado de registro de la versión anterior. |
El credential_type es el vct que los verificadores reconocen; el docType de un mDoc lo declara cada consulta DCQL. Una revisión que los cambiara dejaría huérfanas a las credenciales que ya están en las wallets.
En un mDoc, además, el conjunto de elementos always shared (disclosable: false) se congela dentro de cada credencial al emitirla: una revisión posterior no cambia qué debe divulgar una credencial ya emitida.
Borrado
Un esquema que ya se usó no se borra: se versiona. El borrado solo funciona si ninguna versión tiene una oferta, una credencial o un documento emitido, sea cual sea su estado (si no, 409 schema_in_use), y borra todas las versiones de una vez.
Borrar por API
El borrado toma el UUID (id) de una fila de versión, no el schema_id:
curl -s -X DELETE "$BASE_URL/api/v1/issuer/schemas/$SCHEMA_UUID" \
-H "Authorization: Bearer $SOVRA_API_KEY"Borra todas las versiones de forma atómica. Una oferta vencida de hace un año también cuenta como uso.
El objeto Schema
Los campos que más vas a usar de la respuesta son schema_id, registration_status y, para borrar, id. La lista completa está en la referencia de API.
Todos los campos del objeto
| Campo | Tipo | Descripción |
|---|---|---|
id |
uuid | El id de esta fila de versión. Es el que toma DELETE /schemas/{id}. |
schema_id |
string | Tu identificador estable, el que se manda al emitir. |
credential_type |
string | El vct del SD-JWT y el id del tipo on-chain. |
name |
string | Nombre para mostrar. |
claims |
array | Las definiciones de claim. |
validity_period |
string | null | 1y, 6m, 30d; null si no vence. |
version |
integer | Arranca en 1. Ausente en la respuesta de creación. |
kind |
string | credential o document. |
format |
string | vc+sd-jwt o mso_mdoc. |
registration_status |
string | pending, registered o failed. Solo con registered se puede emitir. |
registration_error |
string | null | Por qué falló el registro. |
doc_type |
string | null | Solo mso_mdoc: el docType, generado si no declaraste uno. null hasta que el workspace esté aprovisionado. |
namespace |
string | null | Solo mso_mdoc: el primer segmento de todo path DCQL de mDoc. |
layout |
object | null | Solo en el listado: el layout de la hoja de un esquema document, definido en el dashboard. |
El ciclo de vida del esquema, en un diagrama, está en Ciclo de vida.