Widgets 1.0: Updates

W3C Working Draft 07 October 2008

This version:
Latest version:
Latest Editor's draft:
Version history:
Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)
Marcos Caceres, Invited Expert


This specification defines a model to allow a widget user agent to locate and replace a widget resource with a new or different version of a widget resource. The updates model is designed to work both over HTTP and from local storage. For updates performed via the Web, the model makes use a simple XML documents that authors place on a Web server to indicate, amongst other things, where the next most suitable version of a widget resource can be retrieved from. It also defines a mechanism that allows authors to be notified of installation errors or success. This specification also describes how to renegotiate security policies when widgets are updated.

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

This is the First Public Working Draft of this document. 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.

This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. 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 is probably out of date! You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. The public is encouraged to send comments to the WebApps Working Group's public mailing list public-webapps@w3.org (archive). See W3C mailing list and archive usage guidelines. A detailed list of changes from the previous version is also available from the W3C's CVS server.

Implementers should be aware that this document is unstable. 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 aforementioned mailing lists 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.

Table of Contents

1. Conformance

Everything in this specification is normative except for diagrams, examples, notes and sections marked as informative.

The key words must, must not, should and may in this document are to be interpreted as described in [RFC2119].

This specification describes the conformance criteria for user agents (relevant to implementers) and various resource types (relevant to authors and authoring tool implementers).

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

Products that generate and/or allow authoring of update description documents must not claim conformance to this specification, though they can claim to produce update description documents that themselves are conforming to this specification. Authoring tools and markup generators must generate conforming update description documents.

Products that check the conformance of update configuration documents must not claim conformance to this specification, though they can claim to verify that an update description document conforms to this specification.

2. Introduction

TBW: Goals of this specification. A brief overview of the architecture, and some background and motivation for its creating. Related specifications (namely OMA-DL) and justification as to why this is needed.

An installed widget is a widget resource that has been correctly installed on a widget user agent, but may or may not be updatable.

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 the an update element.

A potential update is a resource acquired by downloading the resource addressed by the src attribute of the widgetupdate element.

The update process is a multi-step process where by a widget user agent compares the version of a currently installed widget resource 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 configuration document. Otherwise, if no version attribute has been declared for an installed widget, the version may have been computed by the widget user agent using the rules defined by the Widget Packaging specification.

If a widget user agent determines, via the rules defined in this specification, that two widget resources are not the same version, and if the user consents, the widget user agent must attempt replace the currently installed widget resource with the potential update. If a widget user agent determines, via the rules define in this specification, that installed widget does not need updating, then that installed widget is said to be up-to-date.

This document defines three strategies that authors can rely on for having a widget user agent check if a widget resource is up-to-date, as well as the rules that define how widget user agents are expected to behave when performing each update strategy. The strategies are as follows:

  1. Referencing an update description document on the Web.
  2. Updating via the widget.update() method defined in the Widgets-API specification (works in conjunction to update strategy 1).
  3. Updating from local storage.

Update strategies 1 and 2 are performed by acquiring and processing an update description document (UDD) from some IRI. 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 IRI from where the widget user agent can retrieve the potential update (the update source). It is expected that widget user agents will perform updates asynchronously by periodically checking for changes in either the HTTP response codes for the UDD (e.g. a changed HTTP 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).

In the case of update strategy 2, an author can request that a widget asynchronously check if a widget has been updated via the widget.update() method, defined in the Widgets-API specification. This strategy also relies on the author having declared a update element in the widget configuration document, as it makes us of the URI to potentially retrieve an UDD and relay whether an update is available back to the instantiated Widget. Actually performing the update is left to the discretion of the widget user agent.

In the case of update strategy 3, updating from local storage, this specification works in conjunction with the Widget Packaging specification to define the rules for how to verify and install a potential update.

Extended examples of the three update strategies are provided in the usage scenarios section of this specification.

In the use of any of the update strategies, a number of security conditions need to be checked that are described in this document.

3. Value types

The space characters, valid URI, valid version-tag are defined in the Widget Packaging specification.

4. Update Description Document (UDD)

An update description document (UDD) is an XML document that has a widgetupdate element at its root that is in the widget namespace.

The purpose of the UDD is to describe details about a potential update.

4.1 Example Update Description Document

This section is informative.

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

<widgetupdate xmlns="http://www.w3.org/ns/widgets"


bytes="1024" notify="https://example.com/myWidget/updateManager.php">
<details href="http://a.com/myWidget/1.1/whatsnew"> We fixed some bugs and improved performance! </details>

For the widgetupdate element:

The optional details element represents details of changes in the potential update. Its href attribute represents a hyperlink to a (HTML) resource where further details can be read.

4.2 MIME Type

Update description documents MUST be served with the application/xml MIME type.

4.3 The widgetupdate element

The widgetupdate 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.

Expected context:
The root element of an UDD document.
Expected children:
details: zero or one.


Required. A valid version tag that denotes the version number of the potential update.
Required. A valid URI that references a potential update. Over the wire, the potential update must be labeled with a correct widget MIME type (i.e. application/widget).
Optional. The id of the potential update. When used, it must match the id of the installed update. NOTE: need to specify how to migrate to new widget IDs across updates.
Optional. The bytes attribute specifies a valid non-negative integer that represents the number of bytes of the resource identified by the src attribute.
ISSUE: should widget user agents verify this with a HEAD request to the potential update?
Optional. A URI Attribute that is contacted after installation has completed.

4.4 The details element

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

Expected context
Expected children

4.4.1 Attributes

A valid URI that points to additional information about the potential update.

5. UDD Acquisition

TBW: This section will describe how to formulate HTTP requests and deal with authentication and content negotiation. Widget user agents will be expected to handle HTTP response codes and redirects. User agents will also be expected to cache certain information, etc. This section will also discuss confirmation of installation via POST to the notify URI.

6. UDD Processing

TBW: This section will describe how to process a UDD.

6.1 Default values

Widget user agents 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  
update-id DOMString null  
update-size DOMString null  
notifyURI URI null  
details DOMNode null  

Need to define the term invalid UDD...

6.2 Processing model

The term in error, typically used of an element or attribute, means that the element, attribute, or other construct is not conformant according to the rules of this specification. Rules for exactly how the construct must be treated when it is in error 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. For cases where attributes on elements do not conform to this specification, the attributes must be considered to be in error and the UA must ignore them, meaning that the presence of these non-conforming attributes in no way affects the processing.

  1. Let doc be the result of parsing the acquired UDD as a [DOM3Core] Document using a [XMLNS]-aware parser. If the document is not well-formed [XML], then threat this as an invalid UDD.
  2. Let root element be the documentElement of doc.
  3. If the root element is not a widgetupdate element in the widget namespace, then treat this UDD as an invalid.
  4. If the root element is a widgetupdate 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. If the id attribute was used and it is a valid URI, then let update-id be the value of id.
    6. If the bytes attribute was used and it is a valid non-negative integer, then let update-size be the value bytes.
    7. If the notify attribute was used and it is a valid URI, then let notify-uri be the value of notify.
  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. However, need to align this with the i18n model so that <bdo> is allowed (or whatever solution we end up using).
  2. If the child element is a Comment node, or a ProcessingInstruction node, or a Text node that only contains space characters, or a CDATASection node that only contains space characters, or anything else, this is in error and must be ignored.

7. Potential update verification and installation process


7.1 Handling Security Policies

This section will describe how to adjust security policies when an update widget requests additional functionality.

8. Post install


8.1 Notify Response Codes

This section will extend the OMA-DL response codes with anything that is specific to widgets.

9. Security concerns

It is conceivable that the automatic update model could be subject to a man-in-the-middle-attack, as with any unencrypted requests performed over HTTP. For this reason, it is recommended that automatic update are always performed over HTTPS.

10. Usage Scenarios

This section is informative

The following sections describe each of the three automatic update strategies in detail. The sections are divided up in terms of author guidelines that describe how authors are expected to use the specification.

Editor's note: this section and the subsections are incomplete. The following text is just a guide as to what we plan to put in here.

10.1 Using an Update Description Document

This section is informative.

Using an update description document is recommended for any of the following use cases:

In the configuration document, the author provides an <update> element that points to some URI:

<widgets xmlns="..."

The widget engine sends a request:

GET /myWidget/1.0/update.xml
Host: a.com
User-Agent: SuperWidgetEngine
Accept: text/xml
If-modified-since: 23 March, 2008
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7

Server responds with an update description document:

HTTP/1.1 200 OK
Date: Tue, 27 May 2008 06:02:05 GMT
Content-Type: text/xml
Content-Length: 370

<?xml version="1.0" encoding="utf-8"?>
<update xmlns="http://www.w3.org/ns/widgets" src="https://a.com/myWidget/v1.1b/awesome.wgt" notify="https://a.com/myWidget/updateManager.php" version="1.1 beta (awesome edition)"
<details href="http://a.com/myWidget/1.1/whatsnew"> We fixed some bugs and added some new APIs! </details>

So, the widget engine then checks that <update id> matches <widget id> and that <widget version> and <update version> are different. If so, then the user is informed that a new update is available. If the user agrees to download the new widget, then the widget user agent attempts to retrieve the resource indicated by the <update src> attribute. If the widget engine is able to retrieve and verify the potential update, then the widget resource is processed as normal, checking that the <widget id="id"> for the widget stays the same. If all goes the plan, the old widget is either backed up or erased and the new widget takes its place. Any previously set preferences are kept.

10.2 Updating from Local Storage

This section is informative.

This method of updating is suitable for widgets that were downloaded from a web browser to disk or were acquired via some alternative means, such as BlueTooth.

Upon instantiating the widget, the widget user agent compares the id and version of the new widget to the currently existing widget and replacing.

10.3 Updating via widget.update()

This section is informative.

Authors can use scripts to allow a widget to be updated by calling the widget.update() method [Widgets API].

  //custom code to check for update online using XHR


setInterval("checkForUpdate();", 86400000); //check for update once a day