CodeTypes and Code Lists

CodeTypes, and Code List Dictionaries: Working With Controlled Vocabularies

CodeType properties and code list dictionaries serve as foundational elements of DIGGS instances, critical to ensuring both flexibility and interoperability. This article provides comprehensive background on the purpose and implementation of codeType properties and code list dictionaries, featuring practical examples and GUIDANCE for properly referencing these dictionaries in your DIGGS instances.

What Are CodeTypes?

DIGGS codeType properties are XML string elements representing terms from controlled vocabularies or code lists. These elements include a codeSpace attribute – a value that references the dictionary, thesaurus, classification scheme or authority that defines the term. The DIGGS schema defines over 250 codeType properties for cases where property values might come from controlled lists of terms.

How Can I Tell If a DIGGS Element Is a CodeType Property?

Elements that use one of the following data types are DIGGS codeType properties. Click on a link below and then select an element of interest in the Used By section to view specific element documentation:

1. gml:codeType - string element with optional codeSpace attribute
2. gml:CodeWithAuthorityType - restriction of gml:codeType with a mandatory codeSpace attribute
3. diggs:DescriptorCodeType - extension of gml:codeType, adding a howDetermined attribute
4. diggs:SizeClassCodeType - extension of gml:codeType, adding a sizeClass attribute
5. diggs:ConstituentCategoryCodeType - extension of gml:codeType, adding howDetermined and category attributes

You can also view a list of current codeType properties in spreadsheet form here

Using codeSpace to Provide Context for a CodeType Property

⚠️ IMPORTANT

When the value of the codeType property is data only, and processing applications do not need to recognize its value or understand its meaning, then:

• the codeSpace value can be any plain language string that provides context for the value of the codeType property, or
• the codeSpace can be omitted if the meaning of the codeType value is universally clear

Some examples:

1. When no context is needed: ABC Drilling has an employee named Fred Smith. In a DIGGS instance, Fred's name would be encoded in a BusinessAssociate object as follows:

   <BusinessAssociate gml:id="FS>
       <gml:name>Fred Smith</gml:name>
   </BusinessAssociat>

   The codeType property gml:name needs no codeSpace because the meaning is clear from the element name.

2. When context is necessary to distinguish between multiple values: If Fred also has a nickname, context helps distinguish between them:

   <BusinessAssociate gml:id="FS">
       <gml:name codeSpace="full name">Fred Smith</gml:name>
       <gml:name codeSpace="nickname">Smitty</gml:name>
   </BusinessAssociate>

   Here, the codeSpace provides necessary context to understand the meanings of Fred's names.

3. When referencing an authority: If Fred's role on a job has specific meaning within an organization, his role might be encoded in a DIGGS instance as follows:

   <Role>
       <rolePerformed codeSpace="ABC Drilling">Roughneck</rolePerformed>
       <businessAssociate> 
           <BusinessAssociate gml:id="FS">
               <gml:name>Fred Smith</gml:name>
           </BusinessAssociate>
       </businessAssociate>
   </Role>

   The codeSpace attribute in the rolePerfomed codeType property indicates that "Roughneck" should be interpreted according to ABC Drilling's definition.

The Case for Code List Dictionaries

Using a plain language codeSpace value often doesn't provide sufficient information for automated processing. Consider our earlier example: if an application needs to determine whether Fred's "Roughneck" role should map to a database field named "DrillingAssistant," it must understand the precise definition of "Roughneck" in this context.

This is where controlled vocabularies become essential. In DIGGS, controlled vocabularies are implemented through standardized dictionaries that applications reference to process codeType values consistently. These dictionaries provide the definitions, relationships, and metadata that software needs to make intelligent decisions about how to handle each value.

When dictionaries are needed, the codeSpace attribute no longer simply names an authority (like "ABC Drilling"), but instead references the specific dictionary containing the controlled vocabulary. This reference allows applications to:

• Validate that the provided value is permissible for that property
• Access standardized definitions to determine proper handling
• Map between different terminology systems consistently
• Apply business rules based on the specific value's meaning

What is a DIGGS Dictionary?

DIGGS dictionaries hold values and definitions for specific codeType properties, providing controlled vocabularies that ensure interoperability. These dictionaries allow for flexibility and future-proofing by enabling creation and modification without schema changes, while also supporting custom vocabularies for different practices and use cases. They are specialized GML dictionaries (XML files) following the gml:Dictionary schema specification. Each dictionary contains diggs:Definition objects (extensions of gml:Definition), with one or more synonymous codeType values associated with one Definition object.

Each diggs:Definition object has four mandatory properties critical for interoperability:

1. gml:id (attribute): An identifier for the codeType value
2. gml:description: A definition of the codeType value
3. gml:identifier: The full URL to this diggs:Definition object – a globally unique value
4. gml:name: The codeType value itself. A Definition can have multiple synonymous names to support internationalization or localized terminology

Below is an example of a diggs:Definition object that defines a Unified Soil Classification Silty Sand for the classificationCode codeType property:

<diggs:Definition gml:id="SM">
    <gml:description>More than half of coarse soil passes No.4 sieve; passing No.200 > 12%; Atterberg's limits plot below "A" line in the plasticity chart or plasticity index less than 4.</gml:description>
    <gml:identifier codeSpace="https://diggsml.org/def/authorities.xml#DIGGS">https://diggsml.org/def/codes/DIGGS/0.1/astmD2487.xml#SM</gml:identifier>
    <gml:name>Silty sand</gml:name>
    <diggs:dataType>string</diggs:dataType>
    <diggs:authority>ASTM D2487</diggs:authority>
    <diggs:reference>https://www.astm.org/d2487-17.html</diggs:reference>
    <diggs:occurrences>
        <diggs:Occurrence>
            <diggs:sourceElementXpath>//diggs:Lithology/diggs:classificationCode</diggs:sourceElementXpath>
        </diggs:Occurrence>
    </diggs:occurrences>
</diggs:Definition>

In this example, the codeType property value is represented by the gml:name (Silty sand), defined by the gml:description property, and identified by the gml:id attribute (SM) and globally unique gml:identifier property (https://diggsml.org/def/codes/DIGGS/0.1/astmD2487.xml#SM). The diggs:sourceElementXPath property is used for code validation, indicating that this definition is valid for the classificationCode codeType property that occurs within any Lithology object.

⚠️ IMPORTANT

A DIGGS dictionary MUST be defined and referenced in the codeSpace attribute when the value of a codeType property:

1. Is used to map terms to a database or other schema
2. Is used in queries, automated processing, or data analysis
3. Is used to control data display or reporting formats

Although not required, a DIGGS dictionary SHOULD be defined and used when term definitions might not be universally understood, vary by authority, or depend on context.

DIGGS Standard Dictionaries

The DIGGS project develops and maintains a growing library of online DIGGS Standard dictionaries for critical and commonly used codeType properties. An index of these dictionaries, including links to view the dictionary codes and definitions, is available at this web page.

Most important among these are the measurement properties dictionaries that hold valid definitions for the propertyClass codeType property, which defines measurement parameters reported for tests, monitoring, and construction activities. These dictionaries are critical for DIGGS to function as an exchange standard. To ensure interoperability, the propertyClass codeType element MUST reference an appropriate DIGGS Standard measurement properties dictionary definition for an instance to be valid.

💡 NOTE

To promote universal interoperability, codeType properties should reference definitions from DIGGS Standard dictionaries whenever possible. Custom dictionaries and definitions should only be created if appropriate definitions do not exist in the DIGGS Standard dictionaries.

The use of custom dictionaries should be carefully considered. To enhance universal interoperability, you may request that your custom dictionaries or definitions be added to the DIGGS Standard library by posting an issue to the DIGGSml Github def repository.

GUIDANCE FOR ENCODING CODETYPE PROPERTIES

Previous guidance on the use of DIGGS dictionaries with codeType properties was to have the codeSpace represent the URL of the dictionary file, and the value hold either the gml:id or the gml:name of the appropriate diggs:Definition. For example, the classificationCode codeType property with a value of silty sand (as defined in the Unified Soil Classification System) would have been encoded either as:

<classificationCode codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/astmD2487.xml">SM</classificationCode>

or

<classificationCode codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/astmD2487.xml">Silty sand</classificationCode>

This encoding allows receiving and validating applications to retrieve the codeType property's definition unambiguously (assuming thre are no duplicate gml:name values in the dictionary). However, there are several downsides to this encoding, in particular:

• A dictionary lookup is always needed to obtain or verify the property's value (gml:name).
• Only one code value (gml:name) can be assigned to a definition in a dictionary for the code value lookup from a gml:id can be unambiguous.
• Synonymous code values for the codeType cannot be transferred without creation of a custom dictionary.

Because of these limitations, we provide the following guidance for encoding codeType properties in DIGGS instances:

⚠️ IMPORTANT

CodeType properties that reference dictionaries shall be encoded as follows:

The codeSpace attribute must be used and its value must be the gml:identifier for the code definition. This identifier is composed of:

1. The URL to the dictionary file
2. A fragment identifier (#)
3. The id of the code definition (gml:id)

The value of the codeType property shall be:

• Any of the gml:name values from the diggs:DEfinition object referenced by the codeSpace value, or
• Any specialized term that is synonymous with the gml:name of the diggs:Definition object referenced by the codeSpace value

💡 Note: Code list validators will no longer be required to check the codeType value, and will throw an error if the codeSpace URL is not equivalent to the gml:identifier of a valid diggs:Definition object. If a specialized term is used for the codeType value, it is incumbent on the user to ensure that the value is properly defined by the referenced dictionary definition.

Example Encodings Using the New Guidance

DIGGS Standard Encoding of classificationCode (from the dictionary example above)

<classificationCode codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/astmD2487.xml#SM">Silty sand</classificationCode>

The codeSpace attribute holds the value of the gml:identifier for the silty sand definition, while the codeType value matches the defnition's gml:name. Validators can retrieve the definition directly from the codeSpace value while processing applications can obtain the classificationCode value (Silty sand) without needing a dictionary lookup.

Using Localized Terms in codeType Properties

ABC Drilling Example
From the example discussed earlier, ABC Drilling can transmit their localized value "Roughneck" for the rolePerformed value while still maintaining interoperability by mapping "Roughneck" to the DIGGS Standard Dictionary definition with gml:id "helper" as follows:

<rolePerformed codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/roles.xml#helper">Roughneck</rolePerformed>

As long as the DIGGS Standard definition for "helper" is equivalent to ABC Driller's definition, the localized term "Roughneck" can be transmitted in the DIGGS instance, and processing applications that may not recognize that specific term can still process it properly by using the definition from the codeSpace value.

International Collaboration

Imagine you're working on a dam monitoring project with international partners. Your team in the US uses the term "Driller" while your German colleagues use "Bohrarbeiter" to describe the person who is operating the drill rig used for constructing boreholes. The DIGGS Standard Roles Dictionary has a definition with an id of "operator" that serves as the definition for both terms in this context. In your DIGGS instances, you may encode the role as follows:

<rolePerformed codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/roles.xml#operator">Driller</rolePerformed>

whereas your German colleagues would encode the role this way:

<rolePerformed codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/roles.xml#operator">Bohrarbeiter</rolePerformed>

Even though the code values ("Driller" and "Bohrarbeiter") are different, both encodings are valid as they reference a DIGGS Standard definition that is appropriate for the context. Furthermore, because both encodings reference the same definition, applications that might use the rolePerformed property for processing would handle both encodings correctly and consistently. In this way, technical accuracy is preserved while clear communication is maintained through use of the localized terms. Note: because neither of the codeType property values are in the DIGGS Standard dictionary, it is the responsibility of the users to ensure that the terms "Driller" and "Bohrarbeiter" match the "operator" definition.

Benefits of This Change

1. Consistent codeType encoding for any scenario that references a dictionary
2. The ability to transmit a preferred localized term without the need for a custom dictionary
3. Reliable Validation: Clear separation between the required definition and the code
4. Future-Proofing: Better supports evolution of the standard while maintaining backward compatibility

While this change does impact backward compatibility, it's a necessary step toward a more robust and flexible standard that will serve the geotechnical community better in the long run.