UBL Naming and Design Rules Subcommittee Report

1
UBL Naming and Design Rules Subcommittee Report

• Eve Maler
• NDR SC chair
• 18 March 2002
• www.oasis-open.org/committees/ubl/ndrsc/

2
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
  (were the XML geeks)
• SC members champion issues by writing position
  papers
• Eventually, the NDR document will hold all our
  recommendations

3
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!)

4
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

5
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 theyre absent from the
  instance but still part of the data)
• Conclusion implied terms have been acceptable
  for a long time

6
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

7
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

8
Sample modules
9
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

10
Tag structure progress

• Makes use of ISO 11179 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

11
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

12
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, uidRefs, language

13
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

14
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)

15
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 (Tims)
  LC SC in the future, including this week
• New naming and design rules will ideally be much
  more emergent

16
Please visit the NDR SC portal

• It always summarizes our status and provides
  links to all papers, use cases, and additional
  resourceswww.oasis-open.org/committees/ubl/ndrsc
  /
• Updated approximately weekly
• And please review our position papers!

17
Thank you

• Eve Maler
• NDR SC chair
• 18 March 2002
• www.oasis-open.org/committees/ubl/ndrsc/