Style Guide

Overview

This document serves as a guide for using schema.org data, and for designing new or amended schemas. It contains information on principles of schema design, writing and naming conventions, as well as usability conventions for consuming schema. It does not currently address modeling design patterns. For further materials shared by Schema.org community members, see the wiki area of the project's github repository.

Schema.org terms

There are three kinds of schema.org term in the schema.org data model: types, properties and enumerated values. All schema.org data is represented in a graph structure in which entities are related to each other by named properties.

Type

• TitleCase for case format (all words capitalized, all one string).
  • E.g. FoodEstablishment.
• Types have associated properties.
  • E.g. FoodEstablishment has the property servesCuisine.
  • There is a technical terminology, "domain" and "range" which is used during design discussions and in machine-readable files, but which is not intended for widespread use. For example, we say the domain of "alumni" includes EducationalOrganization, and its range includes "Person".
• Types also take their associated properties from their parent types, i.e. their supertypes.
  • E.g. FoodEstablishment has the property openingHours from its parent type(s), LocalBusiness, and has the property address from its parent's parent, Organization.

Property

• Property names must use lowerCamelCase for format (first word lowercase, subsequent words capitalized, all one string).
  • E.g. servesCuisine.
• Properties must have expected types.
  • E.g. the property servesCuisine has the expected type FoodEstablishment.
• Properties may have more than one expected type.
  • E.g. the property acceptsReservations has the expected type Boolean or Text or URL.
• Properties may be used on more than one type.
  • E.g. the property starRating can be used on FoodEstablishment OR LodgingBusiness.
• Properties must not take properties.

Enumerations

• TODO: describe enumeration data model
• TODO: add example

Naming conventions

• Do not give the same name to a type and a property.
  • Note that schema.org has some legacy cases where this was done in the past. This practice should be avoided.
  • E.g. Avoid creating both ContactPoint and contactPoint.
• Term names should use Singular naming only, even if the semantics call for a plural.
  • E.g. parent and not parents, even though for each type, there will always be multiple values for the property parent.
• Prepositions should come after the type or property name.
  • E.g. reservationFor.
• Abbreviations: When creating new types, spell out abbreviations, unless the result is painfully verbose.
  • Due to legacy entries, sometimes certain words may be abbreviated, or not, in schema.org. Due to lack of consistency, should search for both when looking for a schema term.
  • E.g. numTracks exists in schema.org as a legacy property. If we were creating this property now, it would be numberOfTracks (or better yet, name it trackCount to be semantically aligned with other counting properties).
• Spelling: US spellings must be used.
  • E.g. color and not colour.

Additional notes

Some additional notes on schema.org definitions.

• Schema.org types have a specific semantic meaning above what the word itself could mean; consuming applications can't just use a type because the name fits.
  • E.g. Physician as a type means a physician office, not a person who is a physician.
  • Avoid using the word "type" unless referring to the technical notion of a type or class.
  • Existing schema.org types and properties should be reused whenever the semantics needed already exist. The project will often adjust definitions (wording or type/property associations) to facilitate this; see the releases page for examples.
  • Schema.org uses open world philosophy: the omission of a claim should not be taken to imply negation: if a property isn't mentioned, this doesn't mean that it is false. Rather, it means that we don't know whether it's true or false.
  • E.g. restaurant, petsAllowed is a boolean property (T/F) of LodgingBusiness, but if petsAllowed is not set, then it is unknown whether pets are allowed.