How does PropertyValue represent a specification with a unit?

Definition: PropertyValue is a Schema.org property-value pair for an additional characteristic, such as a product specification. Put the specification label in name, its content in value, an identifying code or URL in propertyID when one is available, and its measurement unit in unitCode or unitText.

Key facts

• Schema.org describes PropertyValue as a pair that can represent a feature of a product or place and says to use name for the property name. PropertyValue can also carry a human-readable version in description.
• additionalProperty accepts PropertyValue and represents an extra characteristic for which no matching Schema.org property exists. Schema.org's additionalProperty definition also warns that applications built for specific properties generally expect those properties directly.
• Schema.org allows propertyID to be a prefixed string, a site-specific identifier, or a URL for the property type. The PropertyValue definition gives a standard code, a primary key, and an external vocabulary as examples.
• Google Search documents JSON-LD, Microdata, and RDFa as structured data formats. Its structured data introduction recommends JSON-LD when a site's setup supports it.

What is the outer object?

additionalProperty is the property that connects an entity to an extra characteristic. Its value is a PropertyValue object, so the outer entity can be a Product, Offer, Place, MerchantReturnPolicy, QualitativeValue, or QuantitativeValue, according to the Schema.org definition. A product specification can therefore be represented as a nested object rather than as an unlabelled text string.

Schema.org describes the extra characteristic as a product feature or another characteristic with no matching property in the vocabulary. The same page gives a direct qualification: when a specific property such as width, color, or gtin13 exists and can be populated, that specific property is the intended representation. PropertyValue is the extension point for the remaining characteristic.

What do name, value, propertyID, and the unit fields mean?

name labels the characteristic. Examples in the Schema.org material include Approx. Weight, Operating Voltage, and Luggage Capacity (seats folded). value carries the characteristic's content. For PropertyValue, Schema.org lists Text, Number, Boolean, StructuredValue, and QualitativeValue as possible value types. A number can therefore remain numeric when the specification is numeric, while a textual value can represent a label such as an interface type.

propertyID identifies what the characteristic means beyond its display label. Schema.org permits a prefixed string used by a product-property standard, a site-specific unprefixed identifier such as a vendor's key, or a URL pointing to an external vocabulary or explanatory resource. It is an identifier for the property itself, so it complements name and does not replace the specification's value.

For a measured value, unitCode carries a UN/CEFACT Common Code with three characters or a URL. Schema.org also permits another code with a prefix followed by a colon. unitText carries text indicating the measurement unit and is useful when a standard code cannot be provided. The value and its unit are separate fields, which lets a reader or parser distinguish 500 from LTR.

What does the markup look like?

The following JSON-LD shape follows Schema.org's product example for luggage capacity and places the four fields inside the PropertyValue object:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "additionalProperty": {
    "@type": "PropertyValue",
    "name": "Luggage Capacity (seats folded)",
    "value": 500,
    "unitCode": "LTR",
    "propertyID": "http://purl.org/vvo/ns#luggageCapacitySeatsFolded"
  }
}

Google's structured data documentation says JSON-LD is embedded in a script element and can express nested data items. It also says Google can read JSON-LD injected dynamically into page contents. That format guidance describes how to deliver the markup; it does not turn every Schema.org property into a documented search feature. Google states that it can make general use of Schema.org structured data and that some elements may support future Search features if they are useful.

How should you choose the unit field?

Use unitCode when the measurement has a suitable standard code or URL. Use unitText when the unit needs to remain readable text, such as gram in Schema.org's point-value example. Keep the numeric or textual measurement in value, and keep the label in name; this gives the extra property a defined characteristic, content, and unit.

If the same specification also has a recognized Schema.org property, populate that property according to its definition and reserve additionalProperty for the extra characteristic. Schema.org's warning about width, color, and gtin13 applies to the generic property/value mechanism as a whole.

Related terms

• Structured data
• JSON-LD
• Microdata
• Schema.org @id

FAQ

Can value contain a number and unit together?

Schema.org's examples separate a numeric value from unitCode or unitText. Keep the measurement in value and encode the unit in its dedicated field when the unit can be separated.

Is propertyID the same as name?

No. name is the readable label for the characteristic. propertyID identifies the characteristic with a standard prefix, a site-specific key, or a URL, according to Schema.org's definition.

Should every product specification use additionalProperty?

Use a specific Schema.org property when one exists and can be populated. additionalProperty is for an extra characteristic with no matching property in the vocabulary.

Sources

1. Schema.org, "PropertyValue", undated
2. Schema.org, "additionalProperty", undated
3. Google Search Central, "Intro to How Structured Data Markup Works", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer