From MemberWiki

(Redirected from OpenAjax Metadata Specification Introduction)

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

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

Chapter 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 assembly tools. As a result, the original set of use cases and requirements will not cover all of the target scenarios for this specification.

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 developer tool (e.g., an IDE or mashup assembly application) 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 instead a mashup tool might perform dynamic trancoding (e.g., using XSLT) from the widget's original format into an OpenAjax Widget
- A developer tool 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 is 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 developer 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 (<method>), parameter names and types (<parameter>), and return value types (<returnType>), and therefore does not include various other optional information such as long description (<description>), short description (<shortDescription>), supplemental remarks (<remarks>), coding samples (<examples>), or references to related documentation (<reference>). 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 defines standard metadata that describes the runtime JavaScript APIs (e.g., classes and methods) that are available for an Ajax library.

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:

Ajax IDEs will use OpenAjax API Metadata to provide the developer with (presumably automatically-generated) API documentation, intelligent code-assist, widget palettes, and widget property editors.
Mashup assembly applications will use OpenAjax Widget Metadata for definitions of widget user interface, widget APIs, identification of pub/sub messages to which the widget publishes or subscribes, and identification of shared properties.

File naming conventions

OpenAjax Metadata files must conform to file naming conventions. This naming convention allows developer tools to discover the metadata files through recursive filename-match searches starting from a single root directory. This naming convention allows Ajax library and widget developers flexibility how they organize and store their metadata files.

In some scenarios, the metadata files will be stored within an Ajax library's directory tree, whereas in other scenarios, the metadata files will be stored outside of the files that it describes. This specification does not mandate any rules about how metadata files are organized or where the metadata files should be located relative to the Ajax libraries or widgets that the metdata files describe, and treats the process by which developer tools discover and import OpenAjax Metadata files to be a product-specific implementation issue.

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").

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 developer 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 developer tools will recursively search and discover the various *oam.xml metadata files by examining the directory structure.

Relative URIs

Some attributes in the OpenAjax Metadata Specification take URIs as their values. Unless otherwise stated in other parts of this specification, if a relative URI is specified, then the base URI is the URI of the folder that contains the current OpenAjax metadata file.

Conforming developer tools are NOT REQUIRED to support the XML Base Recommendation; therefore, OpenAjax Metadata files SHOULD NOT include the xml:base attribute.

2009-06-14 Jon: Added the above section per old editorial notes in other parts of the spec.

Reference implementation, test suite and validator tool

OpenAjax Alliance maintains an open source reference implementation and test suite for various technologies relevant to OpenAjax Metadata 1.0 at http://openajaxallianc.sourceforge.net. At this time, the open source project provides:

A formal language schema, expressed in RelaxNG Compact Syntax
A client-side JavaScript implementation of an OpenAjax Widget loader
Sample OpenAjax widgets
A mashup authoring environment that includes the OpenAjax Widget loader (see previous bullet) and uses OpenAjax Hub 2.0 as its secure mashup framework, where widgets are isolated from each other into secure sandboxes.
API metadata converters, such as a tool that converts JavaScript files with JSDoc inline comments into the OpenAjax API Metadata.

OpenAjax Alliance also maintains a Web-based validation tool so that the community can validate their metadata files against the language schema.

Future versions and compatibility

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, developer tools 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.

JSDoc Conventions

Some of the APIs defined within this specification use JSDoc commenting conventions to describe various details about a particular API, such as a method's parameters, return values and exceptions. Here is an example that illustrates the use JSDoc commenting conventions:

/**
 * Returns the ID string corresponding to this widget
 * (i.e., the value of the __WID__ substitution variable).
 * 
 * @returns 
 * 		ID string corresponding to this widget
 * @type {String}
 */
<Widget>.OpenAjax.getId = function() {};

The JSDoc code above identifies the method name (<Widget>.OpenAjax.getId), a description for this method (i.e., "Returns the ID string corresponding..."), and the value returned by the method (i.e., a JavaScript String object).

This specification uses the following subset of JSDoc: (Note: This subset is designed to align with the JSDoc syntax defined by JSDoc Toolkit (http://code.google.com/p/jsdoc-toolkit/.)

At the bottom of the API definition is the name of the specified interface, in the form of a JavaScript function definition. The function definitions show the list of parameters to the function, with an empty function body (i.e., the function body is {}).
Above the function definition are JavaScript comments that conform to JSDoc document commenting conventions, where the comment begins with the characters /** and ends with the characters */
Any textual comments that do not begin with a JSDoc tag (i.e., a keyword that begin with the @ character, such as @param) represent free-form descriptions of the given API
This chapter uses the following JSDoc tags:
- @param {type} name Description - Specifies a parameter to a function.
- @returns Description - Specifies the value returned by a function.
  - @type {type} - An @type immediately after an @returns specifies the datatype of the return value.
- @see Description - Specifies a reference to other documentation.
- @throws {type} Description - Specifies an exception that a function might throw.
Notes:
- The type is an ECMAScript datatype, such as {Object} or {String}. A value of {*} indicates any JavaScript value particular function parameter.
- The Description is free-form text that provides a textual description. The Description might appear on the same line of the tag and/or might appear on one or more immediately following lines.
Optional parameters are defined by surrounding the parameter name in square brackets, as in @param {*} [subscriberData].

When parameters are objects, such as the params object required by OpenAjax.hub.Container:

@param {Object} params

the properties of these objects are specified using separate @param tags:

@param {String} params.IframeContainer.tunnelURI

Terminology

2009-06-15 Jon: What other terms do we need?

The following are definitions for terms used within this document:

Developer tool

In this specification, the term "developer tool" represents the generalized notion of any software application that provides productivity acceleration features for the purpose of creating Ajax-powered Web pages and that implements the features described in this specification. This specification focuses on the following two particular types of developer tools (although it is expected that the metadata features described in this specification will apply to other tool scenarios):

IDEs
Mashup assembly applications

IDE

An IDE ("Integrated Development Environment") is a software product that helps developers create applications. An IDE might include any of the following features: source code editing, intelligent code assist, syntax highlighting, debugging, file navigators, class navigators, and visual authoring (e.g., dragging widgets from a palette onto a canvas).

JSON-serializable value

A JSON-serializable value is a JavaScript data value (e.g., Boolean, Number, Array, Object, etc.) that can be converted, without data loss, to and from one of the following:

For JavaScript objects: JSON object notation
For JavaScript arrays: JSON array notation
For primitive data types: into a JavaScript literal (string, number, true, false, or null).

In particular, any Javascript value that is itself of type Function, or that is an Array or Object value that includes a Function within itself, is not JSON-serializable.

See JSON specification.

Library (in the context of "Ajax library" or "JavaScript library")

A collection of client-side JavaScript runtime logic that provides useful features for Ajax developers.

Mashup

An application that uses the "Web Runtime" (i.e., the browser engine that runs HTML/Ajax applications) and combines data from more than one source into a composite application.

Mashup assembly application

Mashup assembly applications 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.

OpenAjax Widgets

An "OpenAjax Widget" is a user interface control or a mashup component (aka "widget" or "gadget") that conforms to the Widget Metadata sections of the this specification (i.e., the OpenAjax Metadata Specification).

Property (in the context of the <property> element)

A "property" is a general concept that represents a variable on an object. In OpenAjax Widgets, the <property> element defines configurable widget properties, particularly those properties that might appear in a property editor dialog. In OpenAjax Metadata for JavaScript APIs, the <property> element defines JavaScript object properties.

Toolkit (in the context of "Ajax toolkit" or "JavaScript toolkit")

A collection of technologies, products, and other supporting materials such as documentation, that help a customer to produce an Ajax-based solution. In some scenarios, a toolkit might just be a library, but in other cases will consist of some combination of libraries, server components, authoring components, associated utility software, and supporting materials such as documentation.

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

OpenAjax Metadata 1.0 Specification Introduction