The first executable building block of automated interface quality

Automatically Validate JSON Files: From JSON Schema to CI

The larger question—how to test APIs, files, and legacy interfaces automatically—is covered by the English Project Page. This article stays deliberately focused on the completed first iteration.

The contract for our delivery

We start with a small delivery that is easy to understand. The data is synthetic and stored as fixtures in the repository: inputs that are reused unchanged by every test run.

{
  "deliveryId": "DEL-1001",
  "quantity": 3,
  "email": "ops@example.org",
  "address": {
    "street": "Hauptstraße 1",
    "postalCode": "10115",
    "city": "Berlin"
  }
  }

The matching schema defines required fields and allowed values:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "delivery.schema.json",
  "title": "Delivery",
  "type": "object",
  "additionalProperties": false,
  "required": ["deliveryId", "quantity", "email", "address"],
  "properties": {
    "deliveryId": { "type": "string", "minLength": 1 },
    "quantity": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "address": { "$ref": "refs/address.schema.json" }
  }
}

quantity must be an integer of at least one. The string "three" does not satisfy that rule. additionalProperties: false rejects fields that are not part of this object. The address has its own local contract in refs/address.schema.json; its five-digit postal code is a narrow example rule, not an international address model.

Validate JSON files yourself

You need Git and JDK 21. The Maven Wrapper starts Maven, so a separate Maven installation is not required. The first build downloads Maven and dependencies; validation with the built JAR and local schemas does not need network access. The source example is tied to the tested commit d794151.

Clone the fixed source state

Use a directory where zeus-interface-quality-iteration-1 does not already exist:

git clone https://github.com/gzeuner/zeus-interface-quality.git zeus-interface-quality-iteration-1
cd zeus-interface-quality-iteration-1
git checkout --detach d79415111b7d830f2aa4741f7bec647a2652535c

A “detached HEAD” message is expected: you are inspecting a fixed commit rather than a moving branch.

Windows / PowerShell

.\mvnw.cmd -B package

$iqJar = "target/zeus-interface-quality-0.1.0-SNAPSHOT.jar"
$iqFixtures = "src/test/resources/fixtures"

java -jar $iqJar validate --schema "$iqFixtures/delivery.schema.json" --input "$iqFixtures/valid-delivery.json" --report json
$LASTEXITCODE

java -jar $iqJar validate --schema "$iqFixtures/delivery.schema.json" --input "$iqFixtures/invalid-wrong-type.json" --report json
$LASTEXITCODE

java -jar $iqJar validate --schema "$iqFixtures/delivery.schema.json" --input "$iqFixtures/malformed.json" --report json
$LASTEXITCODE

Linux / macOS

./mvnw -B package

iq_jar="target/zeus-interface-quality-0.1.0-SNAPSHOT.jar"
iq_fixtures="src/test/resources/fixtures"

java -jar "$iq_jar" validate --schema "$iq_fixtures/delivery.schema.json" --input "$iq_fixtures/valid-delivery.json" --report json
echo "$?"

java -jar "$iq_jar" validate --schema "$iq_fixtures/delivery.schema.json" --input "$iq_fixtures/invalid-wrong-type.json" --report json
echo "$?"

java -jar "$iq_jar" validate --schema "$iq_fixtures/delivery.schema.json" --input "$iq_fixtures/malformed.json" --report json
echo "$?"

Use --report text for readable console output; text is also the default. For malformed.json, the error goes to stderr and there is no JSON report on stdout. A missing input or schema path also returns exit code 2.

How to read the JSON report

The valid delivery returns status: VALID, valid: true, and an empty findings list. The wrong-type fixture returns:

{
  "status": "INVALID",
  "valid": false,
  "findings": [
    {
      "instancePath": "/quantity",
      "schemaPath": "/properties/quantity/type",
      "keyword": "type",
      "message": "string gefunden, integer erwartet"
    }
  ]
}

instancePath identifies the data location. keyword identifies the violated rule. schemaPath identifies the validator’s evaluation path; references may include $ref sections. Findings are sorted deterministically. The current implementation’s human-readable messages are German even on an English host, so automation should use status, paths, and keywords rather than message wording.

What the review uncovered

The first valid and invalid fixtures were green. That was not enough. A validator must also handle inputs the happy path never produces.

The whole file counts

Empty files, whitespace-only files, trailing content after a JSON document, and duplicate object keys are technical errors with exit code 2. The JSON value null remains a valid JSON document; the schema decides whether it is allowed. Duplicate keys are rejected while reading so a later value cannot silently hide the original ambiguity.

The contract can be wrong too

An object such as "required": "deliveryId" is valid JSON but misuses the schema keyword: required expects an array. Schema files, including local references, are validated against the bundled Draft 2020-12 meta-schema. A broken contract must not be reported as a broken delivery.

The real command must match the example

A report-writer unit test does not prove that the actual validate command produces the same content. An end-to-end test compares the CLI result with a frozen report, including under an English host locale. The important question is which failure assumptions the tests exercise—not how many tests happen to be green.

Why schema references stay local

A $ref avoids duplicate definitions, but it can introduce extra files or network access. Referenced schemas must therefore be regular files inside the actual directory of the selected root schema. The implementation checks normalized and resolved paths, rejects symbolic-link escapes, and rejects HTTP references or foreign hosts before retrieval.

The HTTPS value in $schema names the dialect; the matching meta-schema is bundled with the library. The validation run does not need internet access.

Technology-neutral with a small Java core

Java 21 and one Maven module are enough for this iteration:

“Technology-neutral” means library details stay behind project interfaces, not that Java becomes language-neutral. Spring Boot is not forbidden, but this local CLI needs neither a server nor a server runtime.

What the automated evidence shows

The original GitHub Actions run at commit d794151 passed all 36 tests on Linux without failures or skips. On Windows, 34 passed and two symbolic-link tests were skipped because the local permission was unavailable. The pipeline also builds the package and starts the generated JAR with valid and invalid fixtures; the invalid case must return exit code 1.

This proves the agreed local flow—not a complete interface test. A real SFTP counterparty, HTTP endpoint, business rules, and load behavior are outside this iteration.