JSON Schema
The strict rules AutoClaygent follows for Clay-compatible schemas
Clay's JSON Schema Is Not Standard
Clay uses OpenAI's Structured Outputs, which has stricter rulesthan standard JSON Schema. Many valid JSON Schema features will cause errors in Clay.
If your schema uses any disallowed keywords, Claygent will fail silently or return malformed data. Always validate your schema against these rules.
AutoClaygent generates Clay-compatible JSON schemas automatically. It knows all 12 rules and always produces valid schemas—you never have to debug schema errors manually.
The 12 Rules of Clay JSON Schema
Rule 1: Root Must Be Object
The root of your schema must be { "type": "object" }. Arrays at the root level are not allowed.
Rule 2: No Validation Keywords
These are NOT allowed in Clay:
minLength,maxLengthminimum,maximumpatternformatconst,default
Rule 3: Required additionalProperties: false
Every object in your schema MUST include "additionalProperties": false. This includes nested objects.
Rule 4: Use anyOf for Nullable Fields
To make a field optional/nullable, use anyOf:
"portal_url": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
}Rule 5: All Properties Must Be Required
List every property in the required array. Use anyOfwith null for optional fields instead of omitting from required.
Rule 6: No oneOf, allOf, or not
Only anyOf is allowed, and only for nullable fields.
Rule 7: Enums Must Use enum
For fields with fixed values (like confidence or detection method), use proper enum:
"detection_method": {
"type": "string",
"enum": ["subdomain", "redirect", "widget", "integration_page"]
}Enums enforce canonical values. Instead of getting "subdomain", "Subdomain", "sub-domain", and "SUBDOMAIN" — you get consistent data you can filter on.
Rule 8: Arrays Need items
Array types must define their item schema. Here's a real example for platform detection:
{
"type": "object",
"properties": {
"platforms_detected": {
"type": "array",
"items": {
"type": "object",
"properties": {
"platform_name": { "type": "string" },
"platform_category": {
"type": "string",
"enum": ["CRM", "Support", "Scheduling", "EHR", "Billing"]
},
"detection_method": {
"type": "string",
"enum": ["subdomain", "redirect", "widget", "integration_page"]
},
"evidence_url": { "type": "string" }
},
"required": ["platform_name", "platform_category", "detection_method", "evidence_url"],
"additionalProperties": false
}
},
"portal_url": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
},
"confidence": {
"type": "string",
"enum": ["high", "medium", "low"]
}
},
"required": ["platforms_detected", "portal_url", "confidence"],
"additionalProperties": false
}Bad vs. Good Schema
Bad Schema (Will Fail)
{
"type": "object",
"properties": {
"platform_name": {
"type": "string",
"minLength": 1
},
"confidence_score": {
"type": "number",
"minimum": 0,
"maximum": 100
}
}
}Problems: Uses minLength, minimum, maximum (not allowed), missing additionalProperties, missing required array.
Good Schema (Will Work)
{
"type": "object",
"properties": {
"platforms_detected": {
"type": "array",
"items": {
"type": "object",
"properties": {
"platform_name": { "type": "string" },
"platform_category": {
"type": "string",
"enum": ["CRM", "Support", "Scheduling", "EHR", "Billing"]
},
"detection_method": {
"type": "string",
"enum": ["subdomain", "redirect", "widget", "integration_page"]
},
"evidence_url": { "type": "string" }
},
"required": ["platform_name", "platform_category", "detection_method", "evidence_url"],
"additionalProperties": false
}
},
"portal_url": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
},
"confidence": {
"type": "string",
"enum": ["high", "medium", "low"]
}
},
"required": ["platforms_detected", "portal_url", "confidence"],
"additionalProperties": false
}Real-World Schema: CRM Validation
Here's a schema for validating CRM data against website reality — notice the nested objects, enums for status values, and evidence requirements:
{
"type": "object",
"properties": {
"industry_validation": {
"type": "object",
"properties": {
"crm_value": { "type": "string" },
"website_value": {
"anyOf": [{ "type": "string" }, { "type": "null" }]
},
"status": {
"type": "string",
"enum": ["match", "mismatch", "unknown"]
},
"evidence": { "type": "string" }
},
"required": ["crm_value", "status", "evidence"],
"additionalProperties": false
},
"overall_accuracy": {
"type": "string",
"enum": ["all_match", "some_mismatch", "all_mismatch", "mostly_unknown"]
},
"priority_flag": {
"type": "string",
"enum": ["high_priority", "review_needed", "likely_accurate"]
}
},
"required": ["industry_validation", "overall_accuracy", "priority_flag"],
"additionalProperties": false
}Your schema should enforce the output structure you need for downstream processing. Enums like priority_flag let you filter in Clay: "Show me all high_priority mismatches."
Common Mistakes
| Mistake | Fix |
|---|---|
Using format: "email" | Remove format, just use type: "string" |
Using format: "uri" | Remove format, just use type: "string" |
| Optional field not in required | Add to required, use anyOf with null type |
| Missing additionalProperties | Add "additionalProperties": false to every object |
| Root is an array | Wrap array in an object property (e.g., platforms_detected) |
| Using minimum/maximum | Remove validation, handle in prompt instructions instead |
Try the Validator
Paste your JSON schema below and see if it's valid for Clay:
This validator checks for Clay-specific JSON Schema requirements. Standard JSON Schema validators won't catch these issues.
Test your schema at jsonschema.dev, then manually verify against Clay's rules before using.
Key Takeaways
- Clay uses OpenAI Structured Outputs — not standard JSON Schema
- No validation keywords (minLength, pattern, format, minimum, maximum)
- Always include
additionalProperties: falseon every object - Use
anyOfwith null for optional fields - All properties must be in the required array
- Use enums for canonical values (status, detection_method, confidence)