Conformance Registry Proposals 2008 March

From MemberWiki

Jump to: navigation, search

Contents

Introduction

This wiki page contains a strawman proposal for completing the definition of the term "OpenAjax Conformance" and addressing some of the outstanding issues with the OpenAjax Registry. This proposal will be discussed at the OpenAjax Face-to-face Meeting on March 21, 2008 in NYC.

Where we are now

We have had considerable discussion in the past on OpenAjax Conformance, which has been posted on the OpenAjax web site for 15-18 months, and long discussion about the OpenAjax Registry:

The OpenAjax Conformance Web page identifies a few unresolved questions; we have one outstanding issue with the Registry; and recent discussion has highlight a few more issues. Here are the key open issues:

  • Multiple conformance levels
    • Should we have multiple conformance levels? There has been discussion about having either 2 conformance levels (e.g., basic/partial and full) or 3 conformance levels similar to ODBC (e.g., basic, advanced, full).
  • Conformance claims on a per-spec basis
    • Should OpenAjax Conformance be something that is determined on a per-spec basis (e.g., my Ajax library is fully conformant with OpenAjax Hub 1.0) or something that is determined across all OpenAjax specs (e.g., my Ajax library is fully conformant with everything at OpenAjax Alliance as of Dec. 2008).
  • How hardcore should we be
    • Regarding the OpenAjax Registry, how hardcore should we be about allowing Ajax libraries to make claims of OpenAjax Conformance? For example, suppose a library includes backwards-compatibility features for existing customer content but that we feel are not fully consistent with our interoperability mission, should we disallow any claim of OpenAjax Conformance, or perhaps define a special conformance category (e.g., partial conformance)?
  • CSS class names and non-standard HTML attributes
    • Should the Registry list the CSS class names and non-standard HTML attributes that Ajax libraries use?
  • Policy on prefixes
    • If yes to the above question, in which cases should we condone a prefix approach as an "approved" practice?

Criteria

Here are some criteria that we might use in order to make our decisions. Note that some of the criteria conflict with other criteria.

  • Our mission is to promote industry interoperability - Our high-level mission is to do things that benefit Web developers using Ajax technologies, particularly to promote interoperability such that the Web developer is able to mix-and-match different Ajax technologies and integrate multiple Ajax technologies into the same Web page. In contrast, our mission is *not* to take ideological stands. (Our only ideology is to promote custom success with open technologies.)
  • We need to balance realism and idealism - Ideally, we could wave a magic wand and suddenly all Ajax libraries would obey our conformance rules completely and immediately, and all existing users and component developers would upgrade immediately to the newest releases of these libraries. Realistically, however, this isn't going to happen. We need to find a balance between pushing the industry towards an ideal future where Ajax products interoperate better, while recognizing real-world constraints in terms of the cost of being conformant. In particular, we want to avoid alienating big Ajax industry players because they feel we are making unreasonable requests.
  • Simplicity is good, extreme simplicity is better - We are a relatively small industry group. We don't have the bandwidth to make things complicated.

Proposals

Conformance declarations on a per-spec basis

OpenAjax Alliance has several activities at OpenAjax Alliance (Hub 1.0, Hub 1.1, Metadata, Registry, Mobile Device APIs) and it seems likely that other initiatives will be launched in the next year. All of these efforts are likely to lead to new conformance requirements.

From a simplicity perspective, my recommendation is that conformance claims are relative to particular OpenAjax specifications. For example:

  • In 2008, a new release of the "foo" Ajax library might claim Full Conformance with OpenAjax Hub 1.0 and OpenAjax Registry 1.0 (i.e., once the Registry 1.0 has been completed and approved)
  • In 2010, a new release the "foo" library might claim Full Conformance with OpenAjax Hub 1.1, OpenAjax Registry 1.2, and OpenAjax Metadata 1.1

(See below for examples where a library might be fall short of Full Conformance in some areas.)

Different sets of conformance requirements for different types of products

There are different categories of products in the Ajax ecosystem. Here are some:

  • Ajax libraries (aka toolkits)
  • Ajax IDEs
  • Ajax-powered widgets
  • Mashup tools
  • Server products with specific Ajax features (e.g., Comet servers)
  • Browsers

So far, nearly all of the conformance requirements that we have defined so far in the OpenAjax Hub 1.0 and OpenAjax Registry specifications apply to Ajax libraries. However, we expect that some of our future initiatives will produce conformance requirements to apply to other product areas. For example, OpenAjax Metadata is likely to produce some conformance requirements onto Ajax IDE products, such as a requirement that the IDE supports OpenAjax Metadata (duh!).

(Note that the existing conformance requirements in the Hub 1.0 and Registry specs already define the type of product to which the conformance statement applies. For example:

  • OpenAjax Conformance Requirement (Libraries): Prefix and Namespace - To be OpenAjax Conformant, a library MUST define its own unique prefix and namespace URI...

Two conformance levels: Full and Limited

During our discussion on the OpenAjax Registry, it has become clear that there are some interoperability guidelines that we want the industry to embrace, but it is also clear that there are real-world backwards compatibility issues facing some Ajax libraries that make it infeasible for them to achieve conformance with all of our guidelines.

We have talked about having either 3 conformance levels (e.g., basic vs advanced vs full) or 2 conformance levels (e.g., basic or partial vs full). In order to find the appropriate balance between leading the industry towards our ideals but accepting existing realities, and to keep things simple, I propose two conformance levels, full and limited:

  • Full - An Ajax product has Full Conformance if it supports all of the relevant conformance requirements defined in the given specification.
  • Limited - An Ajax product has Limited Conformance if it supports the subset of relevant conformance requirements defined in the given specification that are necessary for Limited Conformance.

For example:

  • The 2008 release of the "bar" Ajax library might claim Full Conformance with OpenAjax Hub 1.0 but only Limited Conformance with OpenAjax Registry 1.0 because it might not (yet) support our relocatable conformance requirement.

Existing conformance criteria

Here are the conformance criteria that we have so far in our various specifications, with a proposal for which ones apply to both Limited and Full, and which only apply to Full. Note that a new criterion that has been added (i.e., you must register your library).

In the table below:

  • Items that must be supported for Limited Conformance have a yellow background
  • Items that must be supported to go beyond Limited Conformance to reach Full Conformance have a green background
SpecConformance levelCriteriaDetails
Hub 1.0 Required for both Limited and Full Library Registration To be OpenAjax Conformant, libraries MUST register themselves properly via OpenAjax.registerLibrary() at the time when the <script> tag(s) that includes the given library is processed (i.e., when the JavaScript files are fetched and then parsed by the browser's JavaScript's engine). NOTE: See Hub 1.0 spec for additional detail. For example, this does not mean that every Ajax library has to bundle Hub 1.0 inside of it.
Hub 1.0 Required for both Limited and Full Read-only OpenAjax.libraries To be OpenAjax Conformant, libraries MUST treat OpenAjax.libraries as a read-only public variable.
Hub 1.0 Required for both Limited and Full Prefix and Namespace To be OpenAjax Conformant, a library MUST define its own unique prefix and namespace URI. These two values MUST be passed as parameters to OpenAjax.hub.registerLibrary() (see /member/wiki/OpenAjax_Hub_Specification_Libraries). The prefix specifies a short name for the given library and the namespace URI holds a URI reference that uniquely identifies the library. prefix and the namespace URI MUST conform to W3C rules for namespace prefixes and URI references as defined in Namespaces in XML.
Hub 1.0 Required for both Limited and Full Multiple usage To be OpenAjax Conformant, libraries MUST provide a reasonable approach to application developers for addressing the possibility that the given library might be used multiple times within the same Ajax application, such as mashups where different mashup components use the given library multiple times (either same version of the given library or different versions of the given library).
Hub 1.0 Required for both Limited and Full Verify Hub Version To be OpenAjax Conformant, libraries that require a particular version of the OpenAjax Hub MUST check that the currently installed version of the Hub matches its requirements, and if not, produce an appropriate error.
 
Registry 1.0 Required for both Limited and Full Approved entry in the OpenAjax Registry (this one doesn't actually exist yet, but needs to be added)
Registry 1.0 Required for both Limited and Full All "non-approved" globals and extensions MUST be documented To be OpenAjax Conformant, the library MUST offer developer documentation that identifies the globals, extensions, custom elements and custom attributes that might conflict with similar features from other Ajax toolkits and must document any mechanisms, if any, for disabling the potentially conflicting features, relocating these features, and/or accessing these features via "approved" Registry entries.
Registry 1.0 Required for Full All features MUST be available via "approved" Registry entries To be OpenAjax Conformant, the library MUST offer a mechanism to developers such that it is possible to use the library via APIs that are listed in the OpenAjax Registry as "approved" entries.
Registry 1.0 Required for Full All "non-approved" globals and extensions either MUST be relocatable or MUST offer a mechanism to disable To be OpenAjax Conformant, the library MUST offer a mechanism to developers such that a developer can either disable any global or extension that is not listed as “approved” in the OpenAjax Registry or control the location of where that global or extension is installed into the runtime environment.

CSS classnames, HTML attributes, and wildcard prefixes

There is an open issue regarding whether the Registry should include fields for CSS classnames and non-standard HTML attributes. The proposal is that we add 6 new fields to a library's Registry entry:

foolibrary: {
  ...,
  classnames_to_approve: [...],
  classnames_to_acknowledge: [...],
  elements_to_approve: [...],
  elements_to_acknowledge: [...],
  attributes_to_approve: [...],
  attributes_to_acknowledge: [...],
  ...
}

For HTML element extensions, here is the proposed syntax. (Note that we are using namespace prefix syntax, but that is just a notational convention and doesn't require the industry to use XML namespaces. The "html:" prefix is reserved for elements added to an HTML document and the "svg:" prefix would be reserved for elements added to an SVG document.)

html:<HTML element name>

For HTML attributes extensions, here is the proposed syntax:

html:<HTML element name>@<attribute-name>

Below is an example of a library that would qualify for Full Conformance that defines a single classname fooClass, a custom element named <fooCustomElement>, and a custom 'fooType' attribute to the DIV element, all of which are suitably prefixed with "foo" (the hypothetical prefix for this hypothetical library):

foolibrary: {
  ...,
  classnames_to_approve: ['fooClass'],
  classnames_to_acknowledge: [],
  elements_to_approve: ['html:fooCustomElement'],
  elements_to_acknowledge: [],
  attributes_to_approve: ['html:div@fooType'],
  attributes_to_acknowledge: [],
  ...
}

Furthermore:

  • Classnames, custom HTML elements and custom HTML attributes that begin with a suitable prefix (usually, the library's registered prefix) would be "approved". (And this is necessary for Full Conformance.)
  • For other (i.e., non-prefixed classnames, custom HTML elements and custom HTML attributes
    • If a library provides a mechanism to relocate or disable non-prefixed classnames, elements and attributes, then even if the default names do not include a prefix, then the library would still qualify for Full Conformance.
    • Otherwise, non-prefixed classnames, elements and HTML attributes usually would be "acknowledged" and usually map to Limited Conformance.

Regarding wildcards and JavaScript globals:

  • We would keep our existing resolution regarding wildcards and globals, where wildcard JavaScript globals usually are only "acknowledged" and not "approved"
  • However, we should add a clarification that it is still possible to claim Full Conformance if the only time you use wildcard JavaScript globals is in debug mode to facilitate more convenient debugging in an IDE. (See Registry Issue 4: Stack traces in IDEs and impact on Registry)
Personal tools