Machine-Readable Contracts

Most stable CLI JSON objects declare schemaVersion: "1". When present, specVersion identifies the independently versioned OKF document format. Audit contracts and private usage events use a type and numeric version.

CLI output schemas

common.schema.json contains shared issue, link, retrieval, typed-frontmatter, and OKF 0.2 signal definitions. list.schema.json and graph.schema.json reference its okf02 contract. This contract contains derived trust, lifecycle and staleness, generation and verification events, structured sources, and optional Attested Computation data.

Search output can contain an ordered retrieval route. Search match results can contain lexicalScore, vectorScore, and rerankScore. These fields are additive diagnostics. The local vector does not use a model or network service.

Single-bundle search context and match output contain status. The value is managed for an OKF bundle and unmanaged for an ordinary Markdown directory. The unmanaged value identifies search capability without publication or OKF validation readiness.

check.schema.json defines the unified knowledge check. The object contains schemaVersion, root, optional specVersion, overall, and ordered layers. Overall values are READY, NEEDS ATTENTION, BLOCKED, and UNMANAGED. A layer can also use NOT CONFIGURED.

Semantic fact, RDF, SPARQL, Datalog, and hybrid contracts share the same corpus revision and content-addressed provenance model. SPARQL bindings and Datalog results contain their supporting sources. Datalog distinguishes asserted and derived facts and serializes proof trees. Hybrid results preserve per-route ranks and raw scores alongside reciprocal-rank-fusion scores.

The common schema also defines optional claimProfile output. List, graph, search, context, and runtime source objects use this definition. The schemas/claims/v1 directory contains the typed ontology, authored claim, digest-bound claim proposal, and approved entity proposal schemas. schemas/evidence/v1 contains the immutable capture receipt contract. schemas/corpus/v1 contains the optional authored corpus schema extension.

Audit reports use type: openknowledge.audit-report and numeric version: 1. Each finding records category, severity, impact, targets, and evidence. Source baselines use type: openknowledge.audit-source-baseline and numeric version: 1.

Durable report bundles use type: openknowledge.artifact and numeric version: 1. The manifest identifies the artifact kind, run, base revision, creation time, and included files. The first shipped kind is eval-comparison; runtime-local gate bundles use knowledge-ci.

Job contracts are experimental. They can change without a new version before version 1.0. Run plans can contain deterministic preflight commands and can omit agent for empty-prompt jobs that contain verification. Run records preserve preflight results and use preflight_failed when this phase stops execution.

job-run-plan.schema.json can contain an eval object. It records the dataset, target, spec, gate, resolved base SHA, and optional answer runner settings. job-run-record.schema.json can contain the eval result. It records status, dataset, target, base SHA, gate, report paths, regression count, and proposed failure count.

Eval result status is pass, fail, or error. The containing run uses verification_failed when an eval gate or eval operation fails.

Eval dataset v1 policy expectations are minimum_trust, allow_stale, allowed_statuses, and require_sources. They test every selected source against derived OKF 0.2 trust, freshness, lifecycle, and provenance signals.

Answer expectations can require answer or abstain, conflict disclosure, and a minimum number of valid citations with an entailed attestation. The CLI validates the attestation contract and locator. The trusted answer command, not the CLI, makes the semantic entailment judgment.

eval-report.schema.json accepts these names as check kinds. Each check records expected, optional rejected source paths in actual, and passed. Markdown reports include failed policy checks and include all policy checks in the totals.

Eval dataset v1 cases can contain an optional agents list. Eval case results contain the normalized agent IDs, or an empty list when no agent is declared.

eval-comparison.schema.json requires an impact object. The object contains changedPaths, affectedAgents, affectedQuestions, and uncoveredPaths. Each affected question contains its case ID, question, agents, paths, and impact reasons.

Expected, retrieved, and valid cited sources attribute changed paths to cases. Changes to retrieval results, case outcomes, or answer text can also affect a question. An uncovered path is a changed path with no case source link.

Runtime plans include the normalized serve.retrieval_policy object. runtime-search.schema.json and runtime-context.schema.json bind responses to the active generation and retrieval revision.

Runtime plans also include normalized accessProfiles. Each profile contains an environment token name, published knowledge base allowlists, routing labels, and an optional complete retrieval policy override.

Runtime build results can contain staged: true. A staged result has no published object. A published active pointer can contain previousGeneration.

runtime-releases.schema.json defines the verified generation inventory. It records active and previous generation names plus commit, spec, digest, check, file count, and active status for each stored release.

runtime-release-action.schema.json defines preview, pin, and rollback descriptors. Each descriptor binds the action, knowledge base, generation, and content digest. Preview descriptors also contain the listen address.

runtime-cache.schema.json defines persistent index cache command results. Its action is status, rebuild, or prune. Every result contains entries and removed arrays. Prune results also contain applied.

Each entry identifies the knowledge base, generation, search or mcp target, cache path, and state. States are ready, missing, invalid, and rebuilt. Valid and rebuilt entries can include the index digest and section count. Invalid entries can include an error. Each removal identifies one knowledge base and cache generation.

Runtime search and context responses contain access, decision, and refusalReasons. Access identifies the profile and its agents, teams, and useCases labels. Decision is answer or refuse.

A refusal has no selected evidence. Its reason is no_relevant_evidence, no_policy_compliant_evidence, or insufficient_budget. The response preserves rejected candidates for review.

Runtime generation identity includes sorted checks. These names identify the successful GitHub or runtime-local publication checks bound into the generation contentDigest. Runtime plans include normalized github.required_checks names and the github.auto_merge_low_risk switch. Auto-merge configuration requires GitHub integration, check publishing, and at least one required check.

The private hosted exchange can contain a bounded maintenance attestation. It records normalized risk, approval, confidence, owners, insight and finding IDs, insight paths, expert targets, proposal status, and earliest detection time. The request also carries the completed proposal time. A merged exchange marker retains GitHub's exact squash commit. These exchange objects are an internal runtime boundary and are not published CLI schemas.

Both retrieval contracts include the effective policy and rejected candidates. Selected items add trust, freshness, provenance, and selection metadata. Rejected reasons identify trust, staleness, status, source, or an unverified, disputed, rejected, superseded, archived, or otherwise inactive claim.

Runtime plans also include the normalized serve.usage_events object. usage-event.schema.json defines strict local JSONL event records. Each event uses type: openknowledge.usage and numeric version: 1.

The event records generation, channel, HMAC query fingerprint, query length, outcome, selected evidence, and policy rejection counts. Query text is optional and requires explicit runtime configuration. Its generation identity uses the same checks array.

Runtime search and context responses can contain an optional usageEventId. It is a 32-character lowercase hexadecimal ID. The runtime emits it only after successful private usage event persistence.

feedback-event.schema.json defines openknowledge.feedback version 1. Each event binds its ID, time, knowledge base, generation, usage event ID, query fingerprint, channel, outcome, access, sentiment, reasons, and selected evidence. The contract does not contain raw query text.

Feedback sentiment is positive or negative. Positive events have no reasons. Negative events have one to six unique reasons from the schema enum.

quality-report.schema.json defines openknowledge.quality-report version 1. Its input summary includes intervention events. Intervention-backed timing, review, audit outcome, and safe-automation metrics are measured only when the required lifecycle stages are present.

intervention-event.schema.json defines openknowledge.intervention version

1. Each event binds a stable intervention ID to its time, knowledge base,

actor, source, fixed risk route, targets, and evidence. Stages are detected, proposed, reviewed, published, dismissed, failed, and rolled-back.

Reviewed events add decision and duration. Published events add a generation, content digest, non-empty successful checks, automated flag, and required verification. Automated publication is restricted to low/auto routing. Terminal audit-finding events can classify their result as confirmed or false-positive. The CLI additionally validates ordered cross-event lifecycle transitions, which a per-event JSON Schema cannot express. It binds an evaluation time to the current bundle path, specification, and SHA-256. It also records the observation window and input counts.

Each metric has an ID, measured or unavailable status, unit, and evidence note. Measured metrics contain a value. Ratio metrics can contain a numerator and denominator. Trend metrics can contain previous and change values.

Generation records contain usage outcomes and feedback counts. Concept records contain current metadata, sources, evalCoverageStatus, eval coverage, use, feedback, audit findings, priority, and risk reasons. Coverage status is unavailable when no current-revision eval input was supplied. Change records contain base and proposed eval accuracy plus improved and regressed case counts.

The published v1 schema distribution includes eval, diagnostic, runtime, and Railway deployment outputs. Golden tests marshal the current Go result types. The shared schema suite compiles and validates these fixtures.

Error envelope

Place the global option before the command:

okn --error-format json search

A failure produces one JSON document on stderr. The command preserves the original exit status:

{
  "schemaVersion": "1",
  "error": {
    "kind": "usage",
    "command": "search",
    "exitCode": 2,
    "message": "search requires a key or path and a query",
    "truncated": false
  }
}

kind is usage for exit status 2. For all other exit status values, kind is runtime. The maximum diagnostic size is 256 KiB. Command-specific semantic JSON remains on stdout. For example, the CLI does not wrap an invalid validation report as a CLI error.

Schema locations

Draft 2020-12 CLI schemas are in packages/cli/schemas/v1/. The project publishes them at:

https://openknowledge.sh/schemas/cli/v1/<schema>.json

Other version domains are independent:

Claim command output uses claims-find, claims-stale, claims-reconcile, claims-impact, claims-validation, claims-mutation, claims-entities, claims-entity-impact, and claims-entity-mutation schemas. Claim and entity proposals use independent v1 contracts. A merge proposal binds both entity declaration document digests. Approved apply rewrites every affected claim reference and retains the old ID as a deprecated entity with replaced_by. Claim source projections preserve resource, liveResource, observe, and sha256. Claim projections include append-only evidence observations and exact stale evidence IDs. Indexes and graphs remain derived data.

evidence pin --json uses evidence-pin.schema.json. Its nested capture object follows the independent openknowledge.evidence-receipt v1 contract. Artifacts and receipts are content-addressed canonical evidence, not index state.

Runtime generations include the validated private evidence store in their manifest. Runtime context evidenceArtifacts entries bind selected claim evidence to a source ID, private resource, digest, source access labels, and selectors. source_access_denied is a fail-closed rejection reason.

Eval datasets use type: openknowledge.eval and numeric version: 1. The dataset schema defines strict YAML-compatible questions, context settings, retrieval expectations, and answer expectations.

answer-request.schema.json defines the stdin document for an answer command. answer-response.schema.json defines its stdout document. Both protocols use schemaVersion: "1" in the eval v1 domain.

Eval reports use the CLI schemaVersion: "1" contract. They bind results to the dataset digest and corpus revision. Answer results contain decisions, answer text, claims, citation validity, entailment attestations, cited sources, conflicts, applicability metadata, and groundedness. Comparison reports bind base and proposed results to their retrieval revisions. They also record each case classification and the selected gate.

Portable manifests use a numeric version and a concrete spec. Local storage and runtime manifests use their own schemaVersion values. These domains are independent.

Compatibility

Version 1 can add fields when existing field meanings and types do not change. The project then updates the closed v1 schema. A consumer that uses a downloaded schema must refresh it before it accepts this output. A new schema version is usually necessary when the project removes a field. It is also usually necessary when a field type or meaning changes. The project also uses a new version when new output rules reject previously valid output.

Schemas use additionalProperties: false at defined object boundaries. This rule detects encoder drift. Retrieval results bind evidence to a corpus revision, section digest, and okf+sha256:// locator. Federated search adds registry identity, local rank, and RRF score to single-bundle objects.

Repository tests compile each schema offline. They validate golden objects and runtime objects. They verify that undeclared top-level and nested fields fail. The web build verifies each $id against its public route before it copies schemas.