Rules and Standards

General Mandatory Rules

These rules are:

• Always define the encoding of XML documents, and use UTF-8 encoding
• Use XML Schema instead of DTD to validate XML documents

[Top]

Always define the encoding of XML document, and use UTF-8 encoding

XML documents should be easy to exchange across various OS systems and countries. Therefore, it is required that no XML instance should be written or generated using an encoding that may no be available on another system.

For example, using is a sentence in French language is to be found in an XML instance, it must not be encoded in iso-8859-1 (one byte for each character of western European languages) because such encoding may not be available on a system in an Asian country. Moreover, since XML document content can be multi-lingual (like mixing German and Japanese language), so the encoding must include all possible language combinations. UTF-8 is one of the possible encoding format for the UNICODE character set. 

Always use UTF-8 for XML documents, and therefore always begin your XML documents (including XML Schema) with the following line:

<?xml version="1.0" encoding="UTF-8"?>

It is possible to use UTF-16 as an alternative encoding format, but this encoding less commonly used and it tends to lead to larger files than UTF-8.

Do not begin any XML document with the following processing instruction:

<?xml version="1.0"?>
<!-- DO NOT USE THIS XML SAMPLE IN YOUR CODE !! -->

because there would be no way to tell what is the document encoding. 

Use XML Schema instead of DTD to validate XML documents

The valid set of elements, attributes, text, etc. entities in an XML document, and their allowed sequences or nesting can be defined either by a DTD (Document Type Definition), or by an XML Schema.

XML Schema can specify any document structure which can be specified by a DTD, and much more : for example an XML Schema can be used to defined allowed data types in an XML document. XML Schema mappings with most languages are being specified.

[Top]

Mandatory Rules for XML Schema

These rules are:

• Use standard XML Schema, such as XML Schema Recommendation 1.0
• Use namespaces
• Use simple datatypes from the allowed list
• Always define elements through a type
• Use elements instead of attributes

[Top]

Use standard XML Schema, such as XML Schema Recommendation 1.0

Public XML declarations must rely on standards. For XML Schema, use at least the "XML Schema Recommendation 1.0", 2 May 2001, from the World Wide Web consortium (http://www.w3.org). Previous versions of XML Schema (24 October 2001 and 7 July 2001 versions) are non-final versions which should no longer be used. 

For example, don't use:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2000/10/XMLSchema">

<!-- DO NOT USE THIS XML SAMPLE IN YOUR CODE !! -->

<xsd:complexType name="shippingDateType">
  <xsd:sequence>
    <!-- the xsd:year and xsd:month datatypes are deprecated -->
    <xsd:element name="year" type="xsd:year"/>
    <xsd:element name="month" type="xsd:month"/>
  </xsd:sequence>
</xsd:complexType>

</xsd:schema>

Instead, the same XML type should be declared using the following standard syntax:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:complexType name="shippingDate">
  <xsd:sequence>
    <xsd:element name="year" type="xsd:gYear"/>
    <xsd:element name="month" type="xsd:gYearMonth"/>
  </xsd:sequence>
</xsd:complexType>

</xsd:schema>

Note that not only the namespace for XML Schema elements changed from http://www.w3.org/2000/10/XMLSchema to http://www.w3.org/2001/XMLSchema, but also some datatypes, like xsd:month and xsd:year have been renamed into xsd:gYearMonth and xsd:gYear using the XML Schema Recommendation 1.0 (the 'g' prefix stands for the 'g' of 'G'regorian calendar).

[Top]

Use namespaces

Public XML Schema must have a namespace: do not use no-namespace schemas. 

See [3] for more in-depth discussions related to the use of Namespaces.

[Top]

Use simple datatypes from the allowed list

The datatypes used in XML Schema declarations must comply to the chosen XML Schema standard (see [2]) and must be selected in the following list of supported datatypes. Forbidden types are based on redundancy or lack of simple mapping to C++ or Java. 

string

boolean

float

double

decimal

duration

base64Binary

anyURI

ID

IDREF

ENTITY

NOTATION

QName

language

IDREFS

ENTITIES

NMTOKEN

NMTOKENS

Name

NCName

integer

nonPositiveInteger

negativeInteger

long

int

short

byte

nonNegativeInteger

unsignedLong

unsignedInt

unsignedShort

unsignedByte

positiveInteger

dateTime

time

date

gDay
gMonth

gYear

gYearMonth
gMonthDay

century
month
year
timeDuration
recurringDuration

The XML Schema Recommendation 1.0 standard does not specifically addresses how to define array datatypes. Arrays used outside the scope of SOAP and WSDL can be represented by nested <sequence> constructs, otherwise the SOAP and WSDL definitions for arrays should be used. 

[Top]

Always define elements through a type

All elements having a complex type must be defined through a type. For example, do not use the following declaration:

<!-- DO NOT USE THIS XML SAMPLE IN YOUR CODE !! --> <xsd:element name="shippingDate"> <xsd:complexType> <xsd:sequence> <xsd:element name="year" type="xsd:gYear"/> <xsd:element name="month" type="xsd:gYearMonth"/> </xsd:sequence> </xsd:complexType> </xsd:element>

 But use instead the following one:

<xsd:element name="shippingDate" type="shippingDateType">
<xsd:complexType name="shippingDateType">
    <xsd:sequence>
      <xsd:element name="year" type="xsd:gYear"/>
      <xsd:element name="month" type="xsd:gYearMonth"/>
    </xsd:sequence>
</xsd:complexType>

Indeed, types are more re-usable than element definitions.

For example, if the structure is intended to be used as an element in instance documents, and it’s required that sometimes it be nillable and other times not, then it must be defined it as a type. Indeed the following syntax is not supported by XML Schema:

      <!-- DO NOT USE THIS XML SAMPLE IN YOUR CODE !! -->
      <xsd:element ref="shippingDate" nillable="true">

while the following is supported:

      <xsd:element name="sendingDate" type="shippingDateType" nillable="true">
      <xsd:element name="receiptData" type="shippingDateType">

[Top]

Use elements instead of attributes

When defining attributes on a container datatype (in the Object-Oriented sense), two main XML Schema patterns may be used: 

1. Defining an actual XML attribute
2. Defining a typed element

The "default CAA" choice  for attribute definition in XML Schemas is the later choice: "define typed elements" instead actual attributes. There are at least two reasons for this rule: first, arbitrary text values cannot be stored in attributes of string type (line breaks in particular); second, using elements over attributes is a SOAP rule. See the SOAP chapter in [4] for more in-depth references about "elements over attributes".  For example, the following declaration is not the preferred one for a public CAA schema:

<!-- DO NOT USE THIS XML SAMPLE IN YOUR CODE !! -->
<xsd:complexType name="ecType">
  <xsd:attribute name="effectivity" type="xsd:date"/>
</xsd:complexType>

while this declaration does declare attributes in the preferred CAA way:

<xsd:complexType name="ecType2">
  <xsd:sequence>
    <xsd:element name="effectivity" type="xsd:date"/>
  </xsd:sequence>
</xsd:complexType>

Please note that:

1. The two above declarations will not lead to the same XML document instances: the structure is completely different.
2. Defining actual attributes on elements is not forbidden by CAA rules nor enforced by CAA code checking tools. In some situations, such as defining a schema for legacy XML data for which only a DTD, or no DTD, was provided, defining an XML Schema with attributes is the only solution unless the legacy XML data makes no use of attributes, of if the value of such attributes is not relevant to the applications. 

[Top]

Mandatory Rules for XML Instances

We call XML Instances any XML document have all its elements defined in a XML Schema. These rules are:

• Always set the associated XML Schema
• Layout XML property files to allow the use of  text editors

Always set the associated XML Schema

The XML Schema associated to XML instance documents must be declared, even if the documents are to be processed by non-validating XML processors. 

[Top]

Layout XML property files to allow the use of  text editors

XML property files are a particular set of XML instances documents which can be used by end-users to customize their applications. Most end-users do not have an XML editors, so a special care must be taken for such files to allow easy editing:

• Do not generate or deliver XML properties with line having more than 80 characters per line.
• Allow line breaks in the value of string elements that will not be interpreted as such, and give a generic convention for actual line breaks (if it makes sense), such as \n.
• If the XML property files are mono-language (or if there is a distinct property file per language), then do not use UTF-8 or UTF-16 encoding. Use instead the most common encoding for each language. For example, use iso-8859-1 for English, French and German.

[Top]

References

History

Copyright © 2001, Dassault Systèmes. All rights reserved.