Documenting Schema Design

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)