跳转至

06 JSON Schema Requirements

Purpose

This chapter defines schema-level requirements for normative machine-readable artifacts.

Scope

At minimum, v0.1 requires stable schema definitions for the principal normative artifacts used by the repository:

  • manifest.json
  • devicespec.json
  • calset.json
  • pulseir.json
  • runresult.json

The reference drafts also include a core UQCI program schema to reinforce canonical independence from OpenQASM. That same principle should guide schema design in the repository even when the full schema text is maintained outside this chapter.

General Requirements

All normative schemas should:

  • declare an explicit JSON Schema draft
  • use stable top-level titles and identifiers
  • define required versus optional fields clearly
  • forbid uncontrolled extension through accidental extra properties
  • remain aligned with canonical typed models

Artifact-Specific Expectations

The source drafts provide full schema bodies for manifest.json, devicespec.json, and calset.json. In repository-native form, this chapter does not duplicate every field verbatim, but it preserves the structural intent:

  • manifest.json should describe bundle version, profile, entry, sidecar locations, and integrity metadata
  • devicespec.json should describe platform type, topology, channels, native operations, timing, and constraints
  • calset.json should describe versioned calibration context, per-target parameters, pairwise parameters when needed, and resource references

Stability Rule

Schema stability matters because bundles, validators, examples, and backend integrations rely on consistent artifact structure. Editorial prose may evolve, but normative artifact shape must change deliberately and versionably.

Relationship To Canonical Models

Schema does not replace semantics. The canonical UQCI models define meaning; schemas define machine-readable structure for interchange and validation.

This means a schema file should be treated as a structural contract, not as the source of semantic interpretation. Semantics remain anchored in the canonical UQCI model and in the repository's normative chapters.

Relationship To OpenQASM

OpenQASM exports may reference schema-backed sidecars, but they do not replace them. Device and calibration semantics should remain in the relevant sidecar schemas rather than being over-encoded into a single QASM document.

Editorial and Repository Rule

This chapter should remain an umbrella chapter for schema discipline. Full machine-readable definitions belong in the repository schema files, while chapter-specific prose in later sections should explain the role of each artifact without reproducing excessive JSON listings.