Issue 8046: Specification too complex? (xtce-ftf) Source: Integral Systems (Mr. Charles Gerry Simon, gsimon@integ.com) Nature: Clarification Severity: Critical Summary: Early reviewers of the specification have consistently complained that the specification is too complex – particularly in the packaging section and that the annotations that accompany the scheme are oftentimes incomplete, contain typos, or vague. Resolution: Revised Text: Resolution: All subsequent changes have been made with simplification in mind. Packaging did have a great deal of complexity strapped onto it to accommodate a variety of special cases. Packaging was re-engineered to accommodate those special cases in an alternative model Revised Text: For simplicity, the entire Packaging section of the schema is shown <!--******** Packaging Schema --> <annotation> <documentation xml:lang="en">This schema definies the dictionary for containers, which in turn describe the physical composition of data in a communication system</documentation> </annotation> <complexType name="ContainerType" abstract="true" mixed="false"> <annotation> <documentation xml:lang="en">An abstract block of data; used as the base type for more specific container types</documentation> </annotation> <complexContent mixed="false"> <extension base="xtce:NameDescriptionType"> <sequence> <annotation> <documentation>RateInStream is used to: a) generate alarms when the Container is updated too frequently or too infrequently, b) provide some 'guidelines' for generating forward link containers, c) provide some guidelines for spacecraft simulators to generate telemetry containers. If necessary, these rates may be defined on a per stream basis.</documentation> <appinfo>The software should check that any Stream names referenced in the RateInStreamSet actually exist.</appinfo> </annotation> <element name="DefaultRateInStream" type="xtce:RateInStreamType" minOccurs="0"/> <element name="RateInStreamSet" minOccurs="0"> <complexType> <sequence> <element name="RateInStream" maxOccurs="unbounded"> <complexType> <complexContent> <extension base="xtce:RateInStreamType"> <attribute name="streamRef" type="xtce:NameReferenceType" use="required"/> </extension> </complexContent> </complexType> </element> </sequence> </complexType> </element> <element name="BinaryEncoding" type="xtce:BinaryDataEncodingType" minOccurs="0"> <annotation> <documentation>May be used to indicate error detection and correction, chage byte order, provide the size (when it can't be derived), or perform some custom processing.</documentation> </annotation> </element> </sequence> </extension> </complexContent> </complexType> <complexType name="SequenceContainerType"> <annotation> <documentation>A list of raw parameters, parameter segments, stream segments, containers, or container segments. Sequence containers may inherit from other sequence containers; when they do, the sequence in the parent SequenceContainer is 'inherited' and if the location of entries in the child sequence is not specified, it is assumed to start where the parent sequence ended. Parent sequence containers may be marked as "abstract". The idle pattern is part of any unallocated space in the Container.</documentation> </annotation> <complexContent> <extension base="xtce:ContainerType"> <sequence> <element name="EntryList" type="xtce:EntryListType"/> <element name="BaseContainer" minOccurs="0"> <complexType> <sequence> <element name="RestrictionCriteria"> <annotation> <documentation>Given that this Container is the Base container type, RestrictionCriteria lists conditions that must be true for this Container to be 'this' subContainer type. May be a simple Comparison List, a Boolean Expression, and/or in a Graph of containers established by the NextContainer</documentation> </annotation> <complexType> <complexContent> <extension base="xtce:MatchCriteriaType"> <choice> <element name="NextContainer" type="xtce:ContainerRefType" minOccurs="0"/> </choice> </extension> </complexContent> </complexType> </element> </sequence> <attribute name="containerRef" type="xtce:NameReferenceType" use="required"/> </complexType> </element> </sequence> <attribute name="abstract" type="boolean"/> <attribute name="idlePattern" type="xtce:FixedIntegerValueType" default="0x0"/> </extension> </complexContent> </complexType> <complexType name="SequenceEntryType"> <annotation> <documentation>An abstract type used by sequence containers. An entry contains a location in the container. The location may be either fixed or dynamic, absolute (to the start or end of the enclosing container, or relative (to either the previous or subsequent entry). Entries may also repeat.</documentation> </annotation> <sequence> <element name="LocationInContainerInBits" minOccurs="0"> <annotation> <documentation>If no LocationInContainer value is given, the entry is assumed to begin immediately after the previous entry.</documentation> </annotation> <complexType> <complexContent> <extension base="xtce:IntegerValueType"> <attribute name="referenceLocation" default="previousEntry"> <annotation> <documentation>The location may be relative to the start of the container (containerStart), relatitive to the end of the previous entry (previousEntry), relative to the end of the container (containerEnd), or relative to the entry that follows this one (nextEntry). If going forward (containerStart and previousEntry) then, then the location refers to the start of the Entry. If going backwards (containerEnd and nextEntry) then, the location refers to the end of the entry.</documentation> </annotation> <simpleType> <restriction base="string"> <enumeration value="containerStart"/> <enumeration value="containerEnd"/> <enumeration value="previousEntry"/> <enumeration value="nextEntry"/> </restriction> </simpleType> </attribute> </extension> </complexContent> </complexType> </element> <element name="RepeatEntry" type="xtce:RepeatType" minOccurs="0"> <annotation> <documentation xml:lang="en">May be used when this entry repeats itself in the sequence container. If not supplied, the entry does not repeat.</documentation> </annotation> </element> <element name="IncludeCondition" type="xtce:MatchCriteriaType" minOccurs="0"> <annotation> <documentation>This entry will only be included in the sequence when this condition is true. If no IncludeCondition is given, then it is will be included. A parameter that is not included will be treated as if it did not exist in the sequence at all.</documentation> </annotation> </element> </sequence> </complexType> <complexType name="ContainerRefType"> <annotation> <documentation xml:lang="en">Holds a reference to a container</documentation> </annotation> <attribute name="containerRef" type="xtce:NameReferenceType" use="required"> <annotation> <documentation xml:lang="en">name of container</documentation> </annotation> </attribute> </complexType> <complexType name="MessageRefType"> <annotation> <documentation xml:lang="en">Holds a reference to a message</documentation> </annotation> <attribute name="messageRef" type="xtce:NameReferenceType" use="required"> <annotation> <documentation xml:lang="en">name of container</documentation> </annotation> </attribute> </complexType> <complexType name="ServiceType"> <annotation> <documentation xml:lang="en">Holds a set of services, logical groups of containers OR messages (not both).</documentation> </annotation> <complexContent> <extension base="xtce:NameDescriptionType"> <sequence> <element name="MessageRefSet" minOccurs="0"> <complexType> <sequence> <element name="MessageRef" maxOccurs="unbounded"/> </sequence> </complexType> </element> <element name="ContainerRefSet"> <complexType> <sequence> <element name="ContainerRef" type="xtce:ContainerRefType" maxOccurs="unbounded"/> </sequence> </complexType> </element> </sequence> </extension> </complexContent> </complexType> <complexType name="ContainerSetType"> <annotation> <documentation>Unordered Set of Containers</documentation> </annotation> <choice maxOccurs="unbounded"> <element name="SequenceContainer" type="xtce:SequenceContainerType"> <annotation> <documentation>SequenceContainers define sequences of parameters or other containers. </documentation> </annotation> </element> </choice> </complexType> <complexType name="EntryListType" mixed="false"> <annotation> <documentation>Contains an ordered list of Entries. Used in Sequence Container</documentation> </annotation> <choice minOccurs="0" maxOccurs="unbounded"> <element name="ParameterRefEntry" type="xtce:ParameterRefEntryType"/> <element name="ParameterSegmentRefEntry" type="xtce:ParameterSegmentRefEntryType"/> <element name="ContainerRefEntry" type="xtce:ContainerRefEntryType"/> <element name="ContainerSegmentRefEntry" type="xtce:ContainerSegmentRefEntryType"/> <element name="StreamSegmentEntry" type="xtce:StreamSegmentEntryType"/> <element name="IndirectParameterRefEntry" type="xtce:IndirectParameterRefEntryType"/> <element name="ArrayParameterRefEntry" type="xtce:ArrayParameterRefEntryType"/> </choice> </complexType> <complexType name="ParameterRefEntryType"> <annotation> <documentation>An entry that is a single Parameter</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <attribute name="parameterRef" type="xtce:NameReferenceType" use="required"/> </extension> </complexContent> </complexType> <complexType name="ParameterSegmentRefEntryType"> <annotation> <documentation>An entry that is only a portion of a parameter value indicating that the entire parameter value must be assembled from other parameter segments. It is assumed that parameter segments happen sequentially in time, that is the first part if a telemetry parameter first, however (and there's always a however), if this is not the case the order of this parameter segment may be supplied with the order attribute where the first segment order="0".</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <attribute name="parameterRef" type="xtce:NameReferenceType" use="required"/> <attribute name="order" type="positiveInteger"/> <attribute name="sizeInBits" type="positiveInteger" use="required"/> </extension> </complexContent> </complexType> <complexType name="ContainerRefEntryType"> <annotation> <documentation>An entry that is simply a reference to another container.</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <attribute name="containerRef" type="xtce:NameReferenceType" use="required"/> </extension> </complexContent> </complexType> <complexType name="ContainerSegmentRefEntryType"> <annotation> <documentation>An entry that is only a portion of a parameter value indicating that the entire parameter value must be assembled from other parameter segments. It is assumed that parameter segments happen sequentially in time, that is the first part if a telemetry parameter first, however (and there's always a however), if this is not the case the order of this parameter segment may be supplied with the order attribute where the first segment order="0".</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <attribute name="containerRef" type="xtce:NameReferenceType" use="required"/> <attribute name="order" type="positiveInteger"/> <attribute name="sizeInBits" type="positiveInteger" use="required"/> </extension> </complexContent> </complexType> <complexType name="StreamSegmentEntryType"> <annotation> <documentation>An entry that is a portion of a stream (streams are by definition, assumed continuous) It is assumed that stream segments happen sequentially in time, that is the first part if a steam first, however, if this is not the case the order of the stream segments may be supplied with the order attribute where the first segment order="0".</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <attribute name="streamRef" type="xtce:NameReferenceType" use="required"/> <attribute name="order" type="positiveInteger"/> <attribute name="sizeInBits" type="positiveInteger" use="required"/> </extension> </complexContent> </complexType> <complexType name="IndirectParameterRefEntryType"> <annotation> <documentation>An entry whose name is given by the value of a ParamameterInstance. This entry may be used to implement dwell telemetry streams. The value of the parameter in ParameterInstance must use either the name of the Parameter or its alias. If it's an alias name, the alias namespace is supplied as an attribute.</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <sequence> <element name="ParameterInstance" type="xtce:ParameterInstanceRefType"/> </sequence> <attribute name="aliasNameSpace" type="string"/> </extension> </complexContent> </complexType> <complexType name="ArrayParameterRefEntryType"> <annotation> <documentation>An entry that is an array parameter. This entry is somewhat special because the entry may represent only a part of the Array and it's important to decribe which diminsions of the array come first in the sequence as well as the size of the array.</documentation> </annotation> <complexContent> <extension base="xtce:SequenceEntryType"> <sequence> <element name="DimensionList"> <annotation> <documentation>Where the Dimension list is in this form: Array[1stDim][2ndDim][lastDim]. The last dimension is assumed to be the least significant - that is this dimension will cycle through it's combination before the next to last dimension changes. The order MUST ascend or the array will need to be broken out entry by entry. </documentation> </annotation> <complexType> <sequence> <element name="Dimension" maxOccurs="unbounded"> <annotation> <documentation>For partial entries of an array, the starting and ending index for each dimension, OR the Size must be specified. Indexes are zero based.</documentation> <appinfo>For an ArrayParameterType of size N, their should be N Dimensions</appinfo> <appinfo>An array made up by multiple Entries should not have index's that overlap, but should be continuous.</appinfo> </annotation> <complexType mixed="false"> <sequence> <element name="StartingIndex" type="xtce:IntegerValueType"> <annotation> <documentation>zero based index</documentation> </annotation> </element> <element name="EndingIndex" type="xtce:IntegerValueType"/> </sequence> </complexType> </element> </sequence> </complexType> </element> </sequence> <attribute name="parameterRef" type="xtce:NameReferenceType" use="required"/> <attribute name="lastEntryForThisArrayInstance" type="boolean" default="false"/> </extension> </complexContent> </complexType> <complexType name="RateInStreamType"> <annotation> <documentation>Used in packaging to define the expected rate that any individual container will be in a Stream</documentation> </annotation> <attribute name="basis" default="perSecond"> <simpleType> <restriction base="string"> <enumeration value="perSecond"/> <enumeration value="perContainerUpdate"/> </restriction> </simpleType> </attribute> <attribute name="minimumValue" type="double"/> <attribute name="maximumValue" type="double"/> </complexType> <!--******** End of Packaging Schema --> Actions taken: December 31, 2004: received issue August 2, 2005: closed issue Discussion: End of Annotations:===== m: webmaster@omg.org Date: 31 Dec 2004 18:10:19 -0500 To: Subject: Issue/Bug Report -------------------------------------------------------------------------------- Name: Gerry Simon Company: Lockheed Martin mailFrom: gerry.simon@schriever.af.mil Notification: No Specification: XTCE Section: schema FormalNumber: dtc/03-05-07 Version: 1 RevisionDate: 03/29/2003 Page: all Nature: Clarification Severity: Critical HTTP User Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0) Description Summary: Early reviewers of the specification have consistently complained that the specification is too complex . particularly in the packaging section and that the annotations that accompany the scheme are oftentimes incomplete, contain typos, or vague.