Accepted5 Nov 2026
0024. Report what is wrong with a design as issues with stable codes and the Python engine's words
Context and Problem Statement#
The editor shows validation results next to the part they concern, the API returns them from
POST /validate and in a refused document's 422, and the CLI prints them. Today each is an
Issue: a severity, a stable code (edge.unknown_node), a message, the node, link or path it
concerns, and a hint. A document that cannot be read at all is a DocumentInvalidError carrying
its issues, its message the first error's. Stage 1 must give the same results, word for word
(ADR-0005).
How should the Java model report validation results?
Considered Options#
- An
Issuerecord and aDocumentInvalidExceptioncarrying issues, as the Python engine has - Exceptions per kind of problem
- Bean Validation's
ConstraintViolation
Decision Outcome#
Chosen option: "an Issue record and a DocumentInvalidException", because it is the contract the
web app and API clients already read, and a list of values is what a validator naturally returns.
Issue(severity, code, message, nodeId, edgeId, path, hint), built fluently (Issue.error(code, message).atEdge(id).withHint(hint)), written as the API writes it.DocumentValidator.validate(document)returns aValidationResult: the issues in the order the checks run (the Python order), each node's parsed config, and the request types each link carries. Errors stop a simulation; warnings do not.- Reading a document that does not fit the schema throws
DocumentInvalidException; each codec error (ADR-0022) becomes adocument.schemaissue naming the node or link it is in; a node config's errors becomenode.config_invalidissues; an upgrade's refusal becomes onedocument.versionissue. - Messages keep the Python wording, numbers written as Python writes them (ADR-0027). Codes are stable: they are what a client may branch on.
Consequences#
- Good, because the API can return the Java results unchanged, and the editor needs no change.
- Good, because a validator that returns values is easy to test: the golden files check every template and invalid fixture issue by issue.
- Bad, because the messages, written for Python's f-strings, are long format strings in Java. They stay next to their check, one per issue, so each can be compared with its Python line.
Confirmation#
GoldenParityTests checks validate_document on every template, every scenario's resolved
document and every invalid fixture; DocumentValidatorTests shows the shape of the results.