From MemberWiki

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

Chapter 9: Descriptive elements and attributes

Introduction

This chapter describes the various elements and attributes that provide descriptive metadata. The sections below describe:

• descriptive_elements: a collection of descriptive elements that are available as child elements for many elements in the OpenAjax Metadata language
• <aboutMe> element: supplemental text information about an author
• <author> element: information about one or more authors
• <description> element: text description
• <directoryTitle> element: short text string that can be displayed within a widget directory or catalog
• <example> element: one or more illustrative examples
• <icon> element: a small image (child element to <widget>)
• <license> element: textual information about licensing
• <quote> element: a quotation that a person associates with his signature
• <reference> element: indicates a reference to other related documentation
• <remarks> element: supplemental textual comment beyond the information found in the <description>
• <shortDescription> elements: short text description (presumably shorter than <description>)
• <title> element: short descriptive text suitable as a label or title bar
• 'type' attribute: indicates whether an element's textual content is plain text (i.e., text/plain) or HTML rich text (i.e., text/html)

Subsequent sections describe the above attributes and elements.

descriptive_elements

The following is the schema definition for descriptive_elements, which is referenced by other elements defined in other chapters:

descriptive_elements = (
  authors_element*  &  author_element*  &  description_element?  &
  examples_element*  &  example_element*  &  remarks_element?  &
  references_element*  &  reference_element*  &  shortDescription_element?  &  
  title_element?
)

<aboutMe>

The <aboutMe> is a child element of <author> and can be used to provide arbitrary supplemental textual information about the author beyond the information found in the <author> element's other attributes and sub-elements.

Schema

aboutMe_element = element aboutMe {
  aboutMe_content  &  aboutMe_attributes  &  foreign_attributes
}
aboutMe_content = (
  plain_text_or_html
)
aboutMe_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <aboutMe> element can contain either plain text or HTML markup.

Attribute summary

Additional information

Here is an example:

<widget xmlns="http://openajax.org/metadata">
  <authors>
    <author name="Charlie Chaplin">
      <aboutMe>I have many skills</aboutMe>
    </author>
  </authors>
  ...
</widget>

<author>

The <author> element describes one of the authors of the given APIs. Supplemental information about the author beyond what is expressed in the various attributes can be supplied in either the <aboutMe> or <quote> sub-elements.

Schema

author_element = element author {
  author_content  &  author_attributes  &  foreign_attributes
}
author_content = (
  aboutMe_element?  &  quote_element?
)
author_attributes = (
  email?  &  location?  &  name?  &  organization?  &  
  photo?  &  website?
)

Child content

The <author> element might contain any of the following sub-elements:

• <aboutMe>
• <quote>

Attribute summary

<description>

The <description> element provides a textual description for the <description> element's parent.

Schema

description_element = element description {
  description_content  &  description_attributes  &  foreign_attributes
}
description_content = (
  plain_text_or_html
)
description_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <description> element can contain either plain text or HTML markup.

Attribute summary

Additional information

For example, in the following case:

<widget ...>
   <description>Bar chart widget with configurable title and axis labels.</description>
   ...
</widget>

the <description> element provides a textual description for the <widget> element (its parent).

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" that is found later in this chapter.

If the <description> element is not specified on a given parent element, but other similar descriptive metadata is provided (e.g., <shortDescription> or <title>), then developer tools SHOULD use the value of the other descriptive metadata as the value for the (missing) <description> element.

Attributes described elsewhere:

• The lang and locid attributes are defined in the Localization chapter.

<directoryTitle>

Schema

directoryTitle_element = element directoryTitle {
  directoryTitle_content  &  directoryTitle_attributes  &  foreign_attributes
}
directoryTitle_content = (
  text
)
directoryTitle_attributes = ( 
  lang?  &  locid? 
)

Child content

The <directoryTitle> element contains a short text string (plain text) that can be used as a widget name when displayed within a widget directory or catalog.

Attribute summary

<example>

The <example> element provides a single illustrative example (often, source code) for the <example> element's parent element (or, when the <example> is a child of an <examples> element, its grandparent element).

Schema

example_element = element example {
  example_content  &  example_attributes  &  foreign_attributes
}
example_content = (
  plain_text_or_html
)
example_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <example> element can contain either plain text or HTML markup.

Attribute summary

Additional information

An example:

<api ... >
  ...
  <method name="setStateColor">    
    <example>

<![CDATA[
var a = myobject.setStateColor(2008,"California","blue");    
]]> 
      
    </example>
    ...
  </method>
...
</widget>

<icon>

The <icon> element specifies the URI for a small graphical image (i.e., an icon) for a <widget> that is its direct parent element (or, when the <icon> is a child of an <icons> element, its grandparent element).

Schema

icon_element = element icon {
  icon_content  &  icon_attributes  &  foreign_attributes
}
icon_content = (
  empty
)
icon_attributes = ( 
  width?  &  height?  &  src 
)

Child content

The <icon> element must be an empty element (i.e., no child content).

Attribute summary

Additional information

An example:

<widget ... >
  ...
  <icons>                
    <icon width="36" height="36" src="lightwindow_pi.png" />
    <icon width="16" height="16" src="lightwindow.png" />
  </icons>
...
</widget>

The default values for the width and height attributes are implementation-dependent.

Developer tools MAY use the intrinsic width and height of the referenced image file instead of the values provided by the width and height attributes.

When there are multiple <icon> elements within a metadata file, the developer tool MAY use whichever icon is the best match for the intended use.

2009-06-25 Jon: Cleaned up this section per long-ago resolutions. There was an action to compare against <icon> element for W3C Widgets. Their element is pretty much the same as ours.

<license>

The <license> element describes license information about this widget. The textual content might contain the actual license text or might include a URL where the license text can be found.

Schema

license_element = element license {
  license_content  &  license_attributes  &  foreign_attributes
}
license_content = (
  plain_text_or_html
)
license_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <license> element can contain either plain text or HTML markup.

Attribute summary

<quote>

The <quote> provides either plain text or HTML formatted content that provides a quotation that a person associates with his signature.

Schema

quote_element = element quote {
  quote_content  &  quote_attributes  &  foreign_attributes
}
quote_content = (
  plain_text_or_html
)
quote_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <quote> element can contain either plain text or HTML markup.

Attribute summary

<reference>

The <reference> element indicates a reference to other related documentation. The content of the element provides the text that describes the reference.

Schema

reference_element = element reference {
  reference_content  &  reference_attributes  &  foreign_attributes
}
reference_content = (
  plain_text_or_html
)
reference_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <reference> element can contain either plain text or HTML markup.

Attribute summary

<remarks>

The <remarks> element provides optional supplemental textual comments about the <remarks> element's parent element. It is assumed that the primary descriptive text is contained in the <description> element.

Schema

remarks_element = element remarks {
  remarks_content  &  remarks_attributes  &  foreign_attributes
}
remarks_content = (
  plain_text_or_html
)
remarks_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <remarks> element can contain either plain text or HTML markup.

Attribute summary

<shortDescription>

The <shortDescription> element provides a short textual description for the <description> element's parent.

Schema

shortDescription_element = element shortDescription {
  shortDescription_content  &  shortDescription_attributes  &  foreign_attributes
}
shortDescription_content = (
  plain_text_or_html
)
shortDescription_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <shortDescription> element can contain either plain text or HTML markup.

Attribute summary

Additional information

For example, in the following case:

<widget ...>
   <description>
     Bar chart widget with configurable title and axis labels.
     The title can be up to 3 lines of text.
     The vertical axis label can be rendered on its side or as stacked characters.
   </description>
   <shortDescription>Bar chart widget with configurable title and axis labels.</shortDescription>
   ...
</widget>

the <description> element provides the longer textual description for the <widget> element (its parent), and the <shortDescription> element provides the shorter description.

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" that is found later in this chapter.

If the <shortDescription> element is not specified on a given parent element, but other similar descriptive metadata is provided (e.g., <title> or <description>), then developer tools SHOULD use the value of the other descriptive metadata as the value for the (missing) <shortDescription> element.

<title>

The <title> element contains short descriptive text suitable as a label or title bar.

Schema

title_element = element title {
  title_content  &  title_attributes  &  foreign_attributes
}
title_content = (
  plain_text_or_html
)
title_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <title> element can contain either plain text or HTML markup.

Attribute summary

Content that can be plain text or HTML

Several elements within the OpenAjax Metadata specification, such as the <description> element, allow content that can be either "plain text or HTML". Each of these elements has a type attribute that specifies a MIME type for the element's content.

This specification defines behavior for two possible values for the type attribute:

• text/plain: (the default) for plain text that SHOULD be presented "as is" to the user
• text/html: for rich text expressed as an HTML snippet that SHOULD be suitable as the innerHTML of an HTML <div> element and that SHOULD be processed and rendered by an engine that can parse and render HTML

text/plain

If the type attribute has the value text/plain or is unspecified, then the content of the element SHOULD be presented "as is" to the user. For example:

<description>A small amount of text (i.e., "plain text")</description>

SHOULD result in the user seeing the following:

A small amount of text (i.e., "plain text")

With text/plain, newlines and white space SHOULD be preserved. For example:

<description>This is line 1
 This is line 2
   This is line 3</description>

SHOULD result in the user seeing the following:

This is line 1
 This is line 2
   This is line 3

Because the OpenAjax Metadata file is expressed in XML, the metadata author SHOULD take appropriate measures if the plain text content contains any of the special literal markup characters that have special meaning to an XML parser, such as "&", "<" and ">". If the plain text content uses any of these characters, then the content SHOULD be placed inside of a CDATA construct. For example, if you want a description that will present this string to the user: "where N is an integer & N > 0 & N < 20", then you could use a CDATA construct as follows:

<description>
<![CDATA[
where N is an integer & N > 0 & N < 20
]]>
</description>

One possible detailed processing model for plain text content is as follows:

1. From the original source metadata file, extract the complete string of characters between the start element tag and the end element tag, including any white space and newlines. For example, with the <description type="text/plain"> element, extract all characters between the <description> start tag and the </description> end tag. For <description type="text/plain">Here is the description </description>, the extracted text would be "Here is the description ".
2. Strip out all CDATA constructs. For example, with <description& type="text/plain">PPP <![CDATA[-bbb-]]> QQQ</description>, the result text string would be "PPP -bbb- QQQ".
3. If rendering the text using an HTML engine, perform the following substitutions:
   • '&' (ampersand) characters are converted into '&'
   • '"' (double quote) characters are converted into '"'
   • ''' (single quote) characters are converted into '''
   • '<' (less than) characters are converted into '<'
   • '>' (greater than) characters are converted into '>'
   • Newlines are converted into '<br />'
   • White space characters become ' '

text/html

If the type attribute has the value text/html or is unspecified, then the content of the element SHOULD be an HTML snippet that is presented to the user as rich text.

Here are examples using the <description type="text/html"> element:

[1] <description type="text/html">Text that is to be rendered as HTML but contains no markup</description>

[2] <description type="text/html">A small of amount of text with <b>limited use</b> of HTML markup</description>

[3] <description type="text/html">
      <p>This is an example that shows two HTML paragraphs</p>
      <p>This is the second paragraph</p>
    </description>

[4] <description type="text/html">
    <![CDATA[
      <p>Some HTML text that is not well-formed XML</p>
      <ul>
        <li>A bullet without a proper end element
        <li>A second bullet
      </ul>
    ]]>
    </description>

• Example [1] SHOULD be rendered as "Text that is to be rendered as HTML but contains no markup".
• Example [2] SHOULD render the words "limited use" using boldface.
• Example [3] SHOULD render as two paragraphs.
• Example [4] illustrates the use of the CDATA construct to bracket content that is not proper XML (because the </li> end tags are missing) and SHOULD render as a paragraph followed by two bulleted items.

Developer tools SHOULD support the ability to render formatted HTML content as rich text; however, if unable to render HTML rich text, the developer tool SHOULD still render the content somehow, such as stripping out the markup. For example:

<description type="html">
this word is <b>bold</b>.
</description>

which might render as (after stripping out the markup):

this word is bold.

or alternatively the developer tool might simply render the original markup exactly as is:

this word is <b>bold</b>.

(Note: Metadata authors may want to format their content such that the content is still readable if a developer tool chooses to strip out the markup.)

Because the HTML content is meant to be suitable for inclusion within an HTML <div> element, the content SHOULD not contain any of the following HTML elements: <base>, <body>, <iframe>, <frame>, <frameset>, <head>, <html>, or <title>, and most of the time also SHOULD not contain <link>, <meta>, <style>, or <script>.

Metadata authors need to be aware that different developer tools will support different subsets of HTML. Therefore, for common cases, metadata authors are advised to use a simple common subset of HTML for any rich text content to maximize portability.

Developer tools SHOULD prevent take appropriate measures to prevent malicious HTML content from executing unwanted JavaScript logic, such as cross-site scripting (XSS) attacks due to embedded JavaScript logic secretly embedded within the content. (See discussion of cross-site scripting at: [1]). A recommended approach is to adopt a "whitelist" approach which filters the HTML content to allow only a known subset of any elements and attributes and remove any elements and attributes that are not included in the whitelist.

Note that there are several advanced ways to include executable content within HTML, such as

<a href="javascript:alert('hi')">press me</a>

so it usually makes sense to do careful research and look for off-the-shelf software that addresses all possible cases for the whitelisting.

The detailed processing model for the HTML descriptive content is as follows:

1. From the original source metadata file, extract the complete string of characters between the start element tag and the end element tag, including any white space and newlines. For example, with the <description type="text/html"> element, extract all characters between the <description> start tag and the </description> end tag. For <description type="text/html">Here is the description </description>, the extracted text would be "Here is the description ".
2. Strip out all CDATA constructs. For example, with <description& type="text/html"gt;PPP <[CDATA[-bbb-]]> QQQ</description>, the result text string would be "PPP -bbb- QQQ".
3. Take appropriate measures such as whitelisting to filter out potentially malicious HTML constructs.
4. Render the result of the previous steps using an engine capable of parsing and rendering rich text HTML content.