Documenting Schema Design

[Anne Hendry <ahendry@pacbell.net>]

In the interest of furthering consistency and continuity in schema 
implementation this may be a good time to begin documenting design 
guidelines and best practice decisions we've made so far, to avoid 
rehashing, to communicate those decisions more broadly, and to lay 
groundwork for tools and future implementers.  This will also provide 
the base to further the set of guidelines and rules for 1.0 and will be 
invaluable in automating schema generation and in testing schema quality 
before release.  Who would be interested in participating in this 
exercise?  It would require a few people with fairly in-depth schema 
knowledge going forward.  The output would be a separate document 
stating each rule/guideline and rationale.

Here are a few examples of Guiding Principles from other standards 
efforts (not necessarily what we'd implement, just examples):

* The specification SHOULD specify what is necessary for semantic 
interoperability and no more. [1]
* A data component definition SHOULD be drafted before the associated 
data element name is composed. [1]
* Conformant schemas SHOULD NOT specify data that uses mixed content. [1]
* Multiple components with identical or undifferentiated semantics 
SHOULD NOT be defined. [1]
* A namespace SHOULD encapsulate components that tend to change 
together. [1]
* All attributes of a class are declared as a local xsd:element within a 
xsd:complexType. [2]
* User-defined attributes SHOULD NOT be used. [3]
* Imported schema modules SHOULD be fully conformant to the design 
rules. [4]
* Data-centric schemas SHOULD use the documentation element for schema 
construct documentation. [5]

Here are a few examples of Rules created/used by other standards efforts:

* The schema SHALL NOT contain the element xsd:choice. [1]
* Element, attribute, and type names MUST be composed of words in the 
English language, using the primary English spellings provided in the 
Oxford English Dictionary. [2]
* The xsd:any element MUST NOT be used. [3]
* Every information exchange schema version MUST have its own unique 
namespace. [3]
* For every user-defined datatype, a named xsd:simpleType or 
xsd:complexType MUST be defined. [3]
* User-defined information exchange XML element, attribute, and type 
names MUST be ebXML CCTS ISO 11179 compliant. [3]
* Information exchange XML element, attribute, and simple and complex 
type names MUST NOT use acronyms, abbreviations, or other word 
truncations except those in the list of exceptions published in Appendix 
B. [3]
* Each element or attribute name MUST have one and only one fully 
qualified XPath. [4]
* Data-centric schemas MUST include schema header documentation. [5]
* Document-centric schemas MUST NOT use the XLink/XPointer technique for 
information association. [5]

As you can see in the referenced documents, usually rules/guidelines are 
broken into several categories.  We can start by deciding what areas are 
most important to this TC and work on those areas first.

-Anne


[1] http://www.niem.gov/pdf/NIEM-NDR-1-3.pdf
[2] http://www.unece.org/cefact/xml/XML-Naming-and-Design-Rules-V2.0.pdf
[3] http://xml.coverpages.org/OASIS-IJTC-MNDR.pdf  (OASIS LegalXML 
Ingetrated Justice TC, see Section 4)
[4] http://www.oagi.org/oagi/downloads/ResourceDownloads/OAGIS_90_NDR.pdf
[5] http://xml.coverpages.org/EPAXML-DRC-Section2.pdf (EPA Environmental 
Information Exchange Network)
[6] 
http://www.oasis-open.org/committees/download.php/10323/cd-UBL-NDR-1.0Rev1c.pdf
[7] http://docs.oasis-open.org/ubl/cs01-UBL-2.0-NDR/cs01-UBL-2.0-NDR.pdf

[8] Robin Cover's page listing NDR documents (slightly dated, but still 
useful)
[9] NIST Schema Design Test Tool :
     http://www.mel.nist.gov/msidlibrary/doc/Schema_Design.pdf
     (shows how the rules are used for schema testing, and which are 
most useful in determining schema quality)