Jesper Tverskov, July 28, 2005

UBL Naming and Design Rules

Universal Business Language (UBL) has an impressive UBL Naming and Design Rules Checklist [1]. UBL has been a great source of inspiration also for XML Schema projects not related to UBL.

What is good for UBL is not necessarily good or relevant for other XML Schema projects. But what is recommended or not allowed in UBL is most often worth thinking about. Below I only list some of the many naming and design rules. [2]

1.  Attribute Declaration Rules

  1. "The xsd built in nillable attribute MUST NOT be used for any UBL declared element." (ATD7, page 1)
  2. "The xsd:any attribute MUST NOT be used." (ATD8, page 1) [3]

2.  Element Declaration Rules

  1. "All element declarations MUST be global with the exception of ID and Code which MUST be local". (ELD2, page 8)
  2. "Empty elements MUST not be declared." (ELD7, page 8)
  3. "The xsd:any element MUST NOT be used." (ELD9, page 8)

3.  General Naming Rules

  1. "The UpperCamelCase (UCC) convention MUST be used for naming elements and types." (GNR8, page 9)
  2. "The lowerCamelCase (LCC) convention MUST be used for naming attributes." (GNR9, page 9)

4.  General Type Definition Rules

  1. "All types MUST be named." (GTD1, page 9)
  2. The xsd:any type MUST NOT be used." (GTD2, page 10)

5.  General Schema Rules

  1. UBL Schema MUST conform to the following physical layout as applicable (GXS1, page 10):

<!-- Copyright Notice -->
<!-- xsd:schema Element With Namespaces Declarations -->
<!-- Imports -->
<!-- Global Attributes -->
<!-- Root Element --> [4]
<!-- Element Declarations -->
<!-- Type Definitions -->
<!-- Aggregate Business Information Entity Type Definitions -->
<!-- Basic Business Information Entity Type Definitions -->

6.  General XML Schema Rules

  1. "Build-in XSD Simple Types SHOULD be used wherever possible." (GXS3, page 11) [5]
  2. "The xsd:SubstitutionGroups feature MUST NOT be used". (GXS5, page 11)
  3. "The xsd:final attribute MUST be used to control extensions." (GXS6, page 11)
  4. "xsd:notations MUST NOT be used." (GXS7, page 11)
  5. "The xsd:all element MUST NOT be used." (GXS8, page 11)
  6. "The xsd:union technique MUST NOT be used except for Code Lists. The xsd:union technique MAY be used for Code Lists." (GXS11, page 11)

7.  Instance Document Rules

  1. UBL conformant instance documents MUST NOT contain an element devoid of content or null values." (IND5, page 11)

8.  Modeling Constraints Rules

  1. "Mixed content MUST NOT be used except where contained in an xsd:documentation element." (MDC2, page 11) [6]

Footnotes

[1]

UBL Naming and Design Rules Checklist (pdf at OASIS).

[2]

In Denmark, the government has adopted UBL (OASIS standard) under the name of OIOXML. Since 2005-02-01 only XML invoices can be used if you want to do business with the public administration, even with public kindergartens.

[3]

In wordprocessingML (wordML) by contrast, <xsd:anyAttribute> and <xsd:any> (for elements) are used a lot since it most be possible to save "unknown" markup declared in the user's own XML Schema inside a MS Word document saved as wordML.

[4]

In wordprocessingML (wordML) by contrast, the root element, "w:wordDocument", is declared as the very last declaration of the XML Schema (it has almost 10.000 lines).

[5]

In wordprocessingML (wordML) by contrast, not one build-in XSD simpleType is used directly. All 99 simpleTypes are user-defined.

[6]

In wordML by contrast, we would expect a lot of mixed content, elements containing a mixture of elements and data (text). In XHTML it could look like this: <p>This <b>is</b> bold</p>. But Microsoft doesn't like mixed content either: a "run" element with a "runProperty" is used for each formatted fragment like this:

<w:p>
  <w:r>
    <w:t>This </w:t>
  </w:r>
  <w:r>
    <w:rPr>
      <w:b/>
    </w:rPr>
    <w:t>is</w:t>
  </w:r>
  <w:r>
    <w:t> bold</w:t>
  </w:r>
</w:p>

Note that above only the second w:r (run) is bold. In this way wordprocessingML can do without mixed content!

Last updated 2007-01-08