orquestador/schemas/README.md

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; 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.