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

4. Controlled vocabulary representation detail
[> 5.][< 3.3.4][^^^]
4.0 Controlled vocabulary representation detail
[> 4.1][> 5.][< 4.][^^][^^^]
Genericode
[[1] - an XML vocabulary for the representation of an enumerated set of values
 [1] - http://docs.oasis-open.org/codelist/genericode/xsd/genericode.xsd
[[2] - base vocabulary for the genericode namespace
][1] - http://docs.oasis-open.org/codelist/genericode/xsd/xml.xsd
[[2] - imported vocabulary for the XML namespace in support of xml:lang=
]]
Meta data identification of an enumerated set of values
[[1] - information regarding identifying the list as a whole
[[2] - names by which the list is known
 [2] - version of the particular list
 [2] - resource identifiers with which to retrieve the list contents
][1] - information regarding identifying the custodian
[[2] - agency
][1] - information regarding each individual value
]
Many features for supporting sets of code lists or derived code lists
[[1] - Schematron-based context/value association stylesheets as delivered support only simple single-key code lists in standalone declarations
[[2] - interpreting multiple keys or a set of sets or a derivation of sets is not supported
][1] - this documentation is limited to the available document types and to the supported constructs only of simple single-key standalone declarations
[[2] - this documentation is not meant to be exhaustive documentation for genericode files
 [2] - please see the OASIS code list representation committee deliverables for more details on genericode files
]]
4.1 Genericode vocabulary
[> 4.2][< 4.0][^^][^^^]
4.1.1 Genericode information
[> 4.1.2][> 4.2][> 5.][< 4.0][^^][^^^]
Three entry points into the information
[[1] - a genericode file can validly be one of three kinds of collections of information
 [1] - code list set
[[2] - the definition of an aggregate collection of code lists or other sets of enumerated values
 [2] - includes meta data for the set of sets
 [2] - this kind of genericode file is not referenced by context/value association files
 [2] - no other information regarding code list sets is included in this documentation
][1] - column set
[[2] - the definition of a group of meta data columns for enumerated values
[[3] - distinct from the meta data used for identifying code lists
][2] - this is useful when sharing a comment set of column definitions across multiple code list files
[[3] - allows a code list to use an outboard definition of columns rather than an embedded definition of columns
][2] - this kind of genericode file is not referenced by context/value association files
[[3] - the methodology assumes the column definitions are embedded within the code list files in a specified column set
][2] - no other information regarding column sets is included in this documentation
][1] - code list
[[2] - the definition of a single enumerated set of values
 [2] - includes meta data for the single set
 [2] - includes meta data for individual values in the set
 [2] - only this kind of simple genericode file with simple single-key enumeration sets is used by context/value association files
 [2] - no other information regarding derived code lists is included in this documentation
]]
Recall the example UBL enumeration for payment means on [Example 2-5]
[[1] - an example of a simple genericode file with a simple single-key enumeration
]
4.1.2 Genericode list-level meta data
[> 4.1.3][> 4.2][> 5.][< 4.1.1][^][^^][^^^]
Information regarding identifying the list as a whole
[[1] - names by which the list is known
[[2] - short name (token)
 [2] - long names (normalized strings)
[[3] - optional distinguishing meta data can be used for each name
[[4] - arbitrary distinction between one long name and other long names
[[5] - Identifier="listID" attribute indicates the long name referenced with UN/CEFACT listID= meta data
 [5] - other long name is the list name
][4] - the language in which the long name is written
]][2] - canonical name (URI string)
][1] - distinct revision of the particular list
[[2] - version (token)
 [2] - canonical version (URI string)
][1] - addresses with which to retrieve the list contents
[[2] - resource location identifiers (URI strings)
]]
Information regarding identifying the custodian
[[1] - agency short name (token)
 [1] - agency long names (normalized strings)
[[2] - optional distinguishing meta data can be used for each name
][1] - agency identifiers (normalized strings)
[[2] - optional distinguishing meta data can be used for each identifier
]]
4.1.3 Genericode standalone simple enumeration sets
[> 4.1.4][> 4.2][> 5.][< 4.1.2][^][^^][^^^]
An enumeration set is defined by columns and rows
[[1] - one row per member of the enumeration set
[[2] - there may be no rows, thus the file defines a meta-data-only code list
][1] - the columns contain the meta data for each member
[[2] - there must be a column set, but it may be empty
 [2] - following typical ISO use, the empty lists found in UBL define candidate columns of "Code" and "Name" for meta-data-only code lists, but these are not normative and have no meaning as there are no rows
 [2] - context/value association stylesheets do not support a reference to an external definition of columns for a column set and will only respect embedded specifications of columns in a column set
]]
A single column or a combination of columns uniquely identifies the key for each row
[[1] - by definition the keys must be unique so as to be unambiguous
 [1] - context/value association stylesheets assume a key is only a single column
[[2] - when not named, the first declared key column is used as the key
][1] - other uses of genericode may support multiple key columns
]
Meta data (columns) defined for each enumeration member (a row)
[[1] - an arbitrary amount of user-defined information can be kept for members
 [1] - meta data may be specified differently for every enumeration in the set
 [1] - choice of whether the meta data item is mandatory or optional
 [1] - specification of the data type of the meta data item
 [1] - simple values or richly-marked up elements, attributes and mixed content
]
4.1.4 Genericode XML
[> 4.2][> 5.][< 4.1.3][^][^^][^^^]
Only one entry point expected for those files pointed to from context/value association files
[[1] - a standalone specification of a simple code list
]
<gc:CodeList>
[[1] - the specification of a standalone enumerated set of values
 [1] - this element is in the genericode namespace
 [1] - xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/"
[[2] - any prefix can be used, the "gc" prefix is not reserved in any way
 [2] - unusually, the namespace applies only to the document element, not the descendants
 [2] - UBL 2.0 uses a pre-release version of genericode with the namespace URI "xmlns:gc="http://genericode.org/2006/ns/CodeList/0.4/"
 [2] - UBL 2.0 update package republished all code lists using the finalized URI
][1] - all descendent elements of the genericode vocabulary are in no namespace
 [1] - mandatory <Identification> child and <ColumnSet> child
 [1] - optional <SimpleCodeList> child
[[2] - not used if the file specifies a meta-data-only enumeration set
]]
All elements other than the document element are in no namespace
[[1] - thus, it is most convenient to put the document element in a prefixed namespace rather than the default namespace, and to keep the default namespace undefined
]
<Identification>
[[1] - (mandatory) name, version, resource and custodian meta data for the list
]
<ShortName>
[[1] - (mandatory) a token (no spaces) naming the enumeration set suitable for software artefacts
 [1] - xml:lang=
[[2] - optional language specification of the derived language
]]
<LongName>
[[1] - (optional and repeatable) a normalized string
 [1] -
Identifier=
[[2] - (optional) used to distinguish between multiple names
 [2] -
Identifier="listID"
[[3] - recognized by the methodology stylesheets as a UN/CEFACT list identifier
]][1] -
xml:lang=
[[2] - (optional) language specification of the derived language
]]
<Identification> (cont.)
<Version>
[[1] - (mandatory) the version of the enumeration set
]
<CanonicalUri>
[[1] - (mandatory) a unique identifier independent of the version (i.e. for all versions) of the enumeration set
]
<CanonicalVersionUri>
[[1] - (mandatory) a unique identifier for this particular version of the enumeration set
]
<LocationUri>
[[1] - (optional and repeatable) a suggested location for a genericode expression of this enumeration set
]
<AlternateFormatLocationUri>
[[1] - (optional and repeatable) suggested locations for non-genericode expressions of this enumeration set
]
<Identification> (cont.)
<Agency>
[[1] - (optional) information regarding the custodian of the enumeration set
 [1] -
<ShortName>
[[2] - (optional) a token (no spaces) naming the custodian suitable for software artefacts
 [2] - xml:lang=
[[3] - optional language specification of the derived language
][2] - not used by context/value association stylesheets
][1] -
<LongName>
[[2] - (optional and repeatable) a normalized string
 [2] -
Identifier=
[[3] - (optional) used to distinguish between multiple names
][2] -
xml:lang=
[[3] - (optional) language specification of the derived language
]][1] -
<Identifier>
[[2] - (optional and repeatable) a normalized string identifier
 [2] -
Identifier=
[[3] - (optional) used to distinguish between multiple identifiers
][2] -
xml:lang=
[[3] - (optional) language specification of the derived language
]]]
<ColumnSet>
[[1] - (mandatory) identification of the meta data columns for the enumeration set rows
 [1] -
DefaultDatatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
[[2] - (optional) the URI of the data type library utilized by the column type specifications
 [2] - by default the W3C Schema data types are used
 [2] - while other values are possible, context/value association stylesheets do not inspect this attribute
]]
Omitted column set for the example UBL enumeration set shown on [Example 2-5]:
[Example 4-1:
01     <ColumnSet>
02   <Column Id="code" Use="required">
03   <ShortName>Code</ShortName>
04   <Data Type="normalizedString"/>
05   </Column>
06   <Column Id="name" Use="optional">
07   <ShortName>Name</ShortName>
08   <Data Type="string"/>
09   </Column>
10   <Key Id="codeKey">
11   <ShortName>CodeKey</ShortName>
12   <ColumnRef Ref="code"/>
13   </Key>
14   </ColumnSet>
]
The context/value association stylesheets only support single-valued keys
[[1] - the genericode specification allows keys to be combined in a multi-valued lookup
 [1] - context/value association key= provides for selecting which one key to use by the key's Id= attribute
]
<ColumnSet> (cont.)
<Column>
[[1] - (mandatory and repeatable) information about a piece of value-level meta data used for each enumeration in the set
 [1] - Id=
[[2] - (mandatory) identification of the column for referencing purposes
][1] - Use="optional" or Use="required"
[[2] - (mandatory) specification of the row's required specification of the column data
][1] -
<Annotation>
[[2] - (optional and repeatable) user information (not used by the context/value association stylesheets)
][1] -
<ShortName>
[[2] - (mandatory) a token (no spaces) naming the column suitable for software artefacts
 [2] - xml:lang=
[[3] - optional language specification of the derived language
]][1] -
<LongName>
[[2] - (optional and repeatable) a normalized string
[[3] -
Identifier=
[[4] - used to distinguish between multiple names
][3] -
xml:lang=
[[4] - optional language specification of the derived language
]]][1] -
<CanonicalUri>
[[2] - (optional) a unique identifier independent of the version (i.e. for all versions) of the column
][1] -
<CanonicalVersionUri>
[[2] - (optional) a unique identifier for this particular version of the column
][1] -
<Data>
[[2] - (mandatory) specification of the data type for the column
 [2] -
Type=
[[3] - (mandatory) the data type from the data type library
][2] -
DatatypeLibrary=
[[3] - (optional) the data type library overriding the default data type library
][2] -
<Annotation>
[[3] - (optional) user information (not used by context/value association stylesheets)
][2] -
<Parameter>
[[3] - (optional and repeatable) facet parameter (not used by context/value association stylesheets)
 [3] - (mandatory) ShortName= for the facet
 [3] - (optional) LongName= for the facet
]]]
<ColumnSet> (cont.)
<Key>
[[1] - (mandatory and repeatable) definition of a key column of unique values used for enumeration values
 [1] - Id=
[[2] - (mandatory) identification of the key for referencing purposes
][1] -
<Annotation>
[[2] - (optional and repeatable) user information (not used by context/value association stylesheets)
][1] -
<ShortName>
[[2] - (mandatory) a token (no spaces) naming the column suitable for software artefacts
 [2] - xml:lang=
[[3] - optional language specification of the derived language
]][1] -
<LongName>
[[2] - (optional and repeatable) a normalized string
 [2] -
Identifier=
[[3] - used to distinguish between multiple names
][2] -
xml:lang=
[[3] - optional language specification of the derived language
]][1] -
<CanonicalUri>
[[2] - (optional) a unique identifier independent of the version (i.e. for all versions) of the key
][1] -
<CanonicalVersionUri>
[[2] - (optional) a unique identifier for this particular version of the key
][1] -
<ColumnRef>
[[2] - (mandatory) specification of the key column
 [2] -
Ref=
[[3] - (mandatory) the identifier of the key column
][2] -
<Annotation>
[[3] - (optional) user information (not used by context/value association stylesheets)
 [3] -
<Description>
[[4] - (optional) human-readable information
][3] -
<AppInfo>
[[4] - (optional) machine-readable information
]]]]
<SimpleCodeList>
[[1] - this wraps all of the enumeration member rows of the enumeration set
 [1] - this element is not used when there are no value constraints for the list
[[2] - the list is not empty, it just has no constraints
 [2] - the list is effectively an infinite set of all possible values meeting the lexical constraints
]]
<Annotation>
[[1] - (optional) user information (not used by context/value association stylesheets)
 [1] -
<Description>
[[2] - (optional) human-readable information
][1] -
<AppInfo>
[[2] - (optional) machine-readable information
]]
<SimpleCodeList> (cont.)
<Row>
[[1] - (optional and repeatable) specification of a member of the enumeration set
 [1] -
<Annotation>
[[2] - (optional) user information (not used by context/value association stylesheets)
 [2] -
<Description>
[[3] - (optional) human-readable information
][2] -
<AppInfo>
[[3] - (optional) machine-readable information
]][1] -
<Value>
[[2] - (required) specification of the value for this meta data column for this enumeration row
 [2] - the order of <Value> elements is irrelevant
 [2] - ColumnRef=
[[3] - (required) pointer to the identifier of the column of meta data this value specified (allows arbitrary order of <Value> elements
][2] -
<Annotation>
[[3] - (optional) user information (not used by context/value association stylesheets)
 [3] -
<Description>
[[4] - (optional) human-readable information
][3] -
<AppInfo>
[[4] - (optional) machine-readable information
]][2] -
<SimpleValue>
[[3] - optional in the model but required by context/value association stylesheets
 [3] - this is mutually-exclusive with <ComplexValue>
][2] -
<ComplexValue>
[[3] - any foreign content (non-genericode vocabulary) can be used for this value
 [3] - this is mutually-exclusive with <SimpleValue>
 [3] - this information is not used by context/value association stylesheets
]]]
Entry points to genericode files not pointed to by context/value association
[[1] - these entry points are defined by genericode but not supported for context/value association files
 [1] - no other information regarding these is included in this documentation
]
<gc:CodeListSet>
[[1] - document type for the definition of an aggregate collection of code lists
 [1] - this element is in the genericode namespace
[[2] - all descendent elements of the genericode vocabulary are in no namespace
]]
<gc:ColumnSet>
[[1] - document type for the definition of a group of enumeration set meta data columns and/or keys
 [1] - this element is in the genericode namespace
[[2] - all descendent elements of the genericode vocabulary are in no namespace
]]
4.2 Mapping genericode meta data to XML instances
[> 5.][< 4.1.4][^^][^^^]
4.2.1 Mapping genericode meta data to XML instances
[> 5.][< 4.1.4][^^][^^^]
One must consider instance-level meta data when designing an XML vocabulary
[[1] - if an information item is allowed to have a code or an identifier, it should also have associated instance-level meta data
 [1] - allows the author of the XML to qualify the code with list-level meta data values in the instance-level meta data properties
]
Each aspect of list-level meta data should be allowed to be overridden
[[1] - should try to cover all aspects of genericode identification list-level facets
]
Crane validation stylesheets are modular supporting adaptation for any instance-level meta data
[[1] - one can create a Crane-ABC-genericode2Schematron.xsl stylesheet using a Crane-ABC-Metadata.xsl fragment that uses values from genericode code lists checking any instance-level meta data in the ABC vocabulary
 [1] - stylesheets include a pro-forma configuration supporting no instance-level meta data
[[2] - the Crane-NM-genericode2Schematron.xsl stylesheet uses values from genericode code lists without checking any instance-level meta data
 [2] - meta data stub stylesheet is Crane-NM-Metadata.xsl
][1] - stylesheets include a configuration supporting UBL instance-level meta data
[[2] - the Crane-UBL-genericode2Schematron.xsl stylesheet uses values from genericode code lists checking any instance-level meta data
 [2] - meta data stylesheet is Crane-UBL-Metadata.xsl
]]
Recall the available UN/CEFACT meta data attributes for UBL information items on [Instance-level meta data in XML instances - Section 2.3.6 Instance-level meta data in XML instances]
[[1] - the following lists map UBL information item meta data attributes (on the left) to the genericode meta data information items (on the right)
]
The following mappings are for UN/CEFACT-defined supplementary components:
[[1] - currencyCodeListVersionID= for currencyID= maps to Version
 [1] - unitCodeListVersionID= for unitCode= maps to Version
 [1] - unitCodeListID= for unitCode= maps to LongName[@Identifier='listID'] or LongName[1]
 [1] - unitCodeListAgencyID= for unitCode= maps to Agency/Identifier
 [1] - unitCodeListAgencyName= for unitCode= maps to Agency/LongName
]
The following mappings are for UBL-defined code list element meta data (those elements with names ending in "Code"):
[[1] - listID= maps to LongName[@Identifier='listID'] or LongName[1]
 [1] - listAgencyID= maps to Agency/Identifier
 [1] - listAgencyName= maps to Agency/LongName
 [1] - listName= maps to LongName[1]
 [1] - listVersionID= maps to Version
 [1] - listURI= maps to LocationUri
 [1] - listSchemeURI= maps to CanonicalVersionUri
]
The following mappings are for UBL-defined identifier element meta data (those elements with names ending in "ID"):
[[1] - schemeAgencyID= maps to Agency/Identifier
 [1] - schemeAgencyName= maps to Agency/LongName
 [1] - schemeName= maps to LongName[1]
 [1] - schemeVersionID= maps to Version
 [1] - schemeDataURI= maps to LocationUri
 [1] - schemeURI= maps to CanonicalVersionUri
]


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.