Un esquema es el molde del documento: qué campos (claims) lleva, cuánto dura y, si querés, cómo se dibuja la hoja. Sin un esquema de kind document no podés emitir. Pensalo bien antes de la primera emisión: el esquema queda dentro de la firma de cada documento.
Lo que comparten todos los esquemas (identificadores, versionado, borrado) está en Esquemas. Necesitás un workspace aprovisionado y una API key: ver Primeros pasos.
Crear el esquema
Lo podés crear desde el dashboard o por API. El dashboard es el camino recomendado, porque es el único lugar donde se diseña la hoja (el layout).
En el menú Schemas, el asistente tiene cuatro pasos: Metadata → Claims → Layout → Review.
- Metadata: en Type elegí
Document. Completá el nombre (de ahí sale elschema_id, que vas a usar al emitir), el Credential type (el tipo del documento en PascalCase, por ejemploConstanciaDeEstudios) y la Validity (1y,6m,30d). - Claims: una fila por campo, con claim key, label, type (
string,number,dateoboolean) y required. - Layout: el editor visual de la hoja. Ver El layout.
- Review: el resumen antes de guardar.
Mandá los mismos datos a POST /api/v1/issuer/schemas, con "kind": "document". Acá el schema_id lo elegís vos. Por API no se puede definir el layout.
curl -s -X POST "$BASE_URL/api/v1/issuer/schemas" \
-H "Authorization: Bearer $SOVRA_API_KEY" -H 'Content-Type: application/json' \
-d '{
"schema_id": "constancia_de_estudios",
"credential_type": "EnrollmentCertificate",
"name": "Constancia de estudios",
"kind": "document",
"validity_period": null,
"claims": [
{"key": "nombre", "type": "string", "required": true, "label": "Nombre"},
{"key": "carrera", "type": "string", "required": true, "label": "Carrera"},
{"key": "fecha", "type": "date", "required": false, "label": "Fecha"}
]
}'Responde 201 Created con el esquema en registration_status: "pending".
Al cargar los claims, tené en cuenta:
- El
keyes lo que queda firmado. Es el nombre del campo que tu código y cualquier renderizador van a buscar. Una errata queda en todos los documentos de esa versión. Ellabeles solo una etiqueta. requiredsolo pide que el campo esté al emitir. Si falta, la emisión responde422 missing_claims.- Lo que no declares, no se firma. Las claves que el esquema no conoce se descartan en silencio al emitir.
Detalles de un esquema de kind document por API
| Campo | Qué cambia para un documento |
|---|---|
kind |
"document". Sin este campo el esquema nace credential. |
format |
Queda en vc+sd-jwt, el default. mso_mdoc no admite kind: document. |
validity_period |
La clave tiene que estar presente, aunque sea en null: omitirla es un 422. null emite documentos que no vencen, lo habitual en una constancia. |
disclosable |
No tiene efecto: un documento no tiene holder que negocie divulgación. Todos los claims van a la vista. |
El Credential type viaja como vct dentro del documento firmado, y es contra ese valor que se comprueba on-chain si el emisor está autorizado. Es sensible a mayúsculas.
En vc+sd-jwt el type de cada claim es indicativo: no se rechaza un valor por no coincidir.
La lista completa de campos del objeto Schema está en Esquemas y en la referencia de API.
Esperá el registro on-chain
Recién con registered podés emitir. Si queda en failed, registration_error dice por qué y hay que crear el esquema de nuevo. No hay webhook de registro: consultá GET /api/v1/issuer/schemas.
curl -s "$BASE_URL/api/v1/issuer/schemas" \
-H "Authorization: Bearer $SOVRA_API_KEY" \
| jq '.schemas[] | select(.kind == "document") | {schema_id, version, registration_status}'El layout
El layout es el diseño de la hoja A4. En el paso Layout del asistente arrastrás los claims sobre la hoja (cada uno como Label, el texto fijo, y Value, el dato) y sumás títulos, textos, líneas, cajas, imágenes o una imagen de fondo. Preview muestra la hoja con datos de ejemplo.
- Es opcional. Sin layout el documento se emite y se verifica igual; lo que perdés es la hoja para dibujar.
- No está firmado. Define cómo se ve el documento, no qué dice.
- Solo se diseña en el dashboard. No hay endpoints para el layout. Las versiones nuevas del esquema lo heredan.
Quien recibe el documento lo obtiene en GET /api/v1/documents/{id}. Cómo dibujarlo está en Renderizado.
Más sobre el layout
- La hoja mide 794 × 1123 px (la proporción A4 a 96 dpi), y el layout de un documento tiene un techo de 3 MB.
- Del lado del emisor, el layout aparece en el campo
layoutdeGET /api/v1/issuer/schemas, solo en el listado. - El layout no es lo mismo que el diseño (
PUT /schemas/{schema_id}/design): el diseño es cómo se ve una tarjeta en la wallet, y no aplica a un documento.
Versionado y borrado de un esquema de documento
- Editar publica una versión nueva (
v1 → v2). Los documentos ya emitidos siguen válidos con su versión, y al emitir Sovra usa siempre la más reciente de eseschema_id. - No pueden cambiar entre versiones el Schema ID, el Credential type, el
kindni elformat. - Por API, la revisión es
PUT /api/v1/issuer/schemas/{schema_id}con unbase_version(la versión desde la que empezaste a editar).claimsva entero, no como parche. Si alguien publicó otra versión mientras editabas, responde409 schema_revision_conflict. - Borrar (
DELETE /api/v1/issuer/schemas/{id}) toma el UUID de una versión, no elschema_id, y borra todas las versiones. Se rechaza con409 schema_in_usesi alguna tiene documentos emitidos.
Las reglas generales están en Esquemas.
Checklist
Antes de emitir:
- El esquema es de kind
documenty anotaste suschema_id(el slug, no el UUID). - Está en
registration_status: "registered". - Los
keyde los claims están sin erratas y sabés cuáles sonrequired. - (Opcional) Diseñaste el layout, si vas a dibujar la hoja.