Structured Data for ACF Blocks

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:

1. Edit the field group assigned to the block
2. For each field, set the Schema.org Property setting
3. 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 schemaType is optional if fields are mapped; ACF infers the type