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.
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/records/json \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"data": {"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/records/json \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"data": {"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.
---