Skip to main content

[!FROZEN] MPLP Protocol v1.0.0 Frozen Specification Freeze Date: 2025-12-03 Status: FROZEN (no breaking changes permitted) Governance: MPLP Protocol Governance Committee (MPGC) License: Apache-2.0 Note: Any normative change requires a new protocol version.

Common Schemas Reference

1. Purpose​

This document describes the common schema definitions shared across all MPLP modules. These foundational schemas ensure consistency in identifiers, metadata, events, and tracing across the protocol.

Source Directory: schemas/v2/common/

2. Schema Overview​

Schema FileTitlePurpose
identifiers.schema.jsonMPLP IdentifierUUID v4 identifier standard
metadata.schema.jsonMPLP MetadataCommon metadata structure
events.schema.jsonMPLP Base EventBase event model (CloudEvents-based)
common-types.schema.jsonMPLP Common TypesShared type definitions
trace-base.schema.jsonMPLP Trace BaseW3C Trace Context fields
learning-sample.schema.jsonMPLP Learning SampleStructured learning data format

3. Identifiers Schema​

File: identifiers.schema.json

3.1 Definition​

All MPLP identifiers use UUID v4 format for global uniqueness and collision-free generation in distributed environments.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

3.2 Usage​

Used for: context_id, plan_id, trace_id, event_id, confirm_id, role_id, step_id, etc.

3.3 Examples​

"123e4567-e89b-12d3-a456-426614174000"
"550e8400-e29b-41d4-a716-446655440000"

4. Metadata Schema​

File: metadata.schema.json

4.1 Required Fields​

FieldTypeDescription
protocol_versionString (SemVer)MPLP protocol version
schema_versionString (SemVer)Schema version used

4.2 Optional Fields​

FieldTypeDescription
created_atISO 8601 datetimeObject creation time
created_byStringCreator identifier
updated_atISO 8601 datetimeLast update time
updated_byStringLast updater identifier
tagsArray of stringsTags for indexing/search
cross_cuttingArray of enumsCross-cutting concerns enabled

4.3 Cross-Cutting Concerns Enum​

The 9 governance plane concerns:

coordination, error-handling, event-bus, orchestration, 
performance, protocol-version, security, state-sync, transaction

4.4 Example​

{
  "protocol_version": "1.0.0",
  "schema_version": "1.0.0",
  "created_at": "2025-01-28T15:30:00.000Z",
  "created_by": "agent-planner",
  "tags": ["production", "high-priority"],
  "cross_cutting": ["security", "transaction"]
}

5. Events Schema​

File: events.schema.json

Base model for all MPLP events, designed based on CloudEvents v1.0 core fields.

5.1 Required Fields​

FieldTypeDescription
event_idUUID v4Unique event identifier
event_typeStringEvent type (dot-separated)
sourceStringEvent source module/component
timestampISO 8601 datetimeEvent occurrence time

5.2 Optional Fields​

FieldTypeDescription
trace_idUUID v4Associated trace identifier
dataObject or nullEvent-specific business data

5.3 Event Type Pattern​

Pattern: ^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)*$

Examples: execution.started, plan.created, vsl.transition.applied

5.4 Example​

{
  "event_id": "550e8400-e29b-41d4-a716-446655440001",
  "event_type": "execution.completed",
  "source": "runtime.ael",
  "timestamp": "2025-01-28T15:30:00.000Z",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": { "status": "success", "duration_ms": 1234 }
}

6. Common Types Schema​

File: common-types.schema.json

Shared type definitions for cross-module consistency.

6.1 Definitions​

TypeDescription
MplpIdReference to identifiers.schema.json
RefStandard reference to another MPLP object
BaseMetaReference to metadata.schema.json

6.2 Ref Object​

A standard way to reference other MPLP objects.

Required: id, module

FieldTypeDescription
idUUID v4Referenced object ID
moduleEnumModule name
descriptionStringReference description

Module Enum:

context, plan, confirm, trace, role, extension, dialog, collab, core, network

6.3 Example​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "module": "plan",
  "description": "Parent plan reference"
}

7. Trace Base Schema​

File: trace-base.schema.json

Common base fields for Trace/Span structures, based on W3C Trace Context standard.

7.1 Required Fields​

FieldTypeDescription
trace_idUUID v4Complete execution chain ID
span_idUUID v4Current step/operation ID

7.2 Optional Fields​

FieldTypeDescription
parent_span_idUUID v4Parent span ID (omit for root)
context_idUUID v4Associated Context ID
attributesObjectAdditional key-value metadata

7.3 Example​

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "span_id": "550e8400-e29b-41d4-a716-446655440001",
  "parent_span_id": "550e8400-e29b-41d4-a716-446655440002",
  "context_id": "550e8400-e29b-41d4-a716-446655440003",
  "attributes": {
    "module": "plan",
    "operation": "create",
    "user_id": "user-123"
  }
}

8. Learning Sample Schema​

File: learning-sample.schema.json

Structured format for collecting learning data from MPLP runtime executions.

8.1 Required Fields​

FieldTypeDescription
sample_idUUID v4Unique sample identifier
project_idStringProject identifier
success_flagBooleanWhether action succeeded
timestampsObjectExecution timeline

8.2 Core Optional Fields​

FieldTypeDescription
intent_beforeObjectOriginal intent representation
planObjectPlan used
delta_intentsArrayDelta intents proposed/applied
graph_beforeObjectGraph state before change
graph_afterObjectGraph state after change
pipeline_pathArrayPipeline stages traversed

8.3 Metrics Fields​

FieldTypeDescription
token_usageObjectLLM token consumption
execution_time_msNumberExecution time (ms)
impact_scoreNumber (0-1)Impact score

8.4 Feedback Fields​

FieldTypeDescription
user_feedbackObjectHuman feedback on result
error_infoObjectError details if failed
governance_decisionsArrayGovernance rules evaluated

8.5 Token Usage Structure​

{
  "total_tokens": 15000,
  "prompt_tokens": 10000,
  "completion_tokens": 5000,
  "by_agent": [
    { "agent_id": "planner", "role": "orchestrator", "tokens": 8000 },
    { "agent_id": "coder", "role": "executor", "tokens": 7000 }
  ]
}

8.6 User Feedback Structure​

{
  "decision": "approve",  // approve, reject, override, unknown
  "comment": "Looks good",
  "rating": 4.5  // 0-5
}

9. Schema Relationships​

Architecture:

Modules:

Observability:

Learning:

Document Status: Normative (Common Schemas Reference)
Total Schemas: 6 foundational schemas
Standards: UUID v4, CloudEvents v1.0, W3C Trace Context, ISO 8601​

2025 Bangshi Beijing Network Technology Limited Company Licensed under the Apache License, Version 2.0.