Skip to main content
Use the checker to find structural errors in definition and guidance files before people or tools rely on them.

​
What gets checked

The checker uses the protocol’s conformance rules to check supported conditions, including:
  • required declarations and fields;
  • references to declared elements and document types;
  • duplicate codes;
  • protocol-version compatibility, including fields an older declared version does not allow and keys renamed between versions (a kbp/0.8 universe writes no_artifact; a kbp/0.7 universe writes empty_composition);
  • universe terms: unique, with a nonblank term and meaning;
  • permitted uses of frames and factors;
  • the ordering frame: from kbp/0.9, a universe spec with elements declares exactly one ordering frame, and a universe spec with no element declares no ordering frame;
  • relation edge gates: from kbp/0.8, each key is a declared frame or latency, each value is one that frame declares, latency is a nonblank string, and no frame is named latency;
  • guidance references, kinds, and source declarations;
  • fields that the format does not allow.
Guidance is checked against the universe it names, so provide both files in the same run.

​
What requires human review

Passing means the definitions and guidance meet the structural checks currently implemented. Explorer inspection separately reports whether the selected universe can be rendered. Neither result establishes that a question is useful, that an answer is true, or that advice is well supported. The checker does not yet validate answers.yaml or ingest-log.md, the files that ingestion writes. Both are review-only for now; validating them is on the roadmap. The protocol defines rules for instances and exchange, but the checker does not validate those workflows fully.

​
Running the checker

Requires uv. Run these commands from a clone of the repository. Check the bundled definitions and guidance:
Check a particular definition file and its guidance:
Paths in this example are placeholders for your files. A target folder with .knowledge-bus/ selects the definition and guidance files in that directory. Explicit file arguments select exactly those files. The checker applies the rules in Nested Folders to an explicit .knowledge-bus/workspace.yaml argument. For generic directory arguments, the checker scans *.kbp.yaml files and skips nested folders that contain their own .knowledge-bus/. Without explicit targets, the checker uses the nearest .knowledge-bus/ from the working directory upward. It never combines definitions from different Knowledge Bus directories or creates a missing .knowledge-bus/. When the selected .knowledge-bus/workspace.yaml lists universe specs of the parent folder under from_parent, the checker also checks workspace.yaml and those universe specs, one block per file; see Nested Folders. In the implementation checkout, it checks bundled universe-samples/ when no .knowledge-bus/ directory is found. The package supplies the protocol independently of the working directory. See Knowledge Bus Directory. Inspect one universe without writing:
When the scope contains several universes, select one with --universe <id> or target its file. Duplicate ids and ambiguous guidance or marks fail. Print the card for one document type, or list every document type:
--card and --kinds skip marks files. When the scope holds several universe specs, --kinds without --universe prints one group per universe spec. See Document Type Card.

​
Understanding results

The checker first reports whether the protocol is SOUND. It then reports whether each document conforms, with FAIL messages describing the problems it found. Fix the reported declaration or reference and run the check again. A non-zero exit status means the run failed, so scripts and CI can stop on that result.

​
Testing the checker

Before checking documents, the checker checks the protocol itself. This includes checking that fields it expects to read are declared as required. An inconsistent protocol stops the run. Run that check alone with:
The test corpus includes valid documents and 34 deliberately invalid cases, among them a duplicate code, a missing required field, an unknown element in a composition, a mismatched protocol version, and a document using a key from the wrong protocol version. Each invalid case must fail with the expected reason. These cases do not cover every possible violation. Run the tests with: