qhw-data

qhw-data defines provider-neutral schemas and builder APIs for quantum hardware data. The goal is to let runtimes, services, test suites, and provider adapters exchange hardware information without depending on a specific vendor SDK.

The repository deliberately separates the common schema from provider parsing. Provider-specific code belongs in adapter packages such as qhw-iqm. This package only defines the record shapes, validation helpers, serialization helpers, and builders used to create valid records.

Schema Overview

Schema	File	Purpose
qhw-result-v1	schemas/qhw-result-v1.schema.json	Execution result, job status, counts/statevector data, timeline timestamps, derived durations, calibration reference, errors, extensions, and optional raw payload references.
qhw-device-v1	schemas/qhw-device-v1.schema.json	Device identity, provider metadata, technology family, qubit list, and per-qubit properties.
qhw-coupling-v1	schemas/qhw-coupling-v1.schema.json	Connectivity graph, directed/undirected edge metadata, supported operations, supported loci, and graph source metadata.
qhw-calibration-v1	schemas/qhw-calibration-v1.schema.json	Calibration set identity, quality metric set identity, observation counts, high-level summaries, validity metadata, and optional raw payload references. Provider-specific observation sets belong in extensions.

Design

The schemas keep a small provider-neutral core and leave provider-specific fields in two controlled locations.

metadata is for small provider-neutral or operational metadata that is useful to generic consumers. extensions is a namespaced dictionary for provider-specific structured data. Consumers that do not understand an extension namespace must ignore it. raw can embed a raw payload or point to external raw artifacts, but raw payloads should be omitted from runtime data paths when compact records are needed.

Timing data is represented as timestamps first. Result builders derive durations automatically from known timestamp pairs, which avoids callers duplicating phase-duration logic.

Python APIs

API	Record	Use
new_result(provider, device_id, job_status="unknown")	qhw-result-v1	Start a result record for a provider and logical device. Add job data, counts, memory, timeline events, calibration references, errors, extensions, and raw references.
new_device(provider, device_id, num_qubits=None)	qhw-device-v1	Start a device identity record. Add device identity fields, qubits, per-qubit properties, metadata, extensions, and raw references.
new_coupling(provider, device_id, device_name=None, num_qubits=None, directed=False)	qhw-coupling-v1	Start a coupling graph record. Add nodes, edges, source fields, supported operations, and operation loci.
new_calibration(provider, device_id, device_name=None, num_qubits=None)	qhw-calibration-v1	Start a calibration record. Add calibration IDs, validity timestamps, observation counts, summaries, extensions, and raw references.
validate_result(data)	qhw-result-v1	Validate a result dictionary against the bundled JSON schema.
validate_device(data)	qhw-device-v1	Validate a device dictionary against the bundled JSON schema.
validate_coupling(data)	qhw-coupling-v1	Validate a coupling dictionary against the bundled JSON schema.
validate_calibration(data)	qhw-calibration-v1	Validate a calibration dictionary against the bundled JSON schema.
to_json(data, indent=None) / from_json(payload)	Any schema	Convert schema dictionaries to and from deterministic JSON.
to_msgpack(data) / from_msgpack(payload)	Any schema	Convert schema dictionaries to and from MessagePack when the optional msgpack dependency is installed.

The builder methods are chainable. build() returns a normal Python dictionary and validates it by default.

from qhw_data import new_result

record = (
    new_result("iqm", "ornl-iqm-20q")
    .job(id="job-1", status="completed")
    .result(shots=100, counts={"0": 99, "1": 1}, success=True)
    .timestamp("created_at", "2026-05-16T20:01:48.521385Z")
    .timestamp("completed_at", "2026-05-16T20:01:50.264968Z")
    .build()
)

Validation

The schema files are available in schemas/ and are also packaged under qhw_data/schemas/ so installed packages can validate records without the source tree.

from qhw_data.validate import validate_result

validate_result(record)

Examples

Example records live in examples/:

• result_minimal.json
• result_iqm_smoke_normalized.json
• device_synthetic_20q.json
• coupling_synthetic_20q.json
• calibration_synthetic_20q.json