XooCode(){

PropertyValue

PropertyValue is schema.org's key-value pair for additional properties that do not have their own dedicated field. It fills the gap between a type's built-in properties (like price or color on Product) and the real-world specifications that buyers, visitors, or search engines need. Google reads PropertyValue from Product markup to show a "Product specifications" panel in shopping results. It also appears on Place and LocalBusiness for amenity features.

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

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

schema.org/PropertyValue
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "@id": "https://xoocode.com/shop/xootee-classic#product",
  "name": "XooTee Classic",
  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "Material",
      "value": "100% organic cotton"
    },
    {
      "@type": "PropertyValue",
      "name": "Fabric weight",
      "value": 180,
      "unitCode": "GRM",
      "unitText": "gsm"
    },
    {
      "@type": "PropertyValue",
      "name": "Color",
      "value": "Cerulean Blue"
    },
    {
      "@type": "PropertyValue",
      "name": "Fit",
      "value": "Regular"
    },
    {
      "@type": "PropertyValue",
      "name": "Print method",
      "value": "Water-based screen print"
    },
    {
      "@type": "PropertyValue",
      "name": "Care",
      "value": "Machine wash cold, tumble dry low, do not iron print"
    }
  ]
}
</script>

name and value

name is the property label ("Material", "Weight", "Color"). value is the property content ("100% organic cotton", "180 gsm", "Cerulean Blue"). Both are plain strings. Keep names consistent across products so Google can compare specifications across listings. If you call it "Material" on one product and "Fabric" on another, Google treats them as different properties.

unitCode and unitText

For measurable values, use unitCode (a UN/CEFACT code like "GRM" for grams, "CMT" for centimeters, "KGM" for kilograms) or unitText (a human-readable unit like "gsm" or "cm"). unitCode is machine-readable and preferred by structured data processors. unitText is a fallback for units without a standard code. Do not put the unit inside the value string ("180 gsm"); separate it into the unit field so processors can parse the numeric part.

propertyID for identifiers

When PropertyValue represents a product identifier rather than a specification (like a GTIN, MPN, or SKU), set propertyID to the identifier system name and value to the identifier itself. Example: "propertyID": "GTIN-13", "value": "5901234123457". Google uses this to match products across retailers. For common identifiers, prefer the dedicated Product properties (gtin13, mpn, sku) over PropertyValue, but PropertyValue works for non-standard identifier systems.

Minimal valid version

The smallest markup that still produces a valid PropertyValue 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/PropertyValue (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "PropertyValue",
  "name": "Material",
  "value": "100% organic cotton"
}
</script>

Google rich results this unlocks

PropertyValue is a structural type. It does not produce a rich result on its own.

Its value comes from combining it with a primary type whose markup earns a rich result (Article, Product, Event, and so on). PropertyValue becomes the trunk that the primary type branches off viamainEntityorbreadcrumb. Include it on every page as the backbone of your markup.

Common PropertyValue 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

    Unit inside the value string instead of unitCode/unitText

    Wrong
    "value": "180 gsm"
    Right
    "value": 180, "unitCode": "GRM", "unitText": "gsm"

    When the value is a measurement, separate the number from the unit. Putting "180 gsm" as a single string means processors cannot extract the numeric value for comparison or filtering. Use a numeric value with unitCode (machine-readable) or unitText (human-readable) alongside it.

  2. 02

    Inconsistent property names across products

    Wrong
    "Material" on one product, "Fabric" on another, "Fabric Type" on a third
    Right
    use "Material" consistently across all products

    Google compares PropertyValue names across product listings to build specification comparison tables. Inconsistent naming prevents Google from grouping the same property across products. Pick a name and use it everywhere.

  3. 03

    Using PropertyValue for properties that have dedicated fields

    Wrong
    { "@type": "PropertyValue", "name": "Color", "value": "Blue" } when the Product type has a color property
    Right
    "color": "Blue" on the Product directly, plus optionally in additionalProperty for the specs table

    Product has dedicated properties for color, material, weight, size, and pattern. Use the dedicated fields first because Google reads them directly. PropertyValue in additionalProperty is for supplementary details or specifications that do not have a dedicated schema.org property. You can include both for maximum coverage.

  4. 04

    Missing name or value

    Wrong
    { "@type": "PropertyValue", "value": "100% organic cotton" } (no name)
    Right
    { "@type": "PropertyValue", "name": "Material", "value": "100% organic cotton" }

    Both name and value are required for a meaningful PropertyValue. A value without a name is unlabeled data. A name without a value is an empty specification. Google ignores PropertyValue entries that are missing either field.

Schema properties in this example

PropertyValuenamevalueunitCodeunitTextpropertyIDadditionalProperty

About the example data

These specifications describe the XooTee Classic shirt in Cerulean Blue. The same properties would appear inside the Product example's additionalProperty array. Here they are shown with a Product wrapper so you can see how PropertyValue nests in practice.

Comments

Loading comments...

Leave a comment