@mplp/schema 1.0.0

package/schemas/common/metadata.schema.json

@@ -0,0 +1,113 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$id": "https://schemas.mplp.dev/v1.0/common/metadata.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Metadata",
+  "description": "Common metadata structure for all MPLP objects. Provides version control, creation info, tags, and cross-cutting concern declarations. All top-level objects in L2/L3/L4 should include the meta field.",
+  "type": "object",
+  "properties": {
+    "protocol_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "MPLP protocol version, using Semantic Versioning.",
+      "examples": [
+        "1.0.0",
+        "1.1.0"
+      ]
+    },
+    "schema_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Schema version used by the current object, using Semantic Versioning.",
+      "examples": [
+        "2.0.0",
+        "2.1.0"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Object creation time (ISO 8601 format).",
+      "examples": [
+        "2025-01-28T15:30:00.000Z"
+      ]
+    },
+    "created_by": {
+      "type": "string",
+      "description": "Creator identifier (User ID / Agent Name / System ID).",
+      "examples": [
+        "user-123",
+        "agent-planner",
+        "system"
+      ]
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Object last update time (ISO 8601 format).",
+      "examples": [
+        "2025-01-28T16:45:00.000Z"
+      ]
+    },
+    "updated_by": {
+      "type": "string",
+      "description": "Last updater identifier.",
+      "examples": [
+        "user-456",
+        "agent-executor"
+      ]
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Set of tags for indexing/search. Supports custom classification and retrieval.",
+      "uniqueItems": true,
+      "examples": [
+        [
+          "production",
+          "high-priority"
+        ],
+        [
+          "development",
+          "experimental"
+        ]
+      ]
+    },
+    "cross_cutting": {
+      "type": "array",
+      "description": "Declares cross-cutting concerns enabled for the current object (one of the 9 concerns in Governance Plane).",
+      "items": {
+        "type": "string",
+        "enum": [
+          "coordination",
+          "error-handling",
+          "event-bus",
+          "orchestration",
+          "performance",
+          "protocol-version",
+          "security",
+          "state-sync",
+          "transaction"
+        ]
+      },
+      "uniqueItems": true,
+      "examples": [
+        [
+          "security",
+          "transaction"
+        ],
+        [
+          "performance",
+          "event-bus"
+        ]
+      ]
+    }
+  },
+  "required": [
+    "protocol_version",
+    "schema_version"
+  ],
+  "additionalProperties": false
+}

package/schemas/common/trace-base.schema.json

@@ -0,0 +1,43 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$id": "https://schemas.mplp.dev/v1.0/common/trace-base.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Trace Base",
+  "description": "Common base fields for Trace / Span structures. Designed based on W3C Trace Context standard, providing a unified tracing context for the MPLP execution chain. Supports distributed tracing and parent-child relationships of execution steps.",
+  "type": "object",
+  "properties": {
+    "trace_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier for a complete execution chain. All related Spans share the same trace_id."
+    },
+    "span_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier for the current step or operation. Each Span has a unique span_id."
+    },
+    "parent_span_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier of the parent step's span_id. Can be omitted if it is a root span."
+    },
+    "context_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier of the Context Root. Associates the Trace with a specific project context."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Additional attributes (key-value pairs) to extend trace information. Can contain custom metadata, tags, etc.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "module": "plan",
+          "operation": "create",
+          "user_id": "user-123"
+        }
+      ]
+    }
+  },
+  "required": [
+    "trace_id",
+    "span_id"
+  ],
+  "additionalProperties": false
+}

package/schemas/events/mplp-event-core.schema.json

@@ -0,0 +1,58 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-event-core.schema.json",
+  "title": "MPLP Core Event v1.0",
+  "description": "Base structure for MPLP observability events - provides common fields inherited by all event families",
+  "type": "object",
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this event (UUID v4)"
+    },
+    "event_type": {
+      "type": "string",
+      "description": "Specific event subtype (e.g., 'import_started', 'pipeline_stage_completed')"
+    },
+    "event_family": {
+      "type": "string",
+      "enum": [
+        "import_process",
+        "intent",
+        "delta_intent",
+        "impact_analysis",
+        "compensation_plan",
+        "methodology",
+        "reasoning_graph",
+        "pipeline_stage",
+        "graph_update",
+        "runtime_execution",
+        "cost_budget",
+        "external_integration"
+      ],
+      "description": "Event family classification - determines which minimal fields are required"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when event occurred"
+    },
+    "project_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Project context identifier (optional for system-level events)"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific payload data (schema varies by event_family)"
+    }
+  },
+  "required": [
+    "event_id",
+    "event_type",
+    "event_family",
+    "timestamp"
+  ],
+  "additionalProperties": true
+}

package/schemas/events/mplp-graph-update-event.schema.json

@@ -0,0 +1,58 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-graph-update-event.schema.json",
+  "title": "MPLP GraphUpdateEvent v1.0",
+  "description": "**REQUIRED** - PSG structural update events (MANDATORY for v1.0 compliance)",
+  "allOf": [
+    {
+      "$ref": "mplp-event-core.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "event_family": {
+          "const": "graph_update",
+          "description": "Must be 'graph_update' for this event type"
+        },
+        "graph_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "PSG identifier (typically project-level graph)"
+        },
+        "update_kind": {
+          "type": "string",
+          "enum": [
+            "node_add",
+            "node_update",
+            "node_delete",
+            "edge_add",
+            "edge_update",
+            "edge_delete",
+            "bulk"
+          ],
+          "description": "Type of graph mutation"
+        },
+        "node_delta": {
+          "type": "integer",
+          "description": "Node count delta (+/- or 0)"
+        },
+        "edge_delta": {
+          "type": "integer",
+          "description": "Edge count delta (+/- or 0)"
+        },
+        "source_module": {
+          "type": "string",
+          "description": "L2 module emitting this update (e.g., 'context', 'plan', 'collab')"
+        }
+      },
+      "required": [
+        "event_family",
+        "graph_id",
+        "update_kind",
+        "node_delta",
+        "edge_delta"
+      ]
+    }
+  ]
+}

package/schemas/events/mplp-map-event.schema.json

@@ -0,0 +1,147 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-map-event.schema.json",
+  "title": "MPLP MAP Event v1.0",
+  "description": "Events emitted by Multi-Agent Profile (MAP) collaboration sessions in MPLP v1.0 protocol",
+  "type": "object",
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this event"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "MAPSessionStarted",
+        "MAPRolesAssigned",
+        "MAPTurnDispatched",
+        "MAPTurnCompleted",
+        "MAPBroadcastSent",
+        "MAPBroadcastReceived",
+        "MAPConflictDetected",
+        "MAPConflictResolved",
+        "MAPSessionCompleted"
+      ],
+      "description": "Type of MAP session lifecycle event"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when event occurred"
+    },
+    "session_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Collaboration session ID (corresponds to Collab.collab_id)"
+    },
+    "initiator_role": {
+      "type": "string",
+      "description": "Role ID of the initiating agent (optional, depends on event type)"
+    },
+    "target_roles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Array of target role IDs for this event (e.g., broadcast targets)"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data payload",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "event_id",
+    "event_type",
+    "timestamp",
+    "session_id"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "turn_dispatched_payload": {
+      "type": "object",
+      "properties": {
+        "role_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Role receiving execution token"
+        },
+        "turn_number": {
+          "type": "integer",
+          "description": "Sequential turn number"
+        },
+        "token_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Execution token identifier"
+        }
+      },
+      "required": [
+        "role_id",
+        "turn_number"
+      ]
+    },
+    "turn_completed_payload": {
+      "type": "object",
+      "properties": {
+        "role_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Role that completed the turn"
+        },
+        "turn_number": {
+          "type": "integer",
+          "description": "Sequential turn number"
+        },
+        "result": {
+          "type": "object",
+          "description": "Turn execution result"
+        }
+      },
+      "required": [
+        "role_id",
+        "turn_number"
+      ]
+    },
+    "broadcast_sent_payload": {
+      "type": "object",
+      "properties": {
+        "broadcaster_role_id": {
+          "type": "string",
+          "description": "Role sending broadcast"
+        },
+        "target_count": {
+          "type": "integer",
+          "description": "Number of target agents"
+        },
+        "message": {
+          "type": "object",
+          "description": "Broadcast message content"
+        }
+      },
+      "required": [
+        "broadcaster_role_id",
+        "target_count"
+      ]
+    },
+    "broadcast_received_payload": {
+      "type": "object",
+      "properties": {
+        "receiver_role_id": {
+          "type": "string",
+          "description": "Role that received broadcast"
+        },
+        "response": {
+          "type": "object",
+          "description": "Agent response to broadcast"
+        }
+      },
+      "required": [
+        "receiver_role_id"
+      ]
+    }
+  }
+}

package/schemas/events/mplp-pipeline-stage-event.schema.json

@@ -0,0 +1,56 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-pipeline-stage-event.schema.json",
+  "title": "MPLP PipelineStageEvent v1.0",
+  "description": "**REQUIRED** - Pipeline stage transition events (MANDATORY for v1.0 compliance)",
+  "allOf": [
+    {
+      "$ref": "mplp-event-core.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "event_family": {
+          "const": "pipeline_stage",
+          "description": "Must be 'pipeline_stage' for this event type"
+        },
+        "pipeline_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Pipeline instance identifier"
+        },
+        "stage_id": {
+          "type": "string",
+          "description": "Stage identifier (e.g., 'import', 'analyze', 'execute')"
+        },
+        "stage_name": {
+          "type": "string",
+          "description": "Human-readable stage name"
+        },
+        "stage_status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "skipped"
+          ],
+          "description": "Current status of the pipeline stage"
+        },
+        "stage_order": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sequential order of this stage in pipeline"
+        }
+      },
+      "required": [
+        "event_family",
+        "pipeline_id",
+        "stage_id",
+        "stage_status"
+      ]
+    }
+  ]
+}

package/schemas/events/mplp-runtime-execution-event.schema.json

@@ -0,0 +1,58 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-runtime-execution-event.schema.json",
+  "title": "MPLP RuntimeExecutionEvent v1.0",
+  "description": "Runtime execution lifecycle events (agents, tools, LLMs, workers)",
+  "allOf": [
+    {
+      "$ref": "mplp-event-core.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "event_family": {
+          "const": "runtime_execution",
+          "description": "Must be 'runtime_execution' for this event type"
+        },
+        "execution_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Execution instance identifier"
+        },
+        "executor_kind": {
+          "type": "string",
+          "enum": [
+            "agent",
+            "tool",
+            "llm",
+            "worker",
+            "external"
+          ],
+          "description": "Type of executor performing this execution"
+        },
+        "executor_role": {
+          "type": "string",
+          "description": "Role identifier (e.g., 'planner', 'reviewer', 'curl_executor')"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "cancelled"
+          ],
+          "description": "Current execution status"
+        }
+      },
+      "required": [
+        "event_family",
+        "execution_id",
+        "executor_kind",
+        "status"
+      ]
+    }
+  ]
+}

package/schemas/events/mplp-sa-event.schema.json

@@ -0,0 +1,109 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-sa-event.schema.json",
+  "title": "MPLP SA Event v1.0",
+  "description": "Events emitted by a Single Agent (SA) execution in MPLP v1.0 protocol",
+  "type": "object",
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this event"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "SAInitialized",
+        "SAContextLoaded",
+        "SAPlanEvaluated",
+        "SAStepStarted",
+        "SAStepCompleted",
+        "SAStepFailed",
+        "SATraceEmitted",
+        "SACompleted"
+      ],
+      "description": "Type of SA lifecycle event"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when event occurred"
+    },
+    "sa_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Identifier of the SA instance emitting this event"
+    },
+    "context_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Context ID bound to this SA execution"
+    },
+    "plan_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Plan ID being executed by this SA"
+    },
+    "trace_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Trace ID where this event is recorded"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data payload",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "event_id",
+    "event_type",
+    "timestamp",
+    "sa_id"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "step_started_payload": {
+      "type": "object",
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "agent_role": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "step_id"
+      ]
+    },
+    "step_completed_payload": {
+      "type": "object",
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "completed",
+            "failed"
+          ]
+        },
+        "result": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "step_id",
+        "status"
+      ]
+    }
+  }
+}