workflow-artifact.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/ChelseaKR/outcome-receipts/blob/main/docs/schema/workflow-artifact.schema.json",
  "title": "Outcome Receipts workflow artifact",
  "description": "Versioned contract for deterministic evidence-workflow artifacts. Where an artifact embeds a receipt verbatim (an equity-review group, a migration or restatement before/after, a contract milestone's observed/threshold/financial), that object is a receipt from the receipts manifest and follows docs/schema/receipts.schema.json: a figure withheld by small-cell suppression carries suppressed: true with null for value, row_count, slice_hash, and column_names. A consumer must branch on suppressed and must not read, plot, or sum a withheld receipt as zero. `receipts verify-workflow` fails an artifact in which any object declaring suppressed: true still carries a number in one of those fields.",
  "type": "object",
  "required": [
    "schema_version",
    "kind",
    "relationship"
  ],
  "properties": {
    "schema_version": {
      "const": "1.0"
    },
    "kind": {
      "enum": [
        "restatement",
        "migration_equivalence",
        "requirement_change",
        "contract_evidence",
        "federated_rollup",
        "equity_review"
      ]
    },
    "relationship": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "enum": [
            "supersedes",
            "compares_to",
            "supports_contract",
            "rolls_up",
            "slices"
          ]
        },
        "bundle_digest": {
          "$ref": "#/$defs/digest"
        }
      },
      "additionalProperties": false
    },
    "approved_by": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "current_spec_digest": {
      "$ref": "#/$defs/digest"
    },
    "current_manifest_digest": {
      "$ref": "#/$defs/digest"
    },
    "before_spec_digest": {
      "$ref": "#/$defs/digest"
    },
    "after_spec_digest": {
      "$ref": "#/$defs/digest"
    },
    "prior_document_digest": {
      "$ref": "#/$defs/digest"
    },
    "current_document_digest": {
      "$ref": "#/$defs/digest"
    },
    "contract_digest": {
      "$ref": "#/$defs/digest"
    },
    "plan_digest": {
      "$ref": "#/$defs/digest"
    },
    "spec_digest": {
      "$ref": "#/$defs/digest"
    },
    "reason": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "contract_id": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "controlling_text": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "policy_citation": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "legal_determination": {
      "const": "not_made"
    },
    "period": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "population_overlap": {
      "enum": [
        "disjoint",
        "not_deduplicated"
      ]
    },
    "suppression_policy_id": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "dimension": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "purpose": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "controlling_policy": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "consent_basis": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "category_provenance": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "changed": {
      "type": "array"
    },
    "added": {
      "type": "array"
    },
    "removed": {
      "type": "array"
    },
    "unchanged": {
      "type": "array"
    },
    "metrics": {
      "description": "One record per metric compared across the two specs. A metric withheld by small-cell suppression on either side is classified indeterminate rather than aborting the artifact: neither side publishes its value, so neither equivalence nor change can be asserted about it.",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["metric_id", "status", "before", "after"],
        "properties": {
          "metric_id": { "$ref": "#/$defs/nonEmptyString" },
          "status": {
            "description": "equivalent: both sides publish the same value. changed: both publish, and they differ. indeterminate: at least one side is withheld, so no comparison is possible. The same word contract_evidence uses for the same reason.",
            "enum": ["equivalent", "changed", "indeterminate"]
          },
          "delta_status": {
            "description": "Why no delta receipt is present. Required when status is indeterminate, absent otherwise.",
            "enum": ["suppressed"]
          },
          "delta_receipt": {
            "description": "The SQL-grounded difference between the two sides. Present exactly when status is equivalent or changed; a composed receipt over a withheld cell is refused, so an indeterminate metric carries none.",
            "$ref": "#/$defs/composedReceipt"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": { "status": { "const": "indeterminate" } },
              "required": ["status"]
            },
            "then": {
              "required": ["delta_status"],
              "not": { "required": ["delta_receipt"] }
            },
            "else": { "required": ["delta_receipt"] }
          }
        ]
      }
    },
    "requirements": {
      "type": "array"
    },
    "milestones": {
      "type": "array",
      "minItems": 1
    },
    "inputs": {
      "type": "array",
      "minItems": 2
    },
    "rollup_receipt": {
      "$ref": "#/$defs/composedReceipt"
    },
    "groups": {
      "description": "One record per allowlisted subgroup: a label and the subgroup's receipt, embedded verbatim from the receipts manifest. A group whose receipt carries suppressed: true is withheld, not empty.",
      "type": "array",
      "minItems": 2
    },
    "interpretation_limits": {
      "description": "What this artifact does not establish. When any group is withheld by suppression, the limits state that explicitly; `receipts verify-workflow` fails an equity review that withholds a group without saying so.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/nonEmptyString"
      }
    }
  },
  "oneOf": [
    {
      "properties": {
        "kind": {
          "const": "restatement"
        },
        "relationship": {
          "properties": {
            "type": {
              "const": "supersedes"
            }
          },
          "required": [
            "bundle_digest"
          ]
        }
      },
      "required": [
        "reason",
        "approved_by",
        "current_spec_digest",
        "current_manifest_digest",
        "changed",
        "added",
        "removed",
        "unchanged"
      ]
    },
    {
      "properties": {
        "kind": {
          "const": "migration_equivalence"
        },
        "relationship": {
          "properties": {
            "type": {
              "const": "compares_to"
            }
          }
        }
      },
      "required": [
        "approved_by",
        "before_spec_digest",
        "after_spec_digest",
        "metrics"
      ]
    },
    {
      "properties": {
        "kind": {
          "const": "requirement_change"
        },
        "relationship": {
          "properties": {
            "type": {
              "const": "compares_to"
            }
          }
        }
      },
      "required": [
        "prior_document_digest",
        "current_document_digest",
        "requirements"
      ]
    },
    {
      "properties": {
        "kind": {
          "const": "contract_evidence"
        },
        "relationship": {
          "properties": {
            "type": {
              "const": "supports_contract"
            }
          }
        }
      },
      "required": [
        "contract_id",
        "contract_digest",
        "controlling_text",
        "policy_citation",
        "approved_by",
        "milestones",
        "legal_determination"
      ]
    },
    {
      "properties": {
        "kind": {
          "const": "federated_rollup"
        },
        "relationship": {
          "properties": {
            "type": {
              "const": "rolls_up"
            }
          }
        }
      },
      "required": [
        "plan_digest",
        "period",
        "population_overlap",
        "suppression_policy_id",
        "approved_by",
        "inputs",
        "rollup_receipt"
      ]
    },
    {
      "properties": {
        "kind": {
          "const": "equity_review"
        },
        "relationship": {
          "properties": {
            "type": {
              "const": "slices"
            }
          }
        }
      },
      "required": [
        "spec_digest",
        "plan_digest",
        "dimension",
        "purpose",
        "controlling_policy",
        "consent_basis",
        "category_provenance",
        "approved_by",
        "groups",
        "interpretation_limits"
      ]
    }
  ],
  "$defs": {
    "digest": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "nonEmptyString": {
      "type": "string",
      "minLength": 1
    },
    "composedReceipt": {
      "type": "object",
      "required": [
        "provenance_type",
        "metric_id",
        "operation",
        "query",
        "inputs",
        "input_digest",
        "value",
        "display",
        "unit",
        "computed_at"
      ],
      "properties": {
        "provenance_type": {
          "const": "receipt_composed"
        },
        "metric_id": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "operation": {
          "enum": [
            "sum",
            "delta"
          ]
        },
        "query": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "inputs": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "metric_id",
              "receipt_digest"
            ],
            "properties": {
              "metric_id": {
                "$ref": "#/$defs/nonEmptyString"
              },
              "receipt_digest": {
                "$ref": "#/$defs/digest"
              }
            },
            "additionalProperties": false
          }
        },
        "input_digest": {
          "$ref": "#/$defs/digest"
        },
        "value": {
          "type": "number"
        },
        "display": {
          "type": "string"
        },
        "unit": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "computed_at": {
          "$ref": "#/$defs/nonEmptyString"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": true
}