Skip to content

Claiming Conformance

"This implementation conforms to Bars suite X.Y.Z" is only a useful claim if it names one specific, verifiable artifact. This page defines that artifact and the convention for producing it.

The interchange format

The kbars CLI's conformance --full-report[=PATH] mode emits a JSON document validating against full-report.schema.json (reportFormat 1.1): a tool block naming the implementation and its version, a summary with total/passed/failed counts and a per-tier (core/full) breakdown, and a files array recording every fixture file that ran, its declared tier, and a pass/fail verdict per case.

This shape — not the reference implementation's Kotlin, and not prose — is the conformance report: the interchange format any implementation, in any language, emits as machine-checkable proof that it ran the suite and what happened. A workalike does not need to shell out to the kbars CLI to produce one; it only needs its own runner to emit a JSON document with this shape. Because the schema is normative and versioned independently of any one implementation, a report from a Rust port and a report from the reference kBars CLI are directly comparable byte-for-byte in structure.

What a conformance claim means

"Implementation I conforms to Bars suite X.Y.Z at tier T" means, precisely: running I's runner against the X.Y.Z conformance fixtures (see The Conformance Suite) produces a full-report.schema.json document in which:

  • summary.ok is true for the tier(s) claimed — summary.tiers must include a "core" entry with failed: 0 for a core-conformance claim, and additionally a "full" entry with failed: 0 for a full-conformance claim (see Core vs. optional extensions for what distinguishes the two tiers).
  • files accounts for every fixture file recorded in that suite version's manifest.json — a report that silently omitted a fixture directory is not proof of anything for the cases it never ran. Cross-check files against manifest.json's files the same way a runner cross-checks its own fixture inventory (see The manifest).
  • tool.version identifies the implementation and version the report was run against, so the claim is reproducible and falsifiable — anyone can re-run the same fixtures against the same implementation version and expect the same report.

A claim without an accompanying report is an assertion; a claim with one is a verifiable fact. Publish the report (or a link to a CI artifact producing one) alongside any public conformance claim.

Known workalikes

There is no independently-maintained Bars workalike yet. When one exists, this section will list it — implementation name, language, suite version and tier it certifies against, and a link to its conformance report — so a template author choosing between implementations can see, at a glance, which suite version and tier each one actually proved against, rather than trusting an unverified badge.

If you are building one and want it listed, open an issue or pull request against the kBars repository with your implementation's name, repository link, and a conformance report produced as described above.

See also

  • The Conformance Suite — the fixture format and the manifest this report cross-checks against.
  • Writing a Workalike — the translator's notes for building an implementation in another language.
  • Distribution — the versioned ZIP a workalike's runner consumes as its fixture source.