OpenAjax Metadata 1.0 Specification Compatibility
From MemberWiki
NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.
Contents |
Chapter 10: Compatibility elements and attributes
Introduction
This chapter describes the elements and attributes that provide metadata having to do with feature compatibility, such as which versions of which user agents (e.g., browsers) are required for a feature to work, or the versions of an Ajax library when a given feature became available or was deprecated.
This chapter defines the following attribute collection:
- compatibility_elements: a collection of elements that are available as child elements for many elements in the OpenAjax Metadata language
and the following elements:
- <available> element: availability information about the parent element
- <deprecated> element: deprecation information about the parent element
- <userAgent> element: user agent compatibility information about the parent element
- Version number attributes: attributes in OpenAjax Metadata that take a version number, or a range of version numbers, as their values
compatibility_elements
The following is the schema definition for compatibility_elements
, which is referenced by elements defined in other chapters:
compatibility_elements = ( available_element? & deprecated_element? & userAgents_element* & userAgent_element* )
<available>
The <available>
element provides availability information about its parent element. Two forms of compatibility information can be provided:
- 'version' attribute - this provides the version number range for the widget or Ajax library within which the given feature is available
- free form text - the child content of the
<available>
element can provide a textual description that contains supplemental details.
Schema
available_element = element available { available_content & available_attributes & foreign_attributes } available_content = ( plain_text_or_html ) available_attributes = ( lang? & locid? & type? & version? )
Child content
The content of the <available>
element provides optional supplemental text about the availability of this API or widget.
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
version | Version number range for the product (e.g., Ajax library or widget) for which the parent element is available. See the Version number attributes section below. | String | no | See the Version number attributes section below. |
lang | Identifies the natural or formal language for the content. Defined in Localization chapter. | |||
locid | Lookup key into the message bundle files. Defined in Localization chapter. | |||
type | Whether the content is plain text or HTML markup. Defined in Plain text or HTML section. |
<deprecated>
The <deprecated>
element provides deprecation information about its parent element. Two forms of compatibility information can be provided:
- 'version' attribute - this provides the version number range for the widget or Ajax library within which the given feature has been deprecated
- free form text - the child content of the
<deprecated>
element can provide a textual description that contains supplemental details.
Schema
deprecated_element = element deprecated { deprecated_content & deprecated_attributes & foreign_attributes } deprecated_content = ( plain_text_or_html ) deprecated_attributes = ( lang? & locid? & type? & version? )
Child content
The content of the <deprecated>
element provides optional supplemental text about the deprecation of this API or widget.
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
version | Version number range for the product (e.g., Ajax library or widget) for which the parent element has been deprecated. See the Version number attributes section below. | String | no | See the Version number attributes section below. |
lang | Identifies the natural or formal language for the content. Defined in Localization chapter. | |||
locid | Lookup key into the message bundle files. Defined in Localization chapter. | |||
type | Whether the content is plain text or HTML markup. Defined in Plain text or HTML section. |
<userAgent>
The <userAgent>
element provides user agent compatibility information about its parent element (or grandparent element if the parent element is a <userAgents>
element). In browser scenarios, the "user agent" is the Web browser.
Two pairs of attributes can be provided to describe user agent compatibility information:
- 'platform' and 'version' attributes - these attributes describe user agent compatibility (independent of operating system)
- 'os' and 'osVersion' attributes - these attributes describe operating system compatibility
Child content
The content of the <userAgent>
element provides optional supplemental text about user agent or operating system compatibility.
Schema
userAgent_element = element userAgent { userAgent_content & userAgent_attributes & foreign_attributes } userAgent_content = ( plain_text_or_html ) userAgent_attributes = ( lang? & locid? & os? & osVersion? & platform & version? & type? )
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
platform | Name of a user agent (typically, a Web browser). | String | yes | none |
version | Version number range for the user agent. See the Version number attributes section below. | String | no | See the Version number attributes section below. |
os | Name of the operating system to which this compatibility information applies. | String | no | none |
version | Version number range for the operating system. See the Version number attributes section below. | String | no | See the Version number attributes section below. |
lang | Identifies the natural or formal language for the content. Defined in Localization chapter. | |||
locid | Lookup key into the message bundle files. Defined in Localization chapter. | |||
type | Whether the content is plain text or HTML markup. Defined in Plain text or HTML section. |
Version number attributes
Various attributes in OpenAjax Metadata take a version number or range of version numbers as their values:
- On the
<api>
element: theversion
andspec
attributes - On the
<available>
element: theversion
attribute - On the
<deprecated>
element: theversion
attribute - On the
<userAgent>
element: theversion
andosVersion
attributes - On the
<widget>
element: theversion
andspec
attributes - On the
<library>
element: theversion
attribute.
Version number values are expressed using the same syntax for version numbers as used by the OpenAjax.hub.registerLibrary()
method within the OpenAjax Hub, where the version is of the form #[.#]*
, such as "1", "1.1" or "1.20.2", followed by an optional arbitrary string (e.g., "1.20.2Beta" or "1.1 Build 543"). The normative description for the syntax for version numbers can be found at: [1].
Version number ranges are expressed as two version number values separated by a colon character. For example, "1.1:2.5
" indicates the range from version 1.1 to version 2.5. Version number ranges are inclusive (in this example, starting with version 1.1 and continuing up to and including version 2.5).
The processing model for version number ranges is that the developer tool searches from the start of the string for the first colon character. The substring before this character is the start version number string and the substring after this character is the end version string.
Notes about version number ranges:
- The default value for version number range attributes is 0 to infinity.
- If the start version number is null, empty, or cannot be determined (e.g., the start version string begins with a non-numeric character), then assume a start version number of zero.
- If the end version number is null, empty, or cannot be determined (e.g., the end version string begins with a non-numeric character), then assume an end version number of infinity.
- If an attribute specifies a version number range and only a single version number is provided (i.e., there is no colon character), then the value represents the start version and the range is from this start version to infinity.
Most version
attributes take a range of values.
Exceptions include:
- The
version
attribute on the <library> element, which takes a single value that specifies the actual version number of the library. - The
spec
attributes on the<widget>
and<api>
elements also take single values that specify the version number of the Open Ajax Metadata Specification on which the metadata is based, and do not represent a range.
Version number range examples:
version="1.0" | A range from version 1.0 to infinity. |
version="1.0:3.3" | A range from version 1.0 to version 3.3 (inclusive). |
version="1.0:1.0" | A range from version 1.0 to 1.0 (i.e., a single version). |
version="1.0beta:3.3alpha" | A range from version 1.0 to version 3.3 (inclusive). (The alpha strings after the version numbers are ignored for the purposes of numeric version computations.) |
version=":3.3" | A range from version 0 to version 3.3 (inclusive). |
version="" | A range from version 0 to infinity. |