ACF and JSON Schemas are a powerful duo for WordPress developers seeking more structure and automation in custom content modeling.
In today’s WordPress landscape, building flexible, scalable content experiences is more important than ever. Whether you’re working on a headless frontend, a custom dashboard, or a dynamic theme, your content structure needs to be reliable, repeatable, and environment-agnostic.
That’s where Advanced Custom Fields (ACF) and JSON Schema come in. Used together, they enable:
- Schema-based content modeling
- Automated ACF field registration
- Scalable and version-controlled configs
- Real-time validation and documentation
This guide walks you through practical ways to combine ACF and JSON Schemas to create structured WordPress development workflows—ideal for agencies, enterprise teams, or modern JAMstack sites.
What Is ACF?
Advanced Custom Fields (ACF) is a WordPress plugin that lets developers attach structured fields to content types (posts, pages, users, etc.).
You can define field groups via:
- The WordPress Admin UI
- PHP (using
acf_add_local_field_group())
ACF supports field types like:
- Text, image, WYSIWYG
- Repeater and flexible content
- Select, radio, checkbox
- Relationship, post object, taxonomy
What Is JSON Schema?
JSON Schema is a standardized way to define and validate the structure of JSON data. It ensures that your content follows a predefined format.
Example:
{
"title": "BlogPost",
"type": "object",
"properties": {
"title": { "type": "string" },
"content": { "type": "string" },
"featured_image": { "type": "string", "format": "uri" }
},
"required": ["title", "content"]
}Using JSON Schema, you can document, validate, and automate field generation for your WordPress content.
Why Use ACF and JSON Schemas Together?
Combining ACF and JSON Schemas unlocks new capabilities for WordPress projects:
- Consistency: Define content models once and deploy them across all environments.
- Automation: Generate ACF fields directly from JSON files.
- Scalability: Manage dozens of field groups using clean, modular schema files.
- Version Control: Store schemas in Git to track changes.
- Validation: Check that field data matches the schema before saving.
This approach reduces manual UI work and helps enforce standards across teams and deployments.
Dynamic Field Registration via Schema
You can create a simple PHP function to register ACF fields from a JSON Schema file:
function register_acf_from_schema($schema_path) {
$schema = json_decode(file_get_contents($schema_path), true);
$fields = [];
foreach ($schema['properties'] as $key => $value) {
$fields[] = [
'key' => "field_{$key}",
'label' => ucfirst($key),
'name' => $key,
'type' => $value['type'] === 'string' ? 'text' : 'text',
];
}
acf_add_local_field_group([
'key' => 'group_custom_fields',
'title' => $schema['title'],
'fields' => $fields,
'location' => [[
['param' => 'post_type', 'operator' => '==', 'value' => 'custom_type']
]]
]);
}Place this in your theme or plugin’s functions.php, and it will auto-register fields on load.
Example: Team Member Post Type
Let’s say you’re modeling a team_member post type. Your schema might look like this:
{
"title": "TeamMember",
"type": "object",
"properties": {
"name": { "type": "string" },
"position": { "type": "string" },
"bio": { "type": "string" },
"photo": { "type": "string", "format": "uri" }
},
"required": ["name", "position"]
}This schema can then be parsed into an ACF field group dynamically—ensuring consistency across dev, staging, and production.
Validating ACF Content with JSON Schema
During the acf/validate_save_post hook, you can validate ACF field data against your JSON Schema before it’s saved:
add_action('acf/validate_save_post', function() {
$data = $_POST['acf'];
$schema = json_decode(file_get_contents('team-member.schema.json'), true);
$validator = new JsonSchema\Validator();
$validator->validate($data, $schema);
if (!$validator->isValid()) {
foreach ($validator->getErrors() as $error) {
acf_add_validation_error('', 'Validation Error: ' . $error['message']);
}
}
});This adds an extra layer of safety—especially helpful in collaborative environments.
Best Practices for ACF and JSON Schemas
1. Use One Schema per Content Type
Avoid monolithic schemas. Break them down by post type, block, or section.
2. Keep Schemas in Version Control
Create a /schemas directory in your theme or plugin and commit each schema to Git.
3. Automate on Deploy
Write a CLI script or use WP-CLI to regenerate ACF field groups from schemas as part of your deployment process.
4. Add Schema Docs
Include title, description, and examples fields in your schema. Generate docs for onboarding or clients.
How Sitebox Makes This Even Easier
Sitebox streamlines the ACF + JSON Schema workflow with:
- 🔄 Auto-syncing JSON Schemas to ACF field groups
- 🛠️ Visual schema editor for content managers
- ✅ Real-time validation before content save
- 📡 Schema-driven REST and GraphQL APIs
Whether you’re building decoupled frontends or static sites, Sitebox gives you a unified way to manage structured content.
Conclusion
Using ACF and JSON Schemas together brings order and automation to modern WordPress development. You’ll avoid manual inconsistencies, streamline deployments, and improve collaboration between developers and non-technical teams.
Ready to power your next WordPress project with schema-based content modeling? Start integrating ACF and JSON Schemas into your workflow—and consider Sitebox to take your setup to the next level.
