Widget Updates

W3C Working Draft 13 April 2010

This version:
Latest published version:
Latest editor's draft:
Previous version:
Marcos Cáceres, Opera Software
Robin Berjon, Vodafone


This specification defines a process and a document format to allow a user agent to update an installed widget package with different version of a widget package. A widget cannot update itself; instead, a widget relies on the user agent to manage the update process. A user agent can perform an update over HTTP and from non-HTTP sources (e.g., directly from a device's memory card or hard disk).

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 http://www.w3.org/TR/.

Implementers should be aware that this document is not stable and should not be implemented. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the group's public mailing list and take part in the discussions.

User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-webapps so their extensions can be considered for standardization.

This specification is part of the Widgets Family of Specifications.

This Specification takes into account the recommendations from the Widget Updates Patent Advisory Group and considering the large set of prior art the PAG found.

This document was published by the Web Applications WG as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a 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 5 February 2004 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.

Table of Contents

1. Introduction

This section is non-normative.

There are a multitude of reasons why authors might want to update a widget including addressing security vulnerabilities, making performance enhancements, and adding new features. Sometimes authors may even want to revert back to a previous version of a widget, if it is found that a newly deployed version of a widget contains issues or vulnerabilities.

To be written: overview of update model and a cute diagram.

To facilitate the process of updating widgets, this specification introduces an XML element, called update-description, to be included into a widget's configuration document, and an XML format, called an Update Description Document (UUD). This specification also defines the rules the govern the interactions between the user agent, the UDD, and the updated widget.

On the one hand, the update-description element provides an author with a means to point to a UUD. On the other hand, the UUD provides metadata about an update including:

If a user agent determines, via the strategies defined in this specification, that two widget packages are not the same version, and if the user consents, the user agent will attempt to replace the currently installed widget package with a potential update. Updates are designed to retain any locally stored data, so to protect end-users from losing data that a widget may have stored at runtime.

Design Goals and Requirements

This section is non-normative.

This document addresses the Remote and Local Updates the requirement of the 30 April 2009 Working Draft of the Widgets 1.0: Requirements Document (see [WIDGETS-REQS]).

2. 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 must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance requirements for a single class of product: user agents.

3. Definitions

The concepts of a widget package and a configuration document are defined in the [WIDGETS] specification.

A user agent is an implementation of this specification that also implements the [WIDGETS] specification and its dependencies.

An installed widget is a widget package that has been correctly installed on a user agent. Not every installed widget classifies as an updatable widget (see rule for determining if a widget can be updated).

An updatable widget is an installed widget that meets all the preconditions defined in this specification that would allow it to be updated.

An update source is the URI referenced by the src attribute of a update-info element of an update description document.

A potential update is a resource acquired by downloading the update source (i.e., the resource addressed by the src attribute of a update-info element).

The update process is a multi-step process whereby a user agent compares the version of a currently installed widget package to the version of a resource available either on the Web or on local storage.

The version of an installed widget is determined by the version attribute of the widget element declared by an author in a widget package's configuration document.

An installed widget is said to be up-to-date if a user agent determines, via the update-checking strategies, that an installed widget does not need updating.

Precondition for Updating a Widget Package

In order to verify that an installed widget meets the preconditions which deem it an updatable widget, a user agent must apply the rule for determining if a widget can be updated.

Rule for Determining if a Widget can be Updated

The rule for determining if an installed widget can be updated is given by the following algorithm. This rule makes use of values derived in the configuration defaults table (CDT)established in the [WIDGETS] specification.

  1. Let widget be an installed widget.

  2. In the CDT, if the widget identifier is not null and update href is not null, return true. Otherwise, return false.

Update-Checking Strategies

This document defines two update-checking strategies that a user agent can use to check if a widget package is up-to-date, as well as the rules that define how user agents are expected to behave when performing each . The strategies are as follows:

  1. Referencing an update description document on the Web.
  2. Updating from local media.

Update-checking strategy 1 is performed by acquiring and processing an update description document (UDD) from a URI. An UDD is an XML document in which an author declares, amongst other things, what's new or different in the potential update, the version that the widget will be updated to, and the URI from where the user agent can retrieve the potential update (the update source). It is expected that user agents will perform updates asynchronously by periodically checking for changes in either the HTTP response codes for the UDD (e.g. a changed [HTTP11] Etag header or using If-Modified-Since) and by processing the UDD itself. The timing of periodic checks is an implementation detail left to the discretion of the implementer (e.g. once a day or once a week).

A push mechanism could be applied as well that pushes a UDD to the user agent as soon as an update is available.

In the case of update-checking strategy 2, updating from local media, this specification works in conjunction with the Widget Packaging and Configuration specification [WIDGETS] to define the rules for how to verify and install a potential update.

3.1 Value types

The space characters, valid URI, and valid version-tag are defined in the Widget Packaging and Configuration specification [WIDGETS].

4. The update-description Element

The update-description element points, via the href attribute, to an update description document.

The update-description element is in the http://www.w3.org/ns/widgets namespace as defined in [WIDGETS].

Context in which this element may be used:
As a child of the widget element defined in the [WIDGETS] specification.
Content model:
Zero or one.
Expected children:
Localizable via xml:lang:

4.1 Attributes

A URI attribute that points to the location of an update description document.

4.2 Usage example

This example shows the expected usage of the update-description element.

<widget xmlns = "http://www.w3.org/ns/widgets" 
        id    = "http://example.com/my-widget" version="1.0">

  <update-description href="http//example.com/update?widget=my-widget&amp;version=1.0"/>


5. Processing update-description elements in the Configuration Document

A user agent must add the following to the Table of Configuration Defaults [WIDGETS] as part of Step 7.

Table of Configuration Defaults (addendum)
Variable Type Default Value Overridden in Description
update href URI null Processing update-description elements in the Configuration Document The URI for where an update description can be downloaded, corresponding to the update-description element's href attribute.

If this is not the first update-description element, then the user agent must ignore this element and its descendants.

If this is the first update-description element and the href attribute is used, and it is a valid uri, then let update href be the value of the href attribute.

6. Update Description Document (UDD)

An update description document (UDD) is an [XML10] document that has a update-info element at its root.

The purpose of the UDD is to provide the details about a potential update, including a pointer to HTTP resource that will act as the potential update.

6.1 Namespace

This section is non-normative.

All elements defined to be used in a UDD are in the the http://www.w3.org/ns/widgets namespace as defined in [WIDGETS].

Example Update Description Document

Below is an example of a typical UDD. In order for a user agent to retrieve and process a UDD, an author must initially declare a valid URI for the update-description element in the installed widget's configuration document (e.g. <update-description src="https://example.com/myWidget/updates"/>).

<update-info xmlns="http://www.w3.org/ns/widgets"
  This update tries to make 2010 a little bit less like "1984".

6.2 Media Type

Update Description Documents are identified by the application/xml media type.

6.3 The update-info Element

The update-info element is intended to provide metadata about the potential update. In addition, it serves as a container for the other elements; as such, it must be used.

Context in which this element may be used:
The root element of an UDD document.
Content model:
Zero or more details elements.
Expected children:
Localizable via xml:lang:

6.3.1 Attributes

A valid version tag that denotes the version number of the potential update.
A valid URI that references a potential update. Over the wire, the potential update must be labeled with a correct widget media type (i.e. application/widget).

6.4 The details Element

The details element represents a human-readable description of what differentiates this potential update from other versions.

Context in which this element can be used:
Inside a update-info element.
Content model:
Zero or more.
Expected children:
Localizable via xml:lang:

7. UDD Acquisition

A user agent must support the capability to acquire a UDD over [HTTP] and over [HTTPS].

Response Codes

8. UDD Processing

@@ TBW @@

A user agent must assume the following defaults prior to processing a UDD:

Update Defaults
Variable Type Default value Description
update-source URI null  
version-tag DOMString null  
details DOMString null  

8.1 Processing model

The term in error, typically used of an element or attribute, means that the element, attribute, or other construct does not conform to the rules of this specification. Rules for exactly how a user agent needs to treat the erroneous construct are always given when the term is used. Typically this will involve ignoring the erroneous nodes, meaning the UA must, for the purposes of processing, act as if those nodes were absent from the UDD.

The following processing model is written with more concern for clarity over efficiency. As such, a user agent can optimize the processing model so long as the end result is indistinguishable from the result that would be obtained by the following the specification.

TBW: need to integrate i18n model.

  1. Let doc be the result of parsing the acquired UDD as a [DOM-LEVEL-3-CORE] Document using a [XML-NAMES]-aware parser. If the document is not well-formed [XML10], then threat this as an invalid UDD.

  2. Let root element be the documentElement of doc.

  3. If the root element is not a update-info element in the widget namespace, then treat this UDD as an invalid.
  4. If the root element is a update-info element:
    1. If the version attribute was used, and it is a valid version-tag, then let version-tag be the value of version.
    2. If no version attribute was used, or the value was in error, treat this as an invalid UDD.
    3. If the src attribute was used, and it is a valid URI, then let update-source be the value of src.
    4. If no src attribute was used, or the value was in error, treat this as an invalid UDD.
  5. For any child element of the root element:
    1. If the child element is a details element:
      1. If this is not the first details element, then the element is in error and must be ignored.
      2. TBW: Need to extract the text content ignoring any invalid nodes not defined in this document.
    2. Otherwise it must be ignored.

8.2 Dealing with invalid Update Description Documents


8.3 Potential update verification and installation process

@@ TBW @@

9. Security concerns

It is conceivable that an UDD could be subject to a man-in-the-middle-attack, as with any unencrypted requests performed over [HTTP11]. For this reason, it is recommended that, for widgets that have not been digitally signed, updates are always performed over [HTTP-TLS].

Another means of protection is for authors to always digitally sign their widget resources. During an update, the user agent will then validate the signature before installation, ensuring that a widget resource's identity and integrity was maintained over the network.

TBW: downgrade attacks.

A. Acknowledgements

The editors would like to think the following contributors (in no particular order): Raine Hillebrand.

B. References

B.1 Normative references

Gavin Nicol; et al. Document Object Model (DOM) Level 3 Core Specification. 7 April 2004. W3C Recommendation. URL: http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
Marcos Caceres. Widget Packaging and Configuration. 01 December 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-20091201/
Richard Tobin; et al. Namespaces in XML 1.0 (Second Edition). 16 August 2006. W3C Recommendation. URL: http://www.w3.org/TR/2006/REC-xml-names-20060816/
C. M. Sperberg-McQueen; et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 10 February 1998. W3C Proposed Edited Recommendation. Revised 5 February 2008 URL: http://www.w3.org/TR/2008/PER-xml-20080205/

B.2 Informative references

E. Rescorla. HTTP Over TLS. May 2000. Internet RFC 2818. URL: http://www.ietf.org/rfc/rfc2818.txt
R. Fielding; et al. Hypertext Transfer Protocol - HTTP/1.1. June 1999. Internet RFC 2616. URL: http://www.ietf.org/rfc/rfc2616.txt
Marcos Caceres. Widgets 1.0: Requirements. 30 April 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-widgets-reqs-20090430