Rules and Standards
|
CAA V5 XML Code Presentation
Presentation conventions to improve the readability of XML code |
Technical Article |
Abstract
This article gives information on how to edit XML Schema as regards to
the document layout. CAA Use Cases are expected to meet these conventions.
|
Global layout
The XML Schema documents presentation must obey the following order:
- XML header with a UNICODE (UTF-8 recommended) encoding:
<?xml version="1.0" encoding="UTF-8"?>
|
- Copyright:
<!-- COPYRIGHT DASSAULT SYSTEMES 2001 -->
|
- Not mandatory, an historical account of the modifications:
<!-- 04 Jan 2001 creation -->
<!-- 10 Mar 2001 modification, added the weight attribute. -->
|
- The schema element, with namespace declarations:
<xsd:schema targetNamespace="http://dassaultsystemes.com/CATFwk-Product"
xmlns="http://dassaultsystemes.com/CATFwk-Product"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
|
- Import and or include elements, if needed:
<import namespace="http://dassaultsystemes.com/CATFwk-Product"
schemaLocation="CATFwProduct.xsd"/>
|
- Always import each used type and element definition even if it belongs
to the current namespace
- Group import and include elements by namespace
- Explain for what each one is used
- Type or element declaration:
<xsd:complexType name="productType">
|
- Type/element documentation using the
annotation
and documentation
elements (see the Comments section):
<xsd:annotation>
<xsd:documentation>Use this type when a product description is needed.</xsd:documentation>
</xsd:annotation>
|
- All elements declared inside a type or inside an element must be
documented using the
annotation
and documentation
elements.
[Top]
Type and element declaration layout
-
Indentation
- Always use the same type of indentation (2 or 4 spaces)
- Use spaces, not tabs.
- Line Length < 80 characters
When a declaration would not fit on a single line, break it into another
line at a location allowed by the XML syntax.
Align the new line with the beginning of the declaration at the same level
on the previous line, or if it is too far on the right, use an indentation
twice as big as usual.
<xsd:element name="position" type="Positionning3DMatrixType"
minOccurs="0" nillable="false">
<xsd:annotation>
<xsd:documentation>The positioning matrix, relative to the assembly root.
If this element is not set, then the identity matrix is assumed.</xsd:documentation>
</xsd:annotation>
|
- At most one declaration per Line
<xsd:element name="x" type="xsd:float"><xsd:annotation><xsd:documentation>X value.</xsd:documentation></xsd:annotation>
<xsd:element name="y" type="xsd:float"><xsd:annotation><xsd:documentation>Y value.</xsd:documentation></xsd:annotation>
<xsd:element name="z" type="xsd:float"><xsd:annotation><xsd:documentation>Z value.</xsd:documentation></xsd:annotation>
|
[Top]
Naming Conventions
- Type and element names should begin in lower case. Element names should be
short, especially if they are to be repeated possibly a great number of
times in XML document instances.
- Type names in XML Schema should end with 'Type'. For example:
<xsd:complexType name="productType"> ... </xsd:complexType>
|
[Top]
Comments
All exposed entities in XML Schema, i.e., global and local types and
elements, must be documented using the annotation
and documentation
elements. For example:
<xsd:element name="product" type="productType">
<xsd:annotation>
<xsd:documentation>Use this element to exchange product data.</xsd:documentation>
</xsd:annotation>
</xsd:element>
|
Note that since English language is assumed for XML documentation, CAA rules
does not require the use of the xml:lang
attribute with documentation
elements.
If documentation in multiple languages were needed, using the xml:lang
attributes
with documentation
element would be required.
[Top]
History
Version: 1.0 [Sep 2001] |
Document created |
[Top] |
Copyright © 2001, Dassault Systèmes. All rights reserved.