Schema.org Qualified Properties

Documentation Schema.org Qualified Properties

Last updated Mar 30, 2026

Overview

Use dot notation to map fields to nested Schema.org objects.

Description

Some Schema.org properties expect nested objects rather than simple values. Qualified properties use dot notation to specify both the object type and property within that object.

For example, a Product’s price isn’t just a number. It’s part of an Offer object that includes price, currency, and availability. Using Offer.price tells ACF to create the nested structure automatically.

Syntax

{ObjectType}.{propertyName}

Examples: – Offer.price: Price within an Offer – Offer.priceCurrency: Currency code within an Offer – NutritionInformation.calories: Calories within nutrition data – HowToStep.text: Text content of a how-to step

How It Works

When you map a field to a qualified property, ACF:

1. Parses the qualified property into object type and property name
2. Creates the nested object structure in the JSON-LD output
3. Assigns the appropriate @type to the nested object
4. Places the field value in the correct property

Example: Product Pricing

Field mappings: – Price field → Offer.price – Currency field → Offer.priceCurrency – Availability field → Offer.availability

JSON-LD output:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "offers": {
    "@type": "Offer",
    "price": 79.99,
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}

Example: Recipe Nutrition

Field mappings: – Calories field → NutritionInformation.calories – Protein field → NutritionInformation.proteinContent – Fat field → NutritionInformation.fatContent

JSON-LD output:

{
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Chocolate Chip Cookies",
  "nutrition": {
    "@type": "NutritionInformation",
    "calories": "250 calories",
    "proteinContent": "3 g",
    "fatContent": "12 g"
  }
}

Common Qualified Properties

Product/E-commerce

Qualified Property	Description
Offer.price	Product price
Offer.priceCurrency	Currency code (USD, EUR, etc.)
Offer.availability	Stock status
Offer.priceValidUntil	Price expiration date
Offer.itemCondition	New, Used, Refurbished
AggregateRating.ratingValue	Average rating
AggregateRating.reviewCount	Number of reviews
Brand.name	Brand name

Recipe

Qualified Property	Description
NutritionInformation.calories	Calorie count
NutritionInformation.fatContent	Fat amount
NutritionInformation.proteinContent	Protein amount
NutritionInformation.carbohydrateContent	Carb amount
NutritionInformation.servingSize	Serving size
HowToStep.text	Step instructions
HowToStep.name	Step name/title
HowToStep.image	Step image

Event

Qualified Property	Description
Place.name	Venue name
Place.address	Venue address
PostalAddress.streetAddress	Street address
PostalAddress.addressLocality	City
PostalAddress.addressRegion	State/region
PostalAddress.postalCode	ZIP/postal code
PostalAddress.addressCountry	Country
Offer.price	Ticket price
Offer.url	Ticket purchase URL

Organization/LocalBusiness

Qualified Property	Description
PostalAddress.streetAddress	Business address
ContactPoint.telephone	Phone number
ContactPoint.email	Email address
ContactPoint.contactType	Type (sales, support)
OpeningHoursSpecification.dayOfWeek	Day of week
OpeningHoursSpecification.opens	Opening time
OpeningHoursSpecification.closes	Closing time

Person

Qualified Property	Description
Organization.name	Employer name
PostalAddress.addressLocality	City
ContactPoint.email	Contact email

Multiple Fields, Same Object

When multiple fields map to the same object type, they’re combined into a single nested object:

Field mappings: – Street field → PostalAddress.streetAddress – City field → PostalAddress.addressLocality – State field → PostalAddress.addressRegion – ZIP field → PostalAddress.postalCode

JSON-LD output:

{
  "@type": "LocalBusiness",
  "name": "Joe's Coffee Shop",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "Austin",
    "addressRegion": "TX",
    "postalCode": "78701"
  }
}

Notes

• The object type in qualified properties must be a valid Schema.org type
• ACF automatically determines the parent property name (e.g., Offer → offers)
• Multiple fields mapping to the same object type are merged
• Empty values are excluded from nested objects
• If all properties of a nested object are empty, the entire object is excluded

Related

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