XTCE12 — Missed documentation updates from BitBucket subcommittee effort

Several issues have noted that the XTCE 1.0 and 1.1 annotations have been lacking. Many of the updates were performed in conjunction with other issues that were more topic oriented to a particular area. In this, many elements/attributes/types did not require attention and as a result, did not get an opportunity to get annotation updates. In addition, some areas that were touched were done prior to reconciling the annotation updates.

Propose to include many annotation updates (part 1)

This resolution includes the first set of annotation updates that covers most of the elements/attributes in the first few levels of depth in the XML. It is not proposed as a comprehensive and complete set, but appears to be ready for use/evaluation/voting.

The list below is the typical method of showing the before and after of the XSD by type definition in the XSD. Each type is separated by a textual divider to make it easier to review.

================================================================================
xs:schema element contents
================================================================================

The root xml element in the schema is named schema. Immediately following is an "import" element and an "annotation" element. Propose to enhance the documentation here from:

<annotation>
<documentation xml:lang="en">This is the master schema for the OMG Space Domain Task Force XML Telemetric and Command data Exchange (XTCE) format.</documentation>
</annotation>

To:

<annotation>
<documentation xml:lang="en">This XML Schema Definition (XSD) defines syntax with concrete semantics for describing space or remote device telemetry and commanding in a platform and program independent manner.</documentation>
</annotation>

================================================================================
SpaceSystem element contents
================================================================================

The first xs:element xml element in the schema is for the root SpaceSystem. Propose to enhance the documentation from:

<annotation>
<documentation xml:lang="en">The ROOT Element</documentation>
</annotation>

To:

<annotation>
<documentation xml:lang="en">The top-level SpaceSystem is the root element for the set of metadata necessary to monitor and command a space device, such as a satellite. A SpaceSystem defines a namespace. Metadata areas include: packets/minor frames layout, telemetry, calibration, alarm, algorithms, streams and commands. A SpaceSystem may have child SpaceSystems, forming a SpaceSystem tree. See SpaceSystemType.</documentation>
</annotation>

================================================================================
SpaceSystemType contents
================================================================================

<complexType name="SpaceSystemType" mixed="false">
<annotation>
<documentation xml:lang="en">SpaceSystem is a collection of SpaceSystem(s) including space assets, ground assets, multi-satellite systems and sub-systems. A SpaceSystem is the root element for the set of data necessary to monitor and command an arbitrary space device - this includes the binary decomposition the data streams going into and out of a device.</documentation>
</annotation>
<complexContent>
<extension base="xtce:NameDescriptionType">
<sequence>
<element name="Header" type="xtce:HeaderType" minOccurs="0"/>
<element name="TelemetryMetaData" type="xtce:TelemetryMetaDataType" minOccurs="0"/>
<element name="CommandMetaData" type="xtce:CommandMetaDataType" minOccurs="0"/>
<element name="ServiceSet" type="xtce:ServiceSetType" minOccurs="0"/>
<element ref="xtce:SpaceSystem" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="operationalStatus" type="token" use="optional"/>
<attribute ref="xml:base"/>
</extension>
</complexContent>
</complexType>

<complexType name="SpaceSystemType" mixed="false">
<annotation>
<documentation xml:lang="en">SpaceSystem is a collection of SpaceSystem(s) including space assets, ground assets, multi-satellite systems and sub-systems. A SpaceSystem is the root element for the set of data necessary to monitor and command an arbitrary space device - this includes the binary decomposition the data streams going into and out of a device.</documentation>
</annotation>
<complexContent>
<extension base="xtce:NameDescriptionType">
<sequence>
<element name="Header" type="xtce:HeaderType" minOccurs="0">
<annotation>
<documentation xml:lang="en">The Header element contains optional descriptive information about this SpaceSystem or the document as a whole when specified at the root SpaceSystem.</documentation>
</annotation>
</element>
<element name="TelemetryMetaData" type="xtce:TelemetryMetaDataType" minOccurs="0">
<annotation>
<documentation xml:lang="en">This element contains descriptions of the telemetry created on the space asset/device and sent to other data consumers.</documentation>
</annotation>
</element>
<element name="CommandMetaData" type="xtce:CommandMetaDataType" minOccurs="0">
<annotation>
<documentation xml:lang="en">This element contains descriptions of the commands and their associated constraints and verifications that can be sent to the space asset/device.</documentation>
</annotation>
</element>
<element name="ServiceSet" type="xtce:ServiceSetType" minOccurs="0"/>
<element ref="xtce:SpaceSystem" minOccurs="0" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Additional SpaceSystem elements may be used like namespaces to segregate portions of the space asset/device into convenient groupings or may be used to specialize a product line generic SpaceSystem to a specific asset instance.</documentation>
</annotation>
</element>
</sequence>
<attribute name="operationalStatus" type="token" use="optional">
<annotation>
<documentation xml:lang="en">Optional descriptive attribute for document owner convenience.</documentation>
</annotation>
</attribute>
<attribute ref="xml:base"/>
</extension>
</complexContent>
</complexType>

================================================================================
HeaderType contents
================================================================================

<complexType name="HeaderType">
<annotation>
<documentation xml:lang="en">Schema for a Header record. A header contains general information about the system or subsystem.</documentation>
</annotation>
<sequence>
<element name="AuthorSet" type="xtce:AuthorSetType" minOccurs="0"/>
<element name="NoteSet" type="xtce:NoteSetType" minOccurs="0"/>
<element name="HistorySet" type="xtce:HistorySetType" minOccurs="0"/>
</sequence>
<attribute name="version" type="string"/>
<attribute name="date" type="string"/>
<attribute name="classification" type="string" default="NotClassified"/>
<attribute name="classificationInstructions" type="string"/>
<attribute name="validationStatus" type="xtce:ValidationStatusType" use="required"/>
</complexType>

<complexType name="HeaderType">
<annotation>
<documentation xml:lang="en">Schema for a Header record. A header contains general information about the system or subsystem.</documentation>
</annotation>
<sequence>
<element name="AuthorSet" type="xtce:AuthorSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">The AuthorSet contains optional contact information for this document.</documentation>
</annotation>
</element>
<element name="NoteSet" type="xtce:NoteSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">The NoteSet contains optional technical information related to the content of this document.</documentation>
</annotation>
</element>
<element name="HistorySet" type="xtce:HistorySetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">The HistorySet contains optional evolutionary information for data contained in this document.</documentation>
</annotation>
</element>
</sequence>
<attribute name="version" type="string">
<annotation>
<documentation xml:lang="en">This attribute contains an optional version descriptor for this document.</documentation>
</annotation>
</attribute>
<attribute name="date" type="string">
<annotation>
<documentation xml:lang="en">This attribute contains an optional date to be associated with this document.</documentation>
</annotation>
</attribute>
<attribute name="classification" type="string" default="NotClassified">
<annotation>
<documentation xml:lang="en">This attribute contains optional classification status for use by programs for which that is applicable.</documentation>
</annotation>
</attribute>
<attribute name="classificationInstructions" type="string">
<annotation>
<documentation xml:lang="en">This attribute contains an optional additional instructions attribute to be interpreted by programs that use this attribute.</documentation>
</annotation>
</attribute>
<attribute name="validationStatus" type="xtce:ValidationStatusType" use="required">
<annotation>
<documentation xml:lang="en">This attribute contains a flag describing the state of this document in the evolution of the project using it.</documentation>
</annotation>
</attribute>
</complexType>

================================================================================
AuthorSetType contents
================================================================================

<complexType name="AuthorSetType">
<sequence>
<element name="Author" type="xtce:AuthorType" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>

<complexType name="AuthorSetType">
<annotation>
<documentation xml:lang="en">Describe an unordered collection of authors. See AuthorType.</documentation>
</annotation>
<sequence>
<element name="Author" type="xtce:AuthorType" minOccurs="0" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Contains information about an author, maintainer, or data source regarding this document.</documentation>
</annotation>
</element>
</sequence>
</complexType>

================================================================================
AuthorType contents
================================================================================

<simpleType name="AuthorType">
<restriction base="string"/>
</simpleType>

<simpleType name="AuthorType">
<annotation>
<documentation xml:lang="en">Type definition that describes the format of the contents of the Author element.</documentation>
</annotation>
<restriction base="string"/>
</simpleType>

================================================================================
HistorySetType contents
================================================================================

<complexType name="HistorySetType">
<sequence>
<element name="History" type="xtce:HistoryType" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>

<complexType name="HistorySetType">
<annotation>
<documentation xml:lang="en">Describe an unordered collection of History elements. Usage is user defined. See HistoryType.</documentation>
</annotation>
<sequence>
<element name="History" type="xtce:HistoryType" minOccurs="0" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Contains a history record related to the evolution of this document.</documentation>
</annotation>
</element>
</sequence>
</complexType>

================================================================================
NoteSetType contents
================================================================================

<complexType name="NoteSetType">
<sequence>
<element name="Note" type="xtce:NoteType" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>

<complexType name="NoteSetType">
<annotation>
<documentation xml:lang="en">Contains an unordered collection of Notes. Usage is user defined. See NoteType.</documentation>
</annotation>
<sequence>
<element name="Note" type="xtce:NoteType" minOccurs="0" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Contains a program defined technical note regarding this document.</documentation>
</annotation>
</element>
</sequence>
</complexType>

================================================================================
AliasSetType contents
================================================================================

<complexType name="AliasSetType">
<annotation>
<documentation xml:lang="en">Contains an unordered collection of Alias's</documentation>
</annotation>
<sequence>
<element name="Alias" type="xtce:AliasType" maxOccurs="unbounded"/>
</sequence>
</complexType>

<complexType name="AliasSetType">
<annotation>
<documentation xml:lang="en">Contains an unordered collection of Alias elements to describe alternate names or IDs for this named item.</documentation>
<appinfo>Applications should enforce uniqueness of individual nameSpace attribute values. Aliases are usually unique within the same nameSpace attribute value, depending on the physical meaning of that nameSpace. There are some cases where Alias values can be duplicated in a single nameSpace value.</appinfo>
</annotation>
<sequence>
<element name="Alias" type="xtce:AliasType" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">An alternate name, ID number, and sometimes flight software variable name in the code for this item.</documentation>
</annotation>
</element>
</sequence>
</complexType>

================================================================================
AliasType contents
================================================================================

<complexType name="AliasType">
<annotation>
<documentation xml:lang="en">Used to contain an alias (alternate) name or ID for the object. For example, a parameter may have a mnemonic, an on-board id, and special IDs used by various ground software applications; all of these are alias's. Some ground system processing equipment has some severe naming restrictions on parameters (e.g., names must less then 12 characters, single case or integral id's only); their alias's provide a means of capturing each name in a "nameSpace".</documentation>
</annotation>
<attribute name="nameSpace" type="string" use="required"/>
<attribute name="alias" type="string" use="required"/>
</complexType>

<complexType name="AliasType">
<annotation>
<documentation xml:lang="en">Used to contain an alias (alternate) name or ID for the object. For example, a parameter may have a mnemonic, an on-board id, and special IDs used by various ground software applications; all of these are alias's. Some ground system processing equipment has some severe naming restrictions on parameters (e.g., names must less then 12 characters, single case or integral id's only); their alias's provide a means of capturing each name in a "nameSpace". Note: the name is not reference-able (it cannot be used in a name reference substituting for the name of the item of interest). See NameDescriptionType.</documentation>
</annotation>
<attribute name="nameSpace" type="string" use="required">
<annotation>
<documentation xml:lang="en">Aliases should be grouped together in a "namespace" so that they can be switched in and out of data extractions. The namespace generally identifies the purpose of the alternate name, whether for software variable names, additional operator names, or whatever the purpose.</documentation>
</annotation>
</attribute>
<attribute name="alias" type="string" use="required">
<annotation>
<documentation xml:lang="en">The alternate name or ID to use. The alias does not have the restrictions that apply to name attributes. This is useful for capturing legacy identifiers for systems with unusual naming conventions. It is also useful for capturing variable names in software, amongst other things.</documentation>
</annotation>
</attribute>
</complexType>

================================================================================
AncillaryDataSetType contents
================================================================================

<complexType name="AncillaryDataSetType">
<sequence>
<element name="AncillaryData" type="xtce:AncillaryDataType" maxOccurs="unbounded"/>
</sequence>
</complexType>

<complexType name="AncillaryDataSetType">
<annotation>
<documentation xml:lang="en">Describe an unordered collection of ancillary data. AncillaryData elements capture platform/program/implementation specific data about the parent element object that is non-standard and would not fit into the schema. See AncillaryDataType.</documentation>
</annotation>
<sequence>
<element name="AncillaryData" type="xtce:AncillaryDataType" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Optional list of AncillaryData elements associated with this item.</documentation>
</annotation>
</element>
</sequence>
</complexType>

================================================================================
AncillaryDataType contents
================================================================================

<complexType name="AncillaryDataType">
<annotation>
<documentation xml:lang="en">Use for any other data associated with each named object. May be used to include administrative data (e.g., version, CM or tags) or potentially any MIME type. Data may be included or given as an href. </documentation>
</annotation>
<simpleContent>
<extension base="string">
<attribute name="name" type="string" use="required"/>
<attribute name="mimeType" type="string" default="text/plain"/>
<attribute name="href" type="anyURI"/>
</extension>
</simpleContent>
</complexType>

<complexType name="AncillaryDataType">
<annotation>
<documentation xml:lang="en">Use for any other data associated with a named item. May be used to include administrative data (e.g., version, CM or tags) or potentially any MIME type. Data may be included or given as an href.</documentation>
</annotation>
<simpleContent>
<extension base="string">
<attribute name="name" type="string" use="required">
<annotation>
<documentation xml:lang="en">Identifier for this Ancillary Data characteristic, feature, or data.</documentation>
</annotation>
</attribute>
<attribute name="mimeType" type="string" default="text/plain">
<annotation>
<documentation xml:lang="en">Optional text encoding method for the element text content of this element. The default is "text/plain".</documentation>
</annotation>
</attribute>
<attribute name="href" type="anyURI">
<annotation>
<documentation xml:lang="en">Optional Uniform Resource Identifier for this characteristic, feature, or data.</documentation>
</annotation>
</attribute>
</extension>
</simpleContent>
</complexType>

================================================================================
DescriptionType contents
================================================================================

<complexType name="DescriptionType" abstract="true">
<annotation>
<documentation xml:lang="en">An abstract type definition used as the base for NameDescriptionType or OptionalNameDescriptionType. The short description is intended to be used for quick "memory jogger" descriptions of the object. </documentation>
</annotation>
<sequence>
<element name="LongDescription" type="xtce:LongDescriptionType" minOccurs="0"/>
<element name="AliasSet" type="xtce:AliasSetType" minOccurs="0"/>
<element name="AncillaryDataSet" type="xtce:AncillaryDataSetType" minOccurs="0"/>
</sequence>
<attribute name="shortDescription" type="xtce:ShortDescriptionType" use="optional"/>
</complexType>

<complexType name="DescriptionType" abstract="true">
<annotation>
<documentation xml:lang="en">Defines an abstract schema type used as basis for NameDescriptionType and OptionalNameDescriptionType, includes an attribute for a short description and an element for a longer unbounded description. This type also provides alias set and ancillary data set See AliasSetType and AncillaryDataSetType.</documentation>
</annotation>
<sequence>
<element name="LongDescription" type="xtce:LongDescriptionType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Optional long form description to be used for explanatory descriptions of this item and may include HTML markup using CDATA. Long Descriptions are of unbounded length.</documentation>
</annotation>
</element>
<element name="AliasSet" type="xtce:AliasSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Used to contain an alias (alternate) name or ID for this item. See AliasSetType for additional explanation.</documentation>
</annotation>
</element>
<element name="AncillaryDataSet" type="xtce:AncillaryDataSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Use for any non-standard data associated with this named item. See AncillaryDataSetType for additional explanation.</documentation>
</annotation>
</element>
</sequence>
<attribute name="shortDescription" type="xtce:ShortDescriptionType" use="optional">
<annotation>
<documentation xml:lang="en">Optional short description to be used for explanation of this item. It is recommended that the short description be kept under 80 characters in length.</documentation>
</annotation>
</attribute>
</complexType>

================================================================================
NameDescriptionType contents
================================================================================

<complexType name="NameDescriptionType">
<annotation>
<documentation xml:lang="en">The type definition used by most elements that require a name with optional descriptions. </documentation>
</annotation>
<complexContent>
<extension base="xtce:DescriptionType">
<attribute name="name" type="xtce:NameType" use="required"/>
</extension>
</complexContent>
</complexType>

<complexType name="NameDescriptionType">
<annotation>
<documentation xml:lang="en">Defines a base schema type definition used by many other schema types throughout schema. Use it to describe a name with optional descriptions, aliases, and ancillary data. See NameType, LongDescriptionType, ShortDescriptionType, AliasSetType and AncillaryDataSetType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:DescriptionType">
<attribute name="name" type="xtce:NameType" use="required">
<annotation>
<documentation xml:lang="en">The name of this defined item. See NameType for restriction information.</documentation>
</annotation>
</attribute>
</extension>
</complexContent>
</complexType>

================================================================================
OptionalNameDescriptionType contents - core type special case of NameDescriptionType
================================================================================

<complexType name="OptionalNameDescriptionType">
<annotation>
<documentation xml:lang="en">The type definition used by most elements that have an optional name with optional descriptions. </documentation>
</annotation>
<complexContent>
<extension base="xtce:DescriptionType">
<attribute name="name" type="xtce:NameType" use="optional"/>
</extension>
</complexContent>
</complexType>

<complexType name="OptionalNameDescriptionType">
<annotation>
<documentation xml:lang="en">The type definition used by most elements that have an optional name with optional descriptions.</documentation>
</annotation>
<complexContent>
<extension base="xtce:DescriptionType">
<attribute name="name" type="xtce:NameType" use="optional">
<annotation>
<documentation xml:lang="en">Optional name of this defined item. See NameType for restriction information.</documentation>
</annotation>
</attribute>
</extension>
</complexContent>
</complexType>

================================================================================
CommandMetaDataType contents
================================================================================

<complexType name="CommandMetaDataType" mixed="false">
<annotation>
<documentation xml:lang="en">Command Meta Data contains information about commands</documentation>
</annotation>
<sequence>
<element name="ParameterTypeSet" type="xtce:ParameterTypeSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A list of parameter types</documentation>
</annotation>
</element>
<element name="ParameterSet" type="xtce:ParameterSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Parameters referenced by MetaCommands. This Parameter Set is located here so that MetaCommand data can be built independently of TelemetryMetaData.</documentation>
</annotation>
</element>
<element name="ArgumentTypeSet" type="xtce:ArgumentTypeSetType" minOccurs="0"/>
<element name="MetaCommandSet" type="xtce:MetaCommandSetType" minOccurs="0"/>
<element name="CommandContainerSet" type="xtce:CommandContainerSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">The Command Container defines the construction of a Command.</documentation>
</annotation>
</element>
<element name="StreamSet" type="xtce:StreamSetType" minOccurs="0"/>
<element name="AlgorithmSet" type="xtce:AlgorithmSetType" minOccurs="0"/>
</sequence>
</complexType>

<complexType name="CommandMetaDataType" mixed="false">
<annotation>
<documentation xml:lang="en">Describe command related metadata. Items defined in this area may refer to items defined in TelemetryMetaData. See TelemetryMetaDataType.</documentation>
</annotation>
<sequence>
<element name="ParameterTypeSet" type="xtce:ParameterTypeSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A list of parameter types.</documentation>
</annotation>
</element>
<element name="ParameterSet" type="xtce:ParameterSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Parameters referenced by MetaCommands. This Parameter Set is located here so that MetaCommand data can be built independently of TelemetryMetaData.</documentation>
</annotation>
</element>
<element name="ArgumentTypeSet" type="xtce:ArgumentTypeSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A list of argument types. MetaCommand definitions can contain arguments and parameters. Arguments are user provided to the specific command definition. Parameters are provided/calculated/determined by the software creating the command instance. As a result, arguments contain separate type information. In some cases, arguments have different descriptive characteristics.</documentation>
</annotation>
</element>
<element name="MetaCommandSet" type="xtce:MetaCommandSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A list of command definitions with their arguments, parameters, and container encoding descriptions.</documentation>
</annotation>
</element>
<element name="CommandContainerSet" type="xtce:CommandContainerSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Similar to the ContainerSet for telemetry, the CommandContainerSet contains containers that can be referenced/shared by MetaCommand definitions.</documentation>
</annotation>
</element>
<element name="StreamSet" type="xtce:StreamSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Contains an unordered set of Streams.</documentation>
</annotation>
</element>
<element name="AlgorithmSet" type="xtce:AlgorithmSetType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Contains an unordered set of Algorithms.</documentation>
</annotation>
</element>
</sequence>
</complexType>