Schema.org Property Mapping

Documentation Schema.org Property Mapping

Last updated Mar 30, 2026

Overview

Map ACF fields to Schema.org properties for structured data output.

Description

Each ACF field can be mapped to a Schema.org property. This mapping determines how the field value appears in the JSON-LD output. Properties are filtered based on field type compatibility, so you’ll only see properties that make sense for the field type you’re editing.

Configuration

Field-Level Settings

When editing a field, you’ll see two Schema.org settings:

Schema.org Property Select the property this field should map to. Properties are organized by Schema.org type and filtered to show only compatible options.

Schema.org Output Format Choose how the field value should be formatted in the JSON-LD output. Available formats depend on the field type and selected property.

Property Selection

Properties are presented in a hierarchical dropdown grouped by Schema.org type:

Common Properties
├── name
├── description
├── url
└── image

Recipe
├── prepTime
├── cookTime
├── recipeYield
├── recipeIngredient
└── recipeInstructions

Product
├── price
├── priceCurrency
├── sku
└── availability

Context-Aware Suggestions

When editing a field group assigned to a post type with a Schema.org type configured, relevant properties are prioritized at the top of the dropdown.

For example, if your field group is assigned to a “Recipe” post type with schema_type: Recipe, properties like prepTime, cookTime, and recipeIngredient appear first.

Qualified Properties

Some properties belong to nested objects within the main schema. These are represented as “qualified properties” using dot notation:

Qualified Property	Meaning
Offer.price	Price within an Offer object
Offer.priceCurrency	Currency within an Offer object
NutritionInformation.calories	Calories within nutrition data
HowToStep.text	Text of a how-to step

When you use a qualified property, ACF automatically creates the nested structure:

Field mapping: Offer.price with value 29.99

Output:

{
  "@type": "Product",
  "offers": {
    "@type": "Offer",
    "price": 29.99
  }
}

Common Property Mappings

Text Fields

Property	Description	Example Value
name	Primary name/title	“Chocolate Chip Cookies”
description	Description text	“Classic homemade cookies”
headline	Article headline	“How to Bake Perfect Cookies”
alternativeHeadline	Subtitle	“A beginner’s guide”
text	Body text content	Full article content
sku	Product SKU	“COOKIE-001”

Number Fields

Property	Description	Example Value
price	Price amount	29.99
ratingValue	Rating score	4.5
reviewCount	Number of reviews	127
calories	Calorie count	250
recipeYield	Serving size	24

Date/Time Fields

Property	Description	Example Value
datePublished	Publication date	“2024-01-15”
dateModified	Last modified	“2024-01-20”
startDate	Event start	“2024-02-01T09:00:00”
endDate	Event end	“2024-02-01T17:00:00”
prepTime	Prep duration	“PT15M” (15 minutes)
cookTime	Cook duration	“PT30M” (30 minutes)

Image Fields

Property	Description	Output
image	Primary image	URL or ImageObject
thumbnail	Thumbnail image	URL
logo	Organization logo	ImageObject
photo	Person/place photo	ImageObject

Relationship Fields

Property	Description	Output
author	Content author	Person object
publisher	Publisher	Organization object
brand	Product brand	Brand object

Field Type Ranges

Each field type supports specific Schema.org data types:

Text-Based Fields

text, textarea, wysiwyg
├── Text
├── URL
├── CssSelectorType
├── XPathType
└── PronounceableText

Number Fields

number, range
├── Number
├── Integer
├── Float
├── Text (formatted)
└── Duration (ISO 8601)

Date/Time Fields

date_picker → Date
date_time_picker → DateTime
time_picker → Time

Boolean Fields

true_false → Boolean

Media Fields

image
├── ImageObject
├── URL
└── Text (URL string)

file
├── MediaObject
├── URL
└── Text

Notes

• Only fields with a schema_property set are included in JSON-LD output
• Empty values are automatically excluded
• Nested object types (Person, Organization, etc.) get automatic @type assignment
• Properties are validated against Schema.org specifications
• Invalid mappings are silently ignored to prevent malformed output

Related

• Features: Schema.org Qualified Properties
• Features: Schema.org Output Formats
• Features: Automatic Structured Data with Schema.org
• Filters: acf/schema/output_format_choices
• Features: Structured Data for ACF Blocks