How qutech-delft/compute-runtime-schema works
Project Type and Purpose
• Type: Open-source schema library + validation/testing framework
• Purpose: Provide JSON Schema definitions for initialization, execution, dynamic/static data retrieval, state publish, and termination messages between client code and quantum compute runtimes. Also include tests and docs to ensure schema correctness and generate user documentation.
File Structure
• Top-level directories:
– schemas/ : the core JSON Schema files, one subfolder per operation (initialize, execute, get_dynamic, get_static, publish_state, terminate).
– tests/ : two test suites
• control-software-validator/ : Python-based integration tests that import schemas and validate message flows
• schema-check/ : shell-script-driven tests that validate JSON examples against schemas
– docs/ : MkDocs-based documentation, with assets, markdown pages, and publish guidelines
– .github/workflows/ : CI pipelines for schema validation and docs publishing
– requirements.txt : Python dependencies for validators and docs
– mkdocs.yml & mkdocs-base.yml : doc builder configs
README Insights
– Very brief: “JSON schema to connect to the quantum compute runtimes.”
– No built-in runtime or service; it’s purely schemas + tooling.
Main Components
A. Schema Module
• Contains operation-specific folders under schemas/
• Each folder has request.schema.json, reply_success.schema.json, reply_failure.schema.json (or message.schema.json for publish_state)
B. Test Suite
1. Schema-Check Runner
– Shell script + JSON example files under tests/schema-check/data
– Uses a JSON Schema validator CLI to ensure examples conform
2. Control-Software Validator
– Python code that imports schemas and simulates full request/response flows
– models/ for typed message classes, channels/ for I/O simulation, test_flows.py
C. Documentation Generator
• MkDocs reads docs/ and uses schemas (maybe embedded or linked) to build HTML docs
• GitHub Pages (via docs-publish pipeline)
D. CI/CD Pipelines
– validation.yaml: runs both test suites, linting, schema validity
– docs.yaml: builds and deploys docs
E. External Tools/Services
• JSON Schema Validator CLI (e.g., ajv)
• Python interpreter + pytest
• MkDocs for static site generation
• GitHub Actions for CI
Relationships and Data Flows
– Developer → pushes code + schemas → GitHub → CI pipelines
• Validation Pipeline → executes schema-check → runs control-software-validator → reports pass/fail
• Docs Pipeline → runs mkdocs build → publishes to GitHub Pages
– End user (another project) → installs compute-runtime-schema → imports JSON schemas → uses validator library to check payloads when interacting with a quantum runtime
Architectural Patterns and Principles
• Clear separation of concerns:
– Core schema definitions
– Validation/testing layers
– Documentation layer
– CI/CD orchestration
• Modular design: one folder per operation type, making extension of new operations straightforward.
• Infrastructure as code: pipelines defined in YAML, docs configuration in mkdocs.yml.
Essential Details to Capture
• The 6 operation types beneath schemas/
• Two distinct test strategies (shell-based vs. Python-based)
• CI workflow triggers and job sequences
• Docs pipeline and publishing target
• The role of external validators and MkDocs