Allegro
bcf8c31270
- Add JSON schema at schemas/state.json with full validation rules - Implement State, StateType, StateMetadata dataclasses in models/state.py - Support immutable state objects with versioning and TTL - Include serialization/deserialization (JSON and dict) - Add next_version() for state history chaining - Comprehensive test suite with 19 tests (100% pass) - Full documentation at docs/state-schema.md Features: - UUID validation for all ID fields - Optimistic locking via version numbers - Flexible payload structure - Metadata support (source, provenance, tags) - Expiration checking via TTL - Complete type hints Closes Issue #3
100 lines
2.9 KiB
JSON
100 lines
2.9 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"$id": "https://allegro.local/schemas/state.json",
|
|
"title": "SEED State Schema",
|
|
"description": "JSON Schema for State objects in the SEED Architecture",
|
|
"type": "object",
|
|
"required": ["id", "entity_id", "state_type", "payload", "timestamp", "version"],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique identifier for this state record (UUID v4)"
|
|
},
|
|
"entity_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Reference to the entity this state belongs to"
|
|
},
|
|
"state_type": {
|
|
"type": "string",
|
|
"enum": ["active", "inactive", "pending", "archived", "deleted"],
|
|
"description": "The type/category of this state"
|
|
},
|
|
"payload": {
|
|
"type": "object",
|
|
"description": "Flexible JSON payload containing state-specific data"
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when this state was recorded"
|
|
},
|
|
"version": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Version number for optimistic locking"
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Additional metadata about this state record",
|
|
"properties": {
|
|
"source": {
|
|
"type": "string",
|
|
"description": "Source system or service that created this state"
|
|
},
|
|
"provenance": {
|
|
"type": "string",
|
|
"description": "Trace ID or provenance information"
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "User or service that created this state"
|
|
},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Optional tags for categorization"
|
|
}
|
|
}
|
|
},
|
|
"previous_state_id": {
|
|
"type": ["string", "null"],
|
|
"format": "uuid",
|
|
"description": "Reference to the previous state record for this entity (null if first)"
|
|
},
|
|
"ttl": {
|
|
"type": ["integer", "null"],
|
|
"description": "Time-to-live in seconds (null for no expiration)"
|
|
}
|
|
},
|
|
"additionalProperties": false,
|
|
"examples": [
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"entity_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
|
|
"state_type": "active",
|
|
"payload": {
|
|
"status": "running",
|
|
"progress": 75,
|
|
"details": {
|
|
"last_action": "processing",
|
|
"queue_position": 3
|
|
}
|
|
},
|
|
"timestamp": "2026-04-02T19:30:00Z",
|
|
"version": 3,
|
|
"metadata": {
|
|
"source": "electra-archon",
|
|
"provenance": "trace-abc123",
|
|
"created_by": "electra",
|
|
"tags": ["seed", "priority"]
|
|
},
|
|
"previous_state_id": "550e8400-e29b-41d4-a716-446655440001",
|
|
"ttl": null
|
|
}
|
|
]
|
|
}
|