From MemberWiki

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.

Chapter 13: Plural and Singular Elements

Introduction

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 is a corresponding singular element (i.e., an element whose tagname does not end in "s" but shares the same tagname root, such as <class>, <method>, <property> or <topic>).

Plural elements are an optional structuring convenience that allows metadata authors 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 approaches is 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>

It is technically possible to use both approaches at the same time (including one class definition inside a parent <classes> element and the other outside it) 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 one the above approaches.

A third possibility is to use multiple, optionally named, <classes> elements:

<api>
  <classes name="foogroup">
    <class name="foo1">...</class>
    <class name="foo2">...</class>
  </classes>
  <classes name="bargroup">
    <class name="bar1">...</class>
    <class name="bar2">...</class>
  </classes>
</api>

Developer tools 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, developer tools MUST process all <class> elements that are children of a <classes> element which 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, developer tools MUST process all <class> elements that are children of an <api> element.

Furthermore, developer tools MUST NOT process any singular elements that appear in locations that are not valid according to the language schema.

<aliases>

The <aliases> element holds zero or more <alias> child elements.

Schema

aliases_element = element aliases {
  aliases_content  &  aliases_attributes  &  foreign_nodes
}
aliases_content = (
  descriptive_elements  &
  alias_element*
)
aliases_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <alias>

Attribute summary

<ancestors>

The <ancestors> element holds zero or more <ancestor> child elements.

Schema

ancestors_element = element ancestors {
  ancestors_content  &  ancestors_attributes  &  foreign_nodes
}
ancestors_content = (
  descriptive_elements  &  
  ancestor_element*
)
ancestors_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <ancestor>

Attribute summary

<authors>

The <authors> element holds zero or more <author> child elements.

Schema

authors_element = element authors {
  authors_content  &  authors_attributes  &  foreign_nodes
}
authors_content = (
  descriptive_elements_no_authors  &  
  author_element*
)
authors_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <author>

Attribute summary

<categories>

The <categories> element holds zero or more <category> child elements.

Schema

categories_element = element categories {
  categories_content  &  categories_attributes  &  foreign_nodes
}
categories_content = (
  descriptive_elements  &  
  category_element*
)
categories_attributes = ( 
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <category>

Attribute summary

<childProperties>

Defined in the Properties chapter.

<classes>

The <classes> element holds zero or more <class> child elements.

Schema

classes_element = element classes {
  classes_content  &  classes_attributes  &  foreign_nodes
}
classes_content = (
  descriptive_elements  &  
  class_element*
)
classes_attributes = (
  name?  &  
  pattern_attributes  
)

Child content

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

• descriptive_elements such as <description> and <example>
• <class>

Attribute summary

<configs>

The <configs> element holds zero or more <config> child elements.

Schema

configs_element = element configs {
  configs_content  &  configs_attributes  &  foreign_nodes
}
configs_content = (
  descriptive_elements  &  
  config_element*
)
configs_attributes = (
  name?   
)

Child content

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

• descriptive_elements such as <description> and <example>
• <config>

Attribute summary

<contents>

The <contents> element holds zero or more <content> child elements.

Schema

contents_element = element contents {
  contents_content  &  contents_attributes  &  foreign_nodes
}
contents_content = (
  descriptive_elements  &  
  content_element*
)
contents_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <content>

Attribute summary

<constructors>

The <constructors> element holds zero or more <constructor> child elements.

Schema

constructors_element = element constructors {
  constructors_content  &  constructors_attributes  &  foreign_nodes
}
constructors_content = (
  descriptive_elements  &  
  constructor_element*
)
constructors_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <constructor>

Attribute summary

<enums>

The <enums> element holds zero or more <enum> child elements.

Schema

enums_element = element enums {
  enums_content  &  enums_attributes  &  foreign_nodes
}
enums_content = (
  descriptive_elements  &  
  enum_element*
)
enums_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <enum>

Attribute summary

<events>

The <events> element holds zero or more <event> child elements.

Schema

events_element = element events {
  events_content  &  events_attributes  &  foreign_nodes
}
events_content = (
  descriptive_elements  &  
  event_element*
)
events_attributes = (
  name?  &  registerCallbackPattern?  &  unregisterCallbackPattern?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <event>

Attribute summary

<examples>

The <examples> element holds zero or more <example> child elements.

Schema

examples_element = element examples {
    examples_content  &  examples_attributes  &  foreign_nodes
}
examples_content = (
  descriptive_elements_no_examples  &  
  example_element*
)
examples_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <example>

Attribute summary

<exceptions>

The <exceptions> element holds zero or more <exception> child elements.

Schema

exceptions_element = element exceptions {
  exceptions_content  &  exceptions_attributes  &  foreign_nodes
}
exceptions_content = (
  descriptive_elements  &  
  exception_element*
)
exceptions_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <exception>

Attribute summary

<icons>

The <icons> element holds zero or more <icon> child elements.

Schema

icons_element = element icons {
  icons_content  &  icons_attributes  &  foreign_nodes
}
icons_content = (
  descriptive_elements  &  
  icon_element*
)
icons_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <icon>
• <icon>

Attribute summary

<interfaces>

The <interfaces> element holds zero or more <interface> child elements.

Schema

interfaces_element = element interfaces {
  interfaces_content  &  interfaces_attributes  &  foreign_nodes
}
interfaces_content = (
  descriptive_elements  &  
  interface_element*
)
interfaces_attributes = (
  name?  &  
  pattern_attributes  
)

Child content

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

• descriptive_elements such as <description> and <example>
• <interface>

Attribute summary

<javascripts>

The <javascripts> element holds zero or more <javascript> child elements.

Schema

javascripts_element = element javascripts {
  javascripts_content  &  javascripts_attributes  &  foreign_nodes
}
javascripts_content = (
  descriptive_elements  &  
  javascript_element*
)
javascripts_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <javascript>

Attribute summary

<libraries>

The <libraries> element holds zero or more <library> child elements.

Schema

libraries_element = element libraries {
  libraries_content  &  libraries_attributes  &  foreign_nodes
}
libraries_content = (
  descriptive_elements  &  
  library_element*
)
libraries_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <library>

Attribute summary

<methods>

The <methods> element holds zero or more <method> child elements.

Schema

methods_element = element methods {
  methods_content  &  methods_attributes  &  foreign_nodes
}
methods_content = (
  descriptive_elements  &  
  method_element*
)
methods_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <method>

Attribute summary

<mixes>

The <mixes> element holds zero or more <mix> child elements.

Schema

mixes_element = element mixes {
  mixes_content  &  mixes_attributes  &  foreign_nodes
}
mixes_content = (
  descriptive_elements  &  
  mix_element*
)
mixes_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <mix>

Attribute summary

<mixins>

The <mixins> element holds zero or more <mixin> child elements.

Schema

mixins_element = element mixins {
  mixins_content  &  mixins_attributes  &  foreign_nodes
}
mixins_content = (
  descriptive_elements  &  
  mixin_element*
)
mixins_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <mixin>

Attribute summary

<namespaces>

The <namespaces> element holds zero or more <namespace> child elements.

Schema

namespaces_element = element namespaces {
  namespaces_content  &  namespaces_attributes  &  foreign_nodes
}
namespaces_content = (
  descriptive_elements  &  
  namespace_element*
)
namespaces_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <namespace>

Attribute summary

<options>

Defined in the Datatypes chapter.

<parameters>

The <parameters> element holds zero or more <parameter> child elements.

Schema

parameters_element = element parameters {
  parameters_content  &  parameters_attributes  &  foreign_nodes
}
parameters_content = (
  descriptive_elements  &  
  parameter_element*
)
parameters_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <parameter>

Attribute summary

<properties>

Defined in the Properties chapter.

<references>

The <references> element holds zero or more <reference> child elements.

Schema

references_element = element references {
  references_content  &  references_attributes  &  foreign_nodes
}
references_content = (
  descriptive_elements_no_references  &  
  reference_element*
)
references_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <reference>
• <reference>

Attribute summary

<requires>

The <requires> element holds zero or more <require>, <library> and <libraries> child elements.

Schema

requires_element = element requires {
    requires_content  &  requires_attributes  &  foreign_nodes
}
requires_content = (
  descriptive_elements  &  
  library_element*  &  libraries_element*  &  require_element*
)
requires_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <require>
• <library> or <libraries>

Attribute summary

<returnTypes>

The <returnTypes> element holds zero or more <returnType> child elements.

Schema

returnTypes_element = element returnTypes {
  returnTypes_content  &  returnTypes_attributes  &  foreign_nodes
}
returnTypes_content = (
  descriptive_elements  &  
  returnType_element*
)
returnTypes_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <returnType>

Attribute summary

<singletons>

The <singletons> element holds zero or more <singleton> child elements.

Schema

singletons_element = element singletons {
  singletons_content  &  singletons_attributes  &  foreign_nodes
}
singletons_content = (
  descriptive_elements  &  
  singleton_element*
)
singletons_attributes = (
  name?  &  
  pattern_attributes  
)

Child content

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

• descriptive_elements such as <description> and <example>
• <singleton>

Attribute summary

<topics>

The <topics> element holds zero or more <topic> child elements.

Schema

topics_element = element topics {
    topics_content  &  topics_attributes  &  foreign_nodes
}
topics_content = (
  descriptive_elements  &  
  topic_element*
)
topics_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <topic>

Attribute summary

<userAgents>

The <userAgents> element holds zero or more <userAgent> child elements.

Schema

userAgents_element = element userAgents {
  userAgents_content  &  userAgents_attributes  &  foreign_nodes
}
userAgents_content = (
  descriptive_elements  &  
  userAgent_element*
)
userAgents_attributes = (
  name?
)

Child content

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

• descriptive_elements such as <description> and <example>
• <userAgent>

Attribute summary