XSD Tutorial - Part 2 of 5 - Conventions & Recommendations






4.70/5 (30 votes)
This article gives a basic overview of the building blocks underlying XML Schemas.
XSD Tutorial Parts
- Elements and Attributes
- Conventions and Recommendations
- Extending Existing Types
- Namespaces
- Other Useful bits...
Introduction
This section covers conventions and recommendations when designing your schemas.
When to Use Elements or Attributes
There is often some confusion over when to use an element
or an attribute
. Some people say that element
s describe data and attribute
s describe the meta data. Another way to look at it is that attribute
s are used for small pieces of data such as order ids, but really, it is personal taste that dictates when to use an attribute
. Generally, it is best to use a child element
if the information feels like data. Some of the problems with using attribute
s are:
Attribute
s cannot contain multiple values (childelement
s can)Attribute
s are not easily expandable (to incorporate future changes to the schema)Attribute
s cannot describe structures (childelement
s can)
lf you use attribute
s as containers for data, you end up with documents that are difficult to read and maintain. Try to use element
s to describe data. What I am trying to say here is that metadata (data about data) should be stored as attribute
s, and that data itself should be stored as element
s.
Mixed Element Content
Mixed content is something you should try to avoid as much as possible. It is used heavily on the web in the form of XHTML, but that has many limitations. It is difficult to parse and it can lead to unforeseen complexity in the resulting data. XML Data Binding has limitations associated with it making it difficult to manipulate such documents.
Conventions
- All
Element
andAttribute
s should use UCC camel case, e.g. (PostalAddress
), avoid hyphens, spaces or other syntax. - Readability is more important than tag length. There is always a line to draw between document size and readability, wherever possible favor readability.
- Try to avoid abbreviations and acronyms for
element
,attribute
, andtype
names. Exceptions should be well known within your business area, e.g.,ID
(Identifier), andPOS
(Point of Sale). - Postfix new types with the name '
Type
', e.g.,AddressType
,USAddressType
. - Enumerations should use names not numbers, and the values should be UCC camel case.
- Names should not include the name of the containing structure, e.g.,
CustomerName
, should beName
within the subelement
Customer
. - Only produce
complexTypes
orsimpleTypes
fortype
s that are likely to be re-used. If the structure only exists in one place, define it inline with an anonymous complexType. - Avoid the use of mixed content.
- Only define root level
element
s if theelement
is capable of being the rootelement
in an XML document. - Use consistent name space aliases
xml
(defined in XML standard)xmlns
(defined in Namespaces in XML standard)xs
http://www.w3.org/2001/XMLSchemaxsi
http://www.w3.org/2001/XMLSchema-instance
- Try to think about versioning early on in your schema design. If it is important for a new version of a schema to be backwardly compatible, then all additions to the schema should be optional. If it is important that existing products should be able to read newer versions of a given document, then consider adding any and anyAttribute entries to the end of your definitions. See Versioning recommendations.
- Define a
targetNamespace
in your schema. This better identifies your schema and can make things easier to modularize and re-use. - Set
elementFormDefault="qualified"
in the schemaelement
of your schema. This makes qualifying the namespaces in the resulting XML simpler (if not more verbose).