XooCode(){

StructuredValue

StructuredValue is the parent type for every "compound value" in schema.org: a geographic point (GeoCoordinates), a price with currency (MonetaryAmount), a measurement with unit (QuantitativeValue), a key/value pair (PropertyValue), a contact method (ContactPoint, with PostalAddress under it), business hours (OpeningHoursSpecification), a shipping specification (OfferShippingDetails), and around 20 other compound types.

StructuredValue itself adds no properties. Its value is semantic: it is the umbrella under which schema.org expresses "this value is not a single atomic string, it is a small object with multiple named fields." Every property in schema.org that accepts a StructuredValue accepts any of its subtypes.

Full example of schema.org/StructuredValue json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional
schema.org/StructuredValue
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "XooTee Classic",
  "offers": {
    "@type": "Offer",
    "priceSpecification": {
      "@type": "UnitPriceSpecification",
      "price": { "@type": "MonetaryAmount", "value": "39.95", "currency": "CAD" }
    }
  },
  "weight": { "@type": "QuantitativeValue", "value": "180", "unitCode": "GRM" },
  "additionalProperty": [
    { "@type": "PropertyValue", "name": "Fabric certification", "value": "GOTS-certified organic cotton" },
    { "@type": "PropertyValue", "name": "Fit", "value": "Regular" }
  ],
  "manufacturer": {
    "@type": "Organization",
    "name": "Xoo Code Inc.",
    "location": {
      "@type": "Place",
      "geo": { "@type": "GeoCoordinates", "latitude": 41.4200, "longitude": -75.6333 }
    },
    "contactPoint": {
      "@type": "ContactPoint",
      "telephone": "+1-570-555-0100",
      "contactType": "customer support",
      "availableLanguage": ["en", "da"]
    }
  }
}
</script>

When to reach for a StructuredValue subtype

The general rule: if a value has components that consumers will need separately, use a StructuredValue subtype. A price needs value and currency. A weight needs value and unitCode. A geographic point needs latitude and longitude. A key/value property needs name and value. Free-text strings work for display but lose structure for processing.

Composition patterns

StructuredValue subtypes almost never stand alone. MonetaryAmount appears inside shippingRate, baseSalary, funding. QuantitativeValue appears inside weight, height, handlingTime, numberOfEmployees. GeoCoordinates appears inside geo on Place and LocalBusiness. PropertyValue appears inside additionalProperty, identifier, exifData. Learning the StructuredValue subtypes once gives you composable primitives you will use across hundreds of types.

Minimal valid version

The smallest markup that still produces a valid StructuredValue entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/StructuredValue (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "XooTee Classic",
  "weight": { "@type": "QuantitativeValue", "value": "180", "unitCode": "GRM" }
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

  • No dedicated rich result (parent of compound values)
    Google docs

Common StructuredValue mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    Using bare StructuredValue instead of a specific subtype

    Wrong
    "weight": { "@type": "StructuredValue", "value": "180" }
    Right
    "weight": { "@type": "QuantitativeValue", "value": "180", "unitCode": "GRM" }

    Bare StructuredValue carries no vocabulary. The subtypes give you the named fields consumers expect (currency on MonetaryAmount, latitude/longitude on GeoCoordinates, unitCode on QuantitativeValue).

  2. 02

    Flat strings where a StructuredValue subtype would compose

    Wrong
    "price": "39.95 CAD"
    Right
    "price": { "@type": "MonetaryAmount", "value": "39.95", "currency": "CAD" }

    A flat string mixes the two fields (amount and currency) into one opaque blob. Structured subtypes let consumers do currency conversion, filter by price range, and display the amount in local format.

Schema properties in this example

StructuredValueProductOfferpriceSpecificationUnitPriceSpecificationMonetaryAmountvaluecurrencyweightQuantitativeValueunitCodeadditionalPropertyPropertyValuenamemanufacturerOrganizationlocationPlacegeoGeoCoordinateslatitudelongitudecontactPointContactPointtelephonecontactTypeavailableLanguagePostalAddressOpeningHoursSpecificationOfferShippingDetails

About the example data

A generic StructuredValue parent example illustrating how the family composes inside a Product: price as MonetaryAmount, weight as QuantitativeValue, geo as GeoCoordinates, and a certification as PropertyValue.

Comments

Loading comments...

Leave a comment