reporting-governance-plugin/schemas/reporting-governance/decision-record-artifact.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cowbay.org/schemas/reporting-governance/decision-record-artifact.schema.json",
  "title": "Reporting Governance Decision Record Artifact",
  "description": "Portable decision storage artifact combining canonical decision output, truthful receipt state, and source linkage.",
  "type": "object",
  "additionalProperties": false,
  "required": ["kind", "apiVersion", "metadata", "spec"],
  "properties": {
    "kind": { "const": "DecisionRecordArtifact" },
    "apiVersion": { "const": "reporting-governance/v1alpha1" },
    "metadata": { "$ref": "#/$defs/metadata" },
    "spec": { "$ref": "#/$defs/spec" }
  },
  "$defs": {
    "canonicalTimestamp": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
    },
    "sourceEventId": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(?:evt_[A-Za-z0-9._:-]+|/?[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "required": ["record_id", "recorded_at", "policy_id", "decision", "correlation_id", "task_id", "event_id"],
      "properties": {
        "record_id": { "type": "string", "minLength": 1 },
        "recorded_at": { "$ref": "#/$defs/canonicalTimestamp" },
        "policy_id": { "type": "string", "minLength": 1 },
        "decision": { "type": "string", "minLength": 1 },
        "correlation_id": { "type": ["string", "null"] },
        "task_id": { "type": ["string", "null"] },
        "event_id": {
          "oneOf": [
            { "$ref": "#/$defs/sourceEventId" },
            { "type": "null" }
          ]
        }
      }
    },
    "receiptAction": {
      "type": "object",
      "additionalProperties": true,
      "required": ["action", "mandatory"],
      "properties": {
        "action": { "type": "string", "minLength": 1 },
        "mandatory": { "type": "boolean" }
      }
    },
    "blockedAction": {
      "type": "object",
      "additionalProperties": true,
      "required": ["action", "mandatory"],
      "properties": {
        "action": { "type": "string", "minLength": 1 },
        "mandatory": { "type": "boolean" },
        "reason": { "type": "string" }
      }
    },
    "receipt": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "policy_id",
        "decision",
        "status",
        "delivery_state",
        "enforcement_intent",
        "blocked_actions",
        "notes"
      ],
      "properties": {
        "policy_id": { "type": "string", "minLength": 1 },
        "decision": { "type": "string", "minLength": 1 },
        "status": { "enum": ["planned", "acked", "blocked", "degraded", "failed"] },
        "delivery_state": { "enum": ["prepared", "queued", "dispatched", "pending_external_send", "acked", "blocked", "failed", "partial"] },
        "operator_notice_required": { "type": "boolean" },
        "enforcement_intent": {
          "type": "array",
          "items": { "$ref": "#/$defs/receiptAction" }
        },
        "blocked_actions": {
          "type": "array",
          "items": { "$ref": "#/$defs/blockedAction" }
        },
        "notes": {
          "type": "array",
          "items": { "type": "string" }
        },
        "failure_reason": { "type": "string", "minLength": 1 }
      },
      "allOf": [
        {
          "if": {
            "properties": { "status": { "const": "failed" } },
            "required": ["status"]
          },
          "then": { "required": ["failure_reason"] }
        },
        {
          "if": {
            "properties": { "delivery_state": { "const": "partial" } },
            "required": ["delivery_state"]
          },
          "then": {
            "properties": {
              "blocked_actions": { "minItems": 1 },
              "enforcement_intent": { "minItems": 1 }
            }
          }
        },
        {
          "if": {
            "properties": { "status": { "const": "planned" } },
            "required": ["status"]
          },
          "then": {
            "properties": {
              "delivery_state": { "enum": ["prepared", "queued", "dispatched", "pending_external_send", "partial"] }
            }
          }
        },
        {
          "if": {
            "properties": { "status": { "const": "acked" } },
            "required": ["status"]
          },
          "then": {
            "properties": {
              "delivery_state": { "const": "acked" }
            }
          }
        },
        {
          "if": {
            "properties": { "status": { "const": "blocked" } },
            "required": ["status"]
          },
          "then": {
            "properties": {
              "delivery_state": { "const": "blocked" }
            }
          }
        },
        {
          "if": {
            "properties": { "status": { "const": "degraded" } },
            "required": ["status"]
          },
          "then": {
            "properties": {
              "delivery_state": { "enum": ["partial", "failed", "blocked"] }
            }
          }
        },
        {
          "if": {
            "properties": { "status": { "const": "failed" } },
            "required": ["status"]
          },
          "then": {
            "properties": {
              "delivery_state": { "const": "failed" }
            }
          }
        }
      ]
    },
    "source": {
      "type": "object",
      "additionalProperties": false,
      "required": ["event_id", "task_id", "correlation_id"],
      "properties": {
        "event_id": {
          "oneOf": [
            { "$ref": "#/$defs/sourceEventId" },
            { "type": "null" }
          ]
        },
        "task_id": { "type": ["string", "null"] },
        "correlation_id": { "type": ["string", "null"] }
      }
    },
    "spec": {
      "type": "object",
      "additionalProperties": false,
      "required": ["decision", "receipt", "source"],
      "properties": {
        "decision": { "$ref": "decision.schema.json" },
        "receipt": { "$ref": "#/$defs/receipt" },
        "source": { "$ref": "#/$defs/source" }
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "metadata": {
            "properties": {
              "event_id": { "type": "null" }
            },
            "required": ["event_id"]
          }
        }
      },
      "then": {
        "properties": {
          "spec": {
            "properties": {
              "source": {
                "properties": {
                  "event_id": { "type": "null" }
                },
                "required": ["event_id"]
              }
            }
          }
        }
      },
      "else": {
        "properties": {
          "spec": {
            "properties": {
              "source": {
                "properties": {
                  "event_id": { "$ref": "#/$defs/sourceEventId" }
                },
                "required": ["event_id"]
              }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "spec": {
            "properties": {
              "source": {
                "properties": {
                  "task_id": { "type": "null" },
                  "correlation_id": { "type": "null" },
                  "event_id": { "type": "null" }
                },
                "required": ["task_id", "correlation_id", "event_id"]
              }
            },
            "required": ["source"]
          }
        }
      },
      "then": false
    }
  ]
}