Aims and Goals

This is the page where general aims and goals related to the XML Schemas go.

I have added my own aims and goals in

The first 4 were goals raised by Adam Flinton, I have added goals 5 and 6.
I am happy for them to be removed but thought it would be beneficial to have
a discussion about them

  • andrew.patterson 12/12/08

  1. #Simplify
  2. Raise information to the top most level that makes sense
  3. If a singleton, use an attribute
  4. Standardized attribute names where a specific is not required
  5. Matching element names and field ordering to the AOM specification
  6. The interval type has a very loose definition

1) Simplify

Return to Table of Contents
The simpler the structure the lower the implementation costs and the fewer the implementation bugs

2) Raise Information

Return to Table of Contents
 Raising information up to a position which makes sense helps to comply with (1), makes the XML more human readable and quicker to machines to process.

Example:

 Current:

<definition>
   <rm_type_name>CLUSTER</rm_type_name>
   <node_id>at0000</node_id> 

Raised:

<definition node_id="at0000" rm_type_name="CLUSTER">

This statement is unfounded

Assuming statement (1) is true (which I have my doubts) - what makes the use of mixed attributes/elements
more 'human readable' and 'quicker' than having all elements? - andrew.patterson 8/12/08

3)  If Singleton use an attribute

Return to Table of Contents
In part to comply with (2) and in part because attributes are less error prone than element text (for example being immune to pretty printing problems)  where a structure is a single child of another structure then (unless it contains marked up text intended for human reading) then it should be an attribute.

Your tools are broken

You made the comments last year on the list that elements are more prone
to pretty printing errors, and the comments then were that your tools are broken if
they alter the whitespace text of elements. I would still contend this -
what are these tools that break element text and should we concentrate on fixing
them? - andrew.patterson 8/12/08

Use xml:space

Adherence to xml:space should be sufficient.  However I do think that attributes can be used more, spoecifically in cases when it is meta data about an element, such as node_id and rm_type_name - heath.frankel 11/12/08

4)  Standardized attribute names

Return to Table of Contents

Unless there is a specific need for a specific attribute name then use "value".

Should not be necessary

This conflicts with 5 and should not be necessary - heath.frankel 11/12/08

5)  Matching element names and field ordering to the AOM specification

Return to Table of Contents

As the XML schemas are hand built, it is important that it is easy to match
the schema definitions to the corresponding AOM specification. Where possible, it
is useful if the schema elements have exactly matching names, and are defined in
the same order as in the specification.

Isn't this the case

Much effort was taken to ensure that the above is true, if it is not then I would like to see the specific case.  Having said this, I have been working with the ADL and XML serialisations of the same archetype and it is difficult toi compare the two due to the order of the ADL and XML elements being different.  I would suggest that an alternate order would be to follow the ADL specification. - heath.frankel 11/12/08

This is currrently true

I was just noting this as an 'Aim' & 'Goal' of the any XML serialization.
The current ITS does this well. - andrew.patterson 12/12/08

6)  The interval type has a very loose definition

Return to Table of Contents

Taking INTERVAL<int> as an example,

<xs:complexType name="Interval" abstract="true">
		<xs:sequence>
			<xs:element name="lower_included" type="xs:boolean" minOccurs="0"/>
			<xs:element name="upper_included" type="xs:boolean" minOccurs="0"/>
			<xs:element name="lower_unbounded" type="xs:boolean"/>
			<xs:element name="upper_unbounded" type="xs:boolean"/>
		</xs:sequence>
	</xs:complexType>

	<xs:complexType name="IntervalOfInteger">
		<xs:complexContent>
			<xs:extension base="Interval">
				<xs:sequence>
					<xs:element name="lower" type="xs:int" minOccurs="0"/>
					<xs:element name="upper" type="xs:int" minOccurs="0"/>
				</xs:sequence>
			</xs:extension>
		</xs:complexContent>
	</xs:complexType>

I think this definition can be improved. Lower_included and upper_included should be
lower_inclusive and upper_inclusive as this is more descriptive. It is also not
stated what the inclusive/exclusive status is when these elements are not present. It is
also not a schema error to specify inclusive/exclusive when the range is unbounded
(even though this then has no meaning). It is also not a schema error have a
bounded range end, but then no corresponding value for that end.

Conflicts with 5

You have said in 5 that the schema should follow the AOM, this does and your suggested changes conflicts with 5.  The AOM specification provides the invariants for the case when these elements are not present.  The XML schema is not intended to be the sole source the AOM invariants, it is not possible to do that in schema.  Doing so based on the principle of using only Element and specifying defaults would cause ambiguity due to the tri-state nature of XML Elements existence otherwise requiring the element to be present but nil to invoke the default.

However, I do believe there is a better approach to represent intervals.  - heath.frankel 11/12/08

Interval is an assumed type, not an AOM type

My logic here was that because INTERVAL<XX> is an assumed type that we have
munged into the XML schema (as IntervalOfXX), there was much more leeway in how it is crafted.
– andrew.patterson 12/12/08