OpenAjax Metadata 1.0 Specification Compatibility

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.


<--previous       contents--^       next-->


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

AttributeDescriptionTypeRequiredDefault
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

AttributeDescriptionTypeRequiredDefault
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

AttributeDescriptionTypeRequiredDefault
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: the version and spec attributes
  • On the <available> element: the version attribute
  • On the <deprecated> element: the version attribute
  • On the <userAgent> element: the version and osVersion attributes
  • On the <widget> element: the version and spec attributes
  • On the <library> element: the version 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.



<--previous       contents--^       next-->
Personal tools