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.

Download JSON Schema Read the source specification Review or implement it

Anatomy diagram of a QZX Result Contract v1 JSON document, highlighting the success boolean, non-empty message, command output and metadata. — The shared envelope stays deliberately small. Commands can add typed fields without changing the meaning of `success` or `message`.

Stable core

Two fields every consumer can trust

success · boolean: true only 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.

One document on stdout

Readable by a human, dependable for software

QZX prints a concise human message by default. With --json, it writes one complete contract document to stdout and sends progress or incidental native output to stderr.

Failures include error or a stable error_code.
meta.schema_version identifies 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.

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 --json

The 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 and error codes are compatible. Removing a required field, changing the meaning or type of success or message, or allowing multiple stdout documents 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.

Propose a pilot About Alejandro Fund public work