open-standards/wai/wai-quantum/schemas/answer.v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://git.transaction.science/Transaction-Science/open-standards/raw/branch/main/wai/wai-quantum/schemas/answer.v1.json",
  "title": "wai.quantum.answer/1",
  "description": "The answer view layer (engine::answer, wai/extensions/quantum-answers.md), a draft extension and not the agent path: a model's answer as a few view statements over OpenQASM 3, each view's numbers bound to an engine call written with @. This is the answer as the engine reads it (its statements, its root and the order its views are drawn in, its diagnostics, its digest and the receipt its marker carries), what carrying out its calls gives (evaluation), and what a seal over its statements signs (seal_request, seal_result). Its form may change before the extension is settled; DEPRECATIONS.md does not list a change to it.",
  "type": "object",
  "required": [
    "format",
    "complete",
    "statements",
    "diagnostics",
    "errors",
    "warnings",
    "digest"
  ],
  "properties": {
    "format": {
      "const": "wai.quantum.answer/1"
    },
    "complete": {
      "type": "boolean",
      "description": "Whether the text has ended; a snapshot of a stream has not."
    },
    "root": {
      "type": [
        "string",
        "null"
      ]
    },
    "order": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "statements": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/statement"
      }
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/diagnostic"
      }
    },
    "errors": {
      "type": "integer",
      "minimum": 0
    },
    "warnings": {
      "type": "integer",
      "minimum": 0
    },
    "digest": {
      "type": "string",
      "description": "BLAKE3 of the answer's text before its first marker, in hex: what a seal binds."
    },
    "receipt": {
      "type": [
        "object",
        "null"
      ],
      "description": "The receipt the answer's marker line carries."
    }
  },
  "$defs": {
    "statement": {
      "type": "object",
      "description": "A statement that stands: its name and line, what it is (a program, a view, an engine call or a value), whether it is ready, the names it depends on, and its program (the fenced qasm block, its lines, whether it reads, its qubits and bits) or its expression.",
      "required": [
        "name",
        "line",
        "kind",
        "status"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "line": {
          "type": "integer"
        },
        "kind": {
          "enum": [
            "program",
            "view",
            "call",
            "value"
          ]
        },
        "status": {
          "type": "string"
        },
        "deps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "view": {
          "type": "string"
        },
        "call": {
          "type": "string"
        },
        "qasm": {
          "type": "string"
        },
        "lines": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "reads": {
          "type": "boolean"
        },
        "qubits": {
          "type": "integer"
        },
        "bits": {
          "type": "integer"
        },
        "expr": {
          "type": "object",
          "description": "The expression as read: a view or an engine call with its arguments, a name, a list, an object or a literal.",
          "additionalProperties": true
        }
      }
    },
    "diagnostic": {
      "type": "object",
      "description": "A problem with a line: its code (the reader's Q… for a program, J100–J112 for a statement), what it does to the statement, its line and column, and the statement it names.",
      "required": [
        "code",
        "outcome",
        "line",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "outcome": {
          "enum": [
            "dropped",
            "defaulted",
            "warned",
            "refused",
            "lowered",
            "carried",
            "preserved",
            "failed",
            "retry"
          ]
        },
        "severity": {
          "enum": [
            "error",
            "warning"
          ]
        },
        "line": {
          "type": "integer",
          "minimum": 0
        },
        "column": {
          "type": "integer",
          "minimum": 0
        },
        "message": {
          "type": "string"
        },
        "statement": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "evaluation": {
      "type": "object",
      "description": "Every statement that is ready, carried out on the engine, by name: its value, or why the engine refused it.",
      "required": [
        "format",
        "digest",
        "results"
      ],
      "properties": {
        "format": {
          "const": "wai.quantum.answer/1"
        },
        "digest": {
          "type": "string"
        },
        "results": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/outcome"
          }
        }
      }
    },
    "seal_request": {
      "type": "object",
      "description": "What a seal's receipt seals as its request: the answer's digest and the statements it names.",
      "required": [
        "format",
        "answer",
        "sealed"
      ],
      "properties": {
        "format": {
          "const": "wai.quantum.answer/1"
        },
        "answer": {
          "type": "string"
        },
        "sealed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "seal_result": {
      "type": "object",
      "description": "What a seal's receipt seals as its result: each named statement's value.",
      "required": [
        "statements"
      ],
      "properties": {
        "statements": {
          "type": "object",
          "additionalProperties": true
        },
        "receipt": {
          "$ref": "receipt.v2.json"
        }
      }
    },
    "outcome": {
      "type": "object",
      "description": "One statement's value, or its refusal as data (its message, codes, outcome and meaning).",
      "required": [
        "ok"
      ],
      "properties": {
        "ok": {
          "type": "boolean"
        },
        "value": {},
        "error": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "code": {
          "type": [
            "string",
            "null"
          ]
        },
        "codes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "outcome": {
          "type": "string"
        },
        "meaning": {
          "type": "string"
        }
      }
    },
    "verify": {
      "type": "object",
      "description": "A stored answer's receipt checked by running the answer again: whether it seals what its statements give now, its key and signer, the seal's statement and what it seals.",
      "required": [
        "valid"
      ],
      "properties": {
        "valid": {
          "type": "boolean"
        },
        "key": {
          "type": [
            "string",
            "null"
          ]
        },
        "signer": {
          "type": [
            "string",
            "null"
          ]
        },
        "statement": {
          "type": "string"
        },
        "sealed": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}