@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-contracts/maggie-ops/marketing-run-v1.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.topy.ai/contracts/maggie-ops/marketing-run-v1.schema.json",
+  "title": "Maggie marketing run",
+  "description": "One project-scoped run joining content, Social Share, Ads, and measurement. References evidence, approvals, mutations and readbacks by ID; never contains secrets or provider payloads. Validated by tools/clis/maggie_marketing_run.py, which also enforces cross-field rules (approval before external mutation, readback for succeeded mutations, regulated-content review gating only external publication, no secret fields).",
+  "type": "object",
+  "required": ["schemaVersion", "runId", "projectRef", "objective", "conversion", "channels", "timezone", "mode", "approval", "scheduleLayers"],
+  "not": {"anyOf": [{"required": ["scheduled_at"]}, {"required": ["scheduledAt"]}]},
+  "properties": {
+    "schemaVersion": {"const": "maggie-marketing-run-v1"},
+    "runId": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{2,127}$"},
+    "projectRef": {"type": "string", "minLength": 1},
+    "objective": {"type": "string", "minLength": 1},
+    "conversion": {
+      "type": "object",
+      "required": ["event", "source"],
+      "properties": {"event": {"type": "string"}, "source": {"type": "string"}}
+    },
+    "channels": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "timezone": {"type": "string", "description": "IANA time zone for the run."},
+    "mode": {"enum": ["draft", "scheduled", "executing", "completed", "cancelled"]},
+    "sourceRevisions": {
+      "type": "array",
+      "items": {"type": "object", "required": ["sourceId", "revision"], "properties": {"sourceId": {"type": "string"}, "revision": {"type": "string"}}}
+    },
+    "capabilityEvidence": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "approval": {
+      "type": "object",
+      "required": ["state"],
+      "properties": {
+        "state": {"enum": ["pending", "approved", "rejected", "not_required"]},
+        "actor": {"type": ["string", "null"]},
+        "approvalId": {"type": ["string", "null"]}
+      }
+    },
+    "scheduleLayers": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/scheduleLayer"}},
+    "mutations": {"type": "array", "items": {"$ref": "#/$defs/mutation"}},
+    "readbacks": {
+      "type": "array",
+      "items": {"type": "object", "required": ["readbackId"], "properties": {"readbackId": {"type": "string"}, "mutationRef": {"type": "string"}, "evidenceRef": {"type": "string"}}}
+    },
+    "policy": {
+      "type": "object",
+      "description": "Regulated-content review. Default off. When on, only external publication waits for an approved review; delivery, drafts, SEO/GEO and measurement continue.",
+      "properties": {
+        "regulatedContent": {"type": "boolean", "default": false},
+        "reviewRequired": {"type": "boolean", "default": true},
+        "reviewState": {"enum": ["not_required", "pending", "approved", "rejected"]},
+        "reviewerRef": {"type": "string"}
+      }
+    },
+    "stages": {
+      "type": "object",
+      "propertyNames": {"enum": ["delivery", "draft", "seo_geo", "measurement", "external_publication"]},
+      "additionalProperties": {"type": "object", "properties": {"status": {"type": "string"}, "reason": {"type": "string"}}}
+    },
+    "measurement": {"type": "object"}
+  },
+  "$defs": {
+    "scheduleLayer": {
+      "type": "object",
+      "required": ["layer", "timezone", "owner", "status", "reconciliation"],
+      "properties": {
+        "layer": {"enum": ["infrastructure", "content_calendar", "campaign_flight", "measurement_window"]},
+        "id": {"type": "string"},
+        "timezone": {"type": "string"},
+        "owner": {"type": "string", "minLength": 1},
+        "status": {"enum": ["planned", "active", "paused", "completed", "cancelled"]},
+        "start": {"type": "string"},
+        "end": {"type": "string"},
+        "lagDays": {"type": "integer", "minimum": 0},
+        "scheduleRef": {"type": "string", "description": "infrastructure only: the maggie-schedule job name."},
+        "reconciliation": {"type": "string", "minLength": 1, "description": "How this layer's actual state is read back and reconciled."}
+      }
+    },
+    "mutation": {
+      "type": "object",
+      "required": ["mutationId", "kind", "status"],
+      "properties": {
+        "mutationId": {"type": "string"},
+        "kind": {"enum": ["external_publication", "ads_change", "content_delivery", "draft_creation", "configuration"]},
+        "channel": {"type": "string"},
+        "status": {"enum": ["planned", "pending", "succeeded", "failed", "cancelled"]},
+        "idempotencyKey": {"type": "string"},
+        "approvalRef": {"type": "string"}
+      }
+    }
+  }
+}