43 lines
5.0 KiB
Markdown
43 lines
5.0 KiB
Markdown
# JSON Schema del DSL y DTOs
|
||
|
||
Dialect: JSON Schema 2020-12. Archivos canónicos editables directamente; no se requiere generador.
|
||
|
||
| Archivo | Contenido |
|
||
|---|---|
|
||
| flow-definition.schema.json | Definición completa de flujo y $defs para estados, eventos, valores, condiciones, acciones, decisiones, transiciones y tareas |
|
||
| api.schema.json | $defs de comandos, consultas, administración, errores, simulación y conciliación REST |
|
||
| integration-results.schema.json | Ejemplos de contratos normalizados de cliente, buró y documentos; pendientes de confirmar con proveedores en T11 |
|
||
|
||
## DSL v1
|
||
|
||
schemaVersion versiona el formato; version versiona el proceso. Keys/IDs: 1–100 caracteres, comienzan por letra y permiten letras ASCII, dígitos, punto, guion y guion bajo. Los estados/eventos siguen siendo strings configurables, no enums del negocio.
|
||
|
||
`dataSchema` describe datos persistidos y `initialDataSchema` restringe entrada inicial. Son opcionales estructuralmente para aceptar borradores y el ejemplo mínimo original; T06 deberá exigir dataSchema de objeto al publicar. Si initialDataSchema falta, usar dataSchema; al crear validar ambos cuando están presentes. En los schemas de entrada conviene additionalProperties=false y sólo campos aceptados del cliente. La publicación debe rechazar configuraciones que acepten resultados de proveedor como autoridad del front.
|
||
|
||
`InlineSchema` admite booleanos y un subconjunto explícito de JSON Schema: type, properties, required, additionalProperties, items, enum/const, longitudes/pattern/format, rangos numéricos, límites de arrays/objetos y allOf/anyOf/oneOf/not/if/then/else. Formats: uuid, date-time, date, email, uri. No admite referencias externas, $ref, $id ni vocabularios ejecutables. La validación de formats está activada en las pruebas. Schemas embebidos también se validan con el meta-schema 2020-12; consistencia entre rangos y compatibilidad de mappings corresponden a T06.
|
||
|
||
Valores: exactamente `{ "path": "/results/buro/score" }` o `{ "literal": 70 }`. Contextos permitidos: /request/data, /event/data, /results y /actor. Paths usan JSON Pointer y escapes ~0/~1; no son expresiones ejecutables.
|
||
|
||
Condiciones:
|
||
|
||
- EQ, NEQ, GT, GTE, LT, LTE, IN: op, left y right.
|
||
- EXISTS: op y value con path (no literal).
|
||
- AND/OR: op y args con al menos dos condiciones ordenadas.
|
||
- NOT: op y arg con una condición.
|
||
|
||
T05 implementa tipos, BigDecimal, cortocircuito, null frente a ausencia, IN homogéneo, análisis de intervalos simples y UNIQUE ambiguo. Ver [evaluador y límites](../specs/DECISION_EVALUATOR.md); el parser/publicador completo corresponde a T06. UNIQUE requiere defaultOutput; FIRST sólo se habilita seleccionándolo explícitamente como hitPolicy.
|
||
|
||
Transiciones: id/from/event/allowedRoles/actions. Una ruta fija usa to + outcome; una ruta calculada usa decision + destinations y el output seleccionado es el outcome de negocio. No pueden mezclarse. Actions están ordenadas y pueden estar vacías para una captura pura. Guard es opcional y se evalúa antes de aceptar el evento. Updates opcionales se aplican tras las acciones/decisión.
|
||
|
||
`updates.target` es un JSON Pointer no vacío relativo al contenido de request.data. `/validaciones/buro` actualiza ese campo dentro de data; nunca apunta a identidad, estado, revision o ACL de la solicitud. No se puede reemplazar la raíz. T06 rechazará destinos solapados/duplicados y comprobará que el resultado cumple dataSchema antes del commit.
|
||
|
||
Actions del MVP: REGISTER_DOCUMENT, INVOKE_INTEGRATION y NO_OP (sólo simulación, no publicable). No admiten URL, headers, secretos, clases Java ni clasificación de efectos enviada por el editor. Catálogo de despliegue aporta estas capacidades. ContractVersion/profileVersion pueden omitirse en borrador y deben resolverse/fijarse al publicar. Un perfil desconocido se rechaza semánticamente.
|
||
|
||
Tareas: estado/evento/inputSchema/ui. DOCUMENT_UPLOAD exige documentType, acceptedMimeTypes y maxBytes (techo del DSL 100 MiB, sujeto a un límite operativo menor); FORM permite fieldOrder. La UI no sustituye restricciones backend. T06 debe exigir equivalencia del inputSchema de tarea y evento y compatibilidad del documentType con REGISTER_DOCUMENT. El servicio documental verifica MIME real, tamaño, pertenencia, checksum y antimalware en T13.
|
||
|
||
## Límites y fronteras
|
||
|
||
El schema aplica 200 estados, 500 transiciones y 50 acciones por transición; limita también colecciones auxiliares. Longitud en bytes de definición (1 MiB), datos (256 KiB), profundidad AST 20, total 1.000 nodos por decisión, unicidad por ID, alcanzabilidad, catálogos, roles y destinos son comprobaciones semánticas/de recepción pendientes de T06/T09. No confundir arrays únicos con unicidad por clave ni límites de JSON Schema con protección frente a cargas antes de deserializar.
|
||
|
||
BureauResult exige score numérico y consultationId; no asume rango universal 0–100. DocumentValidationResult sólo admite VALID/INVALID: fallos técnicos no se convierten a INVALID. CustomerResult exige customerId cuando found=true. Son ejemplos de contrato interno, no conexión real a proveedores.
|