Important Update: New Guidelines for DIGGS CodeType References

CodeType properties and code list dictionaries serve to manage controlled vocabularies and are foundational elements of the DIGGS standard. To improve both interoperability and flexibility across geotechnical data exchange, the DIGGS Team is pleased to announce updated guidelines for referencing code list dictionaries in DIGGS instances. These changes address key feedback from the 2025 DIGGS Code Jam Challenge.

What's Changing?

We're standardizing how codeType properties reference DIGGS dictionaries. This change offers significant benefits:

Greater flexibility: Use your preferred terminology while maintaining compatibility
Better interoperability: Ensure consistent interpretation across systems
Simplified validation: Clear separation between definitions and displayed values
Future-proofing: Support for evolution without breaking existing implementations

The New Approach in Brief

Previously, code list dictionary references placed the dictionary URL in the codeSpace attribute and allowed either the dictionary code identifier or code name as the element value. For example::

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

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

Our new guidelines now require a single encoding:

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

This change moves the code identifier (SM) into the codeSpace reference after a fragment identifier (#), with the element value being the code name or a synonymous term.

Real-World Benefits

This approach addresses several practical issues:

International collaboration: Teams can exchange data using their local terminology while maintaining technical accuracy
Specialized terms: Organizations can use internal terminology without creating custom dictionaries
Simplified processing: Applications can access standardized definitions directly from the codeSpace reference

What You Need to Do

Existing DIGGS files that reference dictionaries will need updating to pass code list validation
Review your codeType properties to ensure they follow the new reference format

The DIGGS Team is committed to building a robust standard that serves the geotechnical community effectively. While this change does impact backward compatibility, we believe it's a necessary step toward a more flexible and interoperable future.

Learn More

For developers and data managers who need detailed technical guidance, we've prepared comprehensive documentation covering:

Full explanation of codeType properties and dictionaries
Detailed examples of the new reference format
Validation requirements

Join the DIGGS Effort!

We're constantly working to improve DIGGS, and your input is valuable. Here's how you can participate:

GitHub: Contribute to our repositories at https://github.com/DIGGSml/
Monthly Meetings: Join our monthly online discussions where we tackle issues like this one. Contact Allen Cadden or Ross Cutts to receive meeting invites.
Feedback: Share your experiences implementing these changes