Abstract
This document defines expected behavior for conformance checkers,
which are tools that aid authors in verifying that Zip archives and configuration documents conform to the Widgets 1.0: Packaging and Configuration Specification.
Conformance
The keywords must, must not, should, recommended, may and optional in this specification are to be interpreted as described in [RFC2119].
Some text in this specification is non-normative. Non-normative text includes:
- sections marked with the text
This section is non-normative
,
- examples,
- and notes.
Everything else in this specification is normative.
There is only one class of product that can claim conformance to this
specification: a conformance checker.
Conformance Checker
A conformance checker (CC) is an implementation of this specification that verifies
that certain aspects of a widget conform
to the [Widgets-P&C] specification.
The aspects of a widget that a conformance checker is required to validate are:
- Zip archives
- File Entries
- Widget Packages
- Icons
- File Extension and Media Type
- Configuration Document
In case an aspect of a widget does not conform to the [Widgets-P&C] specification, this specification will normally ask a CCs to inform the authors. To inform means displaying an advisory message to an author that would assist them in correcting a conformance violation. Wording of
advisory messages is left to the discretion of implementers.
Automated conformance checkers are exempt from detecting errors that
require interpretation of the author's intent (for example, a CC would not have to check if the description element actually contains a description of the widget).
Although the working group provides a [Widgets-Relax NG Schema] of the elements and attributes that one can use in a configuration document, the schema cannot express all the conformance requirements of this
specification. Therefore, an application that only validates against the [Widgets-Relax NG Schema] cannot
claim to be a conformance checker as defined by this specification.
Conformance Checker Behavior
This section specifies how a conformance checker is expected to behave when examining
It is optional for a CC to inform an author of all conformance violations, or other conditions, at once.
Zip Archive
This section relates to zip archives, as are defined in the [Widgets-P&C] specification.
A CC must inform the author that a Zip archive that is split into multiple files or spans multiple volumes, as defined in the [ZIP] specification.
Reason: Zip archives that are split into multiple files or span multiple volumes are not allowed and a user agent will treat them as an invalid Zip archive.
A CC must inform the author that a Zip archive that is encrypted,
which is denoted by bit 0 of the general purpose
field being set and by the presence of archive decryption
header and an archive extra data record (all three
of which are defined in the [ZIP] specification), is an invalid
Zip archive.
Reason: As widget user agents are not required to support encrypted Zip archives, some user agents will not be able to process the widget package.
A CC must inform the author if a Zip archive that contains zero file entries.
Reason: A zip archive that does not contain any files will be treated by a widget user agent as an invalid Zip
archive.
A CC must inform the author if a Zip archive that contains only folders.
Reason: A zip archive that does not contain any folders will be treated by a widget user agent as an invalid Zip
archive.
File Entries
This section relates to zip archives, as are defined in the [Widgets-P&C] specification.
A CC must verify that
each file entry uses one of the valid compression methods.
If a CC encounters a file entry that uses a compression method that is not one of the valid compression
methods, then the CC must inform the author
to recompressed the file entry using one of the valid compression
methods.
Reason: Widget user agents are only required to support the valid compression methods. If a widget user agent encounters a file entry that has been compressed with any compression method other than one of the valid compression methods, it will cause the widget engine to ignore the offending file entry or possibly treat the zip archive as an invalid widget.
A CC must inform the author of any file
entry with a value for version needed to extract that does not match a valid versions needed to extract value.
Reason: User agents are only required to support up features identified as "version 2.0" of the Zip file format. If a widget uses unsupported features, it can potentially cause the a widget user agent to either ignore the offending file entry or treat whole zip archive as an invalid widget.
Zip relative Paths
This section relates to zip relative paths, as are defined in the [Widgets-P&C] specification.
A CC must inform the author about any file entry whose file name
field does not match the production of a Zip-rel-path.
Reason: The production of a Zip relative paths is intended to provide maximum compatibility across operating system, while also retaining compatibility with IRIs.
A CC must inform the author of any Zip relative path whose length exceeds 120
bytes.
Reason: Some operating systems have a restrictions on the number of bytes a path can have on disk. Exceeding this path length can cause interoperability issues, as a widget user agent might not be able to write a file entry to disk.
A CC must inform the author of the presence of any of the forbidden
characters in a file-name.
Reason: Using forbidden
characters in a file name will cause the widget user agent to behave as if the file entry is missing from the zip archive.
A CC must inform the author of the presence of a U+0020 SPACE character at the
start or end of a file-name.
Reason: when attempting to write a file to disk, the space character may either be maintained or removed by the file system. If the space was not intentional, . Also, certain algorithms defined in the Widgets-P&C specification remove white space at the start and end zip relative paths, which means that a widget user agent to ignore a file that an author has deliberately named using a space character at either the start of the end of the file name.
A CC must inform the author of the presence of any U+002E FULL STOP at either the start or the end of
a file-name.
Reason: On some operating systems, the full stop at the end of a file name may be automatically removed by the operating system when the file is written to disk. Having a full stop at the start of a file name can potentially cause user agents to incorrectly serve
A CC must inform the author of any base-name that case-insensitively
matches any of the following strings (excluding the comma): CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$.
Reason: The strings above are reserved in Microsoft Windows-based operating systems. Attempts by a user agent to create files with such names will fail causing the user agent to ignore the offending file entry.
Widget packages
This section relates to widget packages, as are defined in the [Widgets-P&C] specification.
A CC must verify that
the widget package contains at least one start file by, firstly, checking within the configuration document for a content element that points to
a processable file within the widget package; and, secondly, checking for the presence of a default start file at the root
of the widget package and at the root of all locale
folders.
Reason: a user agent will treat a widget without a start file as an invalid widget.
a CC must inform the author when a widget package does not contain a start file.
Reason: A user
If no default icon has been included, and the CC determines that no custom icons have been declared in the configuration document, a CC must inform the author that it is desirable to
include a default icon.
Icons
This section relates to zip archives, as are defined in the [Widgets-P&C] specification.
If a CC encounters an icon in a format
other than [PNG] or [GIF89] or [GIF87], then the CC MUST inform the author other formats might not be supported by all user agents.
SVG Icons
If a CC encounters an icon in the [SVG] format, the CC may inform the
author if the icon includes script or interactive functionality.
If a CC encounters an icon in the [SVG] format, then the CC MAY inform the
author if the icon does not conform to the [SVGTiny] specification.
File Extension and Media Type
A CC MUST inform the author if a widget package is not being served from a remote
location with the valid widget media type.
For when a widget package is not served over HTTP, a CC must inform the author
if the file-extension is not a widget extension or if the widget lacks a file-extension.
Configuration Document
This section relates to zip archives, as are defined in the [Widgets-P&C] specification.
A CC must inform the author if there is no configuration document at the root of the widget package.
Reason: A widget user agent will treat a widget package without a configuration document as an invalid widget. Hence, the widget will not be able to run.
A CC must inform the author the file-name of the configuration document does not
case-sensitively match the string "config.xml" (that is, by checking for
the configuration document's file-name in other case forms.).
Reason: A widget user agents perfomr case-sensitive searchers when tyring to find a configuration document. If the file name is in the wrong case, the widget user agent will treat the file and an arbritrary file.
A CC must inform the author if the widget namespace is absent from the configuration document.
Reason: A widget user agent will treat a widget whose configuration document lacks the correct namespace as an invalid widget.
A CC must inform the author of the presence of any
elements in the configuration document outside the widget
namespace.
Reason: A widget user agent will ignore elements that are outside the widget namespace. If a widget relies on proprietary extension, then it might not work correctly across widget user agents.
A CC must inform an author if the value of the short attribute is longer in length than the text content of the name element.
A CC must inform an author if there is no name element provided for each localization for every major language.
A CC MUST inform the author if there are empty locale
folders in the widget package.
A CC MUST inform the author if the folder-name of any folder uses deprecated,
grandfathered, or redundant language tags from the IANA Language Subtag
Registry.
A CC MUST inform the author to avoid region or script subtags from the IANA Language Subtag
Registry for the names of folders.
A CC must verify each file entry by applying the rule for verifying a file
entry and inform the author if the result of applying the rule for verifying a file entry is false.
Reason: A use agent will ignore any file entry that returns false when the rule for verifying a file entry is applied. Hence, the user agent will behave as if the file entry is not present in the widget package.
A CC must validate a configuration document against
the [Widgets-Relax NG Schema] for the configuration document or a equivelent representation of the [Widgets-Relax NG Schema].
References