OpenAjax Metadata 1.0 Specification Introduction
From MemberWiki
NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.
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 and use the information in them to populate Ajax-related palettes and menus.
- As an intermediate exchange format. For example:
- An Ajax toolkit might describe its APIs and widgets in a different format, but offer a 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 transcoding (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.
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 for industry interoperability if a product supports all of the features from OpenAjax Metadata, 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>). Even though it does not include various other optional information such as long description (<description>), short description (<shortDescription>), supplemental remarks (<remarks>), coding samples (<example>), or references to related documentation (<reference>), 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 it can in order to maximize usefulness and 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, which include:
- UI controls - The user interface components—such as combo boxes, menu bars, charts, and calendars—that some Ajax libraries provide.
- Mashup components - Pre-packaged mini-applications (sometimes called "widgets" or "gadgets") that can 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, and a different component displays an updated map for that address.
- Ajax APIs - 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, particularly Web page developer tools targeting Ajax developers. It is expected that these software products will consume and use the metadata to provide an enhanced experience for users building Ajax-powered solutions. In particular:
- Ajax IDEs will likely use OpenAjax Metadata to provide developers with 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
This specification defines a file naming convention that requires that the final characters in the file name match the pattern "oam.xml". 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. Developer tools MAY 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. Developer tools MAY 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.
Security considerations
Developer tools and OpenAjax Widget developers SHOULD include appropriate protection against cross-site scripting (XSS) vulnerabilities, particularly in the case of JavaScript logic that executes using a browser engine. The OpenAjax Alliance white paper "Ajax and Mashup Security" is one Web resource among many that describe XSS protection techniques. For OpenAjax Widget developers, techniques include entity encoding (e.g., replace characters such as <
and >
with <
and >
), whitelist filtering (i.e., only pass through markup that conforms to a particular pattern), and use of the entityencode()
construct for any @@propname@@
or ##localizationkey##
constructs into which executable content might be injected. For example, instead of @@propname@@
, the metadata file might include @@entityencode(propname)@@
, and instead of ##localizationkey##
, the metadata file might include ##entityencode(localizationkey)##
.
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 versions 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.
OpenAjax Metadata Schema and Schema Snippets Using Relax NG Compact Syntax
The XML grammar for OpenAjax Metadata (OAM) uses Relax NG Compact Syntax (RNC) for its formal definition. The schema allows custom attributes and elements provided that the extensions are defined in a different XML namespace.
OpenAjax Alliance provides an OpenAjax Metadata XML validator tool on its Web site where the community can determine if their OAM files are constructed correctly. The various RNC files that make up the language schema are maintained at the OpenAjax Alliance open source project.
For each element definition within this specification, the write-up includes the RNC snippet that corresponds to that element. For example, the detailed definition of the <description> element includes the following RNC snippet:
description_element = element description { description_content & description_attributes & foreign_attributes } description_content = ( plain_text_or_html ) description_attributes = ( lang? & locid? & type? )
Most of the schema snippets used in this specification follow the pattern shown above:
- The first section of the schema snippet (lines 1-3 in the example above) defines the XML element. The schema snippet shown above defines the <description> element. Within the first section (line 2 in the example above) are references the two other schema sections that immediately follow: one for the element's child content (
description_content
) and one for the element's attributes (description_attributes
). - The second section (lines 4-6 in the example above) defines the allowable child content. In the example above, the child content is
plain_text_or_html
, which is defined elsewhere in the specification. - The third section (lines 7-9) defines the allowable attributes. In the example above, three attributes are defined:
lang
,locid
andtype
. The question mark after each attribute indicates that each of these attributes is optional. - The first section of the schema (line 2) usually also includes a reference to either
foreign_attributes
orforeign_nodes
. These define the XML namespace extensibility options that are permitted on the given element.-
foreign_attributes
indicates that the element may contain custom attributes so long as those attributes have an XML namespace and that namespace is different than the OpenAjax Metadata namespace (i.e., different thanhttp://openajax.org/metadata
) -
foreign_nodes
indicates that both custom elements (using a different namespace thanhttp://openajax.org/metadata
) and custom attributes are allowed
-
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 begins 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. - 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.
- The type is an ECMAScript datatype, such as
- 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
The following are definitions for terms used within this document:
- Current container object
- In this specification, the term "current container object" is the nearest ancestor element that is not one of the OpenAjax Metadata plural elements. To illustrate, in the following example, the current container object for the
<method>
element is the<class>
element (its direct parent) and the current container object for the<parameter>
element is the<method>
element (its nearest ancestor that is not a plural):
<class name="abc"> <method name="dosomething"...> <parameters> <parameter name="param1".../> </parameters> </method> </class>
- 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).
- Infoset
- The information in a well-formed XML document. The term "infoset" is defined by the W3C XML Information Set specification.
- 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 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 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.
- Transclusion
- The inclusion of part of a document into another document by reference. See Wikipedia description of transclusion.