Image Resource

1. Introduction

Web applications often accept developer-provided image resources to be displayed outside of a HTML document (e.g., in the OS, in the browser UI, etc.). This specification defines a WebIDL dictionary that describes an image, and where that image resource can be fetched from. The user agent can then use this extra information to choose an image that is best suited to display on the end-user's device or most closely matches the end-user's preferences or environment.

2. Privacy and security considerations

Fetching an image resource can reveal the user's IP address. It is RECOMMENDED that user agents fetch the chosen image resources when provided by the developer, and store them for re-use if needed. This limits tracking the user's location over time.

3. Image resource

An image resource consists of:

src

A URL from where to obtain the image data.

sizes

An optional string representing the sizes of the image, expressed using the same syntax as link's sizes attribute.

type

An optional image MIME type.

label

A string representing the accessible name of the image.

In an API, this is represented as an ImageResource dictionary.

4. ImageResource dictionary

WebIDLdictionary ImageResource {
  required USVString src;
  DOMString sizes;
  DOMString type;
  DOMString label;
};

const image = {
  src: "path/to/image.ico",
  sizes: "16x16 32x32 64x64",
  type: "image/vnd.microsoft.icon",
};
some.api.doSomething(image);

5. Processing an ImageResource from an API

The steps to process an ImageResource from an API are given by the following algorithm. The algorithm takes an ImageResource input. It returns an image resource.

1. Let base URL be the relevant settings object’s api base url from where this dictionary is being used.
2. Let image be a new image resource.
3. Set image's src to the result of URL parsing input.src and base URL. If parsing the URL fails, throw a TypeError.
4. If input's sizes member is present:
   1. Set image's sizes to the result of parsing input.sizes as if it was a sizes attribute of a link element whose rel attribute contains the token icon. If parsing fails, throw a TypeError.
5. If input's type member is present and not the empty string:
   1. If type is not an image MIME Type, throw a TypeError.
   2. Set image's type to input.type.
6. If input's label member is present and not the empty string:
   1. Set image's label to input.label.
7. If input's label member is not present and an |=external label=| can be substituted:
   1. Set image's label to the value of |=external label=|.
8. Return image.

6. Processing an image resource from JSON

The steps to process an image resource from JSON are given by the following algorithm. The algorithm takes a JSON Object input and a URL base URL. It returns an image resource.

1. If input is missing "src" property, return failure.
2. Let image be a new image resource.
3. Set image's src to the result of URL parsing object's src property and base URL. If parsing the URL fails, return failure.
4. If input has a "sizes" property and its type is a string of length greater than zero:
   1. Set image's sizes to the result of parsing input.sizes as if it was a sizes attribute of a link element whose rel attribute contains the token icon. If parsing fails, return failure.
5. If input has a "type" property that is a string of length greater than zero:
   1. If input's "type" property value is not a valid MIME type string, return failure.
   2. Set image's type to the value of input's "type" property.
6. If input has a "label" property that is a string of length greater than zero:
   1. Set image's label to the value of input's "label" property.
7. If input's label member is not present and an |=external label=| can be substituted:
   1. Set image's label to the value of external label.
8. Return image.

7. Fetching an image resource

The steps for fetching an image resource are given by the following algorithm. The algorithm takes an image resource image, and an optional Request request. It returns a Response.

1. If request is undefined:
   1. Set request to a new Request.
   2. Set URL to image's src.
   3. Set Destination to "image".
   4. Set Client to the context object's relevant settings object.
2. If request's Client is null, throw a TypeError.
3. Perform a fetch using request and return the Response.

8. Examples of graphics formats supporting embedded accessible names

Certain graphics formats support the inclusion of an embedded accessible name as part of the image’s contents. Examples include:

• The title element in SVG.
• Metadata in raster images (e.g., tiff:ImageDescription, XMP:Description).

9. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and RECOMMENDED in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.