Image Resource

W3C First Public Working Draft

This version:
https://www.w3.org/TR/2020/WD-image-resource-20200507/
Latest published version:
https://www.w3.org/TR/image-resource/
Latest editor's draft:
https://w3c.github.io/image-resource/
Editors:
Aaron Gustafson (Microsoft Corporation)
Rayan Kanso (Google Inc.)
Marcos Càceres (Mozilla Corporation)
Participate:
GitHub w3c/image-resource
File a bug
Commit history
Pull requests

Abstract

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

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

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.

This document was published by the Web Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

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;
};

3.1 src member

The src of an ImageResource is a URL from which a user agent can fetch image data.

3.2 sizes member

The sizes member is equivalent to a link element's sizes attribute, and is processed in the same manner.

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

Note
The 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);

3.3 type member

The 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 type is purely advisory. User agents MUST use the rules for sniffing images specifically to determine the computed MIME type of an image resource.

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.

A. References

A.1 Normative references

[fetch]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[mimesniff]
MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[url]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[webidl]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/