DDI Alliance

Controlled Vocabularies - Overview

The DDI Controlled Vocabularies Group (CVG) has created a set of controlled vocabularies that can be used with DDI as well as for other purposes and applications. Many of the DDI Alliance vocabularies are already in use worldwide -- across Europe, by countries belonging to the Consortium of European Social Science Data Archives (CESSDA), in the United States by the Inter-university Consortium for Political and Social Research (ICPSR), and Mathematica Policy Research, in Canada, etc. DDI Controlled Vocabularies are also incorporated in editing and publishing tools that work with the DDI specification, like Colectica and Nesstar Publisher.

For RDF representations of the DDI Controlled Vocabularies and linked data API documentation, see the DDI CV Postman Collection.

In the controlled vocabularies presentation below, downloads are available in HTML, PDF and XML formats. RDF representations and linked data API documentation are available at the DDI CV Postman Collection.

Usage information for each controlled vocabulary is available in the vocabulary documentation. The published DDI CVs may be used with relevant classes from both DDI-Codebook and DDI-Lifecycle.

The languages in which translations are available are listed in the HTML presentation of the individual CVs. From there, users can select the language(s) they wish to download. The PDF and XML presentations include all available translations in the same document.

The DDI Controlled Vocabularies Group (CVG) functions as the management team for the vocabularies. Comments, as well as suggestions for amendments or additions, are welcome from all users. To provide feedback, or submit proposals for changes, please contact the CVG.

The DDI versioning policy as described below has been approved by the DDI Alliance in November 2022 and is published and implemented starting January 2023. This new protocol supersedes the previous policy which was based on a two-digit version numbering system. Users who have referenced these vocabularies prior to February 1, 2023 will need to retroactively change any version reference from V. x.x (two digits -- e.g., V. 1.0) to V. x.x.x (three digits -- e.g., V. 1.0.0). From that point on, new versions can be used and referenced normally.

Versioning is done at the level of each published controlled vocabulary (CV), and not at the code/concept level.

A code/concept in a vocabulary consists of the following parts:

Code valueThe specific content that can be entered into the DDI specification as an identifier of the code across languages. In hierarchical lists, all of the levels are always mentioned in each code value, and are separated by a period (for example, AutomatedDataExtraction.ApiQuery).
Descriptive termThe display label associated with the code. This may be available in multiple languages.
DefinitionThe definition of the code. This may be available in multiple languages.

Both the vocabularies and the individual concepts/codes have a persistent identifier (PID), that is, a Linked Data URI available in the SKOS/RDF export. Even though the URIs include a CV version number that may change over time, the vocabulary and the codes will remain findable based on the CV short name and the 7-character alphanumeric ID in the URI.

‘English’ refers to the source language of DDI vocabularies, that is, American English.

The versioning policy is based on an intellectual, or logical, assessment of the nature of the change, which distinguishes between major, minor and sub-minor changes in the vocabularies, as described further below. To reflect these distinctions, the version numbering system is based on a three-level structure (examples: 1.0.0, 1.2.3). All version levels will always be included in the version number.

A change in the first digit of the version number will indicate a major change in the controlled vocabulary. Major changes are any substantive amendments in the content or meaning of a vocabulary (concept scheme) or code (concept), as specified below. Changes in the second digit of the version number will indicate a minor change. Minor changes are changes in wording, spelling in English, etc. (i.e., "form") that do not involve changes in intellectual content or meaning. Major and minor changes affect the source language (English) only.

A change in the third digit will indicate a sub-minor change. Sub-minor changes are changes in content of language variants at vocabulary or code level, for instance, title, definition or descriptive term amendments in any other languages than English. Sub-minor changes include the addition of a new language.

Users who have referenced these vocabularies prior to February 1, 2023 will need to retroactively change any version reference to a three-digit version by checking the value of the new third digit number on the DDI Alliance controlled vocabularies website and updating the version reference accordingly. For example, they should change ModeOfCollection 3.0 to ModeOfCollection 3.0.0. After February 1, 2023, new versions can be used and referenced normally. The previous URIs with the old two-digit version number will still find the published vocabularies with the new three-digit version number.

Major, minor and sub-minor changes are specified below. Note that these changes do not include changes to the short name of a vocabulary. Any change to the short name of a vocabulary results in the deprecation of that vocabulary. CV notes, usage information and version history can be edited without impact on versioning.

Major changes that may break the backward compatibility - X.0.0 first digit changes

  • Vocabulary definition is amended with meaning change in English
  • Code/concept is added
  • Code/concept is deprecated
  • Code is replaced by another code
  • Code value of a concept is changed
  • Code/concept definition change with meaning change in English
  • Descriptive term change with meaning change in English

Minor change - 1.X.0 second digit changes

  • Vocabulary long name (title) is rephrased in English with no meaning change, for example, due to a typo
  • Vocabulary definition is rephrased with no meaning change in English
  • Code/concept definition is added in English
  • Code/concept definition is rephrased without meaning change in English
  • Descriptive term is rephrased without meaning change in English

Sub-minor change - 1.0.X third digit changes

  • Changes in any other languages than English that affect versioning, including:
    • Vocabulary long name rephrased with no meaning change
    • Vocabulary definition amended with meaning change
    • Vocabulary definition rephrased with no meaning change
    • Vocabulary definition added
    • Code/concept definition is added
    • Code/concept definition is amended with meaning change
    • Code/concept definition rephrased with no meaning change
    • Descriptive term amended with meaning change
    • Descriptive term rephrased with no meaning change

Deprecation of a vocabulary (concept scheme):

  • The CV short name is an identifier that is the same across languages. It is not translated.

  • If the short name of a vocabulary is changed, the whole vocabulary, including all its language variants, is deprecated, and a new vocabulary is published with the new name. Versioning of the new vocabulary starts from scratch. Changing the short name signifies that it is a different vocabulary used for a different element in the DDI standard and therefore DDI Alliance considers it to be a new vocabulary.

  • Another reason it is necessary to deprecate a vocabulary if its short name changes is because a change to the short name entails a change to all the other machine-actionable vocabulary identifiers, including the PID and URI.

  • If the vocabulary's long name (title) changes with a change in meaning, then the short name also changes, thus causing the vocabulary to be deprecated. Typo corrections and other small changes in the long name do not cause the short name to change.

Vocabulary-level changes in English

DOCUMENTATION CHANGE EXPRESSEDLOGICAL EXPRESSIONEXPLANATIONCHANGE TYPE
CV DEFINITION AMENDED WITH MEANING CHANGEXThe CV definition is amended to reflect a change in meaning for the CV in English.Major
CV LONG NAME REPHRASEDXThe CV title is amended without a change to the meaning (short name does not change).Minor
CV DEFINITION REPHRASEDXThe definition for the CV is rephrased for clarity, edited for accuracy without a change in meaning in English.Minor

Vocabulary-level changes in language variants

DOCUMENTATION CHANGE EXPRESSEDLOGICAL EXPRESSIONEXPLANATIONCHANGE TYPE
CV LONG NAME REPHRASEDXThe CV title is amended without a meaning change in another language than English.Sub-minor
CV DEFINITION REPHRASEDXCV definition is rephrased without a meaning change in another language than English.Sub-minor
CV DEFINITION AMENDED WITH MEANING CHANGEXCV definition is amended with meaning change in another language than English.Sub-minor
CV DEFINITION ADDEDXCV definition is added in another language than English.Sub-minor

Code/concept-level changes in English

DOCUMENTATION CHANGE EXPRESSEDLOGICAL EXPRESSIONEXPLANATIONCHANGE TYPE
CODE ADDED--> ZA new code Z is added to the CV.Major
CODE DEPRECATEDX -->Code X is deprecated from the CV.Major
CODE IS REPLACED BYX, Y (n) --> ZOne or more codes (X, n) are deprecated, and their meaning is taken over by a new Z.Major
CODE VALUE CHANGEDX --> ZThe value of code X is changed to Z but its definition remains the same.Major
CODE DEFINITION AMENDED WITH MEANING CHANGEXThe definition for code X is amended to reflect a change in meaning for code X.Major
CODE DESCRIPTIVE TERM AMENDED WITH MEANING CHANGEXThe descriptive term for code X is amended with a change in meaning.Major
CODE DEFINITION ADDEDXDefinition is added for the code X.Minor
CODE DEFINITION REPHRASEDXThe definition for code X is rephrased for clarity, edited for accuracy, or an example is added or deleted without a change in meaning.Minor
DESCRIPTIVE TERM REPHRASEDXThe term describing code X is rephrased for clarity or edited for accuracy, without a change in meaning.Minor

Code/concept-level changes in language variants

DOCUMENTATION CHANGE EXPRESSEDLOGICAL EXPRESSIONEXPLANATIONCHANGE TYPE
CODE DEFINITION ADDEDXA definition for code X is added.Sub-minor
CODE DEFINITION AMENDED WITH MEANING CHANGEXThe definition for code X is amended to reflect a change in meaning for code X.Sub-minor
CODE DEFINITION REPHRASEDXThe definition for code X is rephrased for clarity, edited for accuracy, or an example is added or deleted without a change in meaning.Sub-minor
CODE DESCRIPTIVE TERM AMENDED WITH MEANING CHANGEXThe descriptive term for code X is amended with a change in meaning.Sub-minor
CODE DESCRIPTIVE TERM REPHRASEDXThe term describing code X is rephrased for clarity or edited for accuracy, without a change in meaning.Sub-minor

In addition to a change in the version number, each new version of a CV will contain documentation in the version history about how the new CV compares with the previous version, filtered by language. The changes will be documented using the following structure:

CV LONG NAME REPHRASED:
Reponse Unit changed to Response Unit
CV DEFINITION AMENDED WITH MEANING CHANGE:
AnalysisUnit
CV DEFINITION REPHRASED:
ModeOfCollection
CODE ADDED:
AutomatedDataExtraction
CODE DEPRECATED:
SelfAdministeredQuestionnaire.FixedForm, is replaced by SelfAdministeredQuestionnaire
CODE VALUE CHANGED:
Interview.FaceToFace.CAPICAMI changed to Interview.FaceToFace.CAPIorCAMI
CODE DESCRIPTIVE TERM AMENDED WITH MEANING CHANGE:
From Geographical to Geospatial
CODE DEFINITION ADDED:
Longitudinal.Panel
CODE DEFINITION AMENDED WITH MEANING CHANGE:
Longitudinal.Panel
CODE DEFINITION REPHRASED:
SelfAdministeredQuestionnaire.CAWI
DESCRIPTIVE TERM REPHRASED:
Interview: Face-to-face: CAOI rephrased into Interview: Face-to-face: CAPI
DESCRIPTIVE TERM REPHRASED:
Haastattelu: Kasvokkainen haastattelu: CAOI rephrased into Haastattelu: Kasvokkainen haastattelu: CAPI (an example in the language variant Finnish)

© 2024 DDI Alliance