UBL Naming and Design Rules Subcommittee Report Eve Maler NDR SC chair 18 March

What does the NDR SC do? “Recommend to the TC rules and guidelines for normative-form schema design, instance design, and markup naming, and write and maintain documentation of these rules and guidelines” (we’re the XML geeks) SC members champion issues by writing position papers Eventually, the NDR document will hold all our recommendations

Current NDR SC members Bill Burcham Mavis Cournane Mark Crawford (editor, vice-chair) Fabrice Desré John Dumay Matt Gertner Phil Griffin Arofan Gregory Eduardo Gutentag Eve Maler (chair) Dale McKay Joe Moeller Sue Probert Ron Schuldt Lisa Seaburg Gunther Stuhec Paul Thorpe (thanks to all these folks for their hard work!)

Status: 16 Mar ‘02 distribution The following papers are nearing completion, and drafts are available for review now –Modularity, namespaces, and versioning (“modnamver”) plus example code: V03 –Defining and naming elements, attributes, and types (“tag structure”): V03 –Choosing elements vs. attributes: V03 –Defining code lists: V04 See the ubl or ubl-comment mail archives as of 17 Mar, or see me this week to borrow a diskette with a zip file

First two recommendations, done a while back Schema language: –The normative source format for schema files will be W3C XML Schema (XSD), though we may not directly author in this –Other formats may be generated Legal issues: –We sought advice on whether default values are a legal problem (as they’re absent from the instance but still part of the “data”) –Conclusion: “implied terms” have been acceptable for a long time

Modnamver progress: nam One namespace for the core library One namespace per root schema –Where a root schema defines all types and message root elements for one functional area Possibility of intermediate namespaces (and thus roots) as we go along –Likely for loading/performance reasons Investigating URNs as namespace names UBL extensions made by others must define their own namespaces –Which are encouraged to be keyed to contexts

Modnamver progress: mod Encourage creation of new instance roots (individual message root elements) even for slightly different document forms Root schema for instance root may include several schema modules, and will import core root schema –If intermediate levels get added, more roots will be imported at the various levels –How to handle “borrowing” across functional areas? Core root schema will probably have an artificial root element –For developer convenience

Sample modules

Modnamver progress: ver Versions are associated with namespaces, not with individual modules We are considering a Major.Minor version number structure –Based on backwards compatibility of the change Not sure how to encode the versions yet –Current common practice: attribute on root element, in namespace URI, in filename –An idea: incorporate into the context methodology? Not sure of relationship between core and functional namespace versions yet

Tag structure progress Makes use of ISO concepts and their realization in ebXML CC –“Object class” and “property” especially XML allows us to reuse types, and thus most names of types and elements will be generic The dictionary will spell out the semantics for the fully qualified path for each element and attribute –This locks down a particular object class/property and other details, so that there is zero semantic ambiguity

More tag structure detail Top-level elements are global, and non- top-level elements are local/unqualified On intermediate elements, “Details” is the RT and is thus left off the name On leaf elements and attributes, RTs generally appear on names –“Text” is the default and is thus left off –“ID” is the required shorthand for “Identifier” –We may need to add XML-specific RTs, e.g. for mixed content

Elements vs. attributes Main component content should be elements –Aggregates will break down into subelements, often using container elements –Order and cardinality are important –Empty elements thus not needed Supplementary components should be attributes –E.g., for currency codes on amounts –They tend to be unordered –Free extension is generally not a desired option Common attributes proposed: –uid, uidRef[s], language

Code lists Design principles: semantic clarity, management of maintenance costs, validation*, subsetting, and extension Code list choices and usage must be documented Codes supplied as XSD QNames –Code list “namespace” prefix and actual code Very extensible while providing clear semantics *But pushes most validation to the application level

Additional work in progress Roles of elements and attributes relative to a type and the potential effect on naming (“role model”) Type hierarchies and abstract types (“reoccurring types”) Representing the original context of extracted data when constructing UBL messages (“native context”)

What we hope to accomplish this week Schema code review “Reoccurring types” “Native context” “Role model” Requirements around embedded documentation How do simple types relate to CCTs and RTs? Exit criteria for the NDR SC We would like to work more directly with (Tim’s) LC SC in the future, including this week –New naming and design rules will ideally be much more “emergent”

Please visit the NDR SC portal It always summarizes our status and provides links to all papers, use cases, and additional resources: Updated approximately weekly And please review our position papers!

Thank you Eve Maler NDR SC chair 18 March