Public schemas

Metewand's version-1 public schemas define the machine-readable contracts used by the conformance kernel. The checked-in documents under schemas/v1 are the source of truth. Each document declares JSON Schema 2020-12, a stable metewand://schemas/v1/... identifier, and x-metewand-compatibility-version: 1.

The public schema compatibility version is independent of the package version, manifest version, wire-protocol version, identity version, and execution-semantics version. A reader must select the schema version declared by the record rather than infer it from the Metewand release that produced the record.

See compatibility versions for the pre-MVP development policy and current accepted inputs. Version externally consumed boundaries; nested records can share their enclosing format's version, and internal helper types do not need public schemas.

Entry points

Schema	Contract
machine-output	Outer envelope for command events, results, and structured diagnostics, including init and scaffold results.
run-output	Sequenced execution events, finalized attempt summaries, and terminal run reports.
inspection-output	Read-only slot coverage, complete attempt history, selected observations, diagnostics, and stable identity explanations.
export-record	Rebuildable index records retaining applicability, attempts, observations, compatibility, and original evidence.
export-row	Tidy evaluator metric coordinates and numeric timing columns without dropping entities that lack metrics.
export-output	Export receipts and adjacent lineage manifests with exact table hashes.
cache-output	Exact cache verification, root management, and garbage collection receipts.
manifest	Initial benchmark manifest, including definitions, environments, experiments, and policies.
problem-contract	Problem-owned schemas, timing scopes, semantics, and reference cases.
one-shot-observation-policy	One result without a scientific budget.
artifact-manifest	Completion marker and hash-complete file inventory for an immutable artifact.
artifact-cache-object	Completed content-addressed tree, including directories and executable flags.
dataset-cache-entry	Dataset manifest path and construction receipt for a derivation mapping.
artifact-cache-lease	Process-held lease receipt for publication, reading, or a private view.
result-manifest	Metewand metadata around problem-defined canonical result data and referenced files.
observation	Independently finalized result, metrics, timing, validity, and provenance.
attempt	Terminal accepted, failed, or superseded execution with its observations and provenance.
metrics	Metewand metadata around evaluator-owned metric data.
dataset-materialization	Construction receipt with a derivation identity and separate output hash.
dataset-validation-request	Versioned request to a contract-owned binary dataset checker.
datamonger-selector	Pinned registry, explicit dataset version, and required verification level.
datamonger-acquisition-request	Bounded standalone command request to the optional Datamonger bridge.
datamonger-acquisition-response	Provider evidence and the complete raw artifact export inventory.
worker-protocol-message	Strict version-1 worker hello request and response.
worker-environment	Actual worker settings and allocated paths with redacted secret channels.

The CLI's json and jsonl modes emit the machine-output envelope and document their stream, exit-code, and diagnostic compatibility contracts separately.

All Metewand-owned objects reject unknown properties. Open values appear only where another contract owns their meaning. In particular, command-specific machine data, family-specific problem semantics, parameter values, provenance details, canonical results, and evaluator metrics may contain fields unknown to the common envelope.

The data value in a result manifest is validated separately against the problem contract's result-schema. The data value in a metrics envelope is similarly validated against metric-schema, and a problem contract's semantics object is validated against semantics-schema. These referenced schemas are repository documents admitted to the same offline catalog; validation never retrieves them from the network.

Every version-1 problem semantics object contains nonempty validity and one_shot_completion rule groups. The common schema enforces their presence; the problem's family-specific semantics schema defines their contents. The initial public-schema compatibility version remains 1 because this constraint completes the still-unreleased version-1 contract rather than revising a released format.

Gate 1 boundary

The initial manifest represents the runner and environment kinds declared by the design so definitions can be inspected before their runtime backends exist. Its observation policies and implementation capabilities are intentionally narrower: version 1 of this public schema set admits only one_shot and the none scientific budget. Applicability, profiles, observation-control schedules, and checkpoint messages will extend the relevant public boundaries with their implementations. Portable result archives follow the local MVP. The worker protocol entry point initially covers session negotiation; work-method messages are added with their execution slices. Keep the schemas and readers in agreement and apply the development policy to affected versions.

JSON Schema enforces the portable record shape. The typed parser requires normalized lexical repository paths, and the runtime performs source-bundle expansion, bytewise path ordering, unique-path and tree-containment checks, and symlink validation. Name resolution, schema-content identity, dataset/problem compatibility, policy combinations, and timestamp ordering remain later repository- or execution-aware checks.

Rust access

metewand-core embeds the exact checked-in documents. Consumers can enumerate the stable entry points or construct the complete offline catalog:

use metewand_core::public_schemas::{PUBLIC_SCHEMAS, public_schema_catalog};

for schema in PUBLIC_SCHEMAS {
    println!("{} {}", schema.slug(), schema.id());
}

let catalog = public_schema_catalog()?;

# Ok::<(), metewand_core::public_schemas::PublicSchemaCatalogError>(())

The catalog also contains the shared common.schema.json resource needed by the entry points. Conformance examples and negative cases live beside the schemas in schemas/v1/fixtures.