From MemberWiki

Notes:

This wiki page holds a portion of a snapshot (20081211 draft contents) of the OpenAjax Metadata 1.0 Specification. The base wiki page for this (latest) version of the draft specification is at /member/wiki/OpenAjax_Metadata_Specification.

1 Introduction

Use cases and requirements

Before developing this specification, the IDE WG at OpenAjax Alliance developed separate documents that describe some of the use cases and an initial list of requirements at:

These documents reflect some key workflows involving Ajax developer tools. Since the development of the initial list of use cases and requirements, the IDE WG has attempted to address other related scenarios, particularly those having to do with widget metadata in conjunction with mashup tools. As a result, the original set of use cases and requirements will not cover all of the target scenarios for this specification.

JON: What should we do about the additional requirements from the Gadgets TF? Perhaps ask them to add supplemental text to the above two wiki pages? Then we could simply remove the paragraph immediately above this comment.

Design goals

Useful as either a native or intermediary format

The OpenAjax Metadata file format has been designed so that products might use the format in either of two manners:

As its native format for particular operations. For example:
- An Ajax toolkit might describe its APIs and widgets using OpenAjax Metadata directly
- A mashup widget might be available on the Web, shipping with an OpenAjax Metadata file as part of the widget's package
- A tool (e.g., an IDE or mashup editor) might import OpenAjax Metadata files directly for the information it uses to populate its palettes and menus regarding information about Ajax libraries and/or Ajax widgets
As an intermediate exchange format
- An Ajax toolkit might describe its APIs and widgets in a different format, but offer a conversion utility to convert the descriptions into OpenAjax Metadata
- A mashup widget might not include an OpenAjax Metadata file within its distribution, but mashup tools that support OpenAjax Metadata might do a dynamic trancoding (e.g., using XSLT) from the widget's original format into OpenAjax Metadata
- A tool (e.g., an IDE or mashup editor) might not support OpenAjax Metadata directly, but instead might include the ability to dynamically transcode OpenAjax Metadata files into formats that they support natively

One key design goal for OpenAjax Metadata was to allow the industry to adopt these metadata standards, and realize the resulting interoperability benefits, as quickly as possible and minimizing the necessity to change existing products. Because of this, OpenAjax Metadata has been designed to maximize compatibility with features found various popular products in a manner that allows insertion of transcoder software that can map proprietary metadata formats to and from the OpenAjax Metadata standards. In some cases, this allows tools to implement support for OpenAjax Metadata within their tool and achieve indirect support for proprietary metadata formats via transcoder software (sometimes available via open source, sometimes developed within OpenAjax Alliance's open source project).

Partial support (i.e., best effort) still provides interoperability benefits

The expectation is that different products will support different subsets of OpenAjax Metadata. Some products will support a large percentage of the features, while other products will support a more restricted subset.

While it is best if a product supports as many of the features from OpenAjax Metadata as possible because that will maximize industry interoperability, OpenAjax Metadata was designed such that partial support is possible and the industry will still realize interoperability benefits in the face of partial support. For example, suppose an Ajax library documents its APIs using OpenAjax Metadata, but only includes method names (<methods>), parameter names and types (<parameters>), and return value types (<returns>), and therefore does not include various other optional information such as short descriptions (<title>), long descriptions (<description>), supplemental remarks (<remarks>), coding samples (<examples>), or references to related documentation (<seealso>). Even with only a subset of potential information, the Ajax library has provided enough critical information about its APIs that Ajax IDEs can still provide important code assist features.

Most of the metadata fields in OpenAjax Metadata are designed to be optional to both producers and consumers; however, the industry is encouraged to include as many fields as they can in order to provide maximal function to the user and to maximize interoperability.

Features

OpenAjax Metadata represents a set of industry-standard metadata defined by the OpenAjax Alliance that enhances interoperability across Ajax toolkits and Ajax products. With version 1.0, OpenAjax Alliance defines metadata for the following:

Ajax widgets - OpenAjax Metadata 1.0 defines metadata for two definitions of the term "widget":
- UI controls - Some Ajax libraries provide a set of user interface building block components such as combo boxes, menu bars, or charts
- Mashup components (aka "widgets" and "gadgets") - Mashup frameworks allow for pre-packaged mini-applications (sometimes called "widgets" or "gadgets") to be combined together within a composite application (the "mashup"), where the mashup components react to each other intelligently, such as when the user selects an address in one component which causes a different component to display an updated map that shows the given address.
Ajax APIs - OpenAjax Metadata 1.0 provides a reasonably comprehensive set of metadata that describes the runtime JavaScript APIs (e.g., classes and methods) that are available for an Ajax library.
Ajax libraries - OpenAjax Metadata 1.0 defines a handful of metadata fields for Ajax runtime libraries, much of which aligns with entries in the OpenAjax Registry.

The primary target consumers of OpenAjax Metadata 1.0 are software products. It is expected that these software products will consume and use the metadata to provide enhanced experience for users who building Ajax-powered solutions. In particular:

Mashup frameworks will use OpenAjax Metadata to use OpenAjax Metadata for widgets, such as the message types that the widget produces and consumes and the customization parameters that the widget supports
Ajax IDEs will use OpenAjax Metadata to provide the developer with (presumably automatically-generated) API documentation, intelligent code-assist, widget palettes, and widget property editors

Overview of how to provide OpenAjax Metadata for an Ajax library

Static files versus dynamic generation

OpenAjax Metadata represents XML infoset standards that promote interoperability between multiple Ajax toolkits and multiple Ajax tooling systems (such as IDEs and mashup editors). These infosets may be:

statically defined within XML files that are included within an Ajax toolkit's directory structure, or
statically defined within XML files that are provided externally to an Ajax toolkit's directory structure, or
dynamically generated by an Ajax tool via a transcoding operation

Even though there are multiple workflows for creating these XML infosets, this specification defines these XML infosets in terms of the first workflow listed above (i.e., statically deifned XML file formats that are included within an Ajax toolkit's directory structure)

Three XML file types: Widget XML, API XML, Library XML

OpenAjax Metadata files conform to file naming conventions to allow software tools to discover the metadata files through recursive directory searches starting from a single root directory. This approach allows Ajax library and widget developers flexibility in where they place OpenAjax Metadata files within their distribution.

This specification defines a file naming convention that requires that the final characters in the file name match the pattern "oam.xml". For example, widget metadata files and API metadata files either must have the exact name "oam.xml" or must have the string "oam.xml" at the end of the file name (e.g., "oam.xml", "combobox.oam.xml", "calendar_oam.xml" or "ZZZoam.xml"). 2008-07-29 Draft Consensus: Shorted the suffix to "oam.xml". Also decided that library files must have the string "library" before "oam.xml".

Ajax libraries should include a single XML file (the "Library Metadata" file) that provides metadata about the library as a whole. Because tools often need to discover and process this file before the other metadata files, this file must have either the exact name "library.oam.xml" or must have the strong "library.oam.xml" at the end of the file name (e.g., "library.oam.xml", "xyz.library.oam.xml" or "ZZZlibrary.oam.xml"). 2008-07-29 Jon: I proposed that either "library.*" or "Library.*" were acceptable, but given our other changes, I suggest we only allow the lowercase alternative. But the WG hasn't discussed this yet.

Here are the three file types:

Metadata files whose root element is <widget> define a single widget (a "widget metadata file"). For a standalone widget that is suitable for use as a mashup component, typically there will be a single widget metadata file for the component. For Ajax toolkits that provide a set of UI Controls, there should be one widget metadata file for each UI control. The widget metadata files may be available within the Ajax toolkit distribution or provided separately. If the widget metadata files are included within the Ajax toolkit distribution, the files may be located anywhere within the directory structure for the toolkit, under the expectation that tools will recursively search and discover the various *oam.xml metadata files by examining the directory structure.
Metadata files whose root element is <api> defines a set of JavaScript APIs provided by an Ajax toolkit ("API metadata files"). Ajax libraries may have any number of API metadata files. The API metadata files may be available within the Ajax toolkit distribution or provided separately. If the API metadata files are included within the Ajax toolkit distribution, the files may be located anywhere within the directory structure for the toolkit, under the expectation that tools will recursively search and discover the various *oam.xml metadata files by examining the directory structure.
Metadata files whose root element is <library> and whose file name ends with the string "library.oam.xml" (a "library metadata file") define global metadata about an Ajax library, where some of that metadata overlaps with similar information within the OpenAjax Registry. A toolkit should have a single such library metadata file. The library metadata file may be available within the Ajax toolkit distribution or provided separately. If the library metadata file is included within the Ajax toolkit distribution, the file may be located anywhere within the directory structure for the toolkit, under the expectation that tools will recursively search and discover the *library.oam.xml library metadata file by examining the directory structure.

Examples

(not yet written - need to include some sample metadata for each of the different XML files we are defining)

OpenAjax Conformance

OpenAjax Conformance is a general term defined at the OpenAjax Alliance Web site () that defines requirements on various aspects of Ajax application development in order to promote interoperability and openness in the Ajax ecosystem and the ability to integrate multiple Ajax technologies within the same Web application.

The OpenAjax Alliance recommends that Web developers and IT professionals demand OpenAjax Conformance as an industry requirement from its Ajax technology providers. By requiring OpenAjax Conformance, customers gain confidence in their technology and product choices and realize benefits in terms of the ability to integrate Ajax technologies from multiple suppliers, ability to change suppliers at reduced costs, and increased certainty that their suppliers are adopting industry best practices.

The primary focus of this specification is on Ajax libraries and Ajax developer tools, such as IDEs and mashup frameworks. This specification includes various OpenAjax Conformance requirements for libraries and tools. For a library or tool to be OpenAjax Conformant, it MUST support all of the relevant conformance requirements included in this specification.

Conformance requirements appear in this specification using the following format:

OpenAjax Conformance Requirement (<category>): <name>

Subsequent text explains conformance requirement <name>, which applies to category <category>, where : <category> might be library or application.

General notes about the OpenAjax Metadata XML grammar

(presumably there will be multiple subsections ultimately, but for now, we only talk about plural elements)

Plural and singular elements

OpenAjax Metadata defines many plural elements (i.e., elements whose tagname ends with an "s"), such as <classes>, <methods>, <properties> and <topics>. For each of these plural elements, there are corresponding singular elements (i.e., elements whose tagname does not end in an "s" but share the same tagname root, such as <class>, <method>, <property> and <topic>

Plural elements are an optional structuring convenience that allow the metadata author to group a collection of similar elements under a single parent. For example, suppose an API metadata file contains two class definitions. Either of the following three approaches are valid according to the OpenAjax Metadata language schema:

Example #1: Two <class> elements within a parent <classes> element

<api>
  <classes>
    <class name="foo">...</class>
    <class name="bar">...</class>
  </classes>
</api>

Example #2: Two <class> elements without using a parent <classes> element

<api ...>
  <class name="foo">...</class>
  <class name="bar">...</class>
</api>

Example #3: It is technically possible to use both approaches at the same time and still have a metadata file that is valid according to the language schema; however, this approach should be avoided, and instead you should use either of the above approaches:

<api ...>
  <classes>
    <class name="foo">...</class>
  </classes>
  <class name="bar">...</class>      <!-- This is considered bad practice -->
</api>

User agents MUST process all singular elements that are located at valid locations within the metadata file. The two valid locations for singular elements are:

As child elements of their corresponding plural element (where the plural element is itself located in a valid position within the file). For example, user agents must process all <class> that are children of a <classes> child which itself is a child of an <api> element.
As singular elements at the same location in the file as where the corresponding plural element is allowed. For example, user agents must process all <class> that are children of an <api> element.

Furthermore, user agents MUST NOT process any singular elements that are located elsewhere in the metadata file because these elements are not valid according to the language schema.

Versioning requirements

(not yet written JON: are there issues about different versions of the metadata? If not, then we don't need this section)

Reference implementation and test suite

(not yet written - JON: this section probably needs to be renamed - purpose of section is to reference the accompanying open source project)

Future versions and compatibility

(not yet written - below are some initial sketches)

It is expected that:

Future versions of OpenAjax Metadata will support additional metadata fields to promote greater levels of interoperability
Future version of OpenAjax Metadata will be backwards compatible with this version

Future versions of this specification might add new metadata fields or new values for existing fields. Because of this, to prevent future compatibility problems, implementations of the Hub MUST NOT define extension features to the OpenAjax Metadata file formats within any of the OpenAjax XML namespaces. Extensions MUST be associated with a different XML namespace.

Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Terminology

(not yet written)

OpenAjax Metadata 20081211 Specification Introduction