From 92187f85af2a19992e72d4ef4fb95bd72fd7b264 Mon Sep 17 00:00:00 2001 From: Lukas Gold Date: Tue, 1 Sep 2026 14:39:41 +0200 Subject: [PATCH] docs(validation): state what --offline pins and what nothing pins - the vendored meta-schemas are byte-exact; a document's @context is not - offline defaults to false, so two runs can disagree if a context moves - say why make validate passes --offline --- docs/how-to/validation.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/how-to/validation.md b/docs/how-to/validation.md index 74d9e72..53a3d0e 100644 --- a/docs/how-to/validation.md +++ b/docs/how-to/validation.md @@ -67,6 +67,18 @@ Exit code is 0 only when no check failed. Warnings do not fail a run. | `--json` | Emit the report as JSON. | | `--output FILE` | Write the JSON report to a file. | +### What `--offline` pins, and what nothing pins + +The vendored meta-schemas are byte-exact per version, so a released version cannot change +meaning between runs. A document's `@context` carries no equivalent guarantee. `offline` is +false by default, which is what lets a cross-directory or genuinely remote `@context` resolve +at all, but it also means two runs over the same document can disagree if a context it reaches +for has moved in between. + +`--offline` closes that gap by refusing to fetch, at the cost of failing on any reference that +is not already local or in the cache. That is why `make validate` passes it: the committed +fixtures are meant to give the same answer today and next year. + ## Meta-schema versions The meta-schemas belong to oold-schema. This package keeps a hand-curated copy of each released