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
$ pip install vdi2770-validateThree 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.
| 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.
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.
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
| 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 itWith 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 aboveThe 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.
- uses: dev365code/vdi2770-validate@v1.1.0
with:
paths: handover.zip nameplate.zipThe 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.
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.
- 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
zipfileor 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.
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
pip install vdi2770-validatebrings 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 vdi2770from 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.zipThe 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.
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.0is the example to read —Z6went from warning to error there, andF2andZ8stopped 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 —X0andX5— 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.
0no error,1at least one finding at the chosen severity or an unreadable path,2nothing could be read at all,3this tool refused to judge because its two halves disagree about which release they are,64a command-line usage error — a bad option, a missing argument, an unknown subcommand — and70this tool's own code failed on a file, raised out of the check or caught inside it and reported asX5: a failure of ours, not a verdict on the delivery. A run whose reader goes away —| head— ends bySIGPIPEwhere the platform has one and with141where it does not, because it did not finish.3is 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_validatefor anything written against the old name, andpython -m vdi2770.validate, which is how apip install "vdi2770[validate]"is run because that install carries no command. - The report. The JSON a run writes, and the
schemaVersioninside it. - The reader's names. What
import vdi2770exports, and their signatures, aspackages/vdi2770/API.jsonrecords them. - The old import name.
import vdi2770_validateresolves to the same objects asvdi2770.validaterather 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.
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.
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.
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.1asked for a fixed reader instead of merely permitting one. Until it,vdi2770-validate==0.5.0installed 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.1bounded 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.2turned a PDF it had silently skipped into anX5error, so a container that came back clean can come back with a finding against that file.0.9.7reads 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 nowZ1, not a readable ZIP archive.0.11.1compares page counts previously declined because of an unrelated xref entry outside Size. A mismatch now produces aP6container warning; matching declarations now pass with--fail-on warning.1.0.1keepsM11andM12silent 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 saysM11is, 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 asZ12and missed the file it holds — so a container with nothing else wrong exits0now.
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.
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.
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.
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).
iirds-validate — the same idea for iiRDS. standards-watch — a daily watch on these standards.