schema.org Documentation

Appearance

Extend a type ​

Reference

Most sites never need to extend the vocabulary. When you do need a property or sub type that the core vocabulary does not provide, schema.org offers an extension mechanism that keeps your data interoperable.

When to consider extending ​

  • You have a property that no existing type captures.
  • You operate in a domain with a hosted extension, such as automotive, financial, or health and life sciences, that already covers your needs.

Steps ​

  1. Check the hosted and pending vocabularies first. Many specialized terms already exist in a hosted extension or in the pending area. Reuse before you invent.

  2. Prefer the most specific existing type. A new sub type is rarely needed. Often an existing type plus additionalType is enough.

  3. Use additionalType for extra typing. The additionalType property lets you attach an extra type identifier to an item without leaving the core model.

json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "additionalType": "https://example.com/ontology/CustomGadget",
  "name": "Custom Gadget"
}

  1. Use a private extension for internal properties. External or private extensions live under your own namespace so they do not collide with the core vocabulary.

  2. Propose changes through the community process. Genuinely general terms should be proposed to the community so they can become part of the shared vocabulary rather than a private extension.

Done when ​

  • You have confirmed no existing term fits.
  • Any custom typing uses additionalType or a clearly namespaced identifier.
  • Core schema.org parsing of your item still succeeds.

Notes ​

  • Extensions should add to the model, not replace core terms.
  • Keep custom identifiers stable so consumers can rely on them.