From MemberWiki

This wiki page holds a portion of the latest internal editorial draft for what ultimately will become the OpenAjax Metadata 1.0 Specification. The base wiki page for this (latest) version of the draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification. Here are the IDE WG's rules for editing this specification:

• The current working text for the specification has normal text properties (i.e., black)
• Open issues that require WG discussion are highlighted with red text
• Notes to the editor about necessary minor editorial changes are highlighted with purple text

Chapter 10: Compatibility elements and attributes

Introduction

This chapter describes the various 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. Elements and attributes described in this chapter include:

• compatibility_elements: a collection of elements that are available as child elements for many elements in the OpenAjax Metadata language
• <available> element: availability information about the parent element
• <deprecated> element: deprecation information about the parent element
• <userAgent> element: user information compatibility information about the parent element
• Version number attributes: attributes in OpenAjax Metadata take a version number, or a range of version numbers, as their values

Subsequent sections describe the above attributes and elements.

compatibility_elements

The following is the schema definition for compatibility_elements, which is referenced by other elements defined in other chapters:

compatibility_elements = (
  available_element?  &  deprecated_element?  &  userAgents_element*  &  userAgent_element*
)

<available>

The <available> element provides availability information about the 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.

Attribute summary

<deprecated>

The <deprecated> element provides deprecation information about the 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.

Attribute summary

<userAgent>

The <userAgent> element provides user agent compatibility information about the 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 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?
)

Child content

The <userAgent> element optionally can contain textual information that provides compatibility information.

Attribute summary

Version number attributes

Various attributes in OpenAjax Metadata take a version number, or a 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 <require> element: the minVersion attribute
• On the <userAgent> element: the version and osVersion attributes
• On the <widget> element: the version and spec attributes

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 range values 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:

• 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.
• If the start version number is a null, empty, or cannot be determined (e.g., the start version string begins with a non-numeric), then assume a start version number of zero.
• If the end version number is a null, empty, or cannot be determined (e.g., the end version string begins with a non-numeric), then assume an end version number of infinity.
• The default value for version number range attributes is 0 to infinity.

Version number range examples: