This specification defines the widget URI scheme that is used to address resources inside a widget package [[!WIDGETS]].

Introduction

Resources inside a widget package are identified and located using a method that is specific to widgets technology. Widget URIs reflect this by providing these specific locators with their own syntax so that resources in widget packages can be readily identified.

In general, authors of widget content use relative URI references. Widget URIs are therefore primarily synthesised by the user agent as it absolutises URI references found in documents contained in widgets packages.

There are three classes of products that can claim conformance to this specification:

Definitions

Throughout this specification, wherever the term URI [[!URI]] is used, it can be replaced interchangeably with the term IRI [[!RFC3987]]. All widget URIs are IRIs, but the term URI is more common and was therefore preferred for readability.

Widget URIs

Widget URIs are URIs as per [[!URI]] and [[!RFC3987]], with specific aspects described in the following sections.

Syntax

A valid widget URI MUST adhere to the IRI grammar rule from [[!RFC3987]], and its scheme component MUST be the case-insensitive string "widget".

A valid widget URI reference MUST adhere to the IRI-reference grammar rule from [[!RFC3987]], and if it is an absolute URI reference then it MUST be a valid widget URI.

A producer MUST generate URIs that are normalised according to chapter 5.3.2. "Syntax-Based Normalization" of [[!RFC3987]].

A consumer MUST be able to parse any valid widget URI.

Example widget URIs could thus be: widget://beefdead/dahuts/sightings/alpes-françaises.svg (assuming the generated opaque authority is beefdead) or widget:///secret-identities/marcoscàceres/batman.foaf if there is no authority component.

Authority

A producer MAY include an authority component in URIs. If present, the authority component is said to be opaque, meaning that the authority component has a syntax as defined by [[!RFC3987]] but that the authority component is devoid of semantics.

A consumer SHOULD ignore the authority component, when present.

Base URI and Relative URI Reference Resolution

When computing the base URI for a resource contained in a widget package a producer MUST concatenate widget://, optionally the opaque authority, the U+002F SOLIDUS (/) character, and the Zip relative path to the resource.

When resolving a relative URI references against a base URI, a consumer MUST use the mechanism defined in chapter 5.2. of [[URI]].

Note that using widget URIs directly when authoring content is discouraged, and authors should stick to using schemeless relative URI references.

Mapping widget URIs to files within a widget package

To resolve a widget URI to a resource within a given widget package a consumer MUST apply the following algorithm (or one that guarantees the same result):

  1. Let uri be the URI reference to resolve. If uri is a relative URI reference, make it absolute as defined in chapter 5.2. of [[!URI]].
  2. Run the algorithm defined in Rule for finding a file within a widget package using the path component as its parameter (excluding any query or fragment components). Return the result, file or error, that was returned.

Usage as Origin

In some contexts one needs to map a URI into an origin, for instance in the [[HTML5]] HTML5 origin algorithm.

Mapping from a widget URI to an origin takes place as follows:

  1. Let url be the valid widget URI for which the origin is being determined.
  2. Parse url with a consumer.
  3. Let scheme be widget.
  4. If url contains an opaque authority, let host be its value. Otherwise, generate a unique value that will always be the same for a given widget package and that no two widget packages will share and assign it to host.
  5. Let port be null.
  6. Return the tuple (scheme, host, port).

Acknowledgments

The following people were instrumental in producing this specification:

Art Barstow, Marcos Caceres, Thomas Roessler, Larry Masinter, Marcin Hanclik, Mark Baker, and Jere Kapyaho.