QuantitativeValue

QuantitativeValue is a StructuredValue type for any measured quantity: weight, length, volume, capacity, distance, duration count, attendee count, mileage, room count. It has 7 properties of its own: value (single measurement), minValue/maxValue (ranges), unitCode (UN/CEFACT unit code), unitText (human-readable unit), additionalProperty, and valueReference. QuantitativeValue appears across schema.org wherever a measurement needs unambiguous machine-readable expression: Product weight, Vehicle mileage, Accommodation floor size, Recipe yield.

The type hierarchy is Thing → Intangible → StructuredValue → QuantitativeValue. The most consequential property is unitCode: a value of "100" with no unit could be 100 grams, 100 pounds, 100 kilograms, 100 cm, 100 inches, or anything else. Always include unitCode (preferred) or unitText.

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

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

Highlight legend:Required by GoogleRecommendedOptional

schema.org/QuantitativeValue

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "QuantitativeValue",
  "value": "220",
  "unitCode": "GRM",
  "unitText": "grams"
}
</script>

unitCode (UN/CEFACT)

unitCode takes a UN/CEFACT Common Code: "GRM" for grams, "KGM" for kilograms, "LBR" for pounds, "MTR" for meters, "FOT" for feet, "MTK" for square meters, "FTK" for square feet, "LTR" for liters, "GLI" for gallons (UK), "GLL" for gallons (US), "USD" for US dollars (in monetary contexts). The full list is at unece.org/trade/uncefact. Use unitCode when possible for international interoperability.

unitText fallback

unitText is a human-readable unit string: "kg", "lbs", "sq ft". Use it when no UN/CEFACT code fits, or alongside unitCode for display purposes. Search engines prefer unitCode but will use unitText when unitCode is absent.

value vs minValue/maxValue

Same pattern as MonetaryAmount: value for a single measurement, minValue+maxValue for a range. A 220-gram t-shirt uses value: 220. A 200-250 gram product range uses min/max.

Minimal valid version

The smallest markup that still produces a valid QuantitativeValue 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/QuantitativeValue (minimal)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "QuantitativeValue",
  "value": "220",
  "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.

Used across other rich results (Product, Vehicle, Accommodation, Recipe)
Google docs

Common QuantitativeValue 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.

01
Missing unitCode
Wrong
```
"value": 100 (no unit)
```
Right
```
"value": 100, "unitCode": "GRM"
```
Without a unit, 100 is ambiguous. Could be grams, kilograms, pounds, meters, items, or anything else. Always include unitCode (UN/CEFACT code) or unitText (human-readable string).
02
unitCode as a unit symbol
Wrong
```
"unitCode": "kg"
```
Right
```
"unitCode": "KGM" (UN/CEFACT code) or "unitText": "kg" (human-readable)
```
unitCode expects UN/CEFACT Common Codes (uppercase 3-letter codes like GRM, KGM, MTR, FTK). Symbols and abbreviations like "kg" or "lbs" go in unitText. The codes look weird but they are the international standard.
03
Mixing value with min/max range
Wrong
```
"value": 220, "minValue": 200, "maxValue": 250
```
Right
```
Use value for a single measurement OR minValue+maxValue for a range, not both
```
Same as MonetaryAmount: pick either single value or range, not both. Setting all three creates ambiguity about whether the data describes a point or an interval.

Schema properties in this example

QuantitativeValue StructuredValue value minValue maxValue unitCode unitText additionalProperty valueReference

About the example data

The weight of a XooTee Classic, used as a structured value inside the Product example.

Comments

Loading comments...