From MemberWiki

Notes:

• 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 is the proposed way for the IDE WG to edit this specification:

• All textual content that has normal text properties (i.e., black) and has no colored status text (e.g., does not say Tentatively approved or Approved) represents preliminary proposed text that requires further review and discussion.
• Members of OpenAjax Alliance are encourage to place inline comments into this document, preferably by identifying your name or initials before your comment, such as "Mary: This bullet should be moved above previous bullet".
• When an item has been deemed complete by the WG chair due to committee consensus, then the annotation Approved will be placed at the end of an approved block of text (e.g., paragraph or bullet). Note that during the development phase of this specification, the group can change its mind and "un-approve" text that was previously approved.
• When an item has been deemed near complete by the WG chair due to committee consensus, but further review is necessary (e.g., review final wording), then the annotation Tentatively approved or DRAFT CONSENSUS will be placed at the end of given block of text (e.g., paragraph or bullet).

9 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.

Subsequent sections describe the relevant attributes and elements.

Element and attribute collections defined in this chapter

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?
)

Elements defined in this chapter

<available>

available_element = element available {
  available_content  &  available_attributes  &  foreign_attributes
}
available_content = (
  plain_text_or_html
)
available_attributes = (
  locid?  &  type?  &  version?
)

The <available> element describes not yet written

The content of the <available> element provides an optional supplemental text explanation that explains details about the availability of this API.

The version attribute specifies the version number range for the product (e.g., Ajax library or widget) for which the parent element is available. (See the section titled "Version number attributes" below.) 2008-06-05 DRAFT CONSENSUS

The type attribute specifies a MIME type that specifies the type of the content. For further details, see the section titled "Content that can be plain text or HTML" in the "Descriptive elements and attributes" chapter.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

<deprecated>

deprecated_element = element deprecated {
  deprecated_content  &  deprecated_attributes  &  foreign_attributes
}
deprecated_content = (
  plain_text_or_html
)
deprecated_attributes = (
  locid?  &  type?  &  version?
)

The <deprecated> element describes not yet written

The content of the <deprecated> element provides an optional supplemental text explanation that explains details about the deprecation of this API.

The version attribute specifies the version numbers for the product (e.g., Ajax library or widget) when the parent element became deprecated. (See the section titled "Version number attributes" below.) 2008-06-05 DRAFT CONSENSUS.

The type attribute specifies a MIME type that specifies the type of the content. For further details, see the section titled "Content that can be plain text or HTML" in the "Descriptive elements and attributes" chapter.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

<useragent>

useragent_element = element useragent {
  useragent_content  &  useragent_attributes  &  foreign_attributes
}
useragent_content = (
  plain_text_or_html
)
useragent_attributes = (
  locid?  &  os?  & osVersion?  &  platform?  &  version?  &  type?
)

The <useragent> element describes not yet written, but in most cases is referring to the browser

The os attribute not yet written, but in most cases is refers to the operating system

The osVersion attribute specifies the version number range for the given operating system in which the parent element is supported. (See the section titled "Version number attributes" below.) 2008-06-05 DRAFT CONSENSUS

The platform attribute not yet written, but in most cases is refers to the browser

The version attribute specifies the version number range for the given user agent in which the parent element is supported. (See the section titled "Version number attributes" below.) 2008-06-05 DRAFT CONSENSUS

OK to allow plain_text_and_html here?

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

<useragents>

useragents_element = element useragents {
  useragents_content  &  useragents_attributes  &  foreign_nodes
}
useragents_content = (
  useragent_element*
)
useragents_attributes = ( empty )

The <useragents> element holds zero or more <useragent> child elements.

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

Version number attributes

2008-06-10 DRAFT CONSENSUS

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 in the form of #[.#]*, 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 user agent 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: