UBL Naming and Design Rules Subcommittee

Report

Eve MalerNDR SC chair

18 March 2002www.oasis-open.org/committees/ubl/ndrsc/

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

core

OrderA

invoicing

InvoiceX

Ordermgmt

Schemamodule

Rootschema

Instanceroot

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

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:www.oasis-open.org/committees/ubl/ndrsc/

• Updated approximately weekly• And please review our position

papers!

Thank you

Eve MalerNDR SC chair

18 March 2002www.oasis-open.org/committees/ubl/ndrsc/