{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.oracleinsight.xyz/x402-quality/v0/x402-quality-v0.schema.json",
  "$comment": "Draft. Reference implementation published by Insight for the #2833 quality-attestation discussion. This is not a proposal to extend delivery-receipt semantics, and it is not an adopted standard.",
  "title": "x402-quality/v0",
  "description": "A composable quality-measurement artifact. It answers a different predicate from a delivery receipt: a delivery receipt answers 'do these response bytes belong to this paid interaction', while a quality attestation answers 'which evaluator, running which procedure, measured what'. Two evaluators may reach different conclusions about the same bytes without invalidating each other, which is why the two are separate artifacts joined only by binding, never by semantic extension.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema", "subject", "measurement", "attester"],
  "properties": {
    "schema": {
      "const": "x402-quality/v0"
    },
    "issued_at": {
      "type": "integer",
      "minimum": 0,
      "description": "Unix seconds at which this artifact was assembled. Not necessarily a signed field; see attester[].covers."
    },
    "subject": {
      "$ref": "#/$defs/subject"
    },
    "measurement": {
      "$ref": "#/$defs/measurement"
    },
    "attester": {
      "type": "array",
      "minItems": 1,
      "description": "List-shaped so a quorum or an independence rule can be expressed without forking the schema. See attester[].covers for what each signature actually commits to.",
      "items": {
        "$ref": "#/$defs/attesterEntry"
      }
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "description": "Escape hatch for implementation-specific metadata that carries no verification weight. Verifiers MUST NOT infer any guarantee from this object."
    }
  },
  "$defs": {
    "bytes32": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$"
    },
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "signature": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{130}$",
      "description": "65-byte ECDSA signature (r || s || v)."
    },
    "subject": {
      "type": "object",
      "additionalProperties": false,
      "description": "What the measurement is about. At least one binding MUST be present; extra bindings may be present together, and all present bindings MUST agree on the same object.",
      "properties": {
        "delivery_receipt_digest": {
          "allOf": [{ "$ref": "#/$defs/bytes32" }],
          "description": "Digest of an external delivery receipt, as defined on the delivery-receipt side. Present only when a delivery receipt exists to bind against."
        },
        "response_body_sha256": {
          "allOf": [{ "$ref": "#/$defs/bytes32" }],
          "description": "SHA-256 of the exact response bytes that were assessed. Appropriate when the assessed object IS the response body."
        },
        "bound_receipt": {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "uid"],
          "description": "Binding to a signed receipt issued by the evaluator itself. Use this when the assessed object is not a single response body but a measurement derived from a set of committed inputs; the integrity of those inputs travels in measurement.inputs.",
          "properties": {
            "kind": {
              "type": "string",
              "minLength": 1,
              "description": "Receipt family, e.g. 'oracle-pretrade', 'execution', 'oracle-watch'. Free-form in v0; a registry of known kinds is expected at v1."
            },
            "uid": {
              "allOf": [{ "$ref": "#/$defs/bytes32" }],
              "description": "The receipt's EIP-712 UID, i.e. the hash the issuer signed."
            },
            "schema_version": {
              "type": "integer",
              "minimum": 1
            },
            "primary_type": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      },
      "anyOf": [
        { "required": ["delivery_receipt_digest"] },
        { "required": ["response_body_sha256"] },
        { "required": ["bound_receipt"] }
      ]
    },
    "measurement": {
      "type": "object",
      "additionalProperties": false,
      "required": ["profile", "algorithm_version", "observed_at", "verdict"],
      "description": "Which procedure produced which numbers. `metrics` and `inputs` are intentionally open objects: the schema fixes the envelope, not the metric vocabulary.",
      "properties": {
        "profile": {
          "type": "string",
          "minLength": 1,
          "description": "Identifier of the measurement procedure, versioned within the profile name, e.g. 'oracle-pretrade/v3'. Two artifacts with different profiles are not comparable, and neither invalidates the other."
        },
        "algorithm_version": {
          "type": "string",
          "minLength": 1,
          "description": "Identifier of the implementation that executed the profile, e.g. 'insight-oracle-safety@3'."
        },
        "observed_at": {
          "type": "integer",
          "minimum": 0,
          "description": "Unix seconds at which the measurement was taken. This is the evaluator's clock, not the artifact's assembly time."
        },
        "verdict": {
          "type": "string",
          "minLength": 1,
          "description": "The profile's terminal outcome. The value domain belongs to the profile: v0 does not fix a global enum. Insight's oracle profiles use PASS, CAUTION and BLOCK."
        },
        "metrics": {
          "type": "object",
          "additionalProperties": true,
          "description": "The measured values, keyed by the profile's vocabulary."
        },
        "inputs": {
          "type": "object",
          "additionalProperties": true,
          "description": "Commitments to the inputs the measurement was derived from. Required in spirit for derived measurements: without these, the numbers cannot be recomputed. Insight's providerObservationsHash specifies its ABI, sort order and pipeline, and ships a test vector."
        },
        "valid_until": {
          "type": "integer",
          "minimum": 0,
          "description": "Unix seconds after which the measurement should be treated as stale. Carried over from the bound receipt when one exists."
        }
      }
    },
    "attesterEntry": {
      "type": "object",
      "additionalProperties": false,
      "required": ["address", "signature", "covers"],
      "description": "One signature over one thing. `covers` exists so the boundary is machine-readable rather than a footnote: an artifact whose signatures cover only a bound receipt is a recomputable view, not a signed assertion, and a verifier must treat it accordingly.",
      "properties": {
        "address": {
          "allOf": [{ "$ref": "#/$defs/address" }],
          "description": "The key that produced the signature. Trust in this key is established by the verifier against a registry it pinned itself; it is never established by this artifact."
        },
        "signature": {
          "$ref": "#/$defs/signature"
        },
        "signature_scheme": {
          "enum": ["eip712", "eip191", "other"],
          "default": "eip712"
        },
        "covers": {
          "enum": ["bound-receipt", "this-document"],
          "description": "'bound-receipt': the signature commits to the receipt named in bound_receipt_uid, and therefore to every field of that receipt, of which `measurement` must be a faithful projection. 'this-document': the signature commits to this artifact's own subject+measurement, canonically serialized per the profile."
        },
        "bound_receipt_uid": {
          "allOf": [{ "$ref": "#/$defs/bytes32" }],
          "description": "Required when covers is 'bound-receipt'. MUST equal subject.bound_receipt.uid when that binding is present."
        },
        "key_id": {
          "type": "string",
          "description": "Optional pointer into the issuer's published key registry, so a verifier can resolve the key's validity window without guessing."
        },
        "role": {
          "enum": ["attester", "sample"],
          "description": "'sample' marks a key that is published for conformance testing and MUST NOT be treated as a production attester. Mirror the registry's own role field."
        }
      },
      "allOf": [
        {
          "if": {
            "required": ["covers"],
            "properties": { "covers": { "const": "bound-receipt" } }
          },
          "then": { "required": ["bound_receipt_uid"] }
        }
      ]
    }
  }
}
