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, an image resource is represented as an ImageResource dictionary.

In [JSON], image resource is represented as an object.

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. Set image's label to the result of deriving the accessible name.
7. Return image.

6. Processing an image resource from JSON

To process an image resource from JSON, given a JSON Object input and a URL base. It returns an ordered map.

1. If input is not of type object, return failure.
2. If input["src"] is not of type string, return failure.
3. Let src be the result of parsing input["src"] with base as the base URL.
4. If src is failure, return failure.
5. Let image be an new ordered map.
6. Set image["src"] to src.
7. If type of input["sizes"] is a string, and its length is greater than zero:
   1. Set 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.
   2. If sizes is failure, return failure.
   3. Set image["sizes"] to sizes.
8. If input["type"] is a string, and it has a length greater than zero:
   1. Let mime be the result of parsing input["type"].
   2. If mime is failure, return failure.
   3. Set image["type"] to the essence of mime.
9. Set image["label"] to the result of deriving the accessible name.
10. 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. Deriving the accessible name

The steps to derive the accessible name for an image resource resource are as follows. It returns a string.

1. If resource["label"] is a string, return input["label"].
2. Otherwise, if image provides an embedded accessible name, return the embedded accessible name.
3. Otherwise, if an external label can be substituted, return the relevant external label.
4. Return "".

9. 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).

10. 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.