Schema piece - ImageObject

Describes an individual image (usually in the context of an embedded media object).

NOTE: Whilst an image property (of a given node) can accept a simple URL representing an image file, we always enforce the use of an ImageObject to enable referencing-by-ID.

Triggers

Should be added as top-level nodes in the graph, as/when required by other nodes. E.g., when a WebPage has a featured image.

Required properties

A valid ImageObject must have the following properties.

  • @type: ImageObject.
  • @id: The site's home URL appended by #/schema/ImageObject/{{ID}}, where {{ID}} is a unique identifier for the image in question.
  • url: The fully-qualified, absolute URL of the image file (e.g., https://www.example.com/images/cat.jpg).
  • contentUrl: The fully-qualified, absolute URL of the image file (e.g., https://www.example.com/images/cat.jpg).

Failure scenarios

When we cannot ascertain the ID of an image but can ascertain its URL (e.g., in the case of filtering for external media storage), then the @id property should be set to the URL of the image.

If any of the required fields are missing or invalid, the node should not be output.

If the node is not output, any entities which would otherwise have declared a relationship with the Image (e.g., as the logo of an Organization) should remove those references.

Optional properties

The following should be added whenever available and valid:

  • caption: A text string describing the image.
    • Fall back to the image alt attribute if no specific caption field exists or is defined.

Conditional properties

Optional properties which should only be output when the required criteria is met.

When both height and width dimensions are known

  • height: The height of the image in pixels
  • width: The width of the image in pixels

When the image has a caption (or any other text properties)

  • inLanguage: The language code for the textual content; e.g., en-GB.

Notes

The contentUrl and url properties are intentionally duplicated.

The contentUrl property more accurately describes/references the actual image resource than the url property (which doesn't disambiguate between the URL where the image resource 'resides', vs the location of the asset itself). Given that, we'd prefer to not set/use the url property - or, to reserve it for use in scenarios where it refers to the location of an image (e.g., an anchor/fragment link to part of a webpage).

However, Google’s testing tools throw errors in some scenarios when the url property is missing (for logo and primaryImageOfPage in the SDTT, and primaryImageOfPage in the RRT). Therefore, we simply add a contentUrl property, with a value of the image URL.

Examples

Minimum criteria

{
"@context": "https://schema.org",
"@graph": [
{
"@type": "ImageObject",
"@id": "https://www.example.com/#/schema/ImageObject/abc123",
"url": "https://www.example.com/uploads/example-image.jpg"
"contentUrl": "https://www.example.com/uploads/example-image.jpg"
}
]
}

Extended criteria

{
"@context": "https://schema.org",
"@graph": [
{
"@type": "ImageObject",
"@id": "https://www.example.com/#/schema/ImageObject/abc123",
"url": "https://www.example.com/uploads/example-image.jpg",
"contentUrl": "https://www.example.com/uploads/example-image.jpg",
"caption": "Example caption",
"inLanguage": "en-US",
"width": 120,
"height": 120
}
]
}