[Accessibility conventions are described at the bottom of the page]

2. Defining and using controlled vocabularies
[> 3.][< 1.1.10][^^^]
2.0 Controlled value list maintenance and identity
[> 2.0.1][> 2.1][> 3.][< 2.][^^][^^^]
A list of values has an identity in the abstract, regardless of how it is maintained
[[1] - e.g. ISO 3166-1 country codes
 [1] - e.g. UN/ECE 4461 payment means codes
 [1] - e.g. UBL 2.0 document status codes
]
The complete list may be maintained by hand or by a database or by any means
[[1] - the management of the values is important to long-term maintenance
 [1] - some lists may have tens of thousands of entries (e.g. vehicle model codes)
 [1] - a list may be synthesized by an algorithmic process
[[2] - e.g. the 100 ISBN numbers assigned to publisher "978-1-894049"
]]
The concrete expressions of the lists may vary based on purpose or contextual use
[[1] - e.g. complete lists
 [1] - e.g. restricted subset lists
 [1] - each list and list subset expression must necessarily be uniquely identified
[[2] - a subset of a list cannot have the same identity as the complete list otherwise there would be confusion regarding which list is the "true" list
 [2] - identity can be expressed as meta data for the list or list subset
][1] - the concrete expression may take any useful form for the user
[[2] - e.g. simple text
 [2] - e.g. comma-separated values
 [2] - e.g. XML files
 [2] - having a standardized representation of lists would encourage the development of more widely-useful applications
]]
The sender and receiver may have different identities for a list of identical values
[[1] - e.g. the sender specifies an ISO country code
[[2] - the meta data for the list is that of the complete list
][1] - e.g. the receiver only accepts a subset of ISO country codes as valid
[[2] - the meta data for the subset list is necessarily different than that of the complete list
 [2] - for validation purposes the subset list must masquerade as the complete list yet reject specified values outside of the subset list
]]
2.0.1 Controlled value specification
[> 2.1][> 3.][< 2.0][^][^^][^^^]
A controlled value is, in fact, a multi-faceted value
[[1] - the list from which the code value is obtained
[[2] - described by meta data for the list
 [2] - the list identification itself may be multi-faceted
][1] - the key code value itself
[[2] - unique within any given list
][1] - properties (value-level meta data) of the values themselves
[[2] - helpful in understanding the semantics of the key code value
]]
When an information item can be populated with a coded value, it should also be possible to specify the associated value list meta data
[[1] - even very stable lists of values will change over time
[[2] - one may need to specify a chronologically-distinct interpretation of a given value
 [2] - e.g. the list of provinces in Canada changed in 1999 when the Northwest Territories was split into two territories: Nunavut and the Northwest Territories
[[3] - the Canadian postal province and territories indication of the Northwest Territories was and remains "NT" even though the definition of the territory changed
 [3] - if the distinction is important to a trading partner, then provision for making the distinction must be made available
][2] - e.g. the list of country codes changes frequently
[[3] - before 2003 "CS" represented Czechoslovakia and since 2006 "CS" is reserved for Serbia and Montenegro
]][1] - one information item value may be an item selected from one of a number of lists
[[2] - if all of the values are mutually exclusive in separate lists, there is no risk of confusion other than changes over time for any given list as noted above
 [2] - if the values in the lists are not mutually exclusive, meta data is required to disambiguate an ambiguous specified value
]]
The risk is borne by the party encoding the information that the recipient can properly decode the intent expressed by the information
[[1] - list meta data is often optional and is often ignored when coded values are specified
 [1] - the more specific a specification is, the less opportunity for improper understanding of the intended meaning
]
2.1 XML value specification and validation
[> 2.2][< 2.0.1][^^][^^^]
2.1.1 Controlled XML information item value specification
[> 2.1.2][> 2.2][> 3.][< 2.0.1][^^][^^^]
Lists evolve over time and are published in many versions
[[1] - different versions of lists have different available values
 [1] - a different version of a list may redefine an old value as having a new meaning
]
One needs to be able to specify both the coded value and any associated list-level meta data
[[1] - necessitates a compound structure in the XML markup for instance-level meta data
 [1] - the recipient can then disambiguate a value determined to be ambiguous
[[2] - ambiguous because the value exists in two different lists thus with two different semantic associations
][1] - without the information there is a risk the recipient misinterprets the sender's intent
]
E.g. UN/CEFACT Core Component Technical specification (CCTS)
[[1] - unqualified data types provide for varying amounts of instance-level meta data for different code and identifier information items
 [1] - e.g. UBL uses CCTS unqualified data types and inherits its code and identifier meta data
 [1] - a given coded information item may be an element or may be an attribute
 [1] - decision to use attached attributes to capture the associated instance-level meta data
[[2] - UN/CEFACT determined that not all lists need wide-ranging flexibility in associated code list identification meta data
]]
There may need to be a strategy to omit meta data from a value
[[1] - an application may anticipate the future standardization of a value
[[2] - in the short term the value can be defined in an ad hoc list used in conjunction with the old standardized list
 [2] - avoiding meta data avoids asserting the new value is in any standardized list, as the standardized list meta data might trigger a constraint violation
 [2] - when the new publication of the revised list has the new value, the ad hoc list can be abandoned
][1] - runs the risk that future standardization does, in fact, use the anticipated value for the anticipated semantic
]
2.1.2 Document context
[> 2.1.3][> 2.2][> 3.][< 2.1.1][^][^^][^^^]
An important aspect of XML structure is the hierarchical document context for an item
[[1] - a labeled information item at one place in the document tree has a different meaning than an identically-labeled information item found elsewhere in the document tree
]
Document context can be widely specified (by scope) or narrowly specified (by address)
[[1] - consider the following example where all uses of currencyID= happen allow the same set of currency values (though in practice this may not indeed be a business case)
 [1] - consider that the controlled values for <cbc:ID> information item are different when the item is a child of <cac:TaxCategory> than when a child of <cac:TaxScheme>
[[2] - the label is the same but the meaning is different
]]
[Example 2-1: An illustration of document context
01  <cac:TaxSubTotal>
02   <cbc:TaxableAmount currencyID="USD">100.00</cbc:TaxableAmount>
03   <cbc:TaxAmount currencyID="USD">15.00</cbc:TaxAmount>
04   <cac:TaxCategory>
05   <cbc:ID>Z</cbc:ID>
06   <cbc:Percent>15</cbc:Percent>
07   <cac:TaxScheme>
08   <cbc:ID>Provincial Tax</cbc:ID>
09   </cac:TaxScheme>
10   </cac:TaxCategory>
11  </cac:TaxSubTotal>
]
Partial-document context specification is needed for documents interchanged between trading partners
[[1] - the business rules for the same information item in different document contexts may be different thus requiring different value validation constraints
[[2] - structural constraints are unchanged and are reliably validated against the document structure
]]
W3C schema enumerated data types assigned to globally-defined constructs only have document-wide context
[[1] - this makes W3C schema enumerations unsuitable for some business document validation
]
2.1.3 Controlled value information item validation
[> 2.1.4][> 2.2][> 3.][< 2.1.2][^][^^][^^^]
Structural, lexical and value validation distinction in regard of business/value rules
[[1] - constraining an information item to its place in the structural hierarchy and in its lexical structure is typically independent of business/value rules
[[2] - suitable to put such constraints in a published and standardized read-only schema
 [2] - esoteric structure requirements can be expressed if necessary as a business rule
[[3] - e.g. "for addresses in the US, the building name cannot be specified"
]][1] - constraining the value of an information item can be very dependent on trading partner business/value rules
[[2] - e.g. list of account identifiers
 [2] - e.g. list of acceptable currency codes
 [2] - unsuitable to put such constraints in a published and standardized read-only schema
 [2] - value constraints should be layered on top of structural and lexical constraints so they can be modified without modifying the structural constraints
 [2] - the structural and lexical constraints are still obligatory as the value constraints mean nothing if the structural and lexical constraints are violated
]]
Direct program validation
[[1] - traditional programming practice leaves structural, lexical and value constraint checking to individual programs
[[2] - modularization of code provided compatibility between applications
 [2] - applications based on different code needed different implementations
 [2] - applications written by different parties employed different implementations
 [2] - opportunities abound for inconsistencies in the implementations of constraint checking
[[3] - errors in implementation
 [3] - errors in interpretation of requirements
]][1] - programs need to reflect (possibly changing) trading partner relationships
[[2] - maintenance required for business reasons as well as technical reasons
]]
Outboard validation
[[1] - traditional XML document validation implements structural and lexical constraint checking using schema expressions
[[2] - an outboard schema expression describes the constraints
 [2] - publicly-available code fragments implement constraint checking
][1] - traditional XML document validation implements value checking using schema expressions
[[2] - enforces document-wide context on globally-defined constructs which may be inappropriate for trading partner business rules
][1] - necessary to abandon traditional value checking and utilize a layered approach
[[2] - changing the value constraints does not change the structural and lexical constraints
 [2] - trading partners can tailor the value constraints to business requirements
][1] - simplified program development can support all codes
[[2] - the outboard validation serves as a filter for messages changing their nature
[[3] - program maintenance reduced to only technical reasons
 [3] - business reasons expressed in value validation
]]]
2.1.4 Layered constraints on business documents
[> 2.2][> 3.][< 2.1.3][^][^^][^^^]
Many parties contribute to the value validation requirements of business documents
[[1] - illustrated by the requirements of UBL, a UBL customization and trading-partner-specific value constraints
[[2] - UBL publishes a set of W3C schemas for structural and lexical constraints on values
 [2] - UBL publishes a set of value constraints on particular information items
[[3] - e.g. document status codes
][2] - a user community (e.g. the country of Denmark, the North European Subset, etc.) publishes a set of value constraints on particular information items
[[3] - e.g. payment means codes
][2] - trading partners publish a set of value constraints on particular information items
[[3] - e.g. account identifiers
]]]
[Figure 2.1: Layered application of value constraints
At the top a concentric tube labeled "UBL code list value specification" surrounds a circle labeled "UBL structural and lexical specification".
Below that is a similar diagram with the same components, but the tube is surrounded by another touching tube labeled "Customization code list value specification".
Below that is a similar diagram with the same components, but the outermost tube is surrounded by yet another touching tube labeled "Trading partner code list/identifier value specification". This outermost tube is cut in half, the left identified as "T1" and connected with a similar set of circles and tubes representing the implementation of trading partner 1, and the right identified as "T2" and connected with a similar set of circles and tubes representing the implementation of trading partner 2.
]
2.2 Example: controlled vocabularies in UBL
[> 2.3][< 2.1.4][^^][^^^]
2.2.1 Example: controlled vocabularies in UBL
[> 2.3][> 3.][< 2.1.4][^^][^^^]
The Universal Business Language (UBL) model is an example to be followed by other vocabularies
[[1] - characterized by the need for trading-partner flexibility and community definition
]
Structural and lexical constraint validation is standardized and supplied
[[1] - published normative W3C Schema expressions
]
UBL provides a non-normative starter kit of sets of code lists for only a few coded values
[[1] - trading partners should maintain compatibility with the starter kit of code lists
[[2] - when possible only use extension and restriction of starter codes rather than replacement
 [2] - a closed community of users may choose to use only their exclusive sets of values
][1] - trading partner code lists can use or build on the UBL code lists
 [1] - no starter sets for identifiers are provided
[[2] - up to trading partners to decide what identifiers are meaningful in their exchanges
][1] - many lists are defined by UBL as empty
[[2] - trading partners can use the empty shells to create their own agreed-upon set of values
][1] - a small number of predefined lists are supplied
[[2] - easily-agreed-upon immutable concepts such as arithmetic operators and compass directions
 [2] - starter sets of basic concepts such as document status
 [2] - compatibility sets of imported enumerations
[[3] - UBL has adopted the Core Components Technical Specification XSD schemas
 [3] - schemas are supplied with built-in XSD enumerations
]]]
Starter value validation is supplied for the starter kit of sets of codes
[[1] - the default validation supplied as part of the UBL package is only for code list coded values for those code lists for which the UBL TC provides values
 [1] - no use of document context, thus mimicking document-wide XSD schema validation
]
UBL also supplies code lists of values that are not engaged by default
[[1] - available in case they are of use to certain trading partners
 [1] - e.g. shipping container sizes/types and location codes
]
Predefined lists of codes are provided for immutable concepts
[[1] - e.g. arithmetic operators (multiply and divide)
 [1] - e.g. compass directions (north, south, east and west)
]
Predefined lists of codes are provided for basic concepts
[[1] - e.g. document status (cancelled, disputed, revised, etc.)
 [1] - e.g. line status (cancelled, disputed, revised, etc.)
 [1] - e.g. chip code (chip vs. magnetic stripe)
]
Predefined lists of codes are provided for published reference lists
[[1] - e.g. payment means (cash, cheque, credit card, etc.)
 [1] - e.g. channel codes (internal mail, postbox number, electronic mail, etc.)
 [1] - e.g. packaging codes (box, drum, bag, bunch, etc.)
 [1] - e.g. transport mode (maritime, rail, road, multimodal, etc.)
]
Non-extensible lists of codes are provided for CCTS supplementary components
[[1] - CCTS assumes the following values are checked using schema-expressed enumerations
[[2] - currencies for amounts (CAD, USD, GBP, DKK, etc.)
 [2] - units of measure for quantities and measures (meter, square meter, cubic meter, etc.)
 [2] - MIME types for binary objects (image/jpeg, image/naplps, application/pdf, etc.)
][1] - trading partners can constrain these sets of values to smaller sets of values
[[2] - these sets cannot be augmented to include values not in the hardwired schema-expressed lists
 [2] - any augmentation would trigger schema validation errors
][1] - anticipating in UBL 2.1 that CCTS code lists will be extensible
[[2] - removing W3C schema code list enumerations
]]
Available code lists for interested parties
[[1] - shipping container types and sizes
 [1] - location codes (rail, road, IATA, etc.)
]
All other code lists and identifiers are declared in the schema with only the lexical constraint of being a normalized string, and without declaring a bounded set of values
[[1] - a "normalized string" is a string where consecutive sequences of white-space characters are replaced with a single space character
[[2] - white-space characters in parsed XML are space, tab, carriage-return and linefeed
][1] - trading partners can agree on any set of coded values to use for a given information item
[[2] - provided the values are lexically acceptable for a normalized string
]]
defaultCodeList.xsl provides code list conformance validation supporting the following:
[[1] - with the corresponding genericode file name in the UBL 2.0 delivery
 [1] - UN/ECE Recommendation 19 Transport Mode Code
[[2] -
cl/gc/default/TransportModeCode-2.0.gc
 [2] - incorrectly documented in UBL 2.0 files as recommendation 16
][1] - UN/ECE Recommendation 20 Unit of Measure Codes
[[2] -
cl/gc/cefact/UnitOfMeasureCode-2.0.gc
][1] - UN/ECE Recommendation 21 Packaging Type Code
[[2] -
cl/gc/default/PackagingTypeCode-2.0.gc
][1] - UN/ECE Recommendation 24 Transportation Status Codes
[[2] -
cl/gc/default/TransportationStatusCode-2.0.gc
][1] - UN/ECE 3155 Communication Address Code Qualifier
[[2] -
cl/gc/default/ChannelCode-2.0.gc
][1] - UN/ECE 4461 Payment Means
[[2] -
cl/gc/default/PaymentMeansCode-2.0.gc
][1] - UN/ECE 4465 Adjustment Reason Description
[[2] -
cl/gc/default/AllowanceChargeReasonCode-2.0.gc
][1] - UN/ECE 8053 Equipment Type Code Qualifier
[[2] -
cl/gc/default/TransportEquipmentTypeCode-2.0.gc
][1] - IANA_7_04 Binary Object MIME Code
[[2] -
cl/gc/cefact/BinaryObjectMimeCode-2.0.gc
][1] - ISO 3166-1 Country Codes
[[2] -
cl/gc/default/CountryIdentificationCode-2.0.gc
][1] - ISO 4217 Alpha Currency Codes
[[2] -
cl/gc/cefact/CurrencyCode-2.0.gc
][1] - UBL chip codes
[[2] -
cl/gc/default/ChipCode-2.0.gc
][1] - UBL document status codes
[[2] -
cl/gc/default/DocumentStatusCode-2.0.gc
][1] - UBL latitude direction codes
[[2] -
cl/gc/default/LatitudeDirectionCode-2.0.gc
][1] - UBL line status codes
[[2] -
cl/gc/default/LineStatusCode-2.0.gc
][1] - UBL longitude direction codes
[[2] -
cl/gc/default/LongitudeDirectionCode-2.0.gc
][1] - UBL operator codes
[[2] -
cl/gc/default/OperatorCode-2.0.gc
][1] - UBL substitution codes
[[2] -
cl/gc/default/SubstitutionStatusCode-2.0.gc
]]
2.3 Declarations of controlled vocabularies
[> 3.][< 2.2.1][^^][^^^]
2.3.1 Declaration techniques
[> 2.3.2][> 3.][< 2.2.1][^^][^^^]
UBL 2.0 illustrates different ways of declaring coded value constraints
[[1] - described in the UBL Naming and Design Rules (NDR)
[[2] - NDR rules govern the synthesis of W3C Schema XSD expressions of model constraints
][1] - 91 code lists cover 98 code list-based information items in the library
[[2] - 18 code lists have defined constrained values
 [2] - 73 code lists are meta-data only and unconstrained
][1] - W3C schema-declared enumerations inherited from UN/CEFACT CCTS approach to base types
[[2] - suitable only for restricting by externally-specified values
][1] - declaration of unconstrained code list-based information item data type
[[2] - suitable for extending and restricting by externally-specified values
][1] - declaration of unconstrained identifier-based information item data type
[[2] - suitable for extending and restricting by externally-specified values
][1] - layered application of genericode-declared enumerations of code lists for values
[[2] - a suitable document format for externally-specified values
]]
UBL 2.1 will be taking the UN/CEFACT lists out of the W3C schema XSD files
[[1] - already some of the lists are out of date because they are explicitly codified
 [1] - using a single approach for all code lists will help keep deployments more consistent
 [1] - abandoning the schema-based approach will help keep deployments more flexible
]
2.3.2 UN/CEFACT controlled-vocabulary declarations
[> 2.3.3][> 3.][< 2.3.1][^][^^][^^^]
W3C schema-declared enumerations of code list-based information item data types
The UBL TC committee agreed to utilize UN/CEFACT CCTS unqualified data types "off-the-shelf"
[[1] - UN/CEFACT ATG definitions of types are published using W3C schema enumerations
[[2] - e.g. the unqualified data type AmountType has a currencyID= attribute
[[3] - constrained by the CurrencyCodeContentType enumerated data type
]][1] - only three W3C schema enumerations are used
[[2] - currency codes of amounts, MIME type codes of binary objects, units of measure for quantities and measures
][1] - one W3C schema enumeration is provided in the UN/CEFACT fragments but is not used
[[2] - language code
][1] - see [Instance-level meta data in XML instances - Section 2.3.6 Instance-level meta data in XML instances] for an overview of UN/CEFACT code list meta data
]
Excerpt from http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/common/CodeList_CurrencyCode_ISO_7_04.xsd:
[Example 2-2:
01    <xsd:simpleType name="CurrencyCodeContentType">
02   <xsd:restriction base="xsd:token">
03   <xsd:enumeration value="AED">
04   <xsd:annotation>
05   <xsd:documentation>
06   <ccts:CodeName>Dirham</ccts:CodeName>
07   <ccts:CodeDescription></ccts:CodeDescription>
08   </xsd:documentation>
09   </xsd:annotation>
10   </xsd:enumeration>
11   <xsd:enumeration value="AFN">
12   <xsd:annotation>
13   <xsd:documentation>
14   <ccts:CodeName>Afghani</ccts:CodeName>
15   <ccts:CodeDescription></ccts:CodeDescription>
16   </xsd:documentation>
17   </xsd:annotation>
18   </xsd:enumeration>
19   <xsd:enumeration value="ALL">
20   <xsd:annotation>
21   <xsd:documentation>
22   <ccts:CodeName>Lek</ccts:CodeName>
23   <ccts:CodeDescription></ccts:CodeDescription>
24   </xsd:documentation>
25   </xsd:annotation>
26   </xsd:enumeration>
27   <xsd:enumeration value="AMD">
28   ...
]
2.3.3 UN/CEFACT instance-level meta data
[> 2.3.4][> 3.][< 2.3.2][^][^^][^^^]
CCTS 2.01 declaration of unconstrained code list-based information item data type
All other code lists are declared only with lexical constraints, not with value constraints
[[1] - the lexical structure of the text value is constrained to be a normalized string
[[2] - no leading spaces, no trailing spaces, all sequences of white-space characters are only a single space each
][1] - meta data attributes identify the code list in which the value is found and defined
]
Excerpt from http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/common/UnqualifiedDataTypeSchemaModule-2.0.xsd:
[[1] - instance-level meta data is defined by UN/CEFACT and utilized unchanged by UBL
]
[Example 2-3:
01    <xsd:complexType name="CodeType">
02   <xsd:annotation>
03   <xsd:documentation xml:lang="en">
04   ...
05   </xsd:documentation>
06   </xsd:annotation>
07   <xsd:simpleContent>
08   <xsd:extension base="xsd:normalizedString">
09   <xsd:attribute name="listID" type="xsd:normalizedString"
10   use="optional"/>
11   <xsd:attribute name="listAgencyID"
12   type="xsd:normalizedString" use="optional"/>
13   <xsd:attribute name="listAgencyName" type="xsd:string"
14   use="optional"/>
15   <xsd:attribute name="listName" type="xsd:string"
16   use="optional"/>
17   <xsd:attribute name="listVersionID"
18   type="xsd:normalizedString" use="optional"/>
19   <xsd:attribute name="name" type="xsd:string"
20   use="optional"/>
21   <xsd:attribute name="languageID" type="xsd:language"
22   use="optional"/>
23   <xsd:attribute name="listURI" type="xsd:anyURI"
24   use="optional"/>
25   <xsd:attribute name="listSchemeURI" type="xsd:anyURI"
26   use="optional"/>
27   </xsd:extension>
28   </xsd:simpleContent>
29   </xsd:complexType>
]
Declaration of unconstrained identifier-based information item data type
Identifiers are constrained very similarly to coded values
[[1] - lexically constrained to be a normalized string
 [1] - meta data attributes identify the scheme by which the identifier is constructed or enumerated
]
Excerpt from http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/common/UnqualifiedDataTypeSchemaModule-2.0.xsd:
[[1] - instance-level meta data is defined by UN/CEFACT and utilized unchanged by UBL
]
[Example 2-4:
01   <xsd:complexType name="IdentifierType">
02   <xsd:annotation>
03   <xsd:documentation xml:lang="en">
04   ...
05   </xsd:documentation>
06   </xsd:annotation>
07   <xsd:simpleContent>
08   <xsd:extension base="xsd:normalizedString">
09   <xsd:attribute name="schemeID" type="xsd:normalizedString"
10   use="optional"/>
11   <xsd:attribute name="schemeName" type="xsd:string"
12   use="optional"/>
13   <xsd:attribute name="schemeAgencyID"
14   type="xsd:normalizedString" use="optional"/>
15   <xsd:attribute name="schemeAgencyName" type="xsd:string"
16   use="optional"/>
17   <xsd:attribute name="schemeVersionID"
18   type="xsd:normalizedString" use="optional"/>
19   <xsd:attribute name="schemeDataURI" type="xsd:anyURI"
20   use="optional"/>
21   <xsd:attribute name="schemeURI" type="xsd:anyURI"
22   use="optional"/>
23   </xsd:extension>
24   </xsd:simpleContent>
25   </xsd:complexType>
]
2.3.4 Genericode controlled-vocabulary declarations
[> 2.3.5][> 3.][< 2.3.3][^][^^][^^^]
Genericode-declared enumerations of code lists
[[1] - synthesized and managed outside of any structural and lexical constraint expression
]
Excerpt from http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/default/PaymentMeansCode-2.0.gc:
[Example 2-5: Genericode excerpt
01  <gc:CodeList xmlns:gc="http://docs.oasis-open.org/
02  codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName>PaymentMeansCode</ShortName>
05   <LongName xml:lang="en">Payment Means</LongName>
06   <LongName Identifier="listID">UN/ECE 4461</LongName>
07   <Version>D03A</Version>
08   <CanonicalUri>urn:oasis:names:specification:ubl:codelist:gc:
09  PaymentMeansCode</CanonicalUri>
10   <CanonicalVersionUri>urn:oasis:names:specification:ubl:codelist:
11  gc:PaymentMeansCode-2.0</CanonicalVersionUri>
12   <LocationUri>http://docs.oasis-open.org/ubl/os-ubl-2.0/cl/gc/
13  default/PaymentMeansCode-2.0.gc</LocationUri>
14   <Agency>
15   <LongName xml:lang="en">United Nations Economic Commission for
16  Europe</LongName>
17   <Identifier>6</Identifier>
18   </Agency>
19   </Identification>
20   ...
21   <SimpleCodeList>
22   ...
23   <Row>
24   <Value ColumnRef="code">
25   <SimpleValue>2</SimpleValue>
26   </Value>
27   <Value ColumnRef="name">
28   <SimpleValue>Automated clearing house credit</SimpleValue>
29   </Value>
30   </Row>
31   <Row>
32   <Value ColumnRef="code">
33   <SimpleValue>3</SimpleValue>
34   </Value>
35   <Value ColumnRef="name">
36   <SimpleValue>Automated clearing house debit</SimpleValue>
37   </Value>
38   </Row>
39   ...
40   </SimpleCodeList>
41  </gc:CodeList>
]
2.3.5 Examples and locations of UBL code list definitions
[> 2.3.6][> 3.][< 2.3.4][^][^^][^^^]
Many UBL information items are described by code lists
[[1] - [http://docs.oasis-open.org/ubl/os-UBL-2.0-update/cl/gc/]
 [1] - support for a prescribed collection of lists is provided by UBL TC
[[2] - validated using http://docs.oasis-open.org/ubl/os-UBL-2.0/val/defaultCodeList.xsl
][1] - a constrained set of CCTS-specified values available only to be restricted
[[2] - [http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/cefact/] directory
 [2] - e.g. Currency_ Code. Type
[[3] - initially defined set of values to be all currencies of the world
]][1] - a predefined set of values available to be supplemented or restricted
[[2] - [http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/default/] directory
 [2] - e.g. Document Status_ Code. Type
[[3] - values "Cancelled", "Disputed", "NoStatus", and "Revised"
][2] - e.g. Payment Means_ Code. Type
[[3] - values "10" (cash), "20" (cheque), etc.
]][1] - a limited set of values unlikely to be changed
[[2] - [http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/default/] directory
 [2] - e.g. Latitude Direction_ Code. Type
[[3] - values "North" and "South"
][2] - e.g. Longitude Direction_ Code. Type
[[3] - values "East" and "West"
]][1] - no predefined values but available to be defined between trading partners
[[2] - [http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/default/] directory
 [2] - e.g. Code. Type for Invoice. Invoice_ Type. Code
 [2] - by far most of the code lists are defined only with meta data in this fashion
 [2] - from a theoretical perspective, these lists are the lists of all possible codes
[[3] - when two trading partners agree on a set of codes for these lists, they are in fact restricting the infinite set of codes to a finite set of codes
]][1] - predefined values available to trading partners but not engaged by default
[[2] - [http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/special-purpose/] directory
 [2] - not all users of UBL need these codes, but if they are available if needed
 [2] - e.g. Container Size Type_ Code. Type
]]
2.3.6 Instance-level meta data in XML instances
[> 2.3.7][> 3.][< 2.3.5][^][^^][^^^]
One can qualify the value for an information item defined by a code list or identifier
[[1] - the qualification is accomplished using meta data attributes on the element with the value
 [1] - all meta data is optional
]
Easiest (but riskiest) not to use instance-level meta data with codes
[[1] - most uses of codes do not need to be disambiguated
 [1] - recommended to use instance-level meta data if values from different lists are ambiguous
]
One can specify only as much instance-level meta data as desired
[[1] - it does not have to be "all or nothing"
 [1] - adding meta data to the value makes the specification of the value more distinguished for the sender
[[2] - the sender is intending to distinguish the value as being not just any value but a particular value from a list so identified
][1] - adding meta data to the value makes the validation of the value more stringent for the recipient
[[2] - the recipient can ensure that the value received isn't just any value but is a particular value from an expected code list
][1] - validation of items without meta data is purposely lax so as not to require meta data be specified
[[2] - validation of meta data only happens in the presence of meta data
]]
Specifying no meta data can be a strategy
[[1] - in anticipation of an as-yet-added entry to a standardized list
 [1] - the future extension can be specified in an ad hoc list that extends the standard list
 [1] - by not specifying meta data, validation does not attempt to constrain from which list the value is obtained
 [1] - once the standard list incorporates the new value, the ad hoc list can be abandoned
]
Consider the difference between the two following values in a UBL instance:
[[1] - country code example: CS
[[2] - prior to 2003 this represented Czechoslovakia
[[3] - codes used now are CZ for Czech Republic and SK for Slovakia
 [3] - simple retiring of one code and birth of two new codes
][2] - as of 2006 the country code "CS" has been reserved for Serbia and Montenegro
[[3] - not so simple change in the semantics with the re-use of the same code
]][1] - country sub-entity code example of Canadian territories:
[[2] - not so simple change in the semantics with the re-use of the same code
 [2] - <CountrySubentityCode listVersionID="1">NT</CountrySubentityCode>
 [2] - <CountrySubentityCode listVersionID="2">NT</CountrySubentityCode>
][1] - not specifying a version would make the value ambiguous
[[2] - <CountrySubentityCode>NT</CountrySubentityCode>
]]
Instance-level meta data is needed to specify the appropriate associated list-level meta data
[[1] - specifying the version of the list ensures a sending application that a distinction is being made with a clear specification of precisely which semantics associated with the given value are intended
 [1] - detecting the version of the list would ensure that a receiving application is aware of the distinction being specified to know precisely which semantics are intended
]
The instance-level meta data varies slightly for UN/CEFACT-defined unqualified data types
[[1] - inherited by those UBL information items derived from CCTS unqualified types
 [1] - the core component value is the value of the element
 [1] - the supplementary component value is an attribute of the element
 [1] - the meta data values are in other attributes of the same element
 [1] - for currencyID= of amounts
[[2] - currencyCodeListVersionID=
[[3] - mapped in CVA2sch to genericode <Version>
]][1] - for unitCode= of the <MeasureType> element
[[2] - unitCodeListVersionID=
[[3] - mapped in CVA2sch to genericode <Version>
]][1] - for unitCode= of the <QuantityType> element
[[2] - unitCodeListID=
[[3] - mapped in CVA2sch to genericode <Version>
][2] - unitCodeListAgencyID=
[[3] - mapped in CVA2sch to genericode <Agency><Identifier>
][2] - unitCodeListAgencyName=
[[3] - mapped in CVA2sch to genericode <Agency><LongName>
]]]
Consider how currency values are entered in a UBL instance
[[1] - e.g. <cbc:Amount currencyID="RON">10.00</cbc:Amount>
[[2] - specifies an amount of 10 Romanian new leu
 [2] - no instance level meta data is included in the element specification
 [2] - the recipient must make an assumption about which code list the value comes from
][1] - e.g. <cbc:Amount currencyID="RON" currencyCodeListVersionID="1951">10.00</cbc:Amount>
[[2] - first Romanian leu in 1867
 [2] - Romanian new leu "RON" in 1947
 [2] - in 1952 "RON" was replaced with "ROL" for Romanian leu
 [2] - in 2005 "ROL" was replaced with "RON" for Romanian new leu
 [2] - 1 RON(2005) is worth over 200,000 RON(1951)
]]
UBL-defined code list element meta data attributes summarized from [Example 2-3]
[[1] - listID=
[[2] - mapped in CVA2sch to genericode <LongName @Identifier='listID'> or just the first <LongName>
][1] - listAgencyID=
[[2] - mapped in CVA2sch to genericode <Agency><Identifier>
][1] - listAgencyName=
[[2] - mapped in CVA2sch to genericode <Agency><LongName>
][1] - listName=
[[2] - mapped in CVA2sch to genericode first <LongName>
][1] - listVersionID=
[[2] - mapped in CVA2sch to genericode <Version>
][1] - listURI=
[[2] - mapped in CVA2sch to genericode <LocationUri>
][1] - listSchemeURI=
[[2] - mapped in CVA2sch to genericode <CanonicalVersionUri>
]]
UBL-defined identifier element meta data attributes summarized from [Example 2-4]
[[1] - schemeAgencyID=
[[2] - mapped in CVA2sch to genericode <Agency><Identifier>
][1] - schemeAgencyName=
[[2] - mapped in CVA2sch to genericode <Agency><LongName>
][1] - schemeName=
[[2] - mapped in CVA2sch to genericode first <LongName>
][1] - schemeVersionID=
[[2] - mapped in CVA2sch to genericode <Version>
][1] - schemeDataURI=
[[2] - mapped in CVA2sch to genericode <LocationUri>
][1] - schemeURI=
[[2] - mapped in CVA2sch to genericode <CanonicalVersionUri>
]]
2.3.7 Polaris controlled-vocabulary declarations
[> 3.][< 2.3.6][^][^^][^^^]
Polaris U.K. Limited [http://www.polaris-uk.co.uk/] is owned and directed by the UK insurance industry
[[1] - assists in the development and adoption of business and technology standards to improve customer service for member organizations
 [1] - big users and definers of code lists within their industry
]
W3C schema-declared enumerations of code list-based information item data types
[[1] - instance-level meta data is built into and inseparable from the code list value
[[2] - note how the code list value "B75 BS" incorporates an identifier for the code list base "B75" (for payment means) from which the value is obtained
 [2] - this inhibits some strategies (described later) for extensibility and list evolution
]]
[Example 2-6:
01  <xs:element name="MethodOfPaymentCode" minOccurs="0" maxOccurs="1">
02   ...
03   <xs:complexType>
04   <xs:sequence>
05   <xs:element name="Value" minOccurs="1" maxOccurs="1">
06   ...
07   <xs:simpleType>
08   <xs:restriction base="xs:string">
09   <xs:enumeration value="B75 BS">
10   <xs:annotation>
11   <xs:documentation>Broker Statement</xs:documentation>
12   </xs:annotation>
13   </xs:enumeration>
14   <xs:enumeration value="B75 CC">
15   <xs:annotation>
16   <xs:documentation>Credit Card</xs:documentation>
17   </xs:annotation>
18   </xs:enumeration>
19   <xs:enumeration value="B75 DC">
20   <xs:annotation>
21   <xs:documentation>Debit Card</xs:documentation>
22   </xs:annotation>
23   </xs:enumeration>
24   ...
25   </xs:restriction>
26   </xs:simpleType>
27   </xs:element>
28   ...
29   </xs:sequence>
30   </xs:complexType>
31  </xs:element>
]
Multiple declarations of the same code list
[[1] - three copies of the declaration of TitleCode in MsgSchemaOfficeQuoteNBAt.xsd
 [1] - note in all three cases that the list of five values is a subset of a list of 88 possible values defined for all possible uses in documents
]
[Example 2-7:
01  <xs:element name="IndividualName" minOccurs="0" maxOccurs="1">
02   ...
03   <xs:complexType>
04   <xs:sequence>
05   <xs:element name="TitleCode" minOccurs="0" maxOccurs="1">
06   ...
07   <xs:complexType>
08   <xs:sequence>
09   <xs:element name="Value" minOccurs="1" maxOccurs="1">
10   ...
11   <xs:simpleType>
12   <xs:restriction base="xs:string">
13   <xs:enumeration value="B53 001">
14   <xs:annotation>
15   <xs:documentation>Doctor</xs:documentation>
16   </xs:annotation>
17   </xs:enumeration>
18   <xs:enumeration value="B53 002">
19   <xs:annotation>
20   <xs:documentation>Miss</xs:documentation>
21   </xs:annotation>
22   </xs:enumeration>
23   <xs:enumeration value="B53 003">
24   <xs:annotation>
25   <xs:documentation>Mr</xs:documentation>
26   </xs:annotation>
27   </xs:enumeration>
28   <xs:enumeration value="B53 004">
29   <xs:annotation>
30   <xs:documentation>Mrs</xs:documentation>
31   </xs:annotation>
32   </xs:enumeration>
33   <xs:enumeration value="B53 005">
34   <xs:annotation>
35   <xs:documentation>Ms</xs:documentation>
36   </xs:annotation>
37   </xs:enumeration>
38   </xs:restriction>
39   </xs:simpleType>
40   </xs:element>
41   ...
]
The code list is maintained in a database (displayed here using two columns):
[Example 2-8:
01  B53 040 Admiral                 B53 056 Lieutenant General        
02  B53 039 Air Chief Marshall B53 021 Lord
03  B53 041 Air Commodore B53 022 Major
04  B53 043 Air Marshall B53 085 Major General
05  B53 044 Air Vice Marshall B53 023 Master
06  B53 042 Airman B53 064 Master Sergeant
07  B53 037 An t'Uasal B53 002 Miss
08  B53 068 Baron B53 036 Mother
09  B53 069 Baroness B53 003 Mr
10  B53 038 Bean B53 079 Mr Justice
11  B53 045 Bombardier B53 004 Mrs
12  B53 008 Brigadier B53 005 Ms
13  B53 027 Brother B53 080 Prince
14  B53 046 Canon B53 057 Private
15  B53 009 Captain B53 024 Professor
16  B53 070 Cardinal B53 077 Provost
17  B53 010 Chief B53 029 Rabbi
18  B53 011 Colonel B53 058 Rear Admiral
19  B53 012 Commander B53 059 Regimental Sergeant Major
20  B53 013 Commodore B53 006 Reverend
21  B53 047 Corporal B53 032 Right Reverend
22  B53 028 Councillor B53 060 Sergeant
23  B53 071 Count B53 081 Sheikh
24  B53 072 Countess B53 007 Sir
25  B53 014 Dame B53 030 Sister
26  B53 048 Dean B53 025 Squadron Leader
27  B53 001 Doctor B53 061 Staff Sergeant
28  B53 087 Estate Of B53 083 The Duke of
29  B53 034 Executor(s) of B53 082 The Earl of
30  B53 035 Father B53 073 The Honourable Lady
31  B53 049 Field Marshall B53 086 The Honourable Miss
32  B53 015 Flight Lieutenant B53 074 The Honourable Mrs
33  B53 050 Flight Sergeant B53 075 The Honourable Sir
34  B53 016 General B53 084 The Marquess of
35  B53 051 Group Captain B53 066 The Most Reverend
36  B53 052 Gunner B53 031 The Right Honourable
37  B53 017 Honourable B53 067 The Venerable
38  B53 018 Judge B53 088 Trustees Of
39  B53 019 Lady B53 033 Very Reverend
40  B53 053 Lance Bombardier B53 065 Viscount
41  B53 055 Lance Corporal B53 078 Viscountess
42  B53 020 Lieutenant B53 062 Warrant Officer 1
43  B53 054 Lieutenant Colonel B53 063 Warrant Officer 2
44  B53 076 Lieutenant Commander B53 026 Wing Commander
]


This is an accessible version of Crane's commercial training material. The content has been specifically designed to assist screen reader software in viewing the entire textual content. Figures are replaced with text narratives.

Navigation hints are in square brackets:
[Tx.x] and [Fx.x] are textual representations of the applicability icons;
[digit] indicates list depth for nested lists;
[link [URL]] indicates the URL of a hyperlink if different than link;
[EXAMPLE] indicates an example listing of code;
[FIGURE] indicates the presence of a figure replaced by its description;
[>] jumps forward;
[<] jumps backward;
[^] jumps to start of the section;
[^^] jumps to the start of the chapter;
[^^^] jumps to the table of contents.
Suggestions for improvement are welcome: [info@CraneSoftwrights.com]
Book sales: [http://www.CraneSoftwrights.com/links/trn-acc.htm]
Information: [http://www.CraneSoftwrights.com/links/info-acc.htm]
This content is protected by copyright and, as there are no means to protect this accessible version from plagiarism, please do not make any commercial edition available to others.

+//ISBN 1-894049::CSL::Presentation::UBL//DOCUMENT Practical Code List Implementation 2009-02-09 22:30UTC//EN
Practical Code List Implementation
First Edition - 2009-02-09
ISBN 978-1-894049-22-1
Copyright © Crane Softwrights Ltd.