ois-validator

Reference validator for the Open Intent Schema (OIS), the open data standard that links what was required to what was built and to the evidence in between. It checks OIS records, bundles and Quality Passports and reports every problem with its rule and level (specification section 11.1):

• violation: a MUST is broken; the input does not conform.
• warning: R8, R12 and R13 ask for a report; the input still conforms.
• info: a SHOULD is not followed.

The package also brings ois-junit, which turns the JUnit XML of an existing pipeline into OIS records, ois-intent, which seals, approves and versions intents written in YAML or JSON, and ois-passport, which assembles a Quality Passport for a release.

Status: pre-alpha, targets specification v0.1. The validator checks Appendix B and every rule of section 5 that can be checked from the records at hand (R1–R5, R8–R17) and passes all conformance fixtures. Signatures are not verified yet, so R12 reports every recorded context as self-declared.

Install

uvx ois-validator bundle.json          # run without installing
pip install ois-validator              # or install; Python 3.13 or later

Validate

ois-validator bundle.json passport.json
ois-validator --format json finding.json
cat bundle.json | ois-validator -

Each file holds one JSON document: a single record, a bundle, or a passport as an in-toto Statement v1. Exit code 0 means every file conforms, 1 means at least one violation, 2 means a file could not be read. Reports point at the field concerned:

same-producer.json: violation [R5] $.records[12].derivedFrom: test and subject are both produced by https://ois.acme.example/actors/dev-agent

With --format json:

[
  {
    "file": "same-producer.json",
    "conforms": false,
    "reports": [
      {
        "level": "violation",
        "rule": "R5",
        "message": "test and subject are both produced by https://ois.acme.example/actors/dev-agent",
        "path": "$.records[12].derivedFrom"
      }
    ]
  }
]

From Python:

from ois_validator import validate

result = validate(document)  # a parsed JSON document
result.conforms  # False if any report is a violation
result.reports  # list of Report(level, rule, message, path)

Record test results from JUnit XML

ois-junit turns the JUnit XML that almost every test framework writes into a bundle, as the Level 1 quick start in specification section 11.4 describes. Run it in the Git checkout the tests ran in:

ois-junit build/test-results/*.xml \
  --namespace https://ois.acme.example \
  --suite "Team Billing" \
  --run "$CI_PIPELINE_URL" \
  --output ois-bundle.json

The bundle holds an actor for the adapter and one for the test suite, a characterization intent in draft with one criterion per test case, an artifact per test file (pinned by sha256 and gitCommit) and an evidence record per result with derivedFrom: unknown. ois-junit validates the bundle before writing it: exit code 0 writes it, 1 means it would not conform and nothing is written, 2 means a report or the Git checkout could not be read.

The getting started guide walks through it step by step, including a CI example.

Write and approve intents

ois-intent takes an intent written in YAML or JSON and does what is error-prone by hand:

ois-intent seal INT-142.ois.yaml                      # criterion and intent digests (RFC 8785)
ois-intent approve INT-142.ois.yaml --by https://ois.acme.example/actors/po-7f3a
ois-intent next .ois/intents/INT-142-v1.ois.json      # draft of version 2, superseding version 1
ois-intent compare .ois/intents/INT-142-v1.ois.json .ois/intents/INT-142-v2.ois.yaml

• approve writes the approved intent and its intent-approval decision, bound by the intent's digest (R1), to .ois/intents/ and .ois/decisions/ (specification section 7). It refuses an approved intent whose content no longer matches its digest: approved intents never change.
• compare shows per criterion whether evidence carries over to the new version or is stale (section 6.3); criticality does not count.
• YAML is read as section 7 requires: 2026-10-14T09:12:00Z and yes stay strings, and tags, merge keys and non-string or duplicate keys are refused, so that digests do not depend on how a YAML library reads the text.

Build a Quality Passport

ois-passport collects the records behind a release into an in-toto Statement with the OIS passport predicate (specification section 8) and validates it before writing:

ois-passport build .ois/ ci-bundles/ \
  --release-name billing --release-version 2026.10.4 \
  --build https://ois.acme.example/artifacts/billing-2026.10.4 \
  --issuer https://ois.acme.example/actors/passport-issuer@0.3.0 \
  --approve-release-by https://ois.acme.example/actors/release-manager-1d2e \
  --output passport.json

• Inputs are record or bundle files, or directories such as .ois/, in JSON or YAML. Identical records are merged, a draft gives way to its approved record, and two different records with the same id are refused (R10).
• The passport lists the latest approved version of each intent unless --intent names them, and embeds every input record. Its subject is the build artifact with its digest.
• --approve-release-by adds the release decision for the build when the records carry none (R16). Exit code 1 means the passport would break a rule and nothing was written; warnings such as R12 are printed and the passport is written.
• The passport is not signed yet; DSSE signing follows.

Privacy

None of the commands (ois-validator, ois-junit, ois-intent, ois-passport) opens a network connection: the JSON Schema ships inside the package, and ois-junit reads the JUnit XML and the local Git checkout only. Installing the package contacts PyPI. Details and a diagram: Privacy and data flows.

Documentation

• Specification, schema and conformance fixtures
• Getting started: first OIS bundle from JUnit XML
• Architecture: how the validator and ois-junit are built, and why
• Development: setup, checks, specification sync, adding a rule, releases
• Changelog

Contributing

What the validator accepts is decided in the specification repository; bug fixes, tooling and documentation are welcome here. See CONTRIBUTING.md and the Code of Conduct. Security issues: SECURITY.md.

License

Apache-2.0.