Position Paper: Data Models for Code Lists

Position Paper: Data Models for Code Lists

Proposal 02, 12 December 2003

Document identifier:

draft-coates-codeListsDataModels-0p2.sxw (or .doc)

Location:

Author:

Anthony B. Coates <

Abstract:

This position paper outlines the use of schema-independent data models to manage code lists, and to improve the opportunities for code list interoperability between different standards & specifications.

Status:

This is V02 of the code list data model position paper intended for consideration by the OASIS UBL Code List subcommittee and other interested parties.

If you are on the list for subcommittee members, send comments there. If you are not on that list, subscribe to the list and send comments there. To subscribe, send an email message to with the word "subscribe" as the body of the message.

Table of Contents

1Introduction3

2Code List Interoperability3

3Schema Languages are not Data Models3

4Possible Features of Code List Data Models4

5A Simple Code List Data Model for UBL 1.04

1Introduction

UBL has a short-term requirement to produce W3C XML Schemas as part of its version 1.0 deliverables. Among those Schemas are the code list Schemas, used to validate enumerated values in UBL instance documents.

Code lists are not unique to UBL, nor to XML standards. They occur just as commonly in applications and databases. If UBL is to eventually deliver code lists that can and will be used to provide integration within and between enterprises, it will need to provide an interchange specification for code lists that is not tied to an XML schema language, nor to any other process-specific format. Instead, what is needed is an independent representation of code lists, a data modelling format for code lists.

2Code List Interoperability

The current UBL code list documents speak of other XML specifications re-using UBL's code list Schemas. While this may occur, there are already many specifications whose use of XML is sufficiently different from UBL's that re-use of UBL Schemas (or Schema fragments) is not an option. That does not mean that those other specifications cannot be interoperable with UBL at the level of code lists.

Code list operability comes about when different specifications or applications use the same enumerated values (or aliases thereof) to represent the same things/concepts/etc. Sharing XML schemas (or fragments) is one way of achieving this, but it is not a necessary method for achieving this goal.

Broader interoperability can be achieved instead by defining a format which models code lists independently of any validation or choice mechanisms that they may be used with. Such a data model should be able to be processed to produce the required XML Schemas, and should also be able to be processed to produce other artifacts, e.g. Java type-safe enumeration classes, database Schemas, code snippets for HTML forms or XForms, etc.

3Schema Languages are not Data Models

It is important to note that XML schema languages are not good data modelling formats. They provide only a physical model of the data, polluted with many design choices (e.g. elements versus attributes). The underlying logical model is obscured, and can be difficult to extract. In particular, XML schema languages commonly allow the same constraint to be modelled in multiple ways, and this processing of the underlying data model more difficult that it need be. XML schema languages are really only useful as a way of specifying rules to an XML validation engine. Database schemas and programming language class models provide similarly poor representations of logical data models.

A good logical data modelling format should allow the information about code lists to be expressed in a format that is as simple and unambiguous as possible.

4Possible Features of Code List Data Models

What follows is a list of some of the features that a code list data model could provide. It is important to note that a first cut code list data model for UBL would certainly not have all of these features. However, future versions might introduce more of these features as appropriate.

A list of the values (codes) for a code list;
Multiple lists of equivalents values (codes) for a code list (e.g. integers & mnemonics);
Unique identifiers for a code list;
Unique identifiers for individual values of a code list;
Names for a code list;
Documentation for a code list;
Documentation for individual values of a code list;
The ability to import, extend, and/or restrict other code lists;
Support for describing code lists that cannot be enumerated, either because of size, volatility, or proprietary restrictions (e.g. a WSDL description of a Web service that can validate which of a set of codes are members of a particular code list);
Support for references to equivalent code lists;
Support for individual values to be mapped to equivalent values in other code lists;
Support for users to attach their own metadata to a code list;
Support for users to attached their own metadata to individual values of a code list;
Support for describing the past and future time-variance of the values of a code list (see, for example, “Patterns for things that change with time”,

5A Simple Code List Data Model for UBL 1.0

6Example code list data model in XML (country identification codes)

<?xml version="1.0" encoding="UTF-8"?>

<CodeList xsi:noNamespaceSchemaLocation="ubl-code-list.xsd" xmlns:xsi="

<CanonicalUri>urn:oasis:names:tc:ubl:codelist:CountryIdentificationCode:1:0-beta</CanonicalUri>

<CreditText>The code values in this file are derived from the ISO 3166-1-alpha-2

code elements list found at

and are used under the terms of the ISO policy stated at

</Enumeration>

</Enumeration>

</Enumeration>

</Enumeration>

</Enumeration>

</Enumeration>

</Enumeration>

</EnumerableList>

</CodeList>

7Example W3C XML Schema for code list data model

<?xml version = "1.0" encoding = "UTF-8"?>

<xsd:schema xmlns:xsd = "

elementFormDefault = "qualified">

<xsd:element name = "CodeList">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref = "CanonicalUri"/>

<xsd:element ref = "CodeListQualifier"/>

<xsd:element ref = "CodeListAgency"/>

<xsd:element ref = "CodeListVersion"/>

<xsd:element ref = "CreditText" minOccurs = "0"/>

<xsd:element ref = "EnumerableList"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>

<xsd:element name = "CanonicalUri" type = "xsd:anyURI"/>

<xsd:element name = "CodeListQualifier" type = "xsd:string"/>

<xsd:element name = "CodeListAgency" type = "xsd:string"/>

<xsd:element name = "CodeListVersion" type = "xsd:string"/>

<xsd:element name = "CreditText" type = "xsd:string"/>

<xsd:element name = "EnumerableList">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref = "Enumeration" minOccurs = "0" maxOccurs = "unbounded"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>

<xsd:element name = "Enumeration">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref = "Value"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>

<xsd:element name = "Value" type = "xsd:string"/>

</xsd:schema>

8XSLT 2.0 script to convert code list model into UBL XML Schema

<?xml version = "1.0" encoding = "UTF-8"?>

<xsl:transform xmlns:xsd=" xmlns:ccts="urn:oasis:names:tc:ubl:CoreComponentParameters:1:0-beta" xmlns:xsl = " version = "2.0">

<xsl:output method="xml" indent="yes" encoding="UTF-8"/>

<xsl:template match="/">

<xsl:comment>

Universal Business Language (UBL) Schema 1.0-beta

This document and translations of it may be copied and furnished to others, and

derivative works that comment on or otherwise explain it or assist in its

implementation may be prepared, copied, published and distributed, in whole or

in part, without restriction of any kind, provided that the above copyright

notice and this paragraph are included on all such copies and derivative works.

However, this document itself may not be modified in any way, such as by

removing the copyright notice or references to OASIS, except as needed for the

purpose of developing OASIS specifications, in which case the procedures for

copyrights defined in the OASIS Intellectual Property Rights document must be

followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by

OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS"

basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT

LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT

INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR

A PARTICULAR PURPOSE.

======

For our absent friend, Michael J. Adcock - il miglior fabbro

======

Universal Business Language Specification

(

OASIS Open (

======

Document Type: CodeList-cnt

Generated On: **** TO-DO ****

Category: **** Demo Only ****

======

Code List Source Information:

Code List Qualifier: <xsl:value-of select="/CodeList/CodeListQualifier"/>

Code List Agency: <xsl:value-of select="/CodeList/CodeListAgency"/>

Code List Version: <xsl:value-of select="/CodeList/CodeListVersion"/>

======

Credits: <xsl:value-of select="/CodeList/CreditText"/>

======

Values enclosed in square-bracket "[" and "]" are subject to change

in future draft, minor or major revisions, and are non-normative.

</xsl:comment>

<xsd:schema version="1:0-beta"

targetNamespace="{/CodeList/CanonicalUri}"

elementFormDefault="qualified" attributeFormDefault="unqualified"

<xsl:namespace name=""<xsl:value-of select="/CodeList/CanonicalUri"/</xsl:namespace>

<xsl:namespace name="cnt"<xsl:value-of select="/CodeList/CanonicalUri"/</xsl:namespace>

<xsl:namespace name="rt">urn:oasis:names:tc:ubl:RepresentationTerms:1:0-beta</xsl:namespace>

<xsd:import namespace="urn:oasis:names:tc:ubl:CoreComponentParameters:1:0-beta"

schemaLocation="../../common/UBL-CoreComponentParameters-1.0-beta.xsd" />

<xsd:import namespace="urn:oasis:names:tc:ubl:RepresentationTerms:1:0-beta"

schemaLocation="../../common/UBL-RepresentationTerms-1.0-beta.xsd" />

<xsd:element name="DerivedCode" type="cnt:DerivedCodeType" />

<xsd:complexType name="DerivedCodeType">

<xsd:annotation>

<xsd:documentation>

<ccts:Instance>

<xsl:comment> Data and values stored in this space are meant for instance-processing purposes, and are non-normative. </xsl:comment>

<ccts:Prefix>cnt</ccts:Prefix>

<ccts:CodeListQualifier<xsl:value-of select="/CodeList/CodeListQualifier"/</ccts:CodeListQualifier>

<ccts:CodeListAgency<xsl:value-of select="/CodeList/CodeListAgency"/</ccts:CodeListAgency>

<ccts:CodeListVersion<xsl:value-of select="/CodeList/CodeListVersion"/</ccts:CodeListVersion>

</ccts:Instance>

</xsd:documentation>

</xsd:annotation>

<xsd:simpleContent>

<xsd:restriction base="rt:CodeType">

<xsl:apply-templates select="/CodeList/EnumerableList/Enumeration"/>

</xsd:restriction>

</xsd:simpleContent>

</xsd:complexType>

</xsd:schema>

</xsl:template>

<xsl:template match="Enumeration">

<xsd:enumeration value="{Value}"/>

</xsl:template>

</xsl:transform>

9Resultant UBL code list Schema

<?xml version="1.0" encoding="UTF-8"?<!--