Overview
Output Schema.org structured data from ACF Block fields.
Description
ACF Blocks can automatically output JSON-LD structured data for their field values. This enables rich snippets and AI discoverability for block-based content.
Requirements
- ACF 6.8 or later
- Schema feature enabled via
add_filter( 'acf/settings/enable_schema', '__return_true' );
Configuration
Via block.json
Add the autoJsonLd and optional schemaType properties to the acf namespace:
{
"name": "acf/recipe-card",
"title": "Recipe Card",
"category": "formatting",
"acf": {
"mode": "preview",
"autoJsonLd": true,
"schemaType": "Recipe"
}
}
Via Programmatic Registration
Use the acf array when registering the block:
acf_register_block_type( array(
'name' => 'recipe-card',
'title' => __( 'Recipe Card' ),
'category' => 'formatting',
'acf' => array(
'autoJsonLd' => true,
'schemaType' => 'Recipe',
),
'render_template' => 'blocks/recipe-card.php',
));
Properties
autoJsonLd
(boolean) Enable JSON-LD output for this block. Default: false
schemaType
(string|array) The Schema.org type(s) for the block. Optional; ACF can auto-detect from field mappings. Can be a single type or array of types.
Field Mapping
Map block fields to Schema.org properties in the field group editor:
- Edit the field group assigned to the block
- For each field, set the Schema.org Property setting
- The mapped values will appear in the block’s JSON-LD output
Output
JSON-LD is output inline with each block instance on the frontend:
<!-- wp:acf/recipe-card -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Recipe",
"name": "Chocolate Chip Cookies",
"prepTime": "PT15M",
"cookTime": "PT12M"
}
</script>
<div class="wp-block-acf-recipe-card">
<!-- Block content -->
</div>
<!-- /wp:acf/recipe-card -->
Multiple Blocks
Each block instance outputs its own JSON-LD script. For pages with multiple blocks of the same type, each gets a separate structured data object.
Filters
Enable JSON-LD for specific blocks
add_filter( 'acf/ai/block_jsonld_enabled', function( $enabled, $block ) {
// Enable for specific block
if ( $block['name'] === 'acf/my-block' ) {
return true;
}
return $enabled;
}, 10, 2 );
Modify block JSON-LD data
add_filter( 'acf/schema/block_jsonld_data', function( $data, $block, $post_id ) {
// Add custom properties
$data['custom'] = 'value';
return $data;
}, 10, 3 );
Example: Recipe Block
block.json:
{
"name": "acf/recipe",
"title": "Recipe",
"acf": {
"autoJsonLd": true,
"schemaType": "Recipe"
}
}
Field mappings:
– Recipe Name → name
– Description → description
– Prep Time (minutes) → prepTime (Duration format)
– Cook Time (minutes) → cookTime (Duration format)
– Servings → recipeYield
– Ingredients (Repeater) → recipeIngredient
– Instructions (Repeater) → recipeInstructions
Output:
{
"@context": "https://schema.org",
"@type": "Recipe",
"name": "Chocolate Chip Cookies",
"description": "Classic homemade cookies",
"prepTime": "PT15M",
"cookTime": "PT12M",
"recipeYield": "24 cookies",
"recipeIngredient": [
"2 cups flour",
"1 cup sugar",
"1 cup chocolate chips"
],
"recipeInstructions": [
{
"@type": "HowToStep",
"text": "Preheat oven to 350°F"
},
{
"@type": "HowToStep",
"text": "Mix dry ingredients"
}
]
}
Notes
- JSON-LD is not output in the block editor preview
- Empty field values are automatically excluded
- Block JSON-LD is output inline with the block, not in
<head> - Multiple blocks on a page each get their own JSON-LD script
- The
schemaTypeis optional if fields are mapped; ACF infers the type
Supercharge Your Website With Premium Features Using ACF PRO
Speed up your workflow and unlock features to better develop websites using ACF Blocks and Options Pages, with the Flexible Content, Repeater, Clone, Gallery Fields & More.
Related
- Features: Automatic Structured Data with Schema.org
- Guides: ACF PRO 6.8 Beta 2 – Schema.org JSON-LD Testing Guide
- Features: Schema.org Property Mapping
- Filters: acf/schema/block_jsonld_enabled
- Features: Schema.org Output Formats
