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

3. Declaring controlled vocabularies
[> 4.][< 2.3.7][^^^]
3.0 Declaring controlled vocabularies
[> 3.1][> 4.][< 3.][^^][^^^]
Standards are in development for the non-schema-based representation of a list of coded values
[[1] - trading partners may wish to trim or augment the list of coded values acceptable
 [1] - trading partners may wish to use different controlled vocabularies for a given information item found in different document contexts
 [1] - the representation of individual coded values includes documentary information and metadata
[[2] - for detailed value description
 [2] - for long-term maintenance and understanding
][1] - OASIS genericode 1.0
[[2] - [http://docs.oasis-open.org/codelist/genericode]
 [2] - an XML representation standardized by the OASIS Code List Representation Technical Committee
 [2] - [http://www.oasis-open.org/committees/codelist/]
 [2] - "Defining an XML format for interchange, documentation and management of code lists (a.k.a. controlled vocabularies or coded value enumerations) in any processing context"
[[3] - not obliged to use XML format inside the application
 [3] - very common to compile the XML interchange format into an internal processing format
[[4] - e.g. conversion to XSLT
 [4] - e.g. implementation in database stored procedures
][3] - XML is designed for interchange and is not always conveniently structured for real-time processing
]]]
One could use schema enumerations but ...
[[1] - too inflexible for globally-defined information items
[[2] - cannot have different sets of values in different document contexts for a globally-defined information item
][1] - modifying the schemas means using non-standardized schema expressions
[[2] - not bad in and of itself but requires extra assurances for compatibility
 [2] - structural and lexical validation is assured if the standardized schema expressions are treated as read-only
]]
Meta-data-only code list are important as placeholders
[[1] - effectively an infinite set of all possible codes satisfying the lexical rules
 [1] - indicating that a particular information item's value is from a controlled vocabulary but that there is no controlled vocabulary listing a set of codes
 [1] - e.g. only 18 of 91 UBL code lists are published with values, 73 uniquely-categorized code lists have only meta data
 [1] - users have the option of restricting the infinite list into a finite list
]
3.1 OASIS Genericode 1.0
[> 3.2][< 3.0][^^][^^^]
3.1.1 OASIS Genericode 1.0
[> 3.1.2][> 3.2][> 4.][< 3.0][^^][^^^]
An XML vocabulary for the representation of a set of coded values
[[1] - [http://docs.oasis-open.org/codelist/genericode]
 [1] - contributed to the formation of the OASIS Code List Representation TC
[[2] - [http://www.oasis-open.org/committees/codelist/]
][1] - also in use by other standardization committees e.g. FpML
 [1] - as of this writing the current version of genericode is 1.0
[[2] - the code lists delivered in UBL 2.0 use genericode 0.4
 [2] - the code lists delivered in UBL 2.0 Update use genericode 1.0
 [2] - the committee is working on genericode version 1.1
]]
Three main sections:
[[1] - code list-level meta data
[[2] - defined by the element <Identification>
][1] - available value-level meta data for coded values
[[2] - defined by the element <ColumnSet>
][1] - coded value enumeration and associated value-level meta data
[[2] - defined by the element <SimpleCodeList>
]]
Enumeration columns have at a minimum a key column for the coded value
[[1] - defined within <ColumnSet> by the element <Key> pointing to the appropriate <Column>
 [1] - other columns are available for meta data for the coded value
]
Enumeration rows have at a minimum a key value defining the coded value
[[1] - each <Row> defines the information for a coded value
 [1] - the <Value> corresponding to the key column defines the coded value
 [1] - the <Value> for other columns defines the meta data
]
Example: currency codes
[[1] - only code and name
[[2] - the name is used as a description
][1] - no other value-level meta data
]
Example: shipping container sizes and types
[[1] - documented properties:
[[2] - container size name detail
 [2] - length, width and height in millimeters
 [2] - length, width and height in imperial
 [2] - container type
][1] - 30Mb of genericode XML
]
Excerpt from http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/cefact/CurrencyCode-2.0.gc with simple item-level meta data:
[[1] - note the rows are limited to only code and name
]
[Example 3-1:
01  <gc:CodeList 
02  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName>CurrencyCode</ShortName>
05   <LongName xml:lang="en">Currency</LongName>
06   <LongName Identifier="listID">ISO 4217 Alpha</LongName>
07   <Version>2001</Version>
08   <CanonicalUri>urn:un:unece:uncefact:codelist:specification:54217
09  </CanonicalUri>
10   <CanonicalVersionUri>urn:un:unece:uncefact:codelist:
11  specification:54217:2001</CanonicalVersionUri>
12   <LocationUri>http://docs.oasis-open.org/ubl/os-ubl-2.0-update/
13  cl/gc/cefact/CurrencyCode-2.0.gc</LocationUri>
14   <Agency>
15   <LongName xml:lang="en">United Nations Economic Commission for
16  Europe</LongName>
17   <Identifier>6</Identifier>
18   ...
19   <ColumnSet>
20   <Column Id="code" Use="required">
21   ...
22   <Key Id="codeKey">
23   <ShortName>CodeKey</ShortName>
24   <ColumnRef Ref="code"/>
25   ...
26   <SimpleCodeList>
27   <Row>
28   <Value ColumnRef="code">
29   <SimpleValue>AED</SimpleValue>
30   </Value>
31   <Value ColumnRef="name">
32   <SimpleValue>Dirham</SimpleValue>
33   </Value>
34   </Row>
35   <Row>
36   <Value ColumnRef="code">
37   <SimpleValue>AFN</SimpleValue>
38   </Value>
39   <Value ColumnRef="name">
40   <SimpleValue>Afghani</SimpleValue>
41   ...
42  </gc:CodeList>
]
Excerpt from http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/special-purpose/ContainerSizeCodeType-2.0.gc with detailed item-level meta data:
[[1] - note the rows have far more information than just code and name, thus providing detailed meta data for each coded value
 [1] - the name is the synthesis of the other seven meta data properties
]
[Example 3-2:
01  <gc:CodeList 
02  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName xml:lang="en">Container Size Type</ShortName>
05   ...
06   <LongName xml:lang="en"
07   >Ship-planning Message Design Group</LongName>
08   ...
09   <SimpleCodeList>
10   <Row>
11   <Value ColumnRef="code"><SimpleValue>10GP</SimpleValue></Value>
12   <Value ColumnRef="name">
13   <SimpleValue>Unventilated general purpose container: 2991mm
14   (10') x 2438mm (8') x 2 438mm (8'0")</SimpleValue>
15   </Value>
16   <Value ColumnRef="lengthmm"><SimpleValue>2991</SimpleValue>...
17   <Value ColumnRef="lengthimperial"><SimpleValue>10'</SimpleValue>...
18   <Value ColumnRef="widthmm"><SimpleValue>2438</SimpleValue>...
19   <Value ColumnRef="widthimperial"><SimpleValue>8'</SimpleValue>...
20   <Value ColumnRef="heightmm"><SimpleValue>2 438</SimpleValue>...
21   <Value ColumnRef="heightimperial"><SimpleValue>8'0"</SimpleValue>..
22   <Value ColumnRef="type">
23   <SimpleValue>Unventilated general purpose container</SimpleValue>
24   </Value>
25   </Row>
26   <Row>
27   <Value ColumnRef="code"><SimpleValue>10G0</SimpleValue></Value>
28   <Value ColumnRef="name">
29   <SimpleValue>Unventilated general purpose container - Openings
30  at one or both ends: 2991mm (10') x 2438mm (8') x 2 438mm (8'0")
31  </SimpleValue>
32   </Value>
33   <Value ColumnRef="lengthmm"><SimpleValue>2991</SimpleValue>...
34   <Value ColumnRef="lengthimperial"><SimpleValue>10'</SimpleValue>...
35   <Value ColumnRef="widthmm"><SimpleValue>2438</SimpleValue>...
36   ...
]
Genericode files are validated using an W3C Schema expression of constraints
[[1] - http://docs.oasis-open.org/codelist/genericode/xsd/genericode.xsd
[[2] - includes http://docs.oasis-open.org/codelist/genericode/xsd/xml.xsd
]]
The development of genericode version 1.0 published in 2007
[[1] - the work is continuing by the OASIS technical committee
 [1] - backward-compatible version 1.1 being developed to package multiple code lists
]
3.1.2 Example code list validation scenario
[> 3.1.3][> 3.2][> 4.][< 3.1.1][^][^^][^^^]
Two trading partners agree to exchange an order
[[1] - one is in Canada and the other is in the US
 [1] - the buyer may be either Canadian- or US-based
[[2] - this limits the country sub-entity code of the buyer to be either provinces or states
][1] - the seller can only be US-based
[[2] - this limits the country sub-entity code of the seller to be only states
][1] - the payment means available supplements the UBL values for payment means
[[2] - all of the UBL-standardized values can be used
 [2] - the value "SHP" can be used to represent "payment by the exchange of sheep"
][1] - currency codes must be limited to either US dollars or Canadian dollars
]
3.1.3 Specifying a controlled vocabulary
[> 3.2][> 4.][< 3.1.2][^][^^][^^^]
Example genericode file enumerating Canadian provinces:
[[1] - artefacts/Crane-artfacts/Crane-CVA2sch/scenario/CA_CountrySubentityCode.gc
 [1] - note that this is version "2" of the list of Canadian provinces and territories
[[2] - the semantic behind the code "NT" representing "Northwest Territories" changed April 1, 1999 when the new territory "Nunavut" (new code "NU") was created from the split of the old territory into two
[[3] - trivia: Nunavut has a land area of 2 million square kilometers (770,000 square miles; larger than the state of Texas or the country of France) and a total population of 28,000 people
]][1] - important note: this genericode file is for illustration purposes and is not intended to be an official representation of the information
]
[Example 3-3:
01  <gc:CodeList 
02  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName>provinces</ShortName>
05   <LongName>Canadian Provinces</LongName>
06   <Version>2</Version>
07   ...
08   </Identification>
09   ...
10   <SimpleCodeList>
11   <Row>
12   <Value ColumnRef="code">
13   <SimpleValue>AB</SimpleValue>
14   </Value>
15   <Value ColumnRef="name">
16   <SimpleValue>Alberta</SimpleValue>
17   </Value>
18   </Row>
19   <Row>
20   <Value ColumnRef="code">
21   <SimpleValue>BC</SimpleValue>
22   </Value>
23   <Value ColumnRef="name">
24   <SimpleValue>British Columbia</SimpleValue>
25   </Value>
26   </Row>
27   ...
]
Example genericode file enumerating US states:
[[1] - artefacts/Crane-artfacts/Crane-CVA2sch/scenario/US_CountrySubentityCode.gc
 [1] - important note: this genericode file is for illustration purposes and is not intended to be an official representation of the information
]
[Example 3-4:
01  <gc:CodeList 
02  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName>states</ShortName>
05   <LongName>US States</LongName>
06   <Version>1</Version>
07   ...
08   </Identification>
09   ...
10   <SimpleCodeList>
11   <Row>
12   <Value ColumnRef="code">
13   <SimpleValue>AL</SimpleValue>
14   </Value>
15   <Value ColumnRef="name">
16   <SimpleValue>ALABAMA</SimpleValue>
17   </Value>
18   </Row>
19   <Row>
20   <Value ColumnRef="code">
21   <SimpleValue>AK</SimpleValue>
22   </Value>
23   <Value ColumnRef="name">
24   <SimpleValue>ALASKA</SimpleValue>
25   </Value>
26   </Row>
27   ...
]
3.2 OASIS Context/value association using genericode
[> 3.3][< 3.1.3][^^][^^^]
3.2.1 OASIS Context/value association using genericode
[> 3.2.2][> 3.3][> 4.][< 3.1.3][^^][^^^]
Extension and restriction accomplished using association
[[1] - declarative approach to the association of a controlled vocabulary to an XML document context
 [1] - specifies lists of codes by pointing to external genericode files
 [1] - pointing to more than one external genericode file specifies the union of the files
]
[Figure 3.1: Context/value association
Three groups of triangles are shown, one triangle labeled "Document Instance Being Validated", a set of triangles labeled "External Value List Expressions", and one triangle labeled "Context/Value Associations".
In the triangle labeled "Context/Value Associations" are a number of drawn areas with arrows pointing to other triangles. The areas are labeled "An association ties a document context to one or more lists of valid values".
All areas each have one arrow to the "Document Instance Being Validated" triangle, with the arrow labeled "Document context specifies information items being validated". All areas have one or more arrows pointing to the "External Value List Expressions" triangles, with the arrow labeled "Lists of valid values are referenced by file location".
]
No implication of use or applicability or process
[[1] - useful in data entry user interface applications
 [1] - useful in document validation
]
3.2.2 Extending a controlled vocabulary
[> 3.2.3][> 3.3][> 4.][< 3.2.1][^][^^][^^^]
The intuition to pick up an existing list and simply add values to it is misguided
[[1] - the new list is a different list than the original list so no longer be considered the original list and must, therefore, be identified distinctly with different list-level meta data
]
List-level meta data impacts on the business validity of instances
[[1] - the new expanded list is obliged to have different list-level meta data so as not to be interpreted as a bona fide original list
 [1] - instance-level-meta-data-qualified specifications from the original list will not validate when the modified list's list-level meta data has been modified
]
Extending an item's values to beyond the existing set of codes involves simultaneously referencing the original list and any lists of extended values
[[1] - association marries the multiple lists together into one suite of values allowed for a given information item
 [1] - specifications of unique values amongst the merged values need not specify list meta data but may choose to do so
 [1] - specifications of ambiguous values amongst the merged values are obliged to specify list meta data to disambiguate from which list the value is obtained
]
Permanently growing a list involves publishing versions
[[1] - list-level meta data distinguishes one set of values from another set of values
 [1] - the semantics of the codes are described for a particular version of the growing list
[[2] - semantics can change over time, so the list version is important to distinguish the true meaning of the values
][1] - during migration association can reference both versions as applicable
[[2] - can provide for the union of older and newer versions for any given information item
]]
Example genericode file enumerating a single value:
[[1] - artefacts/Crane-artfacts/Crane-CVA2sch/scenario/Additional_PaymentMeansCode.gc
]
[Example 3-5:
01  <gc:CodeList 
02  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName>AdditionalPaymentMeansCode</ShortName>
05   <LongName xml:lang="en">Additional Payment Means</LongName>
06   <Version>1</Version>
07   <CanonicalUri>urn:x-company:PaymentMeansCode</CanonicalUri>
08   <CanonicalVersionUri>urn:x-company:PaymentMeansCode-1.0
09  </CanonicalVersionUri>
10   </Identification>
11   <ColumnSet>
12   <Column Id="code" Use="required">
13   <ShortName>Code</ShortName>
14   <Data Type="normalizedString"/>
15   </Column>
16   <Column Id="name" Use="optional">
17   <ShortName>Name</ShortName>
18   <Data Type="string"/>
19   </Column>
20   <Key Id="codeKey">
21   <ShortName>CodeKey</ShortName>
22   <ColumnRef Ref="code"/>
23   </Key>
24   </ColumnSet>
25   <SimpleCodeList>
26   <Row>
27   <Value ColumnRef="code">
28   <SimpleValue>SHP</SimpleValue>
29   </Value>
30   <Value ColumnRef="name">
31   <SimpleValue>Exchange of Sheep</SimpleValue>
32   </Value>
33   </Row>
34   </SimpleCodeList>
35  </gc:CodeList>
]
Of note:
[[1] - the list-level meta data does not look like that of the UN-ECE Payment Means
]
3.2.3 Restricting a controlled vocabulary
[> 3.3][> 4.][< 3.2.2][^][^^][^^^]
The intuition to pick up an existing list and simply remove values from it is misguided
[[1] - but the new list must be identified with different list-level meta data
[[2] - the new list is a different list than the original list so no longer be considered the original list so original meta data cannot apply
]]
List-level meta data impacts on the validity of instances
[[1] - the new reduced list is obliged to have different meta data so as not to be interpreted as a bona fide original list
 [1] - instance-level-meta-data-qualified specifications from the original list will not validate if the list-level meta data has been modified
]
Introduces the concept of the "masquerade"
[[1] - restricting an items values to a subset of an existing set of codes involves referencing the new list of reduced values while masquerading the reduced list to be the original list
 [1] - association provides the opportunity to masquerade the reduced list to appear as the original list
]
Example genericode file limiting an already-constrained schema enumeration for currencies:
[[1] - artefacts/Crane-artfacts/Crane-CVA2sch/scenario/CAUS_CurrencyCode.gc
 [1] - compare this list's meta data with the original list shown on [Example 3-1]
]
[Example 3-6:
01  <gc:CodeList 
02  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
03   <Identification>
04   <ShortName>CAUSCurrencyCode</ShortName>
05   <LongName>Canadian and US Currency Codes</LongName>
06   <Version>1</Version>
07   <CanonicalUri>urn:x-company:CAUS-currency</CanonicalUri>
08   <CanonicalVersionUri>urn:x-company:CAUS-currency:1
09  </CanonicalVersionUri>
10   </Identification>
11   ...
12   <SimpleCodeList>
13   <Row>
14   <Value ColumnRef="code">
15   <SimpleValue>CAD</SimpleValue>
16   </Value>
17   <Value ColumnRef="name">
18   <SimpleValue>Canadian Dollar</SimpleValue>
19   </Value>
20   </Row>
21   <Row>
22   <Value ColumnRef="code">
23   <SimpleValue>USD</SimpleValue>
24   </Value>
25   <Value ColumnRef="name">
26   <SimpleValue>US Dollar</SimpleValue>
27   </Value>
28   </Row>
29   </SimpleCodeList>
30  </gc:CodeList>
]
Of note:
[[1] - the list-level meta data does not look like that of the UN-ECE Currency Codes
]
3.3 Rendering controlled vocabularies
[> 4.][< 3.2.3][^^][^^^]
3.3.1 Rendering controlled vocabularies
[> 3.3.2][> 4.][< 3.2.3][^^][^^^]
Some audiences do not appreciate having to read raw XML to interpret the contents
[[1] - angle brackets are distracting
 [1] - the volume of XML markup overwhelms the information content of the instance
]
Crane Softwrights Ltd. has published free developer resources with which to render a genericode code expression to HTML
[[1] - XSLT 1.0 stylesheet: Crane-genericode2html.xsl
 [1] - standalone production of HTML from genericode file
 [1] - browser-based viewing of HTML from genericode file
]
3.3.2 Standalone production of an HTML rendering
[> 3.3.3][> 4.][< 3.3.1][^][^^][^^^]
Consider the HTML rendering of the earlier example of a genericode file in [Example 3-5] rendered using:
[[1] -
java -jar saxon.jar -o Additional_PaymentMeansCode.html 
Additional_PaymentMeansCode.gc Crane-genericode2html.xsl
]
The resulting HTML file when rendered appears as follows:
[Figure 3.2: HTML rendering of a genericode file
A screen shot shows a tabular rendering of the genericode file.
]
3.3.3 Browser-based viewing of an HTML rendering
[> 3.3.4][> 4.][< 3.3.2][^][^^][^^^]
W3C XML stylesheet association standardized xml-stylesheet processing instruction:
[[1] - [http://www.w3.org/1999/06/REC-xml-stylesheet-19990629]
 [1] - href= points to the stylesheet file (modify as required)
 [1] - type="text/xsl" used to indicate the interpretation of the stylesheet
 [1] - in Windows drag the file from Windows Explorer to the browser canvas to render
]
The modified file includes the processing instruction recognized by XML processing tools:
[[1] - examples in the samp/ss directory
]
[Example 3-7:
01  <?xml version="1.0" encoding="ISO-8859-1"?>
02  <?xml-stylesheet type="text/xsl" href="Crane-genericode2html.xsl"?>
03  <gc:CodeList
04  xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
05   <Identification>
06   <ShortName>AdditionalPaymentMeansCode</ShortName>
07   <LongName xml:lang="en">Additional Payment Means</LongName>
08   <Version>1</Version>
09   <CanonicalUri>urn:x-company:PaymentMeansCode</CanonicalUri>
10   <CanonicalVersionUri>urn:x-company:PaymentMeansCode-1.0
11  </CanonicalVersionUri>
12   </Identification>
13   <ColumnSet>
14   <Column Id="code" Use="required">
15   <ShortName>Code</ShortName>
16   <Data Type="normalizedString"/>
17   </Column>
18   <Column Id="name" Use="optional">
19   <ShortName>Name</ShortName>
20   <Data Type="string"/>
21   </Column>
22   <Key Id="codeKey">
23   <ShortName>CodeKey</ShortName>
24   <ColumnRef Ref="code"/>
25   </Key>
26   </ColumnSet>
27   <SimpleCodeList>
28   <Row>
29   <Value ColumnRef="code">
30   <SimpleValue>SHP</SimpleValue>
31   </Value>
32   <Value ColumnRef="name">
33   <SimpleValue>Exchange of Sheep</SimpleValue>
34   </Value>
35   </Row>
36   </SimpleCodeList>
37  </gc:CodeList>
]
3.3.4 Problems triggering browser-based rendering
[> 4.][< 3.3.3][^][^^][^^^]
It is possible that the rendering initially shows up without interpretation:
[[1] - Internet Explorer does not recognize the file extension to be an XML document
]
[Figure 3.3: Text rendering of a genericode file
A screen shot shows a text rendering of the genericode file.
]
One can teach Windows XP to get the effect shown in [Figure 3.2]:
[[1] - it is possible to indicate that any given file extension is an XML document
 [1] - from either the Control Panel or a Windows Explorer "Tools" menu, select "Folder Options"
 [1] - go to the "File Types" tab
 [1] - press the "New" button to define a new registered file type
 [1] - enter the file extension where indicated
 [1] - press the "Advanced >>" button
 [1] - select "XML Document" for the "Associated File Type"
]
[Figure 3.4: XP dialogues for file extension file type association
A screen shot shows the "File Options" and "Create New Extension" dialogue boxes.
]


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.