iirds 0.7.1

 Apache-2.0 · Python 3.9–3.13 · Linux · macOS · Windows · zero network, by design

Ten seconds · What it catches · The local web door · Where it sits · Five doors · Honest coverage · Roadmap · In your product

Ten seconds

$ pip install iirds

Three parts, every time: what is wrong → the evidence as read from your file → how to fix it. A rule without a prescription does not ship. The old distribution name iirds-validate and the short command iirdsv remain as aliases of the same package.

$ iirds manual.iirds
manual.iirds   iiRDS 1.3
  note: metadata read from META-INF/metadata.rdf

  ERROR M11       Rendition must have exactly one iirds:format
                      urn:example:manual has-rendition
                      0 found
                    → Give the Rendition exactly one iirds:format, holding the media type of the
                    → file it points at, for example application/xhtml+xml or application/pdf.
                    → Add one if there is none; remove the extras if there are several.
  WARN  L1        relation points at an IRI that is never described in this package
                      urn:example:event/al-204
                      referenced by Operating manual via relates-to-event
                    → Either describe the target in this package, or drop the reference. A
                    → relation pointing at an IRI nothing here mentions gives a consumer a name
                    → and no way to resolve it.

  FAIL  1 error(s), 1 warning(s), 0 informational
  208 rules checked, 28 not applicable to this version/variant (26 for iiRDS/H, 2 for other editions)
$ echo $?
1

What it catches

Every code carries a prescription and the section of the specification it enforces — iirds rules C5 -v shows any rule's source and remedy.

It asks whether the package will work, not only whether it conforms. Sixteen interoperability rules, most with no counterpart in the specification, because a conformant package can still be undeliverable:

The local web door

For people who do not read terminals — that is literally what the help says:

$ iirds serve

opens a drop page on your own machine: drag a package, read the verdict. Loopback only — any other host is refused by design. Nothing is uploaded anywhere, because there is nowhere to upload to.

Where it sits

flowchart LR
    A[Authoring · CCMS · DITA-OT] --> P([.iirds package])
    P --> C{{iirds check}}
    C -- "PASS" --> D[Delivery portal · customer]
    C -- "findings + remedies" --> A
    classDef ref fill:#2f5d8a,stroke:#2f5d8a,color:#ffffff
    class C ref

The referee between producer and receiver. Same file → same verdict, byte for byte — no uploads, no telemetry, no model in the judgement loop.

Five doors, one judgement

Honest coverage

At a glance — 236 rules across five editions and three profiles · 169 SHACL shapes carrying the language-neutral encoding · one pure-Python dependency (rdflib), zero for the single-file .pyz · every number in this section is read by a test that fails the build when it goes stale.

$ iirds rules
container  19/19    the ZIP and its layout  +4 of its own
schema     135/135  the metadata graph  +35 of its own
system     3/3      the run itself  +13 of its own
content    -        iiRDS XHTML5 (Appendix B)  +11 of its own
lint       -        will a consumer be able to use it  +16 of its own

157 of 157 catalogued rules, plus 79 of this project's own.

Coverage of the catalogue is not coverage of the standard. The specification states 280 absolute obligations, counted by tools/extract_requirements.py and listed in docs/requirements.json; the rules currently cover 172 of them — a floor, not a ceiling (docs/rule-coverage.json), re-measured on every release.

• Every finding says what to do about it. All 236 rules carry one imperative sentence naming the change, and a test refuses a rule that does not.
• Every rule has been watched fire. The suite records which rule ids actually produce a finding, and 235 of the 236 have — the remaining one is a MAY with nothing to violate.
• What is not established. The 79 rules this project invented have no second implementation to be compared against; docs/divergences.md records where this project reads the specification differently, with reasons.

Why trust the answer

• Deterministic — same file, same verdict, byte for byte.
• Offline — your documents never leave your machine.
• Self-tested — rules are verified against their own mutations before they ship.
• A public divergence ledger — where our reading differs, it is recorded with reasons.

Roadmap

An item moves right only when it is built and verified.

timeline
    title Where iirds is going
    Shipped : One package — validator + reader + writer
            : Local web door · reproducible single file
            : Findings with evidence and prescriptions
    Building : Coverage climb through the obligation index
             : Audit-ready evidence bundle in one command
             : Deeper iiRDS/H handover checks
    Planned : Browser-local validation — no install, nothing uploaded
            : Delivery checks across neighbouring standards
            : Format conversion under the same judgement

When iirds is not the tool

• Authoring or fixing content — iirds judges packages; it does not create them (though every finding tells you the fix).
• Certification — no tool can declare legal conformance. The declaration stays yours.
• Neighbouring standards — for VDI 2770 containers or AAS submodels, use the sibling judges built the same way: vdi2770-validate, aas-submodel-validate.

Using this validator in your product

What is stable here, and what is not

This is 0.x, and the packaging is not the contract. Three names on PyPI install the same code, the module layout moves, and what a wheel carries beyond the command may change in any release.

The verdicts move, and every move is written down. A rule's reading is a claim about the specification, and when a reading changes, so does the verdict on a package that sits on that line. Those changes are in CHANGELOG.md, each with the reading behind it, and a paragraph that moves an exit code says so in those words. If you gate a build on the exit code, read that file before upgrading. That much is discipline, not a gate.

A command-line usage error exits 64, not 2 — breaking, and said here because the exit codes are a stable surface. A mistyped option and an input the run could not read both exited 2, so a build that treats 2 as "this package could not be judged" was catching its own broken command line and reporting it as a package problem. 64 is the conventional value for a usage error (EX_USAGE); 2 keeps its present meaning and nothing else moves. A mistyped verb typed on its own is not one of these: iirds <path> is shorthand for iirds all <path>, so the first word is read as a path and a misspelt one exits 2 -- iirds chekc pkg.iirds exits 2, naming chekc as the file it could not find. Typed with that verb's own options, iirds serv --port 8080 leaves all an option it has never had, and that is a usage error: 64. What a gate holds is narrower and worth more: a rule id is a citation somebody else made, so what fired is compared against a committed record on every build, and a rule that quietly stops firing stops the build.

What has held, and how to see it for yourself. The table below is written by tools/gen_stable_section.py from what those commands print, because a number typed into prose goes stale on the day the thing it counts moves:

The two containers the exit-code rows name are built by the repository rather than committed, and the generator builds them if they are missing; it runs the checker as python -m iirds_validate from the tree, which is the entry point the iirds command is.

What is not the contract, beyond packaging: the set of rules grows, so a count of them is not a promise; the wording of a finding's message is prose for a person to read; and the Python names the next section uses -- iirds.open, iirds_validate.check -- work, and are meant to, but they are not among the surfaces whose changes are announced as breaking. What is held still for another program to depend on is the command, its exit codes, and a report that says which schemaVersion it is.

Releases and version numbers

This is 0.x, and a release goes out when something is ready rather than on a calendar. While something is being built that can mean a release a night, and it can equally mean nothing for a fortnight. The number says what changed, not how long it has been since the last one.

A patch repairs, and names any verdict it moves. Mostly a package that passed goes on passing, and where a repair moves a verdict the changelog says whose and why: 0.6.2 stopped opening a bzip2 entry, which the standard permits and this tool will not read within a bound; 0.6.3 failed a container that will not produce a file it lists. If you gate a build on the exit code, the changelog is the file to read before upgrading, whichever number moved.

A minor release may add a verdict or move one, and the changelog names every package shape whose verdict moved, with the reading behind it.

A security fix goes out ahead of anything else in flight, and carries an advisory on this repository's Security tab naming the versions it reaches and the release that fixes it. SECURITY.md lists them.

Pin what you validated against, and pin iirds. iirds-validate and iirds-sdk are aliases that ship no engine of their own, and their dependency on iirds is a floor rather than an exact pin -- so pinning either fixes the name you install and leaves the rules free to move under it. iirds==<version> is the pin that holds them still.

1.0 will mean the report schema stops moving. Until then it may gain fields, and the coverage figure above is re-measured on every release rather than promised.

Reading and writing packages from Python

import iirds, iirds_validate

pkg = iirds.open("release.iirds")               # reader: metadata graph, files
report = iirds_validate.check("release.iirds")  # the judge, as a function

The reader ships with one dependency and no verdicts; the judge imports the reader, never the other way around.

Stewardship

The iirds name on PyPI belongs to the standard's community more than to any one project. Should the iiRDS Consortium want this name for an official SDK, it will be transferred on request — until then it does real work rather than squatting. iirds-sdk is an alias of this package and travels under the same pledge.

This is an unofficial project, not affiliated with or endorsed by the iiRDS Consortium or tekom Deutschland e.V. "iiRDS" is used descriptively, to name the standard these functions read and write.

Licence

Apache-2.0 — see LICENSE.

The bundled iiRDS ontologies are © tekom Deutschland e.V. / iiRDS Consortium under CC BY-ND 4.0 and are redistributed verbatim; the rule catalogue is derived from plusmeta's MIT-licensed tool. CC BY-ND is not an OSI-approved licence, so this distribution is not wholly open source even though the code is — docs/licensing.md explains what that means for you and what would fix it. Provenance in NOTICE and THIRD_PARTY.md.

Not affiliated with, endorsed by, or certified by the iiRDS Consortium, tekom Deutschland e.V., plusmeta GmbH or Quanos Solutions GmbH. "iiRDS" is used descriptively to name the standard this tool validates against.

_{Numbers above are re-measured on every release · findings are judgements about files, never about people}