What are best practices for designing XML schemas? [closed]

Answer 1

I often find myself struggling with the same issue but I find that in practice it doesn't really matter, xml is just data.

That said, I usually prefer the "if it says something about the node it's an attribute, otherwise it's a childnode" approach.

In your example i'd go for:

<coordinate>
    <x>0</x>
    <y>1</y>
</coordinate>

because the x and y are properties of a coordinate, not actually saying anything about the xml, but about the object represented by it.

Answer 2

I do not know any good learning resource about how to design XML document models (schemas are just a formal way of specifying document models).

In my opinion, one crucial insight to XML is that it is not a language: it is a syntax. And each document model is a separate language.

Different cultures will each use XML in their own special way. Even within W3C specifications you can smell Lisp in dash-separated-names of XSLT, and Java in the camelCaseNames of XML Schema. Similarly, different application domains will call for different XML idioms.

Narrative document models such as HTML or DocBook tend to put printable text in text nodes and metadata in element names and attributes.

More object-oriented document models such as SVG make little or no use of text nodes and instead only use elements and attributes.

My personal rules of thumb for document model design go something like this:

• If it is the sort of the free-from tag soup that requires mixed content, use HTML and DocBook as sources of inspiration. The other rules are only relevant otherwise.
• If a value is going to be composite or hierarchical, use elements. XML data should require no further parsing, except for established idioms such as IDREFS which are simple space-separated sequences.
• If a value may need to occur more than once, use elements.
• If a value may need to be refined further, or enriched later, use elements.
• If a value is clearly atomic (boolean, number, date, identifier, simple label), and may occur at most once, then use an attribute.

Another way to say it could be:

• If it's narrative, it's not object oriented.
• If it's object oriented, model objects as elements and atomic attributes as attributes.

EDIT: Some people seem to like to entirely forgo attributes. There's nothing wrong with it, but I dislike it as it bloats documents and make them unnecessary hard to read and write by hand.

Answer 3

There's nothing inherently wrong with using an element or sub-element for every value you'd like to represent.

The main consideration is that sometimes it's cleaner to use an attribute. Since an element can only have one attribute of a given name, you're stuck with a 1:1 cardinality. If you're representing the data as a child element, you can use whatever cardinality you'd like (or be open to extending it later).

Rob Wells' response above is right: it depends on the relationships you're trying to model.

Any time there's clearly never going to be anything but a 1:1 relationship, an attribute may be cleaner.

Answer 4

I agree w/ cdragon's advice below to avoid option #2. The choice between #1 & #3 is largely a matter of style. I like to use attributes for what I consider to be attributes of the entity, and elements for what I consider to be data. Sometimes, it's hard to classify. Nonetheless, neither are "wrong".

And while we're on the topic of schema design, I'll add my two cents regarding my preferred level of (maximum) reuse (of both elements and types), which can also facilitate external "logical" referencing of these entities in, say, a data dictionary stored in a database.

Note that while the "Garden of Eden" schema pattern offers the maximum reuse, it also involves the most work. At the bottom of this post, I've provided links to the other patterns covered in the blog series.

• The Garden of Eden approach http://blogs.msdn.com/skaufman/archive/2005/05/10/416269.aspx

Uses a modular approach by defining all elements globally and like the Venetian Blind approach all type definitions are declared globally. Each element is globally defined as an immediate child of the node and its type attribute can be set to one of the named complex types.

<?xml version="1.0" encoding="UTF-8"?> 
<xs:schema targetNamespace="TargetNamespace" xmlns:TN="TargetNamespace" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  elementFormDefault="qualified" attributeFormDefault="unqualified"/> 
<xs:element name="BookInformation" type="BookInformationType"/> 
  <xs:complexType name="BookInformationType"/> 
    <xs:sequence> 
      <xs:element ref="Title"/> 
      <xs:element ref="ISBN"/> 
      <xs:element ref="Publisher"/> 
      <xs:element ref="PeopleInvolved" maxOccurs="unbounded"/> 
    </xs:sequence> 
  </xs:complexType> 
  <xs:complexType name="PeopleInvolvedType"> 
    <xs:sequence> 
      <xs:element name="Author"/> 
    </xs:sequence> 
  </xs:complexType> 
  <xs:element name="Title"/> 
  <xs:element name="ISBN"/> 
  <xs:element name="Publisher"/> 
  <xs:element name="PeopleInvolved" type="PeopleInvolvedType"/> 
</xs:schema>

The advantage of this approach is that the schemas are reusable. Since both the elements and types are defined globally both are available for reuse. This approach offers the maximum amount of reusable content. The disadvantages are the that the schema is verbose. This would be an appropriate design when you are creating general libraries in which you can afford to make no assumptions about the scope of the schema elements and types and their use in other schemas particularly in reference to extensibility and modularity.

Since every distinct type and element has a single global definition, these canonical particles/components can be related one-to-one to identifiers in a database. And while it may at first glance seem like a tiresome ongoing manual task to maintain the associations between the textual XSD particles/components and the database, SQL Server 2005 can in fact generate canonical schema component identifiers via the statement

CREATE XML SCHEMA COLLECTION

http://technet.microsoft.com/en-us/library/ms179457.aspx

Conversely, to construct a schema from the canonical particles, SQL Server 2005 provides the

SELECT xml_schema_namespace function

http://technet.microsoft.com/en-us/library/ms191170.aspx

ca·non·i·cal Related to Mathematics. (of an equation, coordinate, etc.) "in simplest or standard form" http://dictionary.reference.com/browse/canonical

Other, easier to construct, but less resuable/more "denormalized/redundant" schema patterns include

• The Russian Doll approach http://blogs.msdn.com/skaufman/archive/2005/04/21/410486.aspx

The schema has one single global element - the root element. All other elements and types are nested progressively deeper giving it the name due to each type fitting into the one above it. Since the elements in this design are declared locally they will not be reusable through the import or include statements.

• The the Salami Slice approach http://blogs.msdn.com/skaufman/archive/2005/04/25/411809.aspx

All elements are defined globally but the type definitions are defined locally. This way other schemas may reuse the elements. With this approach, a global element with its locally defined type provide a complete description of the elements content. This information 'slice' is declared individually and then aggregated back together and may also be pieced together to construct other schemas.

• The Venetian Blind approach http://blogs.msdn.com/skaufman/archive/2005/04/29/413491.aspx

Similar to the Russian Doll approach in that they both use a single global element. The Venetian Blind approach describes a modular approach by naming and defining all type definitions globally (as opposed to the Salami Slice approach which declares elements globally and types locally). Each globally defined type describes an individual "slat" and can be reused by other components. In addition, all the locally declared elements can be namespace qualified or namespace unqualified (the slats can be "opened" or "closed") depending on the elementFormDefault attribute setting at the top of the schema.

Answer 5

I was designated to write a bunch of XML schemas to integrate my company systems with our clients. I've designed a dozen of them more than 10 years ago and saw that a lot of extension features in the specification didn't work well in practice. Before designing the new ones, I've searched for the current best practices (and arrived here!).

Some of the tips above are useful, but I didn't like almost all references. The best place with design recommendations that I found were from Microsoft.

The best reference is XML Schema Design Patterns: Avoiding Complexity. Here you will find this sane advice:

it seems that many schema authors would be best served by understanding and utilizing an effective subset of the features provided by W3C XML Schema instead of attempting to comprehend all of the esoteric and minutiae of the language.

and give detailed explanations of the following guidelines:

• Why you should use global and local element declarations
• Why you should use global and local attribute declarations
• Why you should understand how XML namespaces affect the W3C XML Schema
• Why you should always set elementFormDefault to "qualified"
• Why you should use attribute groups
• Why you should use model groups
• Why you should use the built-in simple types
• Why you should use complex types
• Why you should not use notation declarations
• Why you should use substitution groups carefully
• Why you should favor key/keyref/unique over ID/IDREF for identity constraints
• Why you should use chameleon schemas carefully
• Why you should not use default or fixed values especially for types of xs:QName
• Why you should use restriction and extension of simple types
• Why you should use extension of complex types
• Why you should use restriction of complex types carefully
• Why you should use abstract types carefully
• Do use wildcards to provide well-defined points of extensibility
• Do not use group or type redefinition

My advice about their advice is that when they say "use carefully", you should simply avoid it. My impression is that the Schema specification were not written by software developers. They tried to use some Object Orientation concepts but did a mess of it. A lot of the extension mechanisms are useless or extremely verbose. I don't really understand how someone could have invented the restriction of complex types.

Two more nice articles in this site are:

• Schema Design Patterns: Dealing With Change
• XML Schema Design Patterns: Is Complex Type Derivation Unnecessary?

And one tip that is pervasive is to specify your schemas with something different than the official specification. Relax NG looks the most favored specification language. Unfortunately you will loose one of the best features of it that is the standardization.

Answer 6

When designing an XML-based format, it's often good to think about what you're representing. Try mocking some XML data that fits the purpose you intend. Once you've got something you're satisfied with that meets your requirements, develop the schema to validate it.

When desiging a format, I tend to use elements for holding data content and attributes for applying characteristics to the data like an id, a name, a type, or some other metadata about the data an element contains.

In that regard, an XML representation for coordinates might be:

<coordinate type="cartesian">
  <ordinate name="x">0</ordinate>
  <ordinate name="y">1</ordinate>
</coordinate>

This caters for different coordinate systems. If you knew they'd always be cartesian, a better implementation might be:

<coordinate>
  <x>0</x>
  <y>1</y>
</coordinate>

Of course, the latter could lead to a more verbose schema as each element type would need declaring (though I'd hope a complex type was defined to actually do the hard work for these elements).

Just as in programming, there are often multiple ways of achieving the same ends, but there is no right and wrong in many situations, just better and worse. The important thing is to remain consistent and try to be intuitive so that when others look at your schema, they can understand what you were trying to achieve.

You should always version your schemas and ensure that XML written against your schema indicates it as such. If you don't properly version the XML then making addendums to the schema while supporting XML written to the older schema will be much more difficult.