Profile: image

Profile Schema

The image profile indicates a document that is intended to represent an image resource. Image documents contain 0 or more links to image files themselves, as well as metadata about the image and its intended use.

The image profile is intended to be used as a “type” profile.

Structure

image specifies the following attributes:

Name Type Required? Explanation
enclosures Link[] Yes a list of links to the image files themselves; see “Enclosures” below
title string No the title of the image
producer string No the name of the person or organization who produced the image
provider string No the name of the person or organization who provided the image
providerLink Link No a link to the person or organization who provided the image. This link cannot have rels.
altText string No text that is displayed when a user hovers over the image. It is also what is spoken by a screen reader in place of the image.
caption string No a caption to place alongside the image when rendered
enlargementCaption string No a caption to place alongside an enlarged rendering of the image
displaySize string No the relative size to display the image on the main webpage for the document

Enclosures

image requires that the document contain an enclosures array with one or more links in it. Each enclosure in the image document represents a link to an image file. The attributes defined for enclosure links are:

Name Type Required? Explanation
href string Yes the location of the image file; must begin with http or https
hrefTemplate string No an RFC6570 URI template that can be used to construct a URI to this image; see the “hrefTemplate” section for more details.
rels string[] No string values describing the linked file and its intended use; see the “Image enclosure rels” section for values
type string No the expected RFC6838 media type of the linked file
width integer No the expected width of the original unscaled image, in pixels
height integer No the expected height of the original unscaled image, in pixels

An example enclosure link is below:

{
  "href": "https://npr-image-host.org/images/death-star.jpg",
  "hrefTemplate": "https://npr-image-host.org/images/death-star.png?w={width}&q={quality}&f={format}",
  "rels": [
    "standard",
    "scalable"
  ],
  "type": "image/jpeg",
  "width": 2664,
  "height": 1998
}

hrefTemplate

While the href value will always be present on the enclosure, publishers may also specify an hrefTemplate attribute indicating that a unique URI may be constructed for a custom version of the image. These templates are RFC6570 URI templates, and can have any of the following parameters present:

Parameter Explanation
width This parameter defines the desired width of the image in pixels. Changing this value scales the image up or down, but does not affect the aspect ratio. For a different aspect ratio, look for a different enclosure link in the images array (defined in the has-images profile).
quality This parameter defines the desired compression level of the final image. This value should be an integer between 1 and 100, with 100 being the original image quality, and 1 being 1% of the original quality.
format This parameter defines the desired file format of the final image. This should be an extension (like png, jpeg, or webp). If the default image format is intended to be used, then it should be derived from the image enclosure’s type attribute. If type is not provided, then it should default to using the in place file extension on hrefTemplate.
Publishing a template

Publishing clients should publish templates that conform to their image host’s interface. While the host itself may provide more options beyond format, width, and quality, CDS will only allow those parameters as of now (this prevents clients from breaking on unforeseen options). Note that not all parameters have to be present in the URI, but publishers should strive to make as many options available to the client as possible.

Template parameters should take the format of {<parameter name>}. While RFC6570 allows for more complicated parameter specifications, in practice the image resizing hosts we’re using don’t need them. In the future, this may change; if you find you need a more complicated parameter syntax, please reach out to the Core Services team.

Whenever possible, publishers should provide an hrefTemplate value.

Retrieving a template

If a template is available for an enclosure link, retrieval clients should default to using the template when retrieving the image. If a template is not available (or the URI constructed by the template is unresponsive), then clients should fall back to the href value.

The following is an example template value:

https://npr-media-host.com/tardis-schematics/interior.jpg?w={width}&q={quality}&f={format}

If a retrieval client wants a PNG image of width 200px and compressed to 75% of the original quality, the resulting URL would look like this:

https://npr-media-host.com/tardis-schematics/interior.png?w=200&q=75

When constructing a URI from a template, it is highly recommended that retrieval clients use a library (and not attempt a simple find-replace). RFC6570 defines template parameters with a complex syntax that may be difficult to parse with a simple regex.

Once a URI is constructed from the template, clients should use it as normal.

Image enclosure rels

The following rel values are valid for enclosure links; other rel values will be rejected.

Crop rels; used to indicate the crop type of the linked image:

  • image-standard
  • image-square
  • image-wide
  • image-enlargement
  • image-custom
  • image-brick
  • image-vertical
  • image-slide

Additional image enclosure rel values:

  • primary - Used to indicate the “featured” crop for this image
  • scalable - Indicates the image is resizable via URL parameters

displaySize

The display size for an image is really just relative to the other content on the main web page. It is a choice between

  • small
  • medium
  • large
  • x-large

Example image document 

{
  "id": "12345",
  "profiles": [
    {
      "href": "/v1/profiles/image",
      "rels": [
        "type"
      ]
    },
    {
      "href": "/v1/profiles/document"
    }
  ],

  "title": "Naboo, prior to its destruction",
  "enclosures": [
    {
      "href": "https://npr-media-host.org/images/naboo.jpg",
      "hrefTemplate": "https://npr-media-host.org/images/naboo.jpg?w={width}&q={quality}&f={format}",
      "rels": [
        "image-standard",
        "primary"
      ],
      "type": "image/jpeg",
      "width": 3342,
      "height": 2505
    }
  ],
  "producer": "Pulsar Photography",
  "provider": "Planetary Pictures Inc.",
  "providerLink":
    {
    "href": "https://www.planetpictures.com/"
  },
  "caption": "Naboo, shown two years prior to its destruction, was a largely peaceful planet with a diversity of inhabitants.",
  "displaySize": "small"
}

© 2024 npr