Open specification · Version 1
QZX Result Contract v1
A small, additive JSON envelope that lets AI agents, automation, and people determine whether a command succeeded, understand the outcome, and keep command-specific evidence without guessing at columns or parsing prose.
Created and maintained by Alejandro Sánchez as an open QZX specification.
success or message.Stable core
Two fields every consumer can trust
success· booleantrueonly when the requested operation completed successfully.message· non-empty string- A complete human-readable summary, not a label that forces another lookup.
Additive evidence
Different commands keep different facts
A file search, DNS query, disk inspection, and process operation should not pretend to share the same domain fields. Producers may add typed command-specific data, details, warnings, and meta. Consumers must ignore fields they do not understand.
Transport-neutral core
Readable by a human, dependable for software
The core contract is independent of CLI, MCP, HTTP, or library transport. QZX itself adds a CLI JSON profile: with --json, it writes one complete contract document to stdout and sends progress or incidental native output to stderr.
- Failures include
erroror a stableerror_code; successful results contain neither failure field. - Defined optional fields keep their declared type when present; unavailable fields are omitted instead of set to
null. meta.schema_versionidentifies the shared envelope when metadata is present.- Unknown additional fields remain valid, so commands can evolve additively.
- Contract compatibility does not imply authorization, sandboxing, or universal platform support.
{
"success": true,
"message": "Current local date and time returned in ISO 8601 format.",
"output": "2026-08-07T21:45:00-05:00",
"meta": {
"command": "getCurrentDateTime",
"duration_ms": 2.4,
"schema_version": 1
}
}Adoption without lock-in
Other tools can implement the result shape without adopting QZX commands
The contract separates transport from command vocabulary. A local CLI, MCP server, build tool, or internal automation wrapper can emit a QZX-compatible result while keeping its own operation names and domain fields.
1 · Produce
Emit the core
Return explicit success, a useful message, and truthful domain evidence.
2 · Validate
Use the schema
Validate saved or piped JSON with the downloadable schema or the dependency-free QZX validator.
3 · Report
Publish evidence
Share implementation limits, conformance results, and deviations instead of claiming unsupported certification.
Conformance kit · CI-ready evidence
Turn one success and one failure into a reviewable receipt
QZX ships a dependency-free evidence validator and a reusable GitHub Composite Action. The pair validator checks that the success file really says success: true, the failure file really says success: false, applies the selected core or MCP profile, and writes a deterministic JSON receipt with SHA-256 digests of the exact evidence files.
The Action runs the same check in a caller repository, fails CI on non-conformance, confines evidence and report paths to GITHUB_WORKSPACE, and writes a compact PASS/FAIL job summary. QZX's own GitHub CI exercises both the core and MCP profiles on CPython 3.13.
Every receipt self-identifies the public QZX Result Contract Conformance Receipt v1 schema. Any JSON Schema 2020-12 implementation can therefore validate the report structure without executing QZX. A schema-valid receipt may still report success: false; structural validity and implementation conformance are deliberately separate.
Using QZX's validator is optional: the contract remains implementable with any independent JSON Schema/profile validator. For durable public evidence, pin the Action to the exact QZX commit SHA you tested.
One evidence command
python scripts/validate_result_contract_evidence.py \
--profile mcp-2025-11-25 \
--success evidence/success.json \
--failure evidence/failure.json \
--tool-definition evidence/tool-definition.json \
--report evidence/qzx-conformance.json- Inputs
- Real completed success and failure; MCP tool definition when that profile applies.
- Receipt
- Profile, validator findings, MCP
output_schema_mode, semantic roles, and SHA-256 digests of the exact evidence. - Claim boundary
- Conformance evidence only — not security certification, domain correctness, or QZX endorsement.
MCP interoperability · 2025-06-18 → 2026-07-28
Adopt the result contract without replacing — or upgrading — MCP
MCP has supported tool outputSchema, structuredContent and isError since specification 2025-06-18. QZX therefore provides revision-specific profiles for 2025-06-18, 2025-11-25 and 2026-07-28 instead of forcing a compatible producer to upgrade its whole MCP stack just to test one result contract.
A tool keeps its own name, inputs, permissions, transport and domain fields. QZX records whether its outputSchema relationship is a canonical reference, exact inline schema, allOf composition, or the weaker SDK-portable structural_core form. The receipt exposes that distinction instead of hiding it behind a generic green badge.
An MCP-aware client already has isError. QZX keeps success inside the structured result for a different reason: the result remains self-describing when it is logged, cached, queued, stored, tested, or reused outside its original MCP wrapper. Inside MCP there is no competing source of truth: the effective MCP error state for a completed result must equal !success. MCP treats an omitted isError as false, so success may omit the field while failure must still emit isError: true.
MCP 2026-07-28 additionally requires resultType: "complete" for a completed result. The 2025 profiles deliberately do not invent that field.
Deterministic mapping
outputSchema- Canonical QZX schema when the SDK permits it; otherwise a constrained structural core whose weaker relationship is recorded in the receipt.
structuredContent- The complete QZX result object, validated against Result Contract v1.
isError- For completed results, the effective state must equal
!success; omission is allowed only when that effective value isfalse. resultType- Required as
completeby the 2026-07-28 profile; not required by the 2025 profiles. - MCP / JSON-RPC protocol errors
- Remain protocol errors; do not fabricate a completed QZX result.
Validate without another dependency
The source repository ships a validator that reads a file or stdin:
qzx getCurrentDateTime --output-format iso --json \
| python scripts/validate_result_contract.py -
python scripts/validate_result_contract.py result.json --jsonThe QZX runtime validates its own final envelope before printing it. An invalid internal producer result becomes a conforming invalid_result_contract failure.
Version 1 evolves additively
New optional fields, error codes, and transport profiles are compatible when they preserve the core semantics. Removing a required field, changing the meaning or type of success or message, or changing the root away from one JSON object per completed result requires a new contract version.
“QZX Result Contract v1 compatible” describes a result shape. It does not imply endorsement, command parity, safe execution, or permission to present another product as QZX.
Public review and enterprise pilots
Help test whether this contract deserves wider adoption
Alejandro welcomes independent implementations, interoperability reviews, real agent pilots, and sponsored public conformance work. Financial support may fund testing and documentation, but never private control of the open contract or favorable results.