Graph Validation

By default, we perform validation on Schema-related data to ensure it follows official recommendations and best practices. To start, structural semantics are evaluated which can result in messages about the following.

Unknown Term — e.g. schema:ExampleUnknown is not an official term
Unexpected Class — e.g. resource with a Vehicle type is not valid for an author
Unexpected Value — e.g. DateTime is not valid for a Boolean property
Unexpected Property — e.g. vehicleEngine is not documented for an ImageObject
Actions: Unbound Constraint — e.g. query-input property is not valid for a CreativeWork
Actions: Invalid Textual Constraint Key — e.g. optional is not a valid short-hand key
Roles: Unpropagated Property — e.g. OrganizationRole of a member must itself include a member

In some cases, a formal interpretation of specifications diverges from recommendations. We do not generate errors for the following, ambiguous scenarios and instead normalize them.

Indirect Class Reference — e.g. PlayAction for interactionType could be the type of a nested node
Indirect Literal Property — e.g. text for audience could be the name property of a nested node

Once the structure is evaluated, the following extended validations are also performed.

Properties — e.g. checksum gtin and gtin* numbers

Severity

Given the varied landscape of the web, Schema does not assume publishers will strictly adhere to its recommendations. Ultimately, downstream consumers (e.g. agents, search engines) determine what constitutes invalid data based on their own requirements. As a generalized tool, we use the following principles.

Error — data which cannot be reasonably interpreted, is fundamentally incorrect, or leads to statements which are contradictory.
Warning — data which may be correctly interpreted, but goes against official recommendations, is likely to be misinterpreted, or may unexpectedly be ignored.

The normalization step can help reconcile some warnings and transform data into more deterministic shapes.

Messages

Unknown Term

This message indicates an IRI from the schema.org domain was found, but it is not defined by the official vocabulary.

The most common cause for this is a typo, but it can also occur when validating against an older Schema.org release which has not yet defined the term.

Examples

Usage	Code
Error	{ "@type": "ExampleUnknownThing" }
Error	{ "exampleUnknownProperty": "Example" }
Error	{ "ex:property": { "@type": "ExampleUnknownDataType", "@value": "Example" } }
Error	{ "ex:property": { "@id": "ExampleUnknown" } }

Unexpected Class

This message indicates that a property expected one or more specific type of Thing, but the resource did not include any of them (nor their subtypes).

Examples

Usage	Code
Error	{ "author": { "@type": "ImageObject" } }

Unexpected Value

This generic message indicates that a value could not be matched to an expected type for a property. This can be due to several reasons, including:

Formatting — an improper syntax or format for data types which have expected values (e.g. dates, times); or
Enumeration — an invalid reference or textual name for the type; or
Type — an unexpected data type was used.

Examples

Usage	Code
Error	{ "availability": { "@id": "Monday" } }
Error	{ "availability": "ExampleUnknown" }
Error	{ "availability": false }
Error	{ "startDate": "day 4 of week 3 of month 2 of quarter 1" }

Unexpected Property

This message indicates that a valid property was found, but it is not one of the documented, expected properties for any of the resource types. Generally, agents will ignore properties that are not explicitly associated with a type, so it is always better to use type-recommended properties, when possible.

Examples

Usage	Code
Warning	{ "@type": "ImageObject", "addressCountry": "US" }

Actions: Unbound Constraint

This message indicates that an annotation property (matching *-input or *-output) was found on a non-Action resource. The behavior of these properties are undefined outside of an Action, and should not be used.

Learn more from the official Potential Actions documentation.

Examples

Usage	Code
Warning	{ "@type": "CreativeWork", "query-input": "name=q" }
Warning	{ "@type": "CreativeWork", "result-output": "required" }

Actions: Invalid Textual Constraint Key

This message indicates that the short-hand key used within a textual *-input or *-output property annotation is unsupported. The textual form only supports a limited number of keys with basic values. More complex forms should use a PropertyValueSpecification resource.

Learn more from the official Potential Actions documentation.

Short-hand Properties

Short-hand Key	Property
`required`	`valueRequired`
`value`	`defaultValue`
`name`	`valueName`
`readonly`	`readonlyValue`
`multiple`	`multipleValues`
`minlength`	`valueMinLength`
`maxlength`	`valueMaxLength`
`pattern`	`valuePattern`
`min`	`minValue`
`max`	`maxValue`
`step`	`stepValue`

Examples

Usage	Code
Warning	{ "@type": "SearchAction", "target": "http://example.com/search?q={q}", "query-input": "name=q optional" }

Roles: Unpropagated Property

This message indicates a property references a *Role type, but that role resource does not reuse the original property. Since the *Role types act as qualifiers, the original property should still be used with the unqualified resource.

Learn more from the official blog post announcement.

Examples

Usage	Code
Error	{ "member": { "@type": "OrganizationRole", "name": "Jane Doe" } }

Ignored Scenarios

Indirect Class Reference

Specifications currently do not differentiate between references to a Thing vs references to a resource with a type of Thing. By default, we do not emit a validation message and, instead, convert an otherwise-acceptable value into an anonymous resource using the Thing as its type.

Official documentation has used a mix of practices in examples, and it has been briefly mentioned on public GitHub comments as a potential issue (ref, ref).

Learn more from the related normalization topic.

Indirect Literal Property

Publishers sometimes use a literal value where a resource of a particular type is expected. By default, we do not emit a validation message and, instead, convert an otherwise-acceptable value into an anonymous resource with its equivalent inferred type and properties.

Learn more from the related normalization topic.