RE: [emix] Documenting Schema Design

["Considine, Toby (Campus Services IT)" <Toby.Considine@unc.edu>]

Thanks - and immensely useful.

As we worked in WS-Calendar, we collapsed into a single schema, but that schema seemed to expand into several files. The tools don't care, but it is a way to handle the sheer volume involved.

Do you have a sense of that process?

"It is the theory that decides what can be observed."   - Albert Einstein

Toby Considine
Chair, OASIS oBIX Technical Committee
U.S. National Inst. of Standards and Tech. Smart Grid Architecture Committee
Facilities Technology Office
University of North Carolina
Chapel Hill, NC
  
Email: Toby.Considine@ unc.edu
Phone: (919)962-9073 
http://www.oasis-open.org 
blog: www.NewDaedalus.com



-----Original Message-----
From: Anne Hendry [mailto:ahendry@pacbell.net] 
Sent: Thursday, January 06, 2011 4:16 AM
To: emix@lists.oasis-open.org
Subject: [emix] 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)












---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php