Schema Validation
Enforce required fields, types, min/max, and enums on an agent without migrations.
What you'll learn
- ✓PUT /v1/agents/:id/schema — set a schema
- ✓GET /v1/agents/:id/schema — read it back
- ✓DELETE /v1/agents/:id/schema — remove it
- ✓Supported rules: required, type, minLength, maxLength, minimum, maximum, enum
- ✓Validation error response with violations array
Set schema on orders agent: order_id (string, minLength 5), amount (number, min 0), currency (enum: USD/EUR/GBP). Write one valid and one invalid record.
Interactive Walkthrough
What you'll learn
How to enforce field types and required fields on an agent's records without migrations or external schema tools.
Set a schema on an agent
curl -s -X PUT http://localhost:7475/v1/agents/users/schema \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{
"schema": {
"required": ["user_id", "email", "plan"],
"properties": {
"user_id": {"type": "string", "minLength": 3},
"email": {"type": "string"},
"plan": {"type": "string", "enum": ["free", "starter", "pro", "enterprise"]},
"age": {"type": "number", "minimum": 0, "maximum": 150}
}
}
}' | python3 -m json.toolValid write — succeeds
curl -s -X POST http://localhost:7475/v1/agents/users/write \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"payload": {"user_id": "usr_002", "email": "carol@example.com", "plan": "pro"}}' \
| python3 -m json.toolInvalid write — fails validation
# Missing required field 'plan', and age out of range
curl -s -X POST http://localhost:7475/v1/agents/users/write \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"payload": {"user_id": "u", "email": "x@x.com", "age": 200}}' \
| python3 -m json.toolResponse:
`json
{
"error": "Schema validation failed",
"violations": [
"Missing required field: plan",
"user_id: minLength violation (got 1, min 3)",
"age: maximum violation (got 200, max 150)"
]
}
`
Read the schema back
curl -s http://localhost:7475/v1/agents/users/schema \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolRemove the schema
curl -s -X DELETE http://localhost:7475/v1/agents/users/schema \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"After deletion, all payloads are accepted again.
Supported validation rules
| Rule | Types |
|---|---|
required | Array of field names |
type | string, number, boolean, array, object, null |
minLength / maxLength | String |
minimum / maximum | Number |
enum | Any type — must match one of the listed values |
properties | Nested object, each key is a field schema |
Challenge
Set a schema on an orders agent requiring order_id (string, minLength 5), amount (number, minimum 0), currency (string, enum: USD/EUR/GBP). Write one valid and one invalid record to confirm.
---