Controlled Vocabularies Usage | Data Documentation Initiative

In DDI-Lifecycle a limited number of elements have hard coded controlled vocabularies, therefore mandatory to use. But for most of the elements in which the use of a controlled vocabulary is appropriate, the DDI Alliance is publishing the recommended code lists as a separate product, external to the DDI schema.

This makes both the schema and the CV lists easier to maintain and update, since they are not tied to each other. It also gives DDI users the option of incorporating the controlled vocabularies in their instances or not, or even using alternative vocabularies if needed.

Finally, since they are independent documents, these code lists may be used with any version of DDI (with some restrictions that are noted in the vocabularies’ documentation), as well as in other documentation standards, or environments outside DDI.

Using the Controlled Vocabularies with other documentation standards

For those users who do not reference the CVs from a DDI instance, but choose to use them in conjunction with other documentation standards, the following citation formats are recommended:

For published CVs:

DDI Alliance: [short name] CV, [version], [URI]
Example: DDI Alliance: TimeMethod CV, V1.1, http://www.ddialliance.org/Specification/DDI-CV/TimeMethod_1.1.html

For unpublished CVs:

DDI Alliance: [short name] CV, unreleased beta version, [date in ISO format YYYY-MM-DD]
Example: DDI Alliance: ModeOfCollection CV, unreleased beta version, 2013-03-28.

Please note that, when needed, some organizations may choose to use beta versions of CVs in direct consultation with the Controlled Vocabularies Working Group (ddi-cvg@ddialliance.org)

Using the Controlled Vocabularies in DDI-L

DDI-L elements that support use of external vocabularies have a specific structure, of CodeValueType, to allow this usage, and enable machine-actionability. The content of an element of CodeValueType may be a simple string (if no controlled vocabulary is used) or a code from a CV list, in which case a number of attributes (codeListID, codeListName, codeListAgencyName, codeListVersionID, codeListURN, codeListSchemeURN) allow referencing the external resource. Finally, the attribute otherValue is intended for specifying a value that does not appear in the list that is being used.

The following example is provided to illustrate CV usage.

Example -- AnalysisUnit

The AnalysisUnit controlled vocabulary can be used with the DDI 3.1 Variable element to specify the unit of analysis, or unit of observation.

DDI 3.1 sample markup:

<l:Variable>

<r:AnalysisUnit codeListID="AnalysisUnit"

codeListVersionID="1.0.0"

codeListURN="urn:ddi-cv:AnalysisUnit:1.0.0"

codeListAgencyName="DDI Alliance">Individual</r:AnalysisUnit>

Details

The attributes used in DDI 3.1 to identify the controlled vocabulary that is being used correspond to related items in the Genericode format.

codeListID corresponds to the short name of the code list.
codeListVersionID corresponds to version.
codeListURN corresponds to the canonical URI of this version.
codeListAgencyName corresponds to the short name of the agency
the content is a value of the code list

Resolution of a URN by a local XML catalog (example)

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

<!DOCTYPE catalog SYSTEM "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">

</catalog>

An XML Catalog can map URNs to URLs. An XML Catalog can be used by major XML parsers like xalan and saxon.

Collection migration following the publication of new CV versions

Controlled Vocabularies users may choose to retrofit their collections to reflect changes in the CVs as new versions are published.

The DDI-CVG has produced a set of guidelines intended to provide assistance in collection migration following the publication of new CV versions. They are suggestions only, and as such may not be applicable or suitable to every circumstance.