Widgets 1.0: Packaging and Configuration

Abstract

This document standardizes a Zip-based packaging format, an XML-based configuration document format and a series of steps that user agents follow when processing and verifying various aspects of widgets.The packaging format acts as a container for files used by a widget. The configuration document is an XML vocabulary that authors can use to declare metadata and configuration parameters for a widget. The steps for processing a widget resource describe the expected behavior and means of error handling for widget user agents while processing the packaging format, configuration document, and other relevant files. This document also defines conformance criteria and expected behavior for conformance checkers, which are tools that aid authors in verifying that Zip archives and configuration documents conform to this specification.

This document is part of the Widgets 1.0 Family of Specifications, which together standardize widgets.

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 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 is the 22 December 2008 Last Call Working Draft version of the "Widgets 1.0: Packaging and Configuration" specification. The Last Call period ends on 31 January 2009. This version reflects over of two years work addressing requirements 1 to 23 of the Widgets 1.0: Requirements document [Widgets-Reqs]. The requirements were addressed and specified through extensive research, and via consultation with W3C members and the public via the Working Group's mailing lists (WAF archive, WebApps archive). The purpose of this Last Call is to give external interested parties a final opportunity to publicly comment on how widgets should be packaged and configured before the Working Group makes a call for implementations. The Working Group's goal is to make sure that vendor's requirements for packaging and configuration have been effectively addressed and clearly specified.

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.

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 Web Apps 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 not stable. 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. 1 Introduction
   1. 1.1 Note to Last Call Reviewers
   2. 1.2 Design Goals and Requirements
   3. 1.3 How this Document is Organized
   4. 1.4 The Widget Family of Specifications
   5. 1.5 Global Definitions
2. 2 Conformance
3. 3 Widget User Agents
   1. 3.1 Dependencies on Other Specifications and File Formats
   2. 3.2 Internationalized Tag Set Support
   3. 3.3 Zip Support
4. 4 Conformance Checker
5. 5 Zip Archive
   1. 5.1 Compression Methods
   2. 5.2 Version of Zip Implementation Needed to Extract a File Entry
   3. 5.3 Zip Relative Paths
   4. 5.4 Reserved Characters
6. 6 Widget Resources
   1. 6.1 Invalid Widgets
   2. 6.2 Files and Content Types
   3. 6.3 Reserved File and Folder Names
   4. 6.4 Digital Signatures
   5. 6.5 Content Localization
   6. 6.6 Start file and Default Start Files
   7. 6.7 Custom Icons and Default Icons
   8. 6.8 Thumbnail
   9. 6.9 MIME Type
   10. 6.10 File Extension
7. 7 Configuration Document
   1. 7.1 Namespace
   2. 7.2 Proprietary Extensions
   3. 7.3 Attribute Types
   4. 7.4 The widget Element
   5. 7.5 The name Element
   6. 7.6 The description Element
   7. 7.7 The author Element
   8. 7.8 The license Element
   9. 7.9 The icon Element
   10. 7.10 The access Element
   11. 7.11 The content Element
   12. 7.12 The update Element
   13. 7.13 The feature Element
   14. 7.14 Window Modes
   15. 7.15 Indicating Text Directionality with <its:span>
8. 8 Steps for Processing a Widget Resource
   1. 8.1 Dealing with Invalid Widgets
   2. 8.2 Extracting the File Data from a File Entry
   3. Step 1 - Acquire a Potential Zip Archive
   4. Step 2 - Verify the Zip archive and its File Entries
   5. Step 3 - Set the Configuration Defaults
   6. Step 4 - Locate Digital Signatures for the Widget
   7. Step 5 - Process the Digital Signatures
   8. Step 6 - Determine the Base folder and Widget Locale
   9. Step 7 - Locate the Configuration Document
   10. Step 8 - Process the configuration document
   11. Step 9 - Locate the Start File
   12. Step 10 - Locate the default icons and thumbnail
9. Appendix
   1. Embedding a Widget Resource into an HTML Document
   2. RelaxNG Schema for the Configuration Document
10. Acknowledgements
11. Normative References
12. Informative References

1 Introduction

Widgets are full-fledged client-side applications that are authored using Web standards. They are typically downloaded and installed on a client machine or device where they typically run as stand-alone applications outside of a Web browser. Examples range from simple clocks, stock tickers, news casters, games and weather forecasters, to complex applications that pull data from multiple sources to be "mashed-up" and presented to a user in some interesting and useful way (see [Widgets-Landscape] for more information). The runtime environment in which a widget runs is referred to as a widget user agent.

1.1 Note to Last Call Reviewers

This section is non-normative.

The editor of this specification responds rapidly to all feedback and continuously makes corrections to this document. So, unless you are reading this document on the date of publication, it is extremely likely that this document has been superseded. Instead of reviewing this published draft, please review the latest editor's draft and make sure you cite the date of that draft in the feedback you send to the Web Apps Working Group's public mailing list public-Webapps@w3.org.

Please also be sure to check the mailing list archive to see if any issue you uncover has already been addressed. To help with cataloguing issues, prefix emails to the mailing list with the string [widgets]. Any and all feedback is welcomed.

1.2 Design Goals and Requirements

This section is non-normative.

The design goals and requirements for this specification are addressed in the Widgets 1.0 Requirements [Widgets-Reqs] document. This document addresses the following requirements:

• R1. Packaging Format, see packaging format.
• R2. MIME Type, see the widget MIME Type.
• R3. File Extension, see the widget file extension.
• R4. Internal Abstract Structure, see Zip archive and the widget resource.
• R5. Reserved Resources Names, see reserved file names.
• R6. Addressing Scheme, see valid path.
• R7. Multilingual Resource Names, see Zip relative path, particularly in respect to [UTF-8] support.
• R8. Localization Guidelines, see content localization.
• R9. Automatic Localization, see content localization.
• R10. Device Independent Delivery
• R11. Data Compression, see the valid compression methods.
• R12. Derive the MIME types of Resources, see rules for identifying the MIME type of a file.
• R13. Format and Schema, see the configuration document, configuration defaults, and the RelaxNG Schema for the configuration document.
• R14. Widget Metadata, see configuration document's name, description, and license element.
• R16. Authorship Metadata, see configuration document's author element.
• R16. Copyright Notice and License Metadata, see configuration document's license element.
• R17. Visual Rendering Dimensions, see widget element's width and height attributes.
• R18. Declarative Bootstrap, see content element.
• R19. Automated Bootstrap, see default start files.
• R20. Iconic Representations, see icon element and the default icons.
• R21. Configuration Parameters, see access element.
• R22. Feature Access Declarations, see feature element.
• R23. Configuration Document Independence, see configuration document.

1.3 How this Document is Organized

This section is non-normative.

The reader should be aware that this document is organized into two halves, but not explicitly marked as such. The first half defines the various aspects of what constitutes the packaging format, the configuration document, and reserved files, such as default icons and localized folders, as well as some of the expected behavior of conformance checkers, which are implementations that check the conformance of a Zip archive or a configuration document to this specification. Where possible, the first half avoids describing too many aspects related to processing, which are described in more detail in the second half of the document.

The second half, which starts in the section titled "Steps for Processing a Widget Resource", defines the steps required to process a widget as well as the expected behavior of a widget user agent as it processes the packaging format, the configuration document, and attempts to perform internationalization. The second half of this document also deals with error handling in the event that a widget user agent encounters unsupported or missing files, or erroneous [DOM3Core] nodes in the configuration document. Wherever processing is relevant, sections in the first half of the document link to sections in the second half of the document.

This specification should be read like all other specifications. First, it should be read cover-to-cover; multiple times. Then, it should be read backwards at least once. Then it should be read by picking random sections from the contents list and following all the cross-references.

1.4 The Widget Family of Specifications

This section is non-normative.

This specification is part of the Widgets 1.0 family of specifications, which together standardize widgets as a whole. The Widgets 1.0: APIs and Events [Widgets-APIs] specification defines APIs to store preferences and capture events. The Widgets 1.0: Digital Signature [Widgets-DigSig] specification defines a means for widgets to be digitally signed using a custom profile of the XML-Signature Syntax and Processing Specification. The Widgets 1.0: Security Model [Widgets-Security] specification defines a security model that defines what a widget can or cannot do at runtime. The Widgets: 1.0: Automatic Updates [Widgets-Updates] specification defines a version control model that allows widgets to be kept up-to-date over [HTTP].

1.5 Global Definitions

The following definitions are used globally throughout this specification. Please note that other terms are given throughout this document and defined where they are used.

An author is a person who creates a widget resource or an authoring tool that generates widget resources.

The [Widgets-Landscape] defines a widget as an end-user's conceptualization of an interactive single purpose application for displaying and/or updating local data or data on the Web, packaged in a way to allow a single download and installation on a user's machine, mobile phone, or Internet-enabled mobile device. Because widgets are packaged, they can be liberally shared by users without relying on [HTTP] (i.e., users can share widgets over Bluetooth or through other distribution channels).

Reserved means that a character, or text string, or a file that is identified by a particular file-name, has a specified purpose and meaning in this specification or in some other specification or system. The reason why something is reserved and how it must or must not be used is given when the term is used.

A character, or text string, or a file is arbitrary if it is not reserved.

The space characters, for the purposes of this specification, are [Unicode] code points:

• U+0020 SPACE,
• U+0009 CHARACTER TABULATION (tab),
• U+000A LINE FEED (LF),
• U+000B LINE TABULATION,
• U+000C FORM FEED (FF),
• U+000D CARRIAGE RETURN (CR).

The control characters, for the purpose of this specification, are [Unicode] code points in the range U+0000 NUL to U+001F INFORMATION SEPARATOR 1, and character U+007F DELETE.

2 Conformance

As well as sections marked as non-normative, all 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 describes the conformance criteria for user agents (relevant to implementers) and various resource types (relevant to authors and authoring tool implementers).

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

1. A widget user agent.
2. A widget resource.
3. A configuration document.
4. A conformance checker.

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

Products that check the conformance of widget resources or configuration documents can claim conformance to this specification. They can also claim to verify that a widget resource or a configuration document is conforming to the relevant section(s) of this specification.

3 Widget User Agents

A widget user agent is a user agent that attempts to implement this specification, as well as the [Widgets-APIs], [Widgets-Security], [Widgets-DigSig], and [Widgets-Updates] specifications.

A widget user agent must behave as described by this specification in order to claim conformance, even when faced with a non-conforming widget resource or a non-conforming configuration document.

Note: Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the [Widgets-Test-Suite]. Note, however, that passing all the tests in the test suite does not imply conformance to this specification; It only implies that the implementation conforms to aspects tested by the test suite.

3.1 Dependencies on Other Specifications and File Formats

This specification relies on several other specifications, some of which are file formats.

A specification is said to be supported by a widget user agent if the widget user agent attempts to implement that specification. In addition, a widget user agent is said to support a particular file format if it is able to process or render that file format.

In addition to this specification, a widget user agent must support the following specifications and file formats:

• [ZIP], but with the exclusions listed in the Zip support section.
• [PNG], [GIF87], and [JPEG] and [GIF89] image files formats.
• [XML] and [XMLNS].
• [DOM3CORE].
• [HTML4].
• [XMLHttpRequest].
• [ECMAScript].
• [UTF-8].
• [Deflate].

A widget user agent may also support the following file formats as icons:

• [ICO].
• [SVGTiny].

3.2 Internationalized Tag Set Support

To facilitate content localization in configuration documents, a widget user agent should support the Internationalized Tag Set's ([ITS]) its:span element and the its:dir attribute. Support of other ITS elements and attributes is not required.

Although this specification specifies the elements of the configuration document in which <its:span> and the its:dir attribute can be used (below), it does not define how they are to be interpreted and processed by a widget user agent. If a widget user agent implements <its:span> and its:dir, then the widget user agent must do so in conformance to the processing rules defined by the ITS specification.

3.3 Zip Support

A widget user agent is not required to implement or support any of the following aspects of the [ZIP] specification:

• Any decompression algorithm, other than [Deflate] and Stored (no compression) [ZIP].
• File spanning or multiple volumes.
• Zip64 extensions.
• Any digital signature method, other than the method defined in [Widgets-DigSig].
• Any decryption methods.
• Any patented aspects.

4 Conformance Checker

A conformance checker (CC) is a user agent that verifies that a widget resource or a configuration document conforms to this specification.This specification defines the expected behavior of conformance checkers in sections marked as conformance checker behavior throughout this document.

This specification asks CCs to inform authors of conformance violations, which means they should display messages to authors in a human readable manner that would assist them in correcting problems. Wording of messages is left to the discretion of implementers.

A widget user agent may behave as a conformance checker.

5 Zip Archive

The files of a widget are packaged using the [ZIP] file format (in other words, Zip is the packaging format for widgets).

A file entry is the amalgamation of data held by a local file header, file data, and (optional) data descriptor [ZIP] for each physical file stored in a Zip archive.

A potential Zip archive is a data object that has not been verified to be a valid Zip archive.

A valid Zip archive is a data object that conforms to the production of a .Zip file as defined by the Zip File Format Specification [ZIP], with the exclusion or support for the features and conditions defined in the Zip Support section. Step 2 of the Steps for Processing a Widget Resource describes how widget user agents verify that a Zip archive conforms to this specification.

The magic numbers for a Zip archive is the byte sequence: 50 4B 03 04.

To conform to this specification, a Zip archive must contain one or more file entries and must not be an invalid widget.

5.1 Compression Methods

The compression method is the compression algorithm or storage method used to encode the file data of a file entry. The compression method that is used to store the file data of a file entry is identified by the numeric value derived from the compression method field [ZIP].

The valid compression methods, as indicated by the compression method field, for a file entry are:

8

Data is compressed using [Deflate].

0

Data is Stored (no compression) [ZIP].

Author requirements: File data must be compressed with either [Deflate] or stored (no compression). Of the valid compression methods, [Deflate] is the recommended compression method. Using any other compression methods will result in an invalid widget.

Conformance checker behavior

A conformance checker must check that each file entry uses one of the valid compression methods. If a CC encounters a file entry that uses the Stored compression method, then it should inform the author that file entry should be recompressed with [Deflate]. If a CC encounters a compression method that is not a valid compression method, it must inform the author that the resource as an invalid widget.

5.2 Version of Zip Implementation Needed to Extract a File Entry

The version needed to extract is the 2-byte sequence in the local file header of a file entry that indicates the minimum version supported version of the [ZIP] specification needed to extract the file data.

The valid versions needed to extract values are as follows. Each value is assigned one or more meanings by the [Zip] specification:

0x100 (equivalent to 1.0)

Default value specified in Zip.

0x200 (equivalent to 2.0)

The file data may have been compressed using [Deflate],

or the file data may be a folder,

or the file may have been encrypted using traditional PKWARE encryption.

Note: If the Zip archive has been encrypted using traditional PKWARE encryption, then it will be treated as an invalid widget.

5.3 Zip Relative Paths

For the purpose of this specification, a Zip relative path is the variable-length string derived from a file name field of a local file header of a file entry.

The valid encodings for a Zip relative path are either [CP437] or [UTF-8]. It is recommended that the file name field be encoded using [UTF-8].

Author requirements: As stated in [Zip], the appropriate encoding indicator must be used, meaning that if the Zip relative path is encoded using [UTF-8], then general purpose bit 11 of the local file header must be set to 1; otherwise, it must be set to 0.

Note: A Zip relative path is said to be relative as it stores the string that represents file and folder names relative to where the Zip archive was created on a file system (e.g. images/bg.png), as opposed to storing an absolute path (e.g. c:\images\bg.png). The value of a Zip relative path will generally resemble the string value of a name of the file or folder(s) on the device on which the Zip archive was created, but with the exception of the path delimiter being a U+002F SOLIDUS "/" character.

Author requirements: It is recommended that authors keep their path lengths below 255 bytes. Note that a character can require more than one byte to encode, making the length of the path in characters less than 255.

A valid Zip relative path is one that case-insensitively matches the production of Zip-rel-path in the following [ABNF]. Note that ALPHA, DIGIT, and SP are defined in [ABNF] (but essentially represent alphanumerical characters and the U+0020 SPACE character). Language-Tag is defined in [BCP47]. In addition, reserved characters must not appear anywhere in the file-name.

Zip-rel-path     = [ *localized-folder ] [ *folder-name ] [ file-name ] / 
                   [ localized-folder ] [ *folder-name ] / [ folder-name ] 
localized-folder = "locales" "/" Language-Tag "/"
folder-name      = file-name "/"
file-name        = 1*254( *base-name [ file-extension ] ) 
base-name        = allowed-chars       
file-extension   = "." 1*allowed-chars       
allowed-chars    = cp437-chars / utf8-chars    
utf8-chars       = safe-chars / U+0080 and beyond      
cp437-chars      = safe-chars / x80-FF      
safe-chars       = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" / "@" 
                    / "~" / "!" / "(" / ")" / "^" / "&" / "+" 
                    / "," / "." / "=" / "[" / "]" 

Note: Authors should be aware that, at the time of writing, there are some interoperability issues with regards to using characters outside the allowed-chars for file or folder names in a Zip archive. If an author chooses to use cp437-chars or the UTF8-chars, they should thoroughly test their widgets on various platforms prior to distribution; otherwise it is suggested that authors restrict file and folder names to the allowed-chars (characters in the US-ASCII range).

This specification does not put a restriction on the byte length of Zip relative paths, a widget user agent should be prepared to deal with path lengths longer than 250 bytes.

Conformance Checker Behavior

A CC must inform the author about any file entry whose file name field is not a valid Zip relative path.

A CC must inform the author of any Zip relative paths whose length exceed 250 bytes, and should inform the author of any Zip relative path whose length exceeds 120 bytes.

Note: Having excessively long path names (e.g. over 120 characters) can also result in interoperability issues on some operating systems. Note that a character can require more than one byte to encode, making the length of the path in characters less than 255.

5.4 Reserved Characters

In addition to the control characters, the following characters are reserved and must not appear anywhere in a file-name.

Note: These characters are reserved to maintain interoperability across various file systems and with generic [URI]s.

Note to authors: It is recommended that authors avoid using the following words as either a folder or a base-name in a Zip relative path as they are reserved by some operating systems (case insensitive): CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$. For example, the following names are ok: "CON-tact.txt", "printer.lpt1", "DCOM1.pdf". However, "com3.txt" "Lpt1", "CoM9.gif" would not be. In addition, authors should avoid using 2 and 3 letters names for folders at the root of a widget resource.

In addition, authors should also avoid having a "." U+002E FULL STOP as the last character of a file or folder name as some operating systems will remove the character when the file is extracted from the Zip archive onto the device. Authors should also avoid having the space character (SP) at the start or end of a file name. Authors should also take caution when using the "+" U+002B PLUS SIGN, as it might cause issues on some operating systems.

Conformance Checker Behavior

A CC must inform an author of the presence of any of the reserved characters or control characters in a file-name.

A CC should inform an author of the presence of a U+0020 SPACE character at the start or end of a file-name.

A CC should inform an author of the presence of any U+002E FULL STOP at the end of a file-name.

A CC should inform an author of any base-name that case insensitively matches any of the following strings: CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$.

A CC may inform an author of the presence of any U+002B PLUS SIGN in a file-name.

6 Widget Resources

A widget resource is a valid Zip archive that contains:

• One or more start files, located at the root of the widget or in localized folders.
• Zero or more configuration documents, located at the root of the widget or in localized folders.
• Zero or more icons, located at the root of the widget or in localized folders.
• Zero or more thumbnail, located either at the root of the widget or in localized folders.
• Zero or more arbitrary files located either at the root of the widget or in arbitrary folders or in localized folders.
• Zero or more digital signatures located at the root of the widget.

See step 1 - Acquire a Potential Zip Archive for instructions on how to process a widget resource.

6.1 Invalid Widgets

During the steps for processing a widget resource, certain error conditions will result in a Zip archive being treated as an invalid widget. An invalid widget is a condition whereby a Zip archive, or a file within the Zip archive, is deemed to be corrupt beyond recovery or non-conforming to this specification.

See the section Dealing with Invalid Widgets for instructions on how a widget user agent must treat an invalid widget.

6.2 Files and Content Types

The root of the widget is the top-most folder level of the Zip archive. The root of the widget contains files and folders, some of which are reserved (see reserved file names).

A file is the decompressed representation of a file entry. Unlike [HTTP] resources, files within a Zip archive are not available in multiple representations, nor are they dynamically generated at runtime. Additionally, there is no notion of a [MIME] type within Zip (i.e., no Content-Type metadata), so widget user agents must use file extension to MIME mapping followed by content-type sniffing to determine the MIME type of a file.

A folder is a file entry whose file name field matches the production of folder-name in a valid Zip relative path (the last character of the file name field [ZIP] is a U+002F SOLIDUS) and whose version needed to extract is 0x200. A folder may logically contain files or other folders.

The base folder is the folder from which all relative paths are resolved.

File extension to MIME mapping is the process of mapping the file extension of a file to some MIME type.

Content-type sniffing is the process of determining the MIME type of a file by examining its content. Examination of content involves examining the bytes of a file for well-known patterns of byte sequences (e.g. the byte sequence EF BB BF, which identifies a text file as being encoded in [UTF-8]). Some of these patterns have been registered with the Internet Assigned Numbers Authority (IANA), as part of a MIME type registration, under the name magic numbers.

A processable file is a file that has been verified as residing inside a widget resource and that has a MIME type supported by the widget user agent.

6.3 Reserved File and Folder Names

The following table contains a list of base-names and possible file-extensions that when combined form file-names that are reserved for some purpose by this specification. All reserved file names must be treated as case insensitive.

The following table contains a list of folder-names that are reserved for some purpose by this specification. All reserved file names must be treated as case insensitive.

6.4 Digital Signatures

A widget resource contains a digital signature, and hence is digitally signed, if it contains one or more files that conform to the [Widgets-DigSig] specification.

The naming convention for digital signatures is a string that case-insensitively matches the production of dig-sig-file-names in the following ABNF:

dig-sig-file-names = "signature" *[0..9] ".xml"

6.5 Content Localization

Authors can localize the content of a widget by placing files inside folders that follow the Language Tag conventions set forth in [BCP47]; that is, by naming folders using values derived from the IANA Language Subtag Registry such as "en-us", "en-gb", and so on, but avoiding subtags marked as deprecated, grandfathered, or redundant. These localized folders are then placed inside the container for localized content (which is simply a folder called 'locales/' that sits at the root of the widget).

When an author places localized content in the container for localized content, the widget user agent will automatically select the appropriate localized version of a widget's files based on locale information derived from the system locale. The system locale is the end-user's preferred language and regional settings derived from the operating system or widget user agent (e.g. English, Australia).

Note: See also the Web Services Internationalization Usage Scenarios and the Unicode Locale Data Markup Language for an informative discussion on the term locale.

A localized widget is a widget resource that has a container for localized content, which contains one or more localized folders.

The container for localized content is a folder at the root of the widget whose the first five characters of the folder-name case insensitively match the string 'locales/'.

A localized folder is a folder whose file name field matches localized-folder. A widget resource may contain zero or more localized folders. Localized folders may contain zero or more arbitrary folders and/or files.

Author requirements: According to [BCP47], one should avoid region, script or other subtags except where they add useful distinguishing information to a localized folder. In addition, one should avoid including empty localized folders in a widget resource (unless there is a good reason to include them) as the a widget user agent will match them when it attempts to determine the base folder and widget locale.

A localized file is any resource that has been placed inside a localized folder. The contents of the resource may or may not be translated, localized, or altered for the given context. A widget resource may contain zero or more localized files. Any resource, except digital signatures, can be localized.

Note: A widget user agent will treat any localized digital signature as an arbitrary resource.

For example, a localized folder "/ja" (Japanese) might contain an HTML document translated into Japanese.

Author requirements: Localized folders must be at the root of the widget (a localized folder not at the root of the widget will be treated as an arbitrary folder). At runtime, the widget user agent will set the (HTML or XML) base of the start file to the localized folder (even if the start file does not reside inside the localized folder). Localizing a widget resource is optional and authors should provide a start file at the root of the widget. Please be aware that if localization fails, and there is no default start file at the root of the widget, then the widget user agent will treat the widget resource as an invalid widget.

Note: See Step 6 - determine the base folder and widget locale for the algorithm to process a localized widget.

Localized Widget Example

This section is non-normative.

The following is an example of a localized widget with multiple localized icons, start files and configuration documents. Some relevant things to note from the example:

• The config.xml file at the root configures English (en/, en-gb/) and Korean versions of the widget.
• All localized instances rely on the same un-localized script (engine.js)
• The Spanish version (es/) has its own custom configuration document and icon.

<!doctype html>
<h1>G'day! LOL Cats!</h1>
<script src="/scripts/engine.js">
...

<!doctype html>
<h1>Gatos Graciosos!</h1>
<script src="/scripts/engine.js">
...

Conformance Checker Behavior

A CC should inform the author if they have used deprecated, grandfathered, or redundant language tags from the IANA Language Subtag Registry.

Upon encountering any localized folders named with a region or script subtag, a CC should inform the author to avoid region or script subtags.

6.6 Start file and Default Start Files

The start file of a widget resource is a file that is used by the widget user agent when the widget is instantiated. When a start file is not explicitly declared via the content element or the content element's src attribute is in error, the start file will be one of the default start files.

A default start file is a start file that a widget user agent will attempt to locate when the start file of the configuration defaults is null (i.e., when an author omitted the content element in the configuration document or the content element is in error).

The file-name and MIME type of the default start files is given by the following table. A widget user agent is only required to support the text/html MIME type; support of other MIME types is optional.

A widget user agent will attempt to locate a file entry whose file-name matches one of the default start files based on the order they appear in the table below (from top to bottom). File names must be treated as case insensitive.

See step 9 for instructions for finding a default start file.

Author requirements: Always include at least one start file in a widget resource.

Conformance checker behavior

A CC must check that the widget resource contains at least one start file by:

1. Checking within all configuration documents that the author has used a correct content element to point to a supported file that exists within the widget package.
2. Checking for the presence of a default start file at the root of the widget and in all localized folders.

If the widget does not contain a start file, or the start file is not one that is supported, then the CC must inform the author.

6.7 Custom Icons and Default Icons

An icon is an optional file that is used to represent the widget in various application contexts (e.g. the icon that the user double-clicks to instantiate a widget, or an icon in a dock or task bar or some other visual context). There are two kinds of icons defined by this specification, custom icons and default icons.

An icon must be located either at the root of the widget or in a localized folder.

Custom Icons

A custom icon is an icon explicitly declared to be used as an icon by an author via an icon element of the configuration document. The MIME type of a custom icon is derived by the rules for identifying the MIME type of a file.

Default Icons

A default icon is an icon whose file-name case insensitively matches a file-name given in the first column of the default icons table below and whose MIME type matches the MIME type given in the second column of the table.

A default icon must be located either at the root of the widget or in a localized folder.

A widget user agent must search for a default icon's file-name based on the order they appear in the default icons table below (from top to bottom).

As indicated by the level of support column in the default icons table below, a widget user agent is required to support the image/png and image/gif MIME types; support of other MIME types is optional.

Conformance checker behavior

If no default icon has been included, and the CC determines that no custom icons have been declared in the configuration document, a CC should inform the author that it is desirable, but optional, to include a default icon.

If a CC encounters an icon in a format either than [PNG] or [GIF89] or [GIF87], then the CC should inform the author that these formats might not be supported on all widget user agents.

6.8 Thumbnail

A thumbnail is an optional file inside the widget resource that graphically represents the widget in a running state. The thumbnail must be located either at the root of the widget or in a localized folder.

To be treated as a thumbnail by the widget user agent, the file-name of a file entry must case insensitively match one of the file-name values given in the first column of the default thumbnails table below. In addition, the MIME type must match the MIME type given in the second column of the default thumbnails table below. A widget user agent will search for a thumbnail's filename based on the order they appear in the table below (from top to bottom).

Author requirement: it is recommended that authors use a screenshot of their widget in its running state as the thumbnail.

Conformance checker behavior

If a CC determines that the widget resource does not contain a thumbnail, it may inform the author that the inclusion of a thumbnail is desirable but, nonetheless, optional.

6.9 MIME Type

The widget MIME Type is application/widget [MIME].

Author requirement: Over the wire (e.g. over HTTP), a widget resource must be labeled with an application/widget MIME type. Failure to correctly label a widget resource will likely result in it being treated as an invalid widget.

Note: Widget user agents can support other legacy/proprietary widget types, but they must remain conforming to this specification when dealing with widget resources.

Note: The application/widget MIME type has not yet been registered with IANA. This will happen when the specification reaches Candidate Recommendation status.

6.10 File Extension

A widget file extension is the string .wgt in any case form (e.g. my.wgt, my.WGt, my.WgT, etc. are all valid).

The file extension .wgt is required for widget resources on systems where it's customary for file names to include an extension that symbolizes the MIME type.

Author requirement: As long as the widget resource is appropriately labeled as a application/widget when the widget resource is served over HTTP, the widget file extension is not required.

7 Configuration Document

A configuration document is an [XML] document that has a widget element at its root that is in the widget namespace.

A valid configuration document file name is config.xml, in any case form. Within a widget resource, a configuration document must have a valid configuration document file name.

Configuration documents can exist either at the root of the widget or in a localized folder.

Note: Any configuration document not at the root of the widget or not in a localized folder will be treated by the widget user agent as an arbitrary resource.

Author requirement: Authors should only place configuration documents in localized folders if the content of the configuration document has been localized. It is recommended that authors always include a configuration document at the root of the widget and, for constancy, that the config.xml filename be in lowercase form.

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" 
        identifier="http://datadriven.com.au/exampleWidget" 
        version="2.0 Beta" 
        height="200" 
        width="200">
  <name>The example widget!</name>
  <update href="http://www.bla.com/update.php"/>

  <description>
    A sample widget to demonstrate some of the possibilities.
  </description>
  <author href="http://foo-bar.example.org/"
    email="foo-bar@example.org">Foo Bar Corp</author>  
  <icon src="icons/example.png"/>
  <icon src="icons/boo.png"/>  
  <content src="index.html"/> 
  <access network="true"/>  
  <license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  </license> 
</widget> 

Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format.

See "Step 7 for instructions on how to process a configuration document.

7.1 Namespace

The widget namespace is http://www.w3.org/ns/widgets [XMLNS].

Authoring requirements: Authors must assign the widget namespace to the widget element. Authors should be aware that, if the namespace is missing then Zip archive will be treated as an invalid widget.

7.2 Proprietary Extensions

Vendors wishing to extend the configuration document format with their own [XML] elements and attributes (or those defined in other specifications) may do so by using a separate namespace [XMLNS]. This specification does not define a model for processing XML elements outside the widget namespace. For the sake of interoperability, extensions to the configuration document are not recommended.

<widget xmlns="http://www.w3.org/ns/widgets"
   xmlns:ex="http://widgextension.org/">
       <icon src="idle.png"  ex:role="inactive"/>
       <icon src="big.png" ex:role="big"/>
       <ex:datasource>{a:"b",c:"d"}</ex:datasource>
       <content src="widget.html"/>
</widget>

7.3 Attribute Types

This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types. Some general rules for how attributes are to be processed by widget user agents and conformance checkers are also given in this section.

Version attribute

An attribute defined as containing a valid version-tag. A valid version-tag is a string that matches the production for valid-version-tag in the following [ABNF]:

valid-version-tag  = version-identifier  *[ "." version-identifier ]        
version-identifier = ALPHA / DIGIT / SP / "$" / "%" / "'" / "-" / "_" 
                    / "~" / "!" / "(" / ")" / "^" / "&" / "+" / "@" 
                    / "," / "=" / "[" / "]" / "/" / "\" / "*" / "?"  
                    / "|"/ ":" 

Author Requirements: it is recommended that authors create version strings that conform to the following [ABNF]:

rec-version-tag = 1*2DIGIT ["."  1*2DIGIT [ "." 1*2DIGIT] [ ALPHA / SP / DIGIT]]

Example valid version tags:

Version 1.0 Beta, 1.0 RC1, 1.0-Build/1580, Joey the dog [5.1.2100].

Example of recommended version tags:

1.0, 1.10.1beta1, 1.02.12rc1.

Note: For the purpose of this specification, version tags have no significant semantics; they are just treated as arbitrary strings (e.g. '1.0' is not greater than '2.0', but is simply different). This may change in future versions of this specification.

Numeric attribute

An attribute defined as containing a valid non-negative integer. A valid non-negative integer is a string that consists of one of more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the characters "2", "323", "23214", and so on.

Keyword attribute

An attribute defined as requiring a certain string value (e.g. apple or orange). The values must be specified exactly, in the case given in this specification, and with no leading or trailing space characters. Implementations must only perform literal comparisons, and must not use case insensitive comparisons nor trim attribute values before comparison.

Boolean attribute

A keyword attribute that can only be used with a valid boolean value: a valid boolean value is a string that case insensitively matches true or false. The default behavior, which is used when the attribute is omitted or has a value other than the two allowed values, is false. How a widget user agent is supposed to interpret a boolean attribute is described when the term is used.

MIME type attribute

An attribute defined as containing a valid MIME type. A valid MIME type is one that matches the production for valid-MIME-type in the following [ABNF]:

valid-MIME-type = type "/" subtype *(";" parameter)

The type , subtype, and parameter tokens are defined in [RFC2045].

URI attribute

An attribute defined as containing a valid URI. A valid URI is one that matches the URI token of [URI] or the IRI token of [RFC3987].

Path attribute

An attribute defined as containing a valid path. A valid path is one that matches the path token of [URI]. A path can be either absolute, meaning that it is already resolved to the root of the widget (e.g. "/images/bg.png") or relative, meaning that it is resolved relative to some folder in the widget resource.

Window mode attribute

This feature is at risk! A keyword attribute whose value is one of the following valid window modes: application, floating, fullscreen, docked.

xml:lang attribute

A keyword attribute defined as containing a basic language range, defined in [BCP47], from the IANA Language Subtag Registry.The [XML] specification defines the xml:lang attribute and its influence on child elements that are XML text content. Widget user agents are not required to validate language ranges against the IANA Language Subtag Registry.

Author requirements: Authors should avoid subtags from the IANA Language Subtag Registry marked as deprecated, grandfathered, or redundant.

its:dir attribute

A keyword attribute defined as containing a valid its:dir value (i.e., ltr, or rtl, or lro, or rlo). To use the its:dir attribute, the its namespace (see [ITS]) must be declared on the element where it is used or somewhere in the element's ancestor chain.

7.4 The widget Element

The widget serves as a container for the other elements; as such, it must be used.

Context in which this element must be used:

This is the root element of a configuration document.

Expected children (in any order):

name: zero or one.

description: zero or one.

icon: zero or more.

access: zero or one.

author: zero or one.

license: zero or one.

content: zero or one.

update: zero or one.

feature: zero or more.

Attributes

id

Optional. A valid URI that denotes a identifier for the widget.

version

Optional. A valid version-tag that specifies the version of the widget.

height

Optional. A valid non-negative integer greater than 0 that controls the initial height dimensions of the instantiated widget in CSS pixels [CSS21]. When the value is missing, the widget user agent will assume the value 300.

width

Optional. A valid non-negative integer greater than 0 that controls the initial width dimensions of the instantiated widget in CSS pixels [CSS21]. When the value is missing, the widget user agent will assume the value 150.

mode

This feature is at risk! Optional. A valid window mode. When the value is missing, the widget user agent will assume the value default.

xml:lang

Optional. A basic language range.

Note: The width and height attributes are only relevant to widgets with a visual output.

Usage Example

This section is non-normative.

The following example shows how the widget element can be used. It also demonstrates the use of the xml:lang attribute.

<widget xmlns="http://www.w3.org/ns/widgets" 
        id="http://datadriven.com.au/exampleWidget" 
        version="2.0 Beta" 
        height="200" 
        width="200"
        xml:lang="pt">
  <description>este é um exemplo das possibilidades!</description>
</widget>

7.5 The name Element

The name element represents a human-readable name for a widget resource that can be used, for example, in an application menu or in other contexts.

Context in which this element may be used:

In a widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

The following example shows the usage of the name element.

<widgets xmlns="http://www.w3.org/ns/widgets">
   <name xml:lang="pt">Boletim Metereológico</name>
</widget>

7.6 The description Element

The description element represents a human-readable description of the widget.

Context in which this element may be used:

In a widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

An example usage of the description element.

<widgets xmlns="http://www.w3.org/ns/widgets"> 
  <name>Tornado Chaser</name>
  <description>
Combining the latest weather info with your GPS position, 
this widget alerts you of any significant storm activity in your 
area. When a big one hits, the widget plots the best route on a map based 
on the storm's trajectory so you can chase it! With support for 
built-in cameras, you can quickly upload all the meteorological action to 
your blog or to the insane storm chaser web site! Awesome!   
  </description>
</widget>

7.7 The author Element

An author element represents people or an organization attributed with the creation of the widget.

Context in which this element may be used:

In the widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

href

Optional. A URI attribute that represents a link that is associated with the author (e.g. the homepage of the author).

email

Optional. A string that represents an email address associated with the author.

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

The following example shows the expected usage of the author element.

<widgets xmlns="http://www.w3.org/ns/widgets">
        <name>Cup-a-Joe's Cafe Finder Widget</name>
        <author href  = "http://cup-a-joes-website-visit-us.com" 
                email = "joe@cup-a-joes-website-visit-us.com">
          Joey and Princesa Bacalhau
        </author>
</widget>

7.8 The license Element

The license element represents an end-user license agreement or a copyright statement for the widget.

Context in which this element may be used:

In the widget element.

Content model:

Any.

Occurrences:

Zero or one.

Attributes

href

Optional. A valid URI that points to a representation of a software and/or content license. When the href attribute is present, the widget user agent should allow users the ability to view or otherwise access the referenced license.

xml:lang

Optional. A basic language range.

its:dir

Optional. A valid its:dir value.

Usage Example

This section is non-normative.

This example shows the expected usage of the license element's href attribute.

<widgets xmlns="http://www.w3.org/ns/widgets">    
  <license href="http://creativecommons.org/licenses/by/3.0/">
        Creative Commons Attribution License
  </license>
</widget>

This example shows the expected usage of the license element when the href attribute is omitted.

<widgets xmlns="http://www.w3.org/ns/widgets">    
  <license>
  Copyright (c) 2008 The Foo-Bar Corporation
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
  USE OR OTHER DEALINGS IN THE SOFTWARE.
   </license>
</widget>

7.9 The icon Element

The icon element represents a custom icon for the widget. A widget user agent should expose a custom icon in a way that it is visible to the end user.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or more.

Attributes

src

Required. A valid path that points to an image file inside the widget resource.

width

Optional. A valid non-negative integer greater than 0 that represents the width of the icon in CSS pixels [CSS21]. This attribute is only applicable to graphic formats that have no intrinsic width or height (e.g., SVG). If the file pointed to by the src is a supported raster graphic, this value may be ignored by the widget user agent. If the file pointed to by the src is a vector graphic format, then this value will be used.

height

Optional. A valid non-negative integer greater than 0 that represents the height of the icon in CSS pixels [CSS21].This attribute is only applicable to graphic formats that have no intrinsic width or height (e.g., SVG). If the file pointed to by the src is a supported raster graphic, this value may be ignored by the widget user agent. If the file pointed to by the src is a vector graphic format, then this value will be used.

Author requirement: Authors should not use the width and height attributes for raster graphic formats (as the values will be ignored).

Usage Example

This section is non-normative.

This example shows the expected usage of the icon element. The example declares three icon elements, two of which are raster and one of which is an [SVGTiny] file. The raster graphics would be used for display contexts smaller than 256x256 pixels. Tree order of the elements is irrelevant.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <icon src="icons/medium.png"/>
  <icon src="icons/big.svg" width="256" height="256"/>
  <icon src="icons/tiny.png"/>
</widget>

7.10 The access Element

The access element indicates, through its attributes, what kind of security permissions are afforded to the widget by the widget user agent. When the access element is absent, a widget user agent must deny access to networked resources and to plugins.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Expected children:

none.

Attributes

network

Optional. A boolean attribute that indicates that the widget might need to access network resources as specified in [Widgets-Security].

plugins

Optional. A boolean attribute that indicates that the widget might need browser plugins (such as Flash or Java) to function. Plugin means a runtime component that is not bound to the security model of a widget user agent. In other words, a plugin operates under its own security model and policies (e.g., Flash and Java applets).

Note: Widget user agents are not required to support, or otherwise implement, proprietary plugins.

Conformance checkers requirements: If the access element is used, at least one of its attributes must be used.

Usage example

This section is non-normative.

This example shows the expected usage of the access element. Assume the flash_version.html file combines Adobe Flash and HTML content.

<widget
  xmlns ="http://www.w3.org/ns/widgets"
  width ="400"
  height="500">
  <name>Flight Tracker</name>
  <access network="true" plugins="true"/>
  <content src="flash_version.html"/>
</widget>

7.11 The content Element

The content element is used by an author to declare which start file the widget user agent will use when it instantiates the widget.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Attributes

src

Required. A path attribute that allows an author to point to a file within the widget resource.

type

Optional. A MIME Type attribute that indicates the MIME type of the file referenced by the src attribute. When the value is missing, the widget user agent will assume the value text/html.

charset

Optional. A keyword attribute that denotes the character set of the file identified by the src attribute. The allowed values are any name of a character set listed in [IANA-Charsets] (widget user agents are only required to support UTF-8). When the value is missing, the widget user agent will assume the value UTF-8.

Usage example

This section is non-normative.

This example shows the expected usage of the content element.

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

  <content src="myWidget.html"/>
</widgets>

This example shows the content element being used with a charset attribute to override the default value of this attribute (UTF-8) with the GB2312 character set, which the author has used to encode simplified Chinese characters.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <name xml:lang="zh-cn">古老瓷地图</name>
  <content src="china-maps.html" charset="GB2312"/>
</widgets>

This example shows the content element being used with a type attribute to instantiate a widget created with a proprietary MIME type.

<widgets xmlns="http://www.w3.org/ns/widgets">
  <name>Location-Based Games Finder</name>
  <content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
  <access network="true" plugins="true"/>
</widgets>

7.12 The update Element

The update element points, via the href attribute, to an update description document (see [Widgets-Updates]). The update description document is processed by the widget user agent to check for the availability of an updated version of the widget.

Context in which this element may be used:

In the widget element.

Content model:

Empty.

Occurrences:

Zero or one.

Attributes

href

Required. A URI attribute that indicates the location of an update description document as described in [Widgets-Updates].

Usage example

This section is non-normative.

This example shows the expected usage of the update element.

<widget xmlns   = "http://www.w3.org/ns/widgets"
        id      = "http://example.com/myWidget"
        version = "1.0">
  <update
   href="http//example.com/update.php?widget=myWidget&amp;version=1.0"/>
</widget>

7.13 The feature Element

The feature is used by an author to denote that, at runtime, a widget may require access to a feature. A feature is a runtime component (e.g. an API) that is not part of the standard set provided by the Widgets 1.0 family of specifications.

When a feature element is nested inside another feature element, it denotes a fallback relationship: if the feature identified by the outermost element is unavailable, then the widget user agent will check for the availability of the feature identified by the child's element's name attribute.

Note: the feature element is not a means to import javascript libraries or other resources available on the Web. The feature element should be viewed as a standardized way to request the binding of an (URI) identifiable runtime component to a widget for use at runtime.

Context in which this element may be used:

In the widget element or in the feature element.

Occurrences:

Zero or more.

Expected children:

feature: Zero or one.

Attributes

name

Required. A URI attribute that identifies a feature required by the widget at runtime (such as an API).

required

Optional. A boolean attribute that indicates that this feature or a feature identified in a child feature element must be available to the widget at runtime.

Usage example

This section is non-normative.

<widget xmlns="http://www.w3.org/ns/widgets">
   <feature name="urn:proprietary.camera.api" required="true">
      <!-- can't find it? use the alternative one -->
      <feature name="http://w3.org/apis/camera"/>
   </feature>
</widget>

7.14 Window Modes

Warning: Feature at risk! This specification does not define the semantics of the window modes. We seek input regarding what, if anything, should be specified in this spec versus what should be left as an implementation detail. The widget element's mode attribute and associated window modes will be dropped without substantial evidence that they are needed.

7.15 Indicating Text Directionality with <its:span>

Although it is optional for a widget user agent to implement [ITS], it is recommended that authors use the <its:span> element to indicate the directionality of arbitrary content when needed. Directionality is indicated by either using the dir attribute, with one of the following valid its:dir values, as defined in ITS:

ltr

Left to right text.

rtl

Right to left text.

lro

Left-to-right override.

rlo

Right-to-left override.

<widget 
   xmlns="http://www.w3.org/ns/widgets"
   xmlns:its="http://www.w3.org/2005/11/its">
  <name>Yay for the  
  "<its:span dir="rtl">متعة الأسماك!</its:span>" Widget</name>

  <description its:dir="rtl">متعة الأسماك! </description>
</widget>

The its:dir attribute and the <its:span> element can be used as a child of the following elements of the configuration document:

• name
• description
• author
• license

8 Steps for Processing a Widget Resource

Note: The following steps and associated parsing rules are written with more concern for clarity than efficiency. As such, user agents may optimize any of the parsing rules and the steps, or may perform the steps in a different order, so long as the end result is indistinguishable from the result that would be obtained by following the specification.

The steps for processing a widget resource involves ten steps that a widget user agent must follow, in sequential order, responding accordingly if any of the steps result in an error. The procedures for what to do when an error is encountered are described as part of each step; however, there are times when it will not be possible for the widget user agent to recover from an error and it will be forced to treat the widget as an invalid widget. What to do in a situation when a widget user agent encounters and invalid widget is described below.

Once a widget resource has been successfully processed, a widget user agent may install and instantiate the widget resource as described in [Widgets-Security].

8.1 Dealing with Invalid Widgets

This section describes what to do in the event a widget user agent needs to treat a Zip archive as an invalid widget.

In the event that an implementation encounters an invalid widget during the steps for processing a widget resource, the widget user agent must abort all processing of the steps for processing a widget resource and may inform the end-user with an appropriate localized error message (see example in the note below). The wording of an appropriate localized error message is left to the discretion of implementers; however, their presence is nonetheless recommended.

An example of an appropriate error dialog would be "This widget cannot be installed because it was created using an unsupported compression method."

8.2 Extracting the File Data from a File Entry

When processing a widget resource, a widget user agent will have to decompress (or otherwise extract) the file data of file entry into its original representation. Specifying exactly how to extract file entries from a Zip archive is beyond the scope of this specification. Instead, implementers must follow the processing rules defined in the [ZIP] specification to extract file entries for Zip archive.

A widget user agent is not required to extract all the file entries in a Zip archive at the same time. It may extract specific file entries as they are needed for processing or rendering.

Note: As a security precaution, implementations are discouraged from extracting file entries from untrusted widgets directly onto the file system. Instead, implementations should consider a virtual file system or mapping to access files inside a Zip archive.

Step 1 - Acquire a Potential Zip Archive

Step 1 involves acquiring a potential Zip archive and checking if it is a Zip archive by using the rules for determining if a potential Zip archive is a Zip archive. A widget user agent will acquire a potential Zip archive from a data transfer protocol that either labels resources with a [MIME] type (e.g. [HTTP]) or from a data transfer protocol that does not label resources with a [MIME] type (e.g., BitTorrent, Bluetooth, etc.).

An implementation is not required to acquire all the bytes of a potential zip archive before applying the rules for determining if a potential Zip archive is a Zip archive. It may perform the check once it has acquired the first four bytes of the resource.

Acquisition of potential Zip archive labeled with a MIME type

When attempting to acquire a potential Zip archive over some protocol that labels resources with a MIME type, a widget user agent must only attempt to process resources labeled with the widget MIME type (application/widget) regardless of file extension or no file extension. Unless the widget user agent supports legacy or proprietary MIME types, all other MIME types are in error and the widget user agent must treat the potential Zip archive as an invalid widget.

For example, in [HTTP], where the Content-Type header matches application/widget.

If the protocol used for acquisition of a potential Zip archive does not provide, or otherwise include a MIME type, then a widget user agent may treat the acquired potential Zip archive as if it has been acquired from a protocol that does not label resources with a MIME type.

Acquisition of potential Zip archive not labeled with a MIME type

A widget user agent must attempt to process a resource regardless of the file extension (including situations when there is no file extension) by applying the rules for determining if a potential Zip archive is a Zip archive.

Rules for Determining if a potential Zip archive is a Zip archive

The rules for determining if a potential Zip archive is a Zip archive is as follows.

If the first four bytes of the potential Zip archive do not match the magic numbers for a Zip archive (50 4B 03 04) then a widget user agent must treat the resource as an invalid widget. Otherwise, the widget user agent must treat the potential Zip archive as a Zip archive.

With the Zip archive, the widget user agent must verify the Zip archive and its file entries.

Step 2 - Verify the Zip archive and its File Entries

To verify that a Zip archive and its file entries conform to this specification, a widget user agent must perform the following checks. This specification does not provide the technical details of how to actually perform the checks. Instead, implementers must follow the [Zip] specification.

The potential widget resource can be considered verified only once the checks below have been completed.

If any of the following conditions occur/apply (indicating that a condition is met), then a widget user agent must treat the Zip archive is an invalid widget:

1. The zip archive is split into multiple files or spans multiple volumes [ZIP].
2. The Zip archive is encrypted (which is denoted by general purpose bit 0 being set and by the presence of archive decryption header and an archive extra data record [ZIP]).
3. The Zip archive is digitally signed using any of the digital signature methods defined in [ZIP].
4. The Zip archive contains zero file entries.
5. The Zip archive contains only folders.

Next, for each file entry in the Zip archive, the widget user agent must perform the following checks. If any of the following conditions occur/apply (indicating that a condition is met), then the widget user agent must treat the Zip archive as an invalid widget. For each file entry in the Zip archive, check the following data from the local file header:

1. The value of the CRC-32 field (defined in [ZIP]) fails a CRC-32 check.
2. The version needed to extract is greater than 20 (meaning the archive is using a feature unsupported by this specification, such as Zip64).
3. The value of the compression method field is not one of the valid compression methods (0 or 8).
4. The file name field is an empty string.
5. The file name field contains reserved characters.
6. The file name field is a sequence exclusively composed of (one or more) space characters or a mixed sequence of space characters and U+002E FULL STOP (".") (e.g. " . .   ").
7. The file name field is not a valid Zip relative path.
8. There two are resources whose file name fields, upon normalization, case insensitively match ('images/BG.png' and 'iMaGeS/bG.pNg' are considered canonically equivalent)

A widget user agent must now set the configuration defaults (step 3).

Step 3 - Set the Configuration Defaults

Widget user agents must assume the following configuration defaults at this point of processing:

Once the above configuration defaults have been set, a widget user agent must attempt to locate digital signatures for the widget (step 4).

Step 4 - Locate Digital Signatures for the Widget

The algorithm to locate digital signatures for the widget is as follows:

1. Let signatures be an empty list.
2. For each file entry in the Zip-archive, if the file name field case insensitively matches the naming convention for digital signatures, append this file entry to the list of signatures.
3. If signatures is empty, terminate this algorithm and go to step 6.
4. Otherwise, sort the list of signatures by the file name field in descending order (i.e. signature001.xml followed by signature9.xml followed by signature.xml).
5. Go to Step 5 and process the digital signatures.

Step 5 - Process the Digital Signatures

The following algorithm describes how to process the list of signatures created in step 4.

Note: How a widget user agent uses a digital signature is determined by the security policy implemented by that widget user agent. As such, this specification does not mandate processing rules dependent on the verification of one or more digital signature documents or on the revocation status obtained for the certificates associated with a verified digital signature document.

For each file entry in signatures, apply the Procedure for Verifying a Digital Signature Document in the [Widgets-DigSig] specification in the order they appear in the signatures list:

1. If the file entry is a verified digital signature, as defined in [Widgets-DigSig], set signed to true.
2. If the file entry is deemed by the [Widgets-DigSig] to be an invalid widget, then a widget user agent must treat this widget as an invalid widget.
3. If the widget user agent determines that an exit criteria, as defined in [Widgets-DigSig], has been met, terminate this algorithm and go to step 6. Otherwise, select the next file entry in the signatures list and go to 1 in this algorithm.
4. If every file entry has been processed in accordance to [Widgets-DigSig], but no exit criteria has been met, then go to step 6.

Step 6 - Determine the Base folder and Widget Locale

Before attempting to locate the configuration document, the widget user agent must check for the existence of any localized folders that match the end-user's language preferences (as contained by the wua-language list).

This step makes use of the lookup mechanism as defined in section 3.4 of [RFC4647] (part of [BCP47]). The aim is to match, in order, one of the language ranges in the wua-language list to a localized folder in the widget resource.

The algorithm to determine the base folder and widget locale are as follows:

1. If the wua-language list is 'empty', or null, or 'i-default', or contains a single '*', or is a sequence of items that only contain the '*' character, then terminate this algorithm and attempt to locate the configuration document.
2. For each range in the wua-language list:
   1. If this range is a single '*', then terminate this algorithm and attempt to locate the configuration document.
   2. If this range begins with the subtag '*', then skip this range and, skipping all the steps below, repeat number 2 of this algorithm.
   3. Else if this range contains a subtag '*', remove the '*' and its preceding hyphen (U+002F) and continue (for example, 'en-*-US' becomes 'en-US').
   4. Let potential range be the concatenation of the string 'localized/' and the range (e.g. "en-us" becomes "locales/en-us").
   5. For each file entry in the widget resource, check if the first characters of the file name field match the potential language range (e.g., if the potential range is 'locales/en-us', then 'locales/en-us/anyfile' would match),
      1. If they match:
         1. Let widget locale be the value of the current range in lowercase form.
         2. Let base folder be the potential range.
         3. Terminate this algorithm and attempt to locate the configuration document.
      2. Else, remove the last subtag of the range and repeat this step 2.d. (e.g., if the range is currently "en-US", make the range "en" and search for 'locales/en').
3. If no match is made, attempt to locate the configuration document (step 7).

For example, if the wua-language list is "en-AU" and a match is made on file entry whose name is "locales/En-Au/config.xml", then base folder would be ""locales/En-Au/", and the widget locale would be "en-au".

For example, if the wua-language list is "de-CH,fr-CH,it-CH" and folders included "locales/de", "locales/fr-FR" , and "locales/IT", then the folder "locales/de" would be matched, then base folder would be "locales/de" and the widget locale would be "de".

Step 7 - Locate the Configuration Document

This step involves searching within the zip archive for a configuration document. The configuration document, if it exists, will be located at either the root of the widget or in a localized folder.

The algorithm to locate the configuration document is as follows:

1. Search the widget resource for a file entry whose file name field case insensitively matches the concatenation of the base folder and the string config.xml (e.g. locales/en-us/config.xml). If a match is made, set config doc to be this file entry.
2. If no match is made, search for a file entry residing at the root of the widget whose file name field case insensitively matches config.xml. If a match is made, set config doc to be this file entry.
3. If no match is made, attempt to locate the start file, otherwise process the configuration document (step 8).

Step 8 - Process the configuration document

The config doc must be processed as described in the following sub-sections. The purpose of processing the configuration document is to override the configuration defaults, which are used during instantiation and at runtime [Widgets-security]).

The main algorithm for processing a configuration document is given by the rules for processing a configuration document. To maintain interoperability across implementations, this step also makes use of the following rules for processing certain attribute types and files:

• Rules for parsing a non-negative Integer.
• Rules for removing whitespace.
• Rules for identifying the MIME type of an image.
• Rules for identifying the MIME type of a file.

Rules for Processing a Configuration Document

The rules for processing a configuration document are given in the following algorithm.

The term in error is typically used to mean that an element or attribute in a configuration document is not conforming to the rules of this specification. Rules for how an element or an attribute are to be treated when it is in error are always given when the term is used. Typically the specification will say that the erroneous DOM nodes must be ignored, meaning that the widget user agent must act as if those nodes were not present.

An element or an attribute is correct if it is not in error.

The term text node refers to any Text node, including CDATASection nodes (any Node with node type 3 or 4) as defined in [DOM3Core].

1. Let doc be the result of loading the widget config doc as a [DOM3Core] Document using a [XMLNS]-aware parser. The parser must support xml:lang, and process any occurrence of the xml:lang attribute in accordance to the [XML] specification.
2. If the document is not well-formed [XML], terminate this algorithm and treat this widget resource as an invalid widget.
3. Let root element be the documentElement of doc.
4. If the root element is not a widget element in the widget namespace, then treat this widget resource as an invalid widget.
5. Otherwise,

   it is a widget element:

   If any one of the following attributes is in error or invalid, then that attribute must be ignored. All declared attributes must be processed.

   If the id attribute is used, and it is a valid URI, then let widget id be the value of the id attribute.

   If the version attribute is used, and it is a valid version-tag, then let widget version be the value of the version attribute.

   If the height attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, let widget height be the value of the height attribute.

   If the width attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, let widget width be the value of the width attribute.

   If the mode attribute is used, and it is a valid window mode, then let widget window mode be the value of the mode attribute. This feature is at risk!

   If the widget element does not contain any child elements, then terminate this algorithm and go to step 9.

6. For each child element that is a direct descendent of the root element, starting from the first moving to the last in tree order, if it is:

   A name element

   If this is not the first name element, then this element and its child nodes are in error and must be ignored.

   If this is the first name element encountered, then let widget name be the result of applying the rules for getting text content to this element.

   A description element

   If this is not the first description element, then this element and its child nodes are in error and must be ignored.

   If this is the first description element encountered, then let widget description be the result of applying the rules for getting text content to this element.

   An author element

   If this is not the first author element, then this element and its child nodes are in error and must be ignored.

   If this is the first author element used, then:

   1. let author name be the result of applying the rules for getting text content to this element.

   2. If the href attribute is used, and it is a valid uri, then let author href be the value of the href attribute. Otherwise, the attribute is in error and must be ignored.

   3. If the email attribute is used, then let author email be the value of the email attribute.

   A license element

   If this is not the first license element, then this element and its child nodes are in error and must be ignored.

   If this is the first license element used, then

   1. Let widget license be the result of applying the rules for getting text content to this element.

   2. If the href attribute is used, and it is a valid uri, then let widget license href be the value of the href attribute. However, if the attribute is in error then it must be ignored.

   An icon element

   If the file identified by the src attribute is missing, or not a valid path, or corrupt, or is an unsupported MIME type, or already exists in the icons list, then this element is in error and must be ignored. Otherwise:

   1. If the a src attribute is a valid path that points to a file, apply the rules for identifying the MIME type of an image. If the MIME type is supported, then add the file entry identified by the value of the src attribute to the list of icons.

   2. If the height attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, make the value of the height attribute a property of this file entry.

   3. If the width attribute is used, apply the rules for parsing a non-negative integer to its value. If the value is not in error and greater than 0, make the value of the width attribute a property of this file entry.

   A content element

   If this is not the first content element, then this element and its child nodes are in error and must be ignored.

   If this is the first content element and it has a src attribute that is a valid path that points to a file, then check if the file is supported by the widget user agent by applying the rules for identifying the MIME type of a file. If the file is supported, let the widget start file be the file entry referenced by the src attribute. If the src attribute is missing, or in error, then a widget user agent must treat the widget resource as an invalid widget.

   If the type attribute is used and there is a correct src attribute, and it is a valid MIME type that is supported, then let the start file content-type be the value of the type attribute. If the MIME type is invalid, or unsupported by the widget user agent, then a widget user agent must treat the widget resource as an invalid widget. Otherwise, the attribute is in error and must be ignored.

   If the charset attribute is used and there is a correct src attribute, and it is an encoding that is supported by the widget user agent, then let the start file encoding be the value of the charset attribute. If the encoding is invalid, or unsupported by the widget user agent, then a widget user agent may use the default encoding (UTF-8) or treat the widget as an invalid widget. Otherwise, the attribute is in error and must be ignored.

   A feature element

   If the name attribute is not a valid URI, then this element is in error and must be ignored.

   If the name attribute is a valid URI, then normalize the value of the name attribute using [URI] normalization. If upon [URI] normalization the feature identified by the name attribute is supported by the widget user agent, then add the normalized value of the name attribute to the list of features. Otherwise, the attribute is in error and the element must be ignored.

   An access element

   If this is not the first access element, then this element and its child nodes are in error and must be ignored.

   If this is the first access element and if the network attribute is used, and it is a valid boolean value, then let allow network be the value of the network attribute. Otherwise, the attribute is in error and must be ignored.

   If this is the first access element and if the plugins attribute is used, and it is a valid boolean value, then let allow plugins be the value of the plugins attribute. Otherwise, the attribute is in error and must be ignored.

   An update element

   If this is not the first update element, then this element and its child nodes are in error and must be ignored.

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

   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. Once all the elements have been processed go to step 9.

Rules for Getting Text Content

The rules for getting text content are given in the following algorithm. The algorithm always returns a string, which may be empty.

Let input be the element to be processed.

1. Let result be an empty string.
2. If the widget user agents supports [ITS]:
   1. If the element has the dir attribute from the [ITS] namespace with a valid its:dir value, then process its text nodes in accordance to the [ITS] specification.
3. Ignoring any Text nodes that only contain space characters, or CDATASection nodes that only contain space characters, let result be the concatenation of the input's text nodes, in document order, as a string:
   1. If the node is an element that contains any Text nodes, recursively apply the rules for getting text content to that element and concatenate the returned value to result.
4. While position doesn't point past the end of input, append character to the end of result and let position become the character in input.
5. Return result.

<widget xmlns="http://www.w3.org/ns/widgets">
   <name>
     The <blink>Awesome</blink> 
     <author email="dude@example.com">Super <blink>Dude</blink></author>
     Widget</name>
</widget>

Rules for Parsing a Non-negative Integer

The rules for parsing a non-negative integer are as given in the following algorithm. When invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm will either return zero, a positive integer, or an error. Leading spaces are ignored. Trailing spaces and any trailing garbage characters are ignored.

1. Let input be the string being parsed.
2. Let result have the value 0.
3. Let input be the result of applying the rules for removing whitespace on input.
4. If the length of input is 0, return an error.
5. Let position be a pointer into input, initially pointing at the start of the string.
6. Let nextchar be the character in input at position.
7. If the nextchar is not one of U+0030 (0) .. U+0039 (9), then return an error.
8. If the nextchar is one of U+0030 (0) .. U+0039 (9):
   1. Multiply result by ten.
   2. Add the value of the nextchar to result.
   3. Increment position.
   4. If position is not past the end of input, go to step 6.
9. Return result.

Rules for Removing Whitespace

The rules for removing whitespace are as given in the following algorithm. As with the previous algorithms, when this one is invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm returns a string with all space characters removed.

1. Let input be the string to be parsed.
2. Let result be the empty string.
3. While position doesn't point past the end of input and the character at position is not one of the space characters, append character to the end of result and let position become the character in input.
4. Return result.

Rules for Identifying the MIME type of an Image

The rules for identifying the MIME type of an image are given by the following algorithm. Widget user agents are required to support the MIME types given in the table below, except for image/svg+xml, which is optional.

1. If the file entry has a file extension, attempt to match the file extension to one in the first column in the image identification table. If there is a match, then return the MIME Type value and terminate this algorithm.
2. If the file entry has no file extension, if the first bytes of the decompressed file entry's data field matches one of the byte sequences in the bytes in hexadecimal column of the following table, then return the MIME type in the corresponding cell in the second column on the same row. Otherwise, return unknown/unknown.

Rules for Identifying the MIME Type of a file

The rules for identifying the MIME type of a file are given by the following algorithm. Widget user agents are required to support the MIME types given in the table below.

1. If the file entry has a file extension, attempt to match the file extension to one in the first column in the file identification table. If there is a match, then return the MIME Type value.
2. If there is no file extension, the MIME type of a file can be sniffed by using the rules set forth in [HTML5]'s section on determining the type of a resource. To reduce the risk of exposing the end-user to malicious attacks, those rules must be followed by a widget user agents exactly as specified in [HTML5].

Step 9 - Locate the Start File

This step involves finding and verifying the start file.

1. If the widget start file is not null, terminate this algorithm and go to step 10.
2. If the widget start file is null, then try to find one of the default start files in the base folder.
3. If none is found, and the base folder is not the root of the widget, attempt to find one of the default start files at the root of the widget. If none are found, then treat this widget resource as an invalid widget.
4. If one of the default start files is found, let the widget start file be the file entry of that default start file.
5. If the start file is not null, check that it is a correct file of a supported MIME Type.

Step 10 - Locate the default icons and thumbnail

A widget user agent must search for an icon's file name based on the order they appear in the default icons table (from top to bottom).

1. Search for any of the default icons that reside in the base folder.
2. If the base folder is not the root of the widget, attempt to find default icons at the root of the widget.
3. For each default icon found, if the default icon file entry does not exist in the icons list, then add the file entry to the list of icons.

A widget user agent must search for a thumbnail's file name based on the order they appear in the default thumbnails table (from top to bottom).

1. Search for any of the default thumbnails that reside in the base folder.
2. If the base folder is not the root of the widget, attempt to find default thumbnails at the root of the widget.
3. If the filename field of a file entry matches one of the file name's from the default thumbnails table, then let widget thumbnail be the matching file entry.

Appendix

Embedding a Widget Resource into an HTML Document

This section is non-normative.

This section only applies to HTML user agents [HTML4] [XHTML].

Auto-discovery enables a user agent to identify and install a widget resource that is associated with an HTML page. When a page points to a widget resource, user agents should expose the presence of the widget resource to the end-user and allow the end-user to install the widget.

The link type "widget" indicates that a link of this type references a document that is a widget resource. In HTML, it may be specified for the a, area and link elements to create a hyperlink.

<a rel="widget" 
   href="http://example.org/exampleWidget">The Example Widget</a>

RelaxNG Schema for the Configuration Document

This section is non-normative.

This schema may be out of date, we only update it prior to publication. You can get the latest draft from http://hasather.net/widgets/widgets.rnc.

The following is the RelaxNG schema representation of the elements and attributes of the configuration document. Products that check the conformance of widget resources or configuration documents can use this schema to validate configuration documents.

# Widgets 1.0 (Working Draft) RELAX NG schema
# Latest draft at http://hasather.net/widgets/widgets.rnc
default namespace widgets = "http://www.w3.org/ns/widgets"
namespace its = "http://www.w3.org/2005/11/its"
namespace local = ""

start = elem.widget

elem.widget = element widget {
  attr.xmllang?,
  attribute id { xsd:anyURI }?,
  attribute version { text }?,
  attribute height { data.positiveNumber }?,
  attribute width { data.positiveNumber }?,
  attribute mode { "application" | "fullscreen" | "floating" | "docked" }?,
  ( elem.name?
  & elem.description?
  & elem.icon*
  & elem.access?
  & elem.author?
  & elem.license?
  & elem.content?
  & elem.update?
  & elem.feature*
  & extension )
}

elem.name = element name {
  attr.xmllang?,
  attr.itsdir?,
  extension
}

elem.description = element description {
  attr.xmllang?,
  attr.itsdir?,
  extension
}

elem.icon = element icon {
  attr.allowed*,
  attribute src { xsd:anyURI },
  attribute height { data.positiveNumber }?,
  attribute width { data.positiveNumber }?,
  empty
}

elem.access = element access {
  attr.allowed*,
  attribute network { data.boolean }?,
  attribute plugins { data.boolean }?,
  attribute files { data.boolean }?,
  empty
}

elem.author = element author {
  attr.xmllang?,
  attr.itsdir?,
  attribute href { xsd:anyURI }?,
  attribute email { xsd:string { pattern=".+@.+" } }?,
  extension
}

elem.license = element license {
  attr.xmllang?,
  attr.itsdir?,
  attribute href { xsd:anyURI }?,
  extension
}

elem.content = element content {
  attr.allowed*,
  attribute src { xsd:anyURI },
  attribute type { text }?,
  attribute charset { text }?,
  empty
}

elem.update = element update {
  attr.allowed*,
  attribute href { xsd:anyURI }?,
  empty
}

elem.feature = element feature {
  attribute name { xsd:anyURI },
  attribute required { data.boolean }?,
  ( elem.feature?
  & extension )
}

extension = ( attr.allowed | anyElement )*
anyElement = ( element * - widgets:* { any } | text )*
any = ( attribute * { text } | anyElement )*

attr.allowed = attribute * - (local:* | xml:lang | its:dir) { text }
attr.xmllang = attribute xml:lang { xsd:language }
attr.itsdir = attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }

data.positiveNumber = xsd:string { pattern="[1-9]\d*" }
data.boolean = ( string "true" | string "false" )

Acknowledgements

Special thanks go to Arve Bersvendsen, Anne van Kesteren and Charles McCathieNevile who helped edit the initial version of this specification.

Special thanks also to David Håsäther for creating and maintaining the RelaxNG Schema for the configuration document.

A huge thanks to Bárbara Barbosa Neves for her patience and for doing last minute proof-reads in the dead of night.

Parts of this document reproduce text and behavior from the HTML5 specification and from the XBL 2.0 specification (as permitted by both specifications by their copyright statements).

Graphic icons used some examples of this specification were created by Yusuke Kamiyamane and are available for use under a Creative Commons Attribution 3.0 license.

The editor would also like to thank the following people for their contributions to this specification:

• Addison Phillips
• Alexander Dreiling
• Arun Ranganathan
• Arthur Barstow
• Brian Wilson
• Bjoern Hoehrmann
• Benoit Suzanne
• Bert Bos
• Bradford Lassey
• Cameron McCormack
• Cliff Schmidt
• Claudio Venezia
• Coach Wei
• Corin Edwards
• Dan Brickley
• David Clarke
• Dean Jackson
• David Pollington
• Doug Schepers
• Ed Voas
• Felix Sasaki
• Gautam Chandna
• Geir Pedersen
• Gene Vayngrib
• Gorm Haug Eriksen
• Guido Grassel
• Ian Hickson
• Jay Sweeney
• Jere Kapyaho
• Jim Ley
• Jon Ferraiolo
• Jose Manuel Cantera Fonseca
• Jouni Hakala
• Joey Bacalhau
• Kevin Lawver
• Krzysztof Maczyński
• Lachlan Hunt
• Marc Silbey
• Mark Baker
• Mikko Pohja
• Mohamed Zergaoui
• Olli Immonen
• Philipp Heltewig
• Philip Taylor
• Stephen Paul Weber
• Tex Texin
• Thomas Landspurg
• Yang Wong
• Zachary Fitz-Walter

Normative References

[ABNF]

RFC 5234, Augmented BNF for Syntax Specifications: ABNF. D. Crocker and P. Overell. January 2008.

[BCP47]

BCP 47, Tags for the Identification of Languages. A. Phillips (Ed.) and M. Davis (Ed.). September 2006.

[CP437]

IBM CPGID 00437. ftp://ftp.software.ibm.com/software/globalization/gcoc/attachments/CP00437.txt

[CSS21]

Cascading Style Sheets, level 2 revision 1; CSS 2.1 Specification. Bert Bos, Ian Hickson, Tantek Çelik, Håkon Wium Lie. W3C, April 2006.

[Deflate]

DEFLATE Compressed Data Format Specification version 1.3, P. Deutsch, The Internet Society, May 1996.

[DOM3Core]

Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. World Wide Web Consortium, April 2004.

[ECMAScript]

ECMAScript Language Specification, Third Edition. ECMA, December 1999.

[HTML4]

HTML 4.01 Specification, D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999. Latest version available at: http://www.w3.org/TR/html401

[GIF87]

Graphics Interchange Format. CompuServe Incorporated, June 15, 1987.

[GIF89]

Graphics Interchange Format (sm). CompuServe Incorporated, 1990.

[ICO]

Vendor Tree - vnd.microsoft.icon. S Butcher. 3 September, 2003. IANA Media Type Assignment. http://www.iana.org/assignments/media-types/image/vnd.microsoft.icon

[ITS]

Internationalization Tag Set (ITS) Version 1.0, C. Lieske and F. Sasaki, W3C Recommendation 03 April 2007. Available at http://www.w3.org/TR/2007/REC-its-20070403/

[JPEG]

ISO/IEC 10918. Information Technology Digital Compression And Coding Of Continuous-tone Still Images International Organization for Standardization (ISO).

[HTTP]

RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1. R. Fielding, et al. June 1999.

[HTML5]

HTML 5 (work in progress), I. Hickson, D. Hyatt, editors. W3C, 2008.

[IANA-Charsets]

IANA Character Set Registry, http://www.iana.org/assignments/character-sets

[MIME]

RFC 2045, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed and N. Borenstein. November 1996.

[PNG]

Portable Network Graphics (PNG) Specification (Second Edition), David Duce, ed., 10 November 2003.

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. March 1997.

[RFC2822]

Internet Message Format. P. Resnick. April 2001.

[RFC3987]

RFC 3987, Internationalized Resource Identifiers (IRIs). M. Duerst, M. Suignard. January 2005.

[RFC2045]

RFC2045, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, N. Freed. November 1996.

[RFC4647]

RFC4647. Matching of Language Tags, A. Phillips and M. Davis. September 2006.

[SVGTiny]

Mobile SVG Profiles: SVG Tiny and SVG Basic. W3C Recommendation 14 January 2003.

[Unicode]

The Unicode Consortium. The Unicode Standard, Version 5.0.0, defined by: The Unicode Standard, Version 5.0 (Boston, MA, Addison-Wesley, 2007. ISBN 0-321-48091-0). (See http://www.unicode.org/unicode/standard/versions for the latest version and additional information on versions of the standard and of the Unicode Character Database).

[URI]

RFC 3986, Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee, R. Fielding and L. Masinter. January 2005.

[UTF-8]

RFC 3629, UTF-8, a transformation format of ISO 10646, F. Yergeau. November 2003.

[Widgets-APIs]

Widgets 1.0: API's and Events. A. Bersvendsen and M. Caceres. Forthcoming.

[Widgets-DigSig]

Widgets 1.0: Digital Signature. M. Caceres, Ed. W3C, W3C Working Draft 14 April 2008.

[Widgets-Security]

... forthcoming.

[Widgets-Updates]

Widgets 1.0: Updates. M. Caceres. W3C Working Draft 7 October 2008.

[XML]

Extensible Markup Language (XML) 1.0 (Third Edition). T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau. W3C, February 2004.

 

[XMLHttpRequest]

The XMLHttpRequest Object. A van Kesteren. W3C Working Draft 15 April 2008. (Work in progress)

[XMLNS]

Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin. W3C, August 2006. The latest version of the Namespaces in XML specification is available at http://www.w3.org/TR/REC-xml-names/

[ZIP]

.ZIP File Format Specification (Version 6.3.2, revised September 28, 2007). PKWare Inc.

Informative References

[Widgets-Landscape]

Widgets 1.0: The Widget Landscape (Q1 2008). M. Caceres. W3C Working Draft. 14 April 2008.

[Widgets-Reqs]

Widgets 1.0 Requirements, M. Caceres, Ed. W3C, July 2007.

[Widgets-Test-Suite]

... forthcoming.

[XHTML]

"XHTML 1.0: The Extensible HyperText Markup Language", W3C Recommendation, S. Pemberton et al., 26 January 2000.
Available at: http://www.w3.org/TR/2000/REC-xhtml1-20000126