Skip to content

Repository files navigation

vdi2770-validate — check VDI 2770 document containers before they ship: offline, deterministic, and every finding tells you how to fix it. AI proposes, rules judge, people decide.

CI PyPI rules license

 Apache-2.0 · Python 3.9 · 3.12 · 3.13 · pure Python, nothing compiled · the check opens no socket

Ten seconds · What it catches · Where it sits · Five doors · What it will not tell you · Roadmap · Two layers · In your product

Ten seconds

Real vdi2770-validate output: error F1, a file named in the metadata is not in the container, with the metadata line it is declared on and the remedy; error Z7, the documentation container has no VDI2770_Main.pdf, with its remedy; then a line saying how many findings follow, and one saying how much of the delivery was read.

$ pip install vdi2770-validate

Three parts, every time: what is wrong → the evidence as read from your file → how to fix it. A rule without a remedy does not ship.

Tip

No install for a first try: uvx vdi2770-validate check YOUR-CONTAINER.zip runs it in a throwaway environment. No container to hand either: vdi2770-validate check --example checks the example the package carries, the reference implementation's own.

VDI 2770 is how manufacturers hand over technical documentation in the process industry: PDFs bundled into ZIP "document containers" with an XML metadata file, those bundled into a "documentation container". Operators increasingly ask for it in purchase orders, and a container rejected on intake holds up a delivery. The reference implementation is a Java library and web service; this is a small offline CLI you can drop into a CI job.

Important

Unofficial. Not affiliated with VDI, the Digital Data Chain Consortium, or IDTA. Names are used descriptively.

It exits 0 when it found no error, 1 when it found at least one or could not read a path you gave it, and 2 when it could read none of them. A warning does not move the number, so 0 means no error, not nothing to look at — the report says what it found either way. An intake gate that wants none of the warnings either can say --fail-on warning; the default is error, because a warning here is a warning on purpose.

The whole session the picture above is taken from, checked line by line by the test suite

The rest of this page runs on containers that ship here, so to follow along:

git clone https://github.com/dev365code/vdi2770-validate
cd vdi2770-validate
$ vdi2770-validate check corpus/examples/missingdocuments/folders.zip
folders.zip
  error  F1  A file named in the metadata is not in the container
         at folders.zip!/VDI2770_Main.xml:56:2
         'VDI2770_Main.pdf' is declared but not in the archive
         per the reference implementation - observed there, not verified against the standard (REP_007)
         -> Add the missing file to the container, or remove its DigitalFile entry from the metadata. The two must agree.
  error  Z7  The documentation container has no VDI2770_Main.pdf
         at folders.zip
         per the reference implementation - observed there, not verified against the standard (REP_025)
         -> Add the main document as VDI2770_Main.pdf at the root of the documentation container, next to VDI2770_Main.xml.
  warn   M13  One identifier is called both a type and an individual
         at folders.zip!/VDI2770_Main.xml:19:2
         'ABC1223' is declared as Individual, Type in this delivery (folders.zip, folders.zip!/456-29201/, folders.zip!/AB393/); an identifier names one kind of thing
         per this tool's own rule
         -> Decide which the identifier names and say the same thing in both places: ObjectType="Type" for a product model, ObjectType="Individual" for one manufactured item. If the two documents really are about different things, give them different identifiers.

  … 1 more Z9 warning, then P4 and P4

  2 error(s), 2 warning(s), 2 note(s)
  read 3 of 3 archives, 3 of 3 metadata files

This tool does not verify PDF/A conformance. It reports the claim a file makes
about itself where it finds one; only a PDF/A validator can say whether that
claim is true.

The last line is there on every report. 0 error(s) says what was found; that line says how much of the container was reached, counted over the names the archive itself lists — so a delivery with a part this tool could not open cannot come back looking like one it read end to end.

What it catches

You ship this vdi2770-validate says
metadata that declares VDI2770_Main.pdf, and an archive without it error F1 — with the line and column of the declaration that has nothing behind it
a class id outside the twelve VDI 2770 publishes error M2 — the id is quoted back, and the twelve are listed
documents delivered as folders instead of nested containers warn Z9 — and each folder is read as the container it holds, its findings under the folder's path; error Z13 only for one this tool could not open, said plainly as this tool declining to look
a member name that would escape the extraction directory error Z4 — refused, and nothing was ever written to disk to escape into
a declared PDF the scan could not confirm is a PDF error P5 — reported as not confirmed, never as not a PDF
a main document that refers to documents the handover does not contain error M11 — each dangling reference named, and silent when this tool did not read the whole delivery, unless what it did not read is a file a document declares

Every code carries a remedy and the source its requirement comes from — docs/rules.md lists all of them.

Where it stands

Coverage: 41 of 44 rules have a fixture pair; Explanation: what is wrong, evidence, remedy, source, line; Report contract: schemaVersion, golden, exit codes, schema; Entrances: command line, library, single file, Action, browser; Input safety: read budgets, advisory, own mutations, encodings; Upstream: pinned by commit, checked weekly

Six things this tool holds itself to, measured on the code this page describes, against the conditions 1.0 was held to. The picture is drawn from docs/capabilities.json, and every item it marks done names a file in this repository that says so; the cases behind each axis are in docs/what-it-catches.md.

Where it sits

flowchart LR
    A[Authoring · CAD · ERP · supplier documents] --> P([documentation container .zip])
    P --> C{{vdi2770-validate check}}
    C -- "exit 0 · with what was reached" --> D[Operator intake · plant handover]
    C -- "findings, each with a remedy" --> A
    classDef judge fill:#2f5d8a,stroke:#8fb8dd,color:#e8edf2
    class C judge
Loading

Five doors, one judgement

Door For One line
Terminal build scripts, people vdi2770-validate check handover.zip
Python your own tooling import vdi2770 / import vdi2770_validate
Single file closed networks, approvals python vdi2770.pyz check handover.zip
GitHub Action a workflow that blocks a bad delivery uses: dev365code/vdi2770-validate@v1.1.0
Browser a machine where nothing may be installed open vdi2770.html, drop the container on it

No route to a package index? No pip, no virtual environment, no rights to make one? Carry one file in instead. It still needs a Python — that is the one thing it cannot bring — and nothing else.

Take it from the latest release, where its SHA-256 is printed beside it, or build the one this working tree produces:

python tools/build_zipapp.py --check     # writes dist/vdi2770.pyz and runs it

With the locked wheels already downloaded, --wheels DIR builds it without a network.

Pure Python, nothing compiled, and an ordinary readable zip: whoever has to approve software entering the network can open it and read every line, which matters more than convenience when the approval is the hard part.

Nothing may be installed at all, not even a Python? Open one page instead. vdi2770.html carries the checker, its rules and a Python built for the browser, and it checks the container inside the tab: once the page has loaded it makes no network request, and opened from a disk it makes none at all. Its report is what vdi2770-validate check --no-bundle prints on the Python the page carries, CPython 3.13.2, at a UTF-8 console -- byte for byte, with the same exit code -- and the JSON it saves is what --json prints there. The container is held in the tab's memory while it is checked, so a very large delivery is one for the command line.

Take it from the latest release, beside the single file, or build the one this working tree produces:

python tools/build_browser.py            # writes dist/vdi2770.html
python tools/browser_gates.py            # opens it in a browser and holds it to the above

The second needs Playwright and the Python the page carries, to the patch release, because it runs the command beside the page and compares the two, and a patch release can change what the standard library accepts.

Exit codes and a versioned JSON report make it a CI gate in one line.

In a workflow

- uses: dev365code/vdi2770-validate@v1.1.0
  with:
    paths: handover.zip nameplate.zip

The step fails when the checker does, which is what a gate is for. If you want the number instead — 0 clean, 1 a finding or an unreadable path, 2 nothing readable at all, 3 the install disagreed with itself, 64 a mistyped command line, 70 this tool failed on a file — ask for it:

70 (EX_SOFTWARE) is an exception raised by this tool's own code while checking a file, wherever the tool caught it — out of the check, or inside it and reported as X5 — so a gate can tell a finding about your delivery from a failure of ours. A file that cannot be read — a path that does not exist, one you may not open — is not ours: 2 when nothing in the run could be read, 1 beside a path that could.

- uses: dev365code/vdi2770-validate@v1.1.0
  id: vdi
  with:
    paths: handover.zip
    fail-on-finding: "false"
- run: echo "the checker said ${{ steps.vdi.outputs.exit-code }}"

exit-code is filled in either way — a failed step does still publish it, which this repository's CI measures on every push rather than taking on trust. What fail-on-finding: false buys you is a step that succeeds, so the job carries on to whatever reads the number; with the default you would add continue-on-error: true to get that far.

Input What it is
paths the containers to check, separated by spaces
version which release to install. Left empty it is the ref you pinned — @v1.1.0 installs 1.1.0 — falling back to the version the action's own checkout publishes, so @main may name a version not on the index yet. The rules travel with the engine: an older version is an older rule set and may return a different verdict. Four releases cannot be asked for at all: 0.8.0, 0.8.1, 0.8.2 and 0.9.0 name their engine with a floor, so installing one brings a newer engine beside it and the tool refuses to judge a pair that disagrees with itself (exit 3). Ask for 1.0.0 or later, which closes every advisory this repository lists
pyz a vdi2770.pyz you already have. Given, this action installs nothing and fetches nothing
sha256 the hash pyz must have. For a file carried into a closed network; the default path does not need it, because pip checks the index's own hashes
args anything else for check, such as --json
fail-on-finding true by default: a non-zero verdict fails the step. false succeeds and fills exit-code
Output What it is
exit-code what the checker returned: 0 nothing at the fail severity, 1 a finding or an unreadable path, 2 nothing could be read, 3 the install disagreed with itself, 64 a usage error, 70 this tool failed on a file
pyz the single file this step ran, when it ran one; empty on the default path, which installs instead
version the release this step decided to run -- from version, from the ref you pinned, or from the tree the action came from; empty when pyz is given, since nothing was installed and the file answers --version itself

When the action cannot run the checker — no Python, a pyz that is not there, a sha256 that does not match, a version it cannot work out, an install that fails — or the checker ends with a code it does not define, such as 127, the step fails whatever fail-on-finding says, and exit-code is empty.

The runner needs a Python on PATH (python3 or python); actions/setup-python is the usual way to be sure.

By default the action installs the released checker from PyPI and runs it — pip checks what the index serves against the hashes the index publishes, and publishing to the index is something the release workflow does by itself. Release assets are attached by a person, and a person can forget; the reader's first five releases and the command's first seven carry none, so the default path does not lean on one.

If your runners cannot reach an index at all, commit the single file and point pyz at it: the step then installs nothing and fetches nothing, and sha256 holds that file to a hash if you want the step to check rather than trust. The checker opens no socket for any input either way; reaching the index is the action's doing, not the tool's.

What it will not tell you

Whether a PDF really is PDF/A. That needs a full PDF/A validator such as veraPDF. This tool reports what a file claims, which catches the common failure: files that never claimed at all. It says so on every line where it matters, and the JSON output is one document for the run — a list with an entry per path you gave, each carrying that path. An entry for a container that was checked also carries "pdfaVerified": false; a path that could not be opened at all carries "unreadable" and no verdict — no pdfaVerified, no counts, no findings — because there is nothing to report about a file nobody read. It carries the three fields that say what produced the run, like every other entry: a run where some entries can be version-checked and some cannot is worse for a consumer than one where none can.

Page-count comparison is a bounded read, and reaching a limit is reported as P6 on the tool axis; scope gives the limits.

What is inside a file the metadata declares. A .zip a document declares as one of its files is that document's content, the way a PDF's pages are, and nothing in it is judged as VDI 2770 — Z14 says so on the report. For one this reader opens, how the archive stores its entries is still read. A declared .zip this reader opens whose own root holds VDI2770_Metadata.xml or VDI2770_Main.xml is a container all the same, and is judged as one — Z11 says it should not be inside a document container. One the depth limit keeps closed is reported as Z14: its entries are not read and it is not judged as a container.

What the guideline text says. It is sold by DIN Media and was not read. Every rule names a free source instead, or says the judgement is ours and explains itself. The rest of the refusals are in docs/scope.md.

If you want the parsed container and not a verdict, take the reader on its own — two layers, below. iirds-validate is the same idea for iiRDS, if that is the handover format you are on.

Why trust the answer

  • Deterministic and offline. No network at runtime, proven by a test that counts socket attempts rather than waiting for one to fail — a tool that reaches out and falls back quietly on error would satisfy the weaker check. Nothing is extracted to disk; a supplier archive does not get to pick a path on your filesystem or expand an XML entity.
  • Rules are data. rules.json, rendered as docs/rules.md — each rule carries where its requirement comes from, a remedy sentence, and — where the reference implementation checks the same thing — the message keys it uses.
  • 41 of 44 rules have a minimal fixture pair — a container that violates the rule and a conforming one differing in as little as a single member. The other three cannot have one: two report a fault in this tool rather than in a file, and the third fires on every conforming container. A rule that fires nowhere fails the build, and every rule here has been checked against its own mutations.
  • Rules cannot reach the parser. A test fails if a rule module imports zipfile or an XML library, so a rule cannot accidentally check how a document was spelled instead of what it says. Rules may read the readers' constants — the reserved file names, the container kinds — but not call a parser.
  • Every published sample container, judged in the open. The reference repository's sample files are in this repository unmodified, and docs/official-samples.md is this tool's verdict on each container among them, with where every rule that fired takes its requirement from -- written from the tool itself, so the build fails when the two differ.
  • Recorded disagreements. Where the free sources disagree, this project picks one reading, marks the finding, and writes down the question in docs/divergences.md.

Roadmap

An item moves right when it is built and checked, not when it is decided.

timeline
    title Where vdi2770-validate is going
    Shipped : Reader and rules, same version, one tag, one install
            : 44 rules, each with a source and a remedy
            : Versioned JSON report, exit codes, single-file offline build
            : Browser-local checking — no install, and the file never leaves the machine
    Building : Deeper documentation-container checks
    Planned : An obligation index — what the guideline asks for, and how much of it is covered, once its text is read
            : Cross-checks with neighbouring handover standards
Loading

One install, two layers

pip install vdi2770-validate

brings all of it, and there is nothing else to do. That command is also what anybody already using this tool types, and it goes on meaning what it meant.

The layering is real and it is inside one package now. vdi2770 opens a container, refuses what it should refuse, and hands back a typed model with a line number on every node — it decides nothing, it names no rule, and a test fails if one of those modules so much as mentions a rule id. vdi2770.validate is that model plus an opinion, and a rule set is an opinion: if your customer's supplement disagrees with ours, or you want the parsed model for something other than a verdict, take the readers and leave the opinion behind.

pip install vdi2770
from vdi2770 import read_container_file

container = read_container_file("corpus/examples/container/documentcontainer.zip")
print(container.kind, len(container.members))

That install has no dependencies, which is a property worth keeping rather than an accident: the schema check is the one part that needs a parser, and it is an extra. pip install "vdi2770[validate]" adds it.

That install carries no command — the vdi2770-validate executable belongs to the distribution of that name, and this one deliberately does not pull it in. Run it as a module:

python -m vdi2770.validate check YOUR-CONTAINER.zip

The command comes with pip install vdi2770-validate, and it is the same code either way. The reason the command lives there rather than here is the upgrade: whichever distribution owns that file, pip writes it when that distribution is installed and deletes it when that distribution's record is removed, so an owner that changes between releases means an upgrade in which the order of two steps decides whether the command survives. This owner does not change.

A machine that installs the readers alone and then asks for a schema check is told so by name — the report carries X0 and says in its own summary that one of those errors is this tool declining to look, not a verdict on the container.

What is stable here, and what is not

From 1.0.0, breaking anything below takes a new major version, except a verdict: verdicts move across releases, the way the first item says. Through 0.x the packaging moved under minor versions: 0.8.0 moved the validator inside the reader, with the old name kept working as an alias, which changed how the tool is installed and which distribution owns the executable.

What a build script can rely on:

  • The verdicts, within a release. Across releases they move, and never quietly: the CHANGELOG section for the release that moves one names it. 0.7.0 is the example to read — Z6 went from warning to error there, and F2 and Z8 stopped firing on files inside folders. 42 of the 44 fire on a container in the corpus or fixtures. Comparisons with the reference implementation publish divergences and identify inputs not yet compared; the other two — X0 and X5 — say that this tool could not run a check, which no container can cause, and they are exercised by breaking the installation, by making each step raise, and by making the reader hand back nothing for a member it accepted.
  • The exit codes. 0 no error, 1 at least one finding at the chosen severity or an unreadable path, 2 nothing could be read at all, 3 this tool refused to judge because its two halves disagree about which release they are, 64 a command-line usage error — a bad option, a missing argument, an unknown subcommand — and 70 this tool's own code failed on a file, raised out of the check or caught inside it and reported as X5: a failure of ours, not a verdict on the delivery. A run whose reader goes away — | head — ends by SIGPIPE where the platform has one and with 141 where it does not, because it did not finish. 3 is not a verdict on any container.
  • The command line. vdi2770-validate check <container> and its options. There is one console script, and two module doors that run the same code: python -m vdi2770_validate for anything written against the old name, and python -m vdi2770.validate, which is how a pip install "vdi2770[validate]" is run because that install carries no command.
  • The report. The JSON a run writes, and the schemaVersion inside it.
  • The reader's names. What import vdi2770 exports, and their signatures, as packages/vdi2770/API.json records them.
  • The old import name. import vdi2770_validate resolves to the same objects as vdi2770.validate rather than to copies of them.

What is not stable: which distribution ships which file, the wheel layout, and the module paths under vdi2770.validate. A pickle written through the new path names the new modules, and no aliasing carries that across.

What changed in 0.8, and what it means for an installation you already have

The readers and the rules used to be two distributions that had to match. From 0.2.0 to 0.6.0 vdi2770-validate asked for the reader with a range, which let the pair be half-moved, and 0.7.0 pinned it exactly. They are one distribution now. vdi2770-validate is the old import name kept working: an alias that makes it the same object as vdi2770.validate, asking for vdi2770[validate]==1.1.0 — its own version, exactly. A floor would stop an older engine and let a newer one install beside it, and halves that disagree about which release they are do not judge. (This page follows the working tree, so the number is the release being prepared; each release on PyPI carries its own.)

pip install -U vdi2770-validate is the upgrade, and it is now an ordinary one. On an installation of 0.7 that same command used to leave a tool that could not run: the two distributions shared file paths, so installing one wrote files the other's record still listed, and removing either took them away. The new arrangement has no shared paths — a gate compares the built wheels against the ones already published to say so — and the upgrade ends with everything at the new version.

What has not gone away, because saying so would be untrue: an installation that takes half the upgrade still has old rules in it. If you move the engine forward and leave the old vdi2770-validate behind, that older package keeps its own command and goes on judging with its own rules — honestly, under its own version number, which is what its reports say. And if the halves that are loaded disagree about which release they are, the tool refuses to judge rather than sign a verdict it cannot account for: exit 3, on a line beginning vdi2770-validate: INSTALLATION. That is not a verdict on any container — it is this tool saying it cannot account for itself, and it belongs in a bug report against this project rather than against a supplier's delivery.

Everything written against the old name goes on working — import vdi2770_validate, from vdi2770_validate.cli import main, python -m vdi2770_validate and the command itself. One thing cannot be carried across: a pickle written through the new module path names vdi2770.validate.…, and code that only has the old release cannot read it.

When something looks wrong

What a bug report carries, and what it does not. vdi2770-validate check FILE --bug-report writes a diagnostic bundle for that run: it prints a summary of it, writes it where you ran the check, and sends nothing; --show-bundle prints all of it and writes nothing. It carries the shape of the file -- its size and SHA-256, and for each member of the archive its size, compression method and flags, never its name -- what the run said by rule code and count, the release and Python it ran on, and a sentence of your own if you add one with --note. It does not carry a member's name, a file path, any value or identifier from the metadata, a language or product name, a finding's message, detail or remedy, any byte of a PDF or of the XML, a ZIP comment or what an extra field holds, an environment variable's value, or a user or host name. When this tool stops on a file with an error of its own, it writes the same bundle without being asked, and says so; --no-bundle stops that. When one of its checks fails and the run goes on, the report says so as X5, and a sentence after it says how to report it.

Attach the bundle to an issue; do not attach the file itself, since an issue is public.

Releases and version numbers

This is 1.x. A release goes out when a unit of judgement is ready rather than on a calendar. Breaking anything What is stable lists — the exit codes, the command line, the report, the reader's names, the old import name — takes a new major version; how a verdict moves is below. Through 0.x the packaging was not the contract: 0.8.0 moved the validator inside the reader, and 0.9.1 changed how this package asks for it.

Releases come in batches rather than one per fix. Three things do not wait for a batch: a security fix, a wrong verdict (a conforming container refused, or a non-conforming one passed), and following a change in the standard. SECURITY.md is where to report the first of those.

A minor release moves judgement — a rule added, a reading corrected, a condition that was silent becoming a finding, a severity moved. That release's CHANGELOG section names every verdict that moves and, where an exit code moves with it, says so in a paragraph addressed to whoever gates a build on the number. That is the paragraph to read before upgrading; it is the one place this project undertakes to be exhaustive.

A patch release repairs — and six of the seventeen patch releases of this package changed what a pipeline sees:

  • 0.5.1 asked for a fixed reader instead of merely permitting one. Until it, vdi2770-validate==0.5.0 installed beside the unfixed reader, so the hang 0.5.0 announced a fix for went on happening to anyone who took that fix.
  • 0.8.1 bounded what one member of an archive may cost, and began refusing a member compressed with a method it does not expand — naming the method, and the two this reader does expand.
  • 0.8.2 turned a PDF it had silently skipped into an X5 error, so a container that came back clean can come back with a finding against that file.
  • 0.9.7 reads an archive from the start of the file, so a container cut short, or with bytes in front of it, which was read as an archive it held and passed, is now Z1, not a readable ZIP archive.
  • 0.11.1 compares page counts previously declined because of an unrelated xref entry outside Size. A mismatch now produces a P6 container warning; matching declarations now pass with --fail-on warning.
  • 1.0.1 keeps M11 and M12 silent when the delivery holds an archive this tool did not open, other than one a document declares as a file, or metadata it read and did not model, as What it catches says M11 is, instead of reporting the documents in them as missing. It also reads as one name the two spellings an entry's header and its Unicode Path field give it when they differ only in how the same characters are composed (canonically equivalent, compared in NFC wherever Unicode 3.2 had every character, so that every Python compares them alike), where 1.0.0 refused that entry as Z12 and missed the file it holds — so a container with nothing else wrong exits 0 now.

The other eleven moved no verdict at all: 0.9.1; 0.9.2, which repaired what a delivery costs to check and left every finding, every location and every exit code exactly where they were; 0.9.3, which bounded how large a report can grow, leaving every summary count and exit code where it was and adding one key to the JSON, listingStopped, empty unless a rule's listing reached its size budget; 0.9.4, which counts that budget in what a report prints rather than in the characters it stores; 0.9.5, which keeps every sentence of the text report on its own line and charges the budget for the console that prints most; 0.9.6, which keeps a value the sender wrote from deciding how a line begins and measures only a finding that can fit; 0.10.1, which carried only this project's pages about itself; 0.10.2, which writes a bug report a person can attach and leaves every verdict where it was; 0.10.3, which gives every rule a container can break a fixture pair; 1.0.2, which rewords the Z12 title and the F1 message for an entry refused for where its bytes lie, and moves no verdict; and 1.0.3, which moves an empty archive's Z2 to obligation ours and says why, says which Z1 reasons are this reader declining what ZIP allows, rewords the Z1 sentence for an archive its zip64 locator splits, and moves no verdict. A patch is a smaller promise than a minor release; it is not a promise that nothing your pipeline reads can change.

Pin the version you validated against, and pin it exactly. A rule added is a verdict your pipeline has not seen, and the point of a validator is that the answer it gives today is the answer it gave when you signed off on it. From 0.9.1 this package names the engine it was built with exactly, so vdi2770-validate==1.1.0 installs one matching pair.

Four releases cannot be pinned that way: 0.8.0, 0.8.1, 0.8.2 and 0.9.0 name their engine with a floor, and a floor stops holding the moment a newer engine exists. Move to 1.0.0 or later, which pins both halves exactly — and pinning one of those four by both names is not a way to stay put, because every release from 0.8.0 to 0.9.1 is inside the range of GHSA-f9xw-89gp-x52p:

pip install "vdi2770-validate==1.1.0"

Move there from any release, not only those four. Every release up to 0.9.6 is inside GHSA-h676-59p4-6632, every one up to 0.9.5 inside GHSA-3pfq-57fx-w4q5, every one up to 0.9.4 inside GHSA-6hqr-phm3-chpf, and every one before 0.9.2 inside another advisory as well — GHSA-xp97-jcmj-h45f reaches every release up to 0.8.0, and GHSA-f9xw-89gp-x52p every release from 0.8.0 to 0.9.1 — so 0.9.7 is the first release outside those five. GHSA-62p8-4642-mwfp reaches releases up to 0.10.3 and is closed in full by 0.11.0. GHSA-fv32-69r4-3fm7 reaches every release of both up to 0.14.0 and is closed by 1.0.0. The pin runs one way: the engine does not name this package back, so upgrading the engine alone beside an older command leaves a mismatched pair, and a command from 0.8.0 on refuses that pair rather than judging with it (exit 3).

1.0 means two things. This page says which parts of VDI 2770 are checked and to what depth, so that "checks VDI 2770 containers" is not a phrase you have to read the source to size: What it catches and What it will not tell you above, the 44 rules in docs/rules.md with where each one's requirement comes from — the XSD VDI publishes free, the class table IDTA 02004 publishes, the mechanics of ZIP and XML, what the MIT reference implementation was observed to do, or a judgement of this project's own with its reason — and the limits in docs/scope.md. What it cannot say is which clauses of the guideline those are: the guideline is sold by DIN Media and was not read, so an index of what it asks for, and how much of that is checked, waits on its text. And the report's schemaVersion is 1, on the list above, and 1.0 commits to not changing it. Neither meaning is that the rule set is finished.

What 1.0 waited for besides is drawn under Where it stands; in words:

Before it called a release 1.0, this project asked of itself — Coverage: 41 of 44, every rule that can have one; Explanation: what is wrong, in one sentence · the evidence as read from the file · a remedy, for every rule · the source of every rule's requirement · the line, for every metadata finding; Report contract: schemaVersion in every report · a golden report held by a test · exit codes under test · a field-by-field schema page; Entrances: command line · Python library · single file, nothing to install · GitHub Action · browser, nothing installed; Input safety: read budgets, per member and per archive · a security fix ships with an advisory · tests verified against their own mutations · declared encodings read without loss; Upstream: upstream corpus pinned by commit · checked weekly for change.

The classification table, and a disagreement

VDI 2770 defines twelve document classes. Two sources publish that table for free — IDTA 02004 v2.0.1 Table 1, and the MIT reference implementation. Both renderings of every name are stored, so you can check rather than trust: they agree on all twelve German names and disagree on five English ones (02-03, 02-04, 03-01, 03-04, 04-01). So matching here is keyed on the class id and the German name, and an English name never fails a document — it produces a note that shows both renderings.

$ vdi2770-validate classes
02-03  Bauteile                                   Assemblies   [sources disagree]
      English — IDTA 02004: 'Assemblies'   reference impl: 'Components'

Details in docs/divergences.md.

Using this validator in your product

Embedding, versions and support

Apache-2.0. You may embed it in commercial products, ship it to your customers and run it inside closed networks; keep the LICENSE, NOTICE and THIRD_PARTY.md files with it. A run makes no network requests and uploads nothing. The surfaces you can build on are the ones What is stable lists — the exit codes, the command line, the report, the reader's names, the old import name — and a change that breaks one of them comes in a new major version, announced as a breaking change in the CHANGELOG. Everything else may change between releases.

Releases follow semantic versioning, and the reader and the rule set move together under one tag. Released files are not deleted, and a release with a security problem stays installable, so a version you have pinned keeps installing; SECURITY.md lists the advisory that reaches it and the release that closes it. When the free sources a rule is built on change, the CHANGELOG says what changed in the judgement and why.

The software is free and stays free, and there is no paid tier of the judgement itself: a free run and a supported run give the same result on the same file. Professional support is available for the work around it — update guarantees when the sources change, backports to a version you have frozen, help with embedding, and change-impact notes for your product. Contact: zero8004paz@gmail.com. For security reports see SECURITY.md.

Licensing

Apache-2.0. The VDI 2770 guideline text is sold by DIN Media and was not read, quoted, or paraphrased. Every rule names its source in rules.json instead: the schema VDI publishes free, a freely published table, ZIP and XML mechanics, the MIT reference implementation (observed there, not verified against the standard), or a judgement of our own that has to explain itself. See docs/licensing.md and NOTICE.

Contributions take a Signed-off-by line (DCO).

Related

iirds-validate — the same idea for iiRDS. standards-watch — a daily watch on these standards.

Releases

Sponsor this project

Packages

Contributors

Languages