How can a website express specifications without a dedicated Schema.org property?

Definition: Schema.org's additionalProperty is a property-value pair for an additional characteristic when Schema.org has no matching property. Its value is a PropertyValue, which carries the name of the characteristic and its value.

Key facts

• Schema.org defines additionalProperty for an additional characteristic for which there is no matching property in the vocabulary.
• The property expects a PropertyValue value.
• Schema.org lists Product, Offer, Place, MerchantReturnPolicy, QualitativeValue, and QuantitativeValue among the types that use additionalProperty.
• PropertyValue uses name for the characteristic's name and description for an additional human-readable version of the value.
• Schema.org instructs publishers to use a specific property when it exists and can be populated.

When is additionalProperty the right field?

Start by checking the properties available for the type being described. A product with a standard color, width, or gtin13 value has a named field for that characteristic. Schema.org's additionalProperty definition says applications built for such specific properties typically expect data through those properties. The generic field is therefore the place for a characteristic that has no matching Schema.org property.

The property is available on several types, including Product, Offer, and Place. Its value type remains PropertyValue, so the same basic structure can describe an extra fact attached to each of those entities. The definition also lists MerchantReturnPolicy, QualitativeValue, and QuantitativeValue as types that use it.

How should a custom specification be represented?

A PropertyValue is a structured value with a label for the characteristic and a value for the fact. Schema.org's PropertyValue documentation says to use name for the property name. It also provides description for a human-readable version of the value. For a measured specification, the page's product example places additionalProperty around a PropertyValue with name, value, and unitText:

<div itemscope itemtype="https://schema.org/Product">
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="https://schema.org/PropertyValue">
      <span itemprop="name">Approx. Weight</span>
      <span itemprop="value">450</span>
      <span itemprop="unitText">gram</span>
  </div>
</div>

The outer item identifies the entity. The nested item identifies the generic property-value pair, while name, value, and unitText make the specification legible as structured data. The example uses Microdata embedded in HTML, and the same PropertyValue concept can be represented in another Schema.org syntax.

What should happen when a more specific property exists?

Use the specific Schema.org property whenever it exists and the website has the corresponding value. Schema.org's PropertyValue page states that a PropertyValue substitute typically does not trigger the same effect as the original specific property. This is a documented consumer expectation, so a generic additionalProperty entry should not duplicate a value that already has an appropriate named field.

For a characteristic that comes from another vocabulary, propertyID can identify the characteristic. Schema.org describes propertyID as a commonly used identifier and allows a prefixed standard identifier, a site-specific identifier, or a URL pointing to an external vocabulary or glossary. The value still belongs inside PropertyValue.

When is a vocabulary extension more suitable?

An additionalProperty entry describes a fact inside the existing Schema.org model. A vocabulary extension gives a broadly applicable characteristic its own term. Schema.org's extension documentation says that third-party hosted extensions for broadly applicable vocabulary continue as before. It also reserves pending for experimental terms that may later enter the core vocabulary or be dropped.

The extension page says hosted extension terms are considered part of Schema.org while retaining a label for their origin. That route suits a term intended for reuse across sites; additionalProperty suits a characteristic that can be expressed as one named value on an entity.

Related terms

• Structured data
• JSON-LD
• How does Schema.org validation differ from Google's Rich Results Test?
• Does Google require special structured data for AI features?

FAQ

Can additionalProperty replace a specific Schema.org property?

Use the specific property when it exists and you can populate it. Schema.org documents additionalProperty for an additional characteristic with no matching property.

What fields belong inside PropertyValue?

Use name for the characteristic name. Add value for the value, and use a unit field such as the documented unitText example when a measurement needs a unit.

Does additionalProperty create a new Schema.org property?

It records a named fact through the existing additionalProperty and PropertyValue terms. A reusable term hosted outside the core vocabulary follows the extension model described by Schema.org.

Sources

1. Schema.org, "additionalProperty", undated
2. Schema.org, "PropertyValue", undated
3. Schema.org, "Schema.org extensions", undated

---

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