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 from 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. 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 sizes attribute.

type

An image MIME type.

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

3. ImageResource dictionary

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

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

4. 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. Return image.

5. 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. Return image.

6. 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 Mode to "no-cors".
2. Perform a fetch using request and return the Response.

7. 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 and MUST 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.