Technical article

JSON Schema validation routes, orchestrated by the CLI

LightESB-Camel validates inbound, outbound, and callback JSON against Draft 2020-12 schemas through jsonSchemaValidationProcessor. The CLI turns schema management into two deterministic commands: message schema generate derives the schema from the registered message model and writes the fixed file, then ai route apply commits the route together with exactly the schemas it references.

Sample: example/routes/security-validation/DemoSecuritySrv/v1.0.0Repository: github.com/nghxni/lightesb-camel

Hand-written schemas drift from the message model

Services already register their contracts: the current service's serviceInId and serviceOutId, plus a serviceCallbackId for callbacks. Deriving a schema by hand from msgStructure invites drift, and the callback direction adds a lookup trap — serviceCallbackId is a service ID, not a message ID; you must query the callback service first and take its serviceInId.

The CLI closes that gap. message schema generate wraps the server's JSON Schema preview API and writes only the returned data.schema into the service version directory; ai route apply then lands the reviewed route and the managed fixed schemas in one authorized call.

Three directions, one paired block

Three fixed directions

INPUT uses serviceInId with request-schema.json, after inbound and before business processing. OUTPUT uses serviceOutId with response-schema.json, before the response returns. CALLBACK uses the callback service's serviceInId with callback-schema.json, before invoking the callback. All three schemas live in the current service version directory.

Paired configuration

Every validation point is the same full block: set JsonSchemaPath, set JsonSchemaValidationMode, then process ref jsonSchemaValidationProcessor — only the file name and placement change. JsonSchemaContent, when present, takes highest priority; JsonSchemaId only aids identification and caching.

STRICT, LENIENT, SKIP

STRICT is the default and throws on failure; LENIENT continues and records X-Validation-Warnings; SKIP bypasses validation for temporary joint debugging, never as a business switch. Validation runs on com.networknt:json-schema-validator and defaults to JSON Schema Draft 2020-12.

Route XML is the only switch

Validation is enabled by adding the full block and disabled by deleting it — no global, service-config, or database toggle. Deleting a direction's block and re-applying removes that managed fixed schema; custom schemas are untouched.

Two commands, from message model to applied route

Generate the fixed schema file. --id and --file are mutually exclusive; --app-dir defaults to lightesb-camel-app and the target serviceName/serviceVersion directory must already exist. The command writes data.schema to --schema-file and never deploys or reloads the service:

lightesb message schema generate \
  --id <messageId> \
  --service-name DemoSrv \
  --service-version v1.0.0 \
  --schema-file request-schema.json \
  --yes --output json

--output json returns data.file, data.schema, data.warnings, and data.jsonSchemaPath — write the latter verbatim into the route. After review, one apply call commits the route with its referenced schemas; remote apply must carry both properties files, accepts only the three fixed schema names, and requires them to match route references one-to-one:

lightesb ai route apply --file DemoAiSrv-route.xml --save-remote \
  --service-name DemoAiSrv --service-version v1.0.0 \
  --route-file-name DemoAiSrv-route.xml \
  --resource-file common.config.properties \
  --resource-file service.config.properties \
  --resource-file request-schema.json \
  --return-logs --log-lines 80 --timeout 30 --yes --output json

Fail the request, not the route

Under STRICT a failed validation throws; wrap the processor so the caller gets a stable 400 body instead of a broken flow:

<doTry>
  <process ref="jsonSchemaValidationProcessor"/>
  <doCatch>
    <exception>java.lang.Exception</exception>
    <setHeader name="CamelHttpResponseCode"><constant>400</constant></setHeader>
    <setBody><simple>{"error":"VALIDATION_ERROR","message":"${exception.message}"}</simple></setBody>
  </doCatch>
</doTry>

Expected posture: valid JSON passes under STRICT; invalid JSON returns 400 or enters the global exception response; under LENIENT the flow continues with the warning visible in the response or logs.

Boundaries the CLI keeps

Schema content may only come from the API's data.schema — never generated, completed, or edited from msgStructure by a model. A non-empty data.warnings stops automatic apply and must be shown in full; only an explicit user confirmation continues.

With --save-remote the server backs up, writes, and waits for hot reload (bounded by --timeout). A FAILED, FAILED_ROLLED_BACK, or ROLLBACK_FAILED result prints operationId, deleted files, restore state, and logs, then exits with code 69 — the local candidate is kept and never retried automatically.

Schema validation guide Security validation sample