Canonical Best Practices

Here are some quick notes on best practices for creating a canoncial data model that is easily understandable and useable across an organization.

Define clear schema creation guidelines

• Versioning, namespaces, and naming
• Use file comments and xsd:documentation

Centralize "common" types and elements in common schemas

• Define entities shared across schemas in a common schema
• Have a simpleType schema and a commonTypes schemas

Beware of enumerations (make sure it can be strictly defined and will not change). There are actually very few things that can be represented by a truely definitive list.  For example, most people think the US states are a good example of an enumeration since there are only 50 of them but what about Guam or the District of Columbia or US Virgin Island.

Protocol-independent

• Create types in domain schema and create separate message schema that contain messages. The message schemas would leverage the domain schemas.  (i.e. Guest.xsd and GuestMessages.xsd)

There are several XML schema design patterns at http://developers.sun.com/jsenterprise/archive/nb_enterprise_pack/reference/techart/design_patterns.html. Over the years we have found that several tools don't fully support the different patterns so care should be taken to make sure your current and future tools support the pattern that you choose.  We prefer a modified Garden of Eden pattern.  It is modified because we don't recommend exporting everything but think of it as an API and expose only the types that schema users want to reference.

Schema versioning is one of the greatest concerns when working with a canonical data model.  Once developers start using your CDM it becomes harder and harder to make changes without impacting the current services.  Determine a standard on how major and minor version numbers will be used to support backward compatibility.  We use minor version numbers to represent changes that are fully backward compatibility and major version numbers to represent changes that require users to modify their code to utilize the new schema.

Define magical words that are used consistantly across all schemas.

• If 'Id' is used to identify a single object use it consistantly across all schemas. Don't mix Code and Id (eg. CountryId, CountryCode)
• Use attributes only for metadata and/or optional data

Stay away from edge XSD elements since tool vendors support them differently

• xsd:any
• xsd:substitutionGroup