Code List Representation (genericode) Version 1.0

The key-value store concept is a long-understood data storage paradigm for managing as associative array arrangement of information. The keys of the store are unique values expressed either as monolithic values or the combination of multi-faceted components. The keys are unique to ensure unambiguous association to them with the information values that belong with a given key value.

The associated information values may be simple values or richly-structured values, or may not exist at all for a given key value. Simply the enumeration of a set of unique values can be regarded as a useful key-value association without any values specified. It may be that users of a set of keys implicitly understand the concept associated with each key value without the need to explicitly reify the concept in any associated information values.

When moving information between key-value stores, or publishing the information found in a key-value store, an IT-enabled serialization format needs to accommodate the collection of information as a whole, the individual key values however composed, and the optional though potentially voluminous information item values associated with each key.

Supporting multiple ad hoc or colloquial expressions of key-value associations, whether IT-enabled in a data format or not IT-enabled in arbitrary and opaque publication formats such as PDF and HTML tables, can be a burden for publishers and consumers alike. Adopting a single standardized IT-enabled key-value serialization will promote easier publishing and easier ingestion of the pertinent aspects of a set of keys and their associated information values.

ISO/IEC 14662 Open-edi reference model provides standards for the inter-working of organizations through interconnected information technology (IT) systems. See Appendix E, The Open-edi reference model perspective of code lists (Non-Normative) for the relationship between the semantic and IT-enabling perspectives of business transactions in, respectively, the Business Operational View (BOV) and the Functional Services View (FSV).

ISO/IEC 15944-10 IT-enabled coded domains as semantic components in business transactions details important aspects of the BOV of a “set of codes representing X”, where X is a semantic umbrella concept scope and individual codes are distinct and separate semantic concepts within that scope. Simple umbrella semantic examples are days of the week, countries of the world, and financial currencies. Individual distinct semantic concepts are “Tuesday” and “Thursday”, “Australia” and “Tanzania”, and “the US dollar” and “the Euro”.

Some semantic concepts, such as days of the week, are accepted as given without the need for any governing Source Authority or coded domain Source Authority. Most other e-business semantic concepts involved in connecting the IT systems for the inter-working of organizations need such authoritative governance and managed publication of the semantics to be mutually understood by the expression of a code in a coded domain. Such code-level metadata could express linguistic or illustrative explication of the semantics of the given coded value unique key.

Colloquially, such collections of codes of a coded domain are referred to as code lists. The genericode specification satisfies the FSV perspective of code lists by providing an IT-enabled expression of coded domains for the direct interchange or open publishing of their content and semantics in a machine-readable syntax.

Code lists, often regarded simply as enumerated values, have been with us since long before computers. They should be well understood and easily dealt with by now. Unfortunately, they are not. As is often the case, if you take a fundamentally simple concept, you find that everyone professes to understand it with complete clarity. When you look more closely, you find that everybody has their own unique view of what the problem is and how it should be solved.

If code lists were really so simple and obvious, there would already be a single, well-known and accepted way of handling them in XML. There is no such agreed solution, though. The problem is that while code lists are a well understood concept, people don’t actually agree exactly on what code lists are, and how they should be used.

The OASIS Code List Representation format, “genericode”^[1], is a single semantic model of code lists and accompanying XML serialization (supported by a W3C XML Schema) that can encode a broad range of code list information. The serialization is designed to IT-enable the interchange or distribution of machine-readable code list information between systems. Note that genericode is not designed as a run-time format for accessing code list information, and is not optimized for such usage. Rather, it is designed as an interchange format that can be transformed into formats suitable for run-time usage, or loaded into systems that perform run-time processing using code list information.

What is a code list, then? Most people would agree that the following is a code list:

{“SUN”, “MON”, “TUE”, “WED”, “THU”, “FRI”, “SAT”}

Example 1: Days of the week: English, uppercase

This is a perfectly reasonable set of alphabetic codes for representing days of the week. However, so is:

{“Sun”, “Mon”, “Tue”, “Wed”, “Thu”, “Fri”, “Sat”}

Example 2: Days of the week: English, mixed case

These two code lists are similar, but certainly not identical. That said, they can both be used to represent the days of the week. Of course, you could also use:

{“Dim”, “Lun”, “Mar”, “Mer”, “Jeu”, “Ven”, “Sam”}

Example 3: Days of the week: French, mixed case

which is created from abbreviations for the days of the week in French. Then again, you could use:

{0, 1, 2, 3, 4, 5, 6}

Example 4: Days of the week: numeric

which is suitable as a computer representation, e.g. for a database column. On the other hand:

{“S”, “M”, “T”, “W”, “T”, “F”, “S”}

Example 5: Days of the week: English, single character

is not suitable as a code list for the days of the week, because the values are not unique.

Now suppose that you are using codes to represent days of the week in an application, and you are displaying the days of the week using 3-letter abbreviations in English or French. In that context, should Example 2 and Example 3 be considered to be code lists, or should they be considered to be display values that would be keyed to either the Example 1 or Example 4 codes? The fact is, they could be either code lists or display values. A value which is a code in one context might only be an associated value for that code in another context. Nothing privileges any of these code lists over the others in terms of ability or suitability to be the code list (except the Example 5 values which are not suitable). There is a choice of code lists that can be used, and the answer to the question “which choice is the best?” depends on the needs of each particular situation.

What the above examples show is that for each distinct entry in a code list, there are many possible associated values (we use the term distinct entry to express the idea that we are talking a single item that needs to be represented in the code list, rather than about the code value(s) that can be used to identify that item). Some of those associated values are suitable for use in code lists, some are not. This leads to a tabular model, where each row of the table represents a conceptual code, and each column represents an associated value (code list metadata), as follows:

Table 1: Days of the week

Notice that the first 4 of the 5 columns have been labeled as “key” columns. This means that the values in those columns can be used to uniquely identify the rows, and hence they can be used as code list values. The term key is used here similarly to a relational database table.

This is the most common case, where a single column can be used as a key. However, consider the following modification:

Table 2: Days of the week, version 2

Here, the first two columns are each a key column. The last two columns are not individually key columns, but together they form a compound key, i.e. while the individual columns do not contain unique values, the pair of values is unique within each row. This is again similar to what happens in some relational databases, that a key for the rows need not be constructed from a single column, but instead may be constructed by combining two or more columns.

Finally, there is no reason why a column should only contain simple values like strings or numbers. A column could also contain a complex compound group of data, such as a fragment of XML:

Table 3: Days of the week, version 3

Notice that the final XHTML column is not marked as a key column. The values are unique, so it certainly could be used as a key column. However, sometimes you may not wish to mark a column as a key column, even if the values are unique. The values in the column may not make particularly suitable keys. They might be too long to process quickly and conveniently, or they might not be able to be used in a particular context, such as for an XML attribute value. Also, it may be that while the values in a particular column are unique now, there is no guarantee or expectation that they will remain unique as the code list grows or changes in the future.

Once you see the tabular nature that underlies the information that can be associated with code lists, it becomes clear why they can be a source of so much debate. Different users need different subsets of the code list information, and people often assume that the information they need is all the information that anyone needs.

That kind of thinking doesn’t work well with code lists, because code lists are sufficiently generic a concept that they are used across messages/documents, applications, and databases. The code list details that you need for the XML schemas often will not be exactly the same as the details that you need for your database or your application. If the code list information cannot be shared easily across these different areas, the result is duplication of effort and potential loss of synchronization between different implementations of the same code list.

The XML schema may only require a set of 3-letter codes to represent the code list. The database may require a set of numeric codes, plus display labels (possibly in different languages). The application may need to know which 3-letter code corresponds to which numeric code, so that it can process the XML and update the database. Also, some information related to a code list might not be appropriate for the XML format. For example, if you have a different image file for each code, it isn’t ideal to include this image inline in the code list XML, since it vastly increases the size of the XML, and makes it more difficult to read. So in an XML representation, you are more likely to include some reference (e.g. a URL) to the image. For a database, however, it may be feasible to store the image in a BLOB^[2] column in a database.

One last piece of experience from databases is that support for undefined values will be required. Sometimes users will have values that need to be associated with some of the codes in a code list, but won’t have values to associate with every code. In that case, the concept of a undefined (nil or null) value is needed.

There are 3 kinds of genericode documents, all supported by the one W3C XML Schema:

A column set document has the root element <gc:ColumnSet>. It contain definitions of genericode columns or keys that can be imported into code list documents or into other column set documents.

A code list document has the root element <gc:CodeList>. It contains metadata describing the code list as a whole, as well as explicit code list data – codes and associated values.

A code list set document has the root element <gc:CodeListSet>. It contains references to particular versions of code lists, and can also contain version-independent references to code lists. A code list set document can be used to define a particular configuration of versions of code lists that are used by a project, application, standard, etc.

· Section 3.4.5, “CodeList (Element)”

· Section 3.4.8, “CodeListSet (Element)”

· Section 3.4.16, “ColumnSet (Element)”

· Section 3.4.1, “Agency (Complex Type)”

· Section 3.4.2, “Annotation (Complex Type)”

· Section 3.4.3, “AnyOtherContent (Complex Type)”

· Section 3.4.4, “AnyOtherLanguageContent (Complex Type)”

· Section 3.4.6, “CodeListDocument (Complex Type)”

· Section 3.4.7, “CodeListRef (Complex Type)”

· Section 3.4.10, “CodeListSetDocument (Complex Type)”

· Section 3.4.11, “CodeListSetRef (Complex Type)”

· Section 3.4.12, “Column (Complex Type)”

· Section 3.4.14, “ColumnRef (Complex Type)”

· Section 3.4.17, “ColumnSet (Complex Type)”

· Section 3.4.20, “ColumnSetDocument (Complex Type)”

· Section 3.4.21, “ColumnSetRef (Complex Type)”

· Section 3.4.22, “Data (Complex Type)”

· Section 3.4.23, “DataRestrictions (Complex Type)”

· Section 3.4.24, “DatatypeFacet (Complex Type)”

· Section 3.4.28, “GeneralIdentifier (Complex Type)”

· Section 3.4.30, “Identification (Complex Type)”

· Section 3.4.33, “Key (Complex Type)”

· Section 3.4.35, “KeyColumnRef (Complex Type)”

· Section 3.4.36, “KeyRef (Complex Type)”

· Section 3.4.38, “LongName (Complex Type)”

· Section 3.4.39, “MimeTypedUri (Complex Type)”

· Section 3.4.44, “Row (Complex Type)”

· Section 3.4.45, “ShortName (Complex Type)”

· Section 3.4.46, “SimpleCodeList (Complex Type)”

· Section 3.4.48, “SimpleValue (Complex Type)”

· Section 3.4.50, “Value (Complex Type)”

· Section 3.4.49, “UseType (Simple Type)”

· Section 3.4.9, “CodeListSetChoice (Model Group)”

· Section 3.4.13, “ColumnChoice (Model Group)”

· Section 3.4.18, “ColumnSetChoice (Model Group)”

· Section 3.4.19, “ColumnSetContent (Model Group)”

· Section 3.4.26, “DocumentHeader (Model Group)”

· Section 3.4.31, “IdentificationRefUriSet (Model Group)”

· Section 3.4.32, “IdentificationVersionUriSet (Model Group)”

· Section 3.4.34, “KeyChoice (Model Group)”

· Section 3.4.40, “NameSet (Model Group)”

· Section 3.4.42, “OuterCodeListChoice (Model Group)”

· Section 3.4.47, “SimpleCodeListSequence (Model Group)”

· Section 3.4.51, “ValueChoice (Model Group)”

· Section 3.4.53, “VersionLocationUriSet (Model Group)”

· Section 3.4.15, “ColumnReference (Attribute Group)”

· Section 3.4.25, “DefaultDatatypeLibrary (Attribute Group)”

· Section 3.4.27, “ExternalReference (Attribute Group)”

· Section 3.4.29, “IdDefinition (Attribute Group)”

· Section 3.4.37, “Language (Attribute Group)”

· Section 3.4.41, “OptionalUseDefinition (Attribute Group)”

· Section 3.4.43, “RequiredUseDefinition (Attribute Group)”

· Section 3.4.52, “ValueIdentification (Attribute Group)”

Details of an agency which produces code lists or related artifacts.

Content Model: (ShortName? , LongName* , Identifier*)

Mixed Content: No

Elements:

User annotation information.

Content Model: (Description* , AppInfo?)

Mixed Content: No

Elements:

Container for any XML content which is in a different namespace to the Schema’s target namespace.

Content Model: (ANY[##other]*)

Mixed Content: No

Container for any human-readable XML content which is in a different namespace to the Schema’s target namespace.

Extension of: Section 3.4.3, “AnyOtherContent (Complex Type)”

Content Model: (ANY[##other]*)

Mixed Content: No

Attributes:

Top-level (root) element for a genericode code list definition.

A code list definition defines the details of a particular (version of a) code list.

Complex Type: Section 3.4.6, “CodeListDocument (Complex Type)”

Document type for genericode code list definitions.

Rules:

Content Model: ((Annotation? , Identification) , (ColumnSet | ColumnSetRef) , ((SimpleCodeList))?)

Mixed Content: No

Elements:

Attributes:

Reference to a code list, possibly defined in an external document.

Rules:

Content Model: (Annotation? , CanonicalUri , CanonicalVersionUri? , LocationUri*)

Mixed Content: No

Elements:

Attributes:

Top-level element for the definition of a code list set.

Complex Type: Section 3.4.10, “CodeListSetDocument (Complex Type)”

A choice between a code list reference, an inline code list set, or a code list set reference.

Content Model: (CodeListRef | CodeListSet | CodeListSetRef)

Elements:

Document type for the definition of a set of code lists.

Content Model: ((Annotation? , Identification) , (CodeListRef | CodeListSet | CodeListSetRef)*)

Mixed Content: No

Elements:

Attributes:

Reference to a code list set, possibly defined in an external document.

Rules:

Content Model: (Annotation? , CanonicalUri , CanonicalVersionUri? , LocationUri*)

Mixed Content: No

Elements:

Attributes:

Definition of a column.

Each column of a code list defines a piece of metadata that can be specified for each item in the code list.

Content Model: (Annotation? , (ShortName , LongName*) , (CanonicalUri , CanonicalVersionUri?)? , Data)

Mixed Content: No

Elements:

Attributes:

A choice between a column definition and a column reference.

Content Model: (Column | ColumnRef)

Elements:

Reference to a column defined in an external column set or code list.

Rules:

Content Model: (Annotation? , (CanonicalVersionUri , LocationUri*) , Data?)

Mixed Content: No

Elements:

Attributes:

Attribute set for referring to a column definition.

Attributes:

Top-level element for the definition of a column set.

Complex Type: Section 3.4.20, “ColumnSetDocument (Complex Type)”

Definition of a column set (columns and keys for a code list).

Content Model: ((Column | ColumnRef)* , (Key | KeyRef)*)

Mixed Content: No

Elements:

Attributes:

A choice between a column set definition and a column set reference.

Content Model: (ColumnSet | ColumnSetRef)

Elements:

Specific details of a column set.

Content Model: ((Column | ColumnRef)* , (Key | KeyRef)*)

Elements:

Document type for the definition of a column set, which is a set of code list columns and/or keys.

Content Model: ((Annotation? , Identification) , ((Column | ColumnRef)* , (Key | KeyRef)*))

Mixed Content: No

Elements:

Attributes:

Reference to a column set defined in an external column set or code list document.

Rules:

Content Model: (Annotation? , (CanonicalVersionUri , LocationUri*))

Mixed Content: No

Elements:

Attributes:

Data type definition.

Content Model: (Annotation? , Parameter*)

Mixed Content: No

Elements:

Attributes:

Restrictions to a data type.

Rules:

Content Model: (Parameter*)

Mixed Content: No

Elements:

Attributes:

Facet information for refining a datatype.

Extension of: xsd:string

Attributes:

Identification of the default datatype library for a column set.

Attributes:

General document information (metadata).

Content Model: (Annotation? , Identification)

Elements:

Attribute set used to identify a definition within an external document.

Attributes:

An identifier value. Typically not a long or short name.

Extension of: xsd:normalizedString

Attribute set used to identify a definition within the document.

Attributes:

Identification and location information (metadata).

Content Model: ((ShortName , LongName*) , Version , CanonicalUri , (CanonicalVersionUri , LocationUri* , AlternateFormatLocationUri*) , Agency?)

Mixed Content: No

Elements:

Identification and location URIs.

Content Model: (CanonicalVersionUri , LocationUri*)

Elements:

URIs used as unique identifiers.

Content Model: (CanonicalUri , CanonicalVersionUri?)

Elements:

Definition of a key.

A key is a set of one or more columns whose values together provide a unique identification of each item in a code list.

Rules:

Content Model: (Annotation? , (ShortName , LongName*) , (CanonicalUri , CanonicalVersionUri?)? , ColumnRef+)

Mixed Content: No

Elements:

Attributes:

A choice between a key definition and a key reference.

Content Model: (Key | KeyRef)

Elements:

Reference to a column which forms part of a key.

Content Model: (Annotation?)

Mixed Content: No

Elements:

Attributes:

Reference to a key defined in an external column set or code list.

Rules:

Content Model: (Annotation? , (CanonicalVersionUri , LocationUri*))

Mixed Content: No

Elements:

Attributes:

Attributes which describe the language of a piece of text.

Attributes:

A human-readable name.

Extension of: xsd:normalizedString

URI for a resource, with support for specifying the MIME type.

Extension of: xsd:anyURI

Attributes:

Various names.

Content Model: (ShortName , LongName*)

Elements:

Attribute set which defines the usage (optional attribute).

Attributes:

A choice which currently only allows a simple (explicit) code list definition.

Content Model: ((SimpleCodeList))

Elements:

Attribute set which defines the usage (required attribute).

Attributes:

Row which represents an individual item in a code list.

Content Model: (Annotation? , Value+)

Mixed Content: No

Elements:

A short name without whitespace that is suitable for use in generating names for software artifacts.

Rules:

Extension of: xsd:token

Attributes:

Simple (explicit) code list definition.

Rules:

Content Model: (Annotation? , Row*)

Mixed Content: No

Elements:

Details of a simple code list definition.

Content Model: (SimpleCodeList)

Elements:

Simple textual value.

Extension of: xsd:string

Indicates whether the usage is required or optional.

Restriction of: xsd:token

Allowed Values:

· optional

· required

An individual code list metadata value.

Content Model: (Annotation? , (SimpleValue | ComplexValue)?)

Mixed Content: No

Elements:

Attributes:

A choice between a simple textual value and a complex (structured) XML value.

Content Model: (SimpleValue | ComplexValue)

Elements:

Information which identifies one of a set of alternate values.

Attributes:

Identification and location URIs for a version.

Content Model: (CanonicalVersionUri , LocationUri* , AlternateFormatLocationUri*)

Elements: