Image Resource

This document defines the concept of an "image resource" and a corresponding WebIDL {{ImageResource}} dictionary. Web APIs can use the {{ImageResource}} dictionary to represent an image resource in contexts where an `HTMLImageElement` is not suitable or available (e.g., in a Worker).

This specification is not stable. Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways.

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.

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.

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 [^link/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.

ImageResource dictionary 

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

src member

The {{ImageResource/src}} of an {{ImageResource}} is a [=URL=] from which a user agent can [=fetch=] image data.

sizes member

The {{ImageResource/sizes}} member is equivalent to a [^link^] element's [^link/sizes^] attribute, and is processed in the same manner.

When multiple {{ImageResource}} dictionaries are available, a user agent MAY use the {{ImageResource/sizes}} value to decide which image is most suitable for a display context (and ignore any that are inappropriate).

The {{ImageResource/sizes}} member allows for multiple space-separated size values in order to accommodate image formats (such as ICO) that can act as a container for multiple images of varying dimensions. 
            const image = {
              src: "path/to/image.ico",
              sizes: "16x16 32x32 64x64",
              type: "image/vnd.microsoft.icon",
            };
            some.api.doSomething(image);

type member

The {{ImageResource/type}} member represents an [=image MIME Type=] for the image resource. A user agent MAY ignore media types it does not support.

There is no default [=MIME type=] for an {{ImageResource}}. The {{ImageResource/type}} is purely advisory. User agents MUST use the [=rules for sniffing images specifically=] to determine the [=computed MIME type=] of an [=image resource=].

label member

The {{ImageResource/label}} of an {{ImageResource}} is a [=string=] that provides the accessible name for the associated image.

Implementors MUST [=derive the accessible name=] for every {{ImageResource}} they expose to users.

Authors are strongly encouraged to add a {{ImageResource/label}} unless the {{ImageResource}}’s [=accessible name=] can be inferred from an external label in its context. For example, in the context of a [=manifest=], the [=manifest/`name`=] (or [=manifest/`short_name`=]) provides an [=external label=] for all members of the [=manifest/`icons`=] array that don’t have a {{ImageResource/label}} defined.

If neither an explicit {{ImageResource/label}} nor an [=external label=] is provided, but the {{ImageResource/type}} supports providing an [=embedded accessible name=], implementors MAY choose to defer assigning the {{ImageResource/label}} until the {{ImageResource/src}} has been fetched and processed. If the {{ImageResource/src}} is found to provide an [=embedded accessible name=], implementors MUST update the {{ImageResource/label}} to match that value.

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:ImageResource|. It returns an [=image resource=].

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

Processing an image resource from JSON

To process an image resource from JSON, given a JSON Object |input:object| and a [=URL=] |base:URL|. 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:URL| be the result of [=URL parser|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:string| to the result of parsing |input|["sizes"] as if it was a [^link/sizes^] attribute of a [^link^] element whose [^link/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 [=parse a mime type|parsing=] |input|["type"].
    2. If |mime| is failure, return failure.
    3. Set |image|["type"] to the [=MIME type/essence=] of |mime|.
  9. Set |image|["label"] to the result of [=deriving the accessible name=].
  10. Return |image|.

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 [=request/URL=] to |image|'s [=image resource/src=].
    3. Set [=request/Destination=] to "image".
    4. Set [=request/Client=] to the context object's [=relevant settings object=].
  2. If |request|'s [=request/Client=] is null, throw a {{TypeError}}.
  3. Perform a [=fetch=] using |request| and return the [=Response=].

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

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: