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
A [=string=] representing the sizes of the image, expressed using the same syntax as [^link^]'s [^link/sizes^] attribute.
type
An [=image MIME type=].

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

ImageResource dictionary

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

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=].

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 [=link type "icon"|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. Return |image|.

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:Object| 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 [=image resource/src=] to the result of [=URL parser|URL parsing=] |object|'s [=image resource/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 [=image resource/sizes=] to the result of [=link type "icon"|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, 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 [=image resource/type=] to the value of |input|'s "type" property.
  6. 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=].