DDI Design Rules - draft work

Owned by Wendy Thomas
Last updated: Aug 08, 2019

Recommended Guidelines:

UML:

Default Values (TC-167):

Terminology:

"Model Default" When a piece of content like the xml:lang in the DDI Intance tag sets the "default" value to a specific language, so you can pull out a single object and not have to worry about an inherited value for some something

"Binding Default" Example: Version number defaulted to 1.0 in codelists for codeValues
DECISIONS:

Model Default: Anything that can be reused should not have information that has been inherited from a parent object within a specific hierachy. Information should be at the level of the reusable object.

Binding Default: binding level defaults are not allowed

Documentation: Documentation should be provided to implementers and tools creators identifying content that may be consistent throughout an instance (examples: agency ID, decimal delimitor, version number during development, language) and advise providing an option for setting this value throughout the document and allowing the user to overwrite the value at any given location.

Binding creation rules:

General:

Where the binding has a means of dealing with language we should use it, if not we need to create it (example: In JSON we will need to create a structure to specify language tagged strings) (TC-162)

XML:

In creating XML bindings all objects should be expressed as element except xml:lang  and xml:space which is a specific attribute of a textual string (TC-162)

Background and other related documents:

  File Modified

PDF File DDI Roadmap v1.0.pdf

Oct 21, 2019 by Jon Johnson

PDF File DDI Roadmap v2.0.pdf

Oct 21, 2019 by Jon Johnson

Microsoft Word Document DDI-Codebook-20210215.docx

Feb 24, 2021 by Wendy Thomas

Microsoft Word Document Technical Committee Review Coverage.docx

Apr 17, 2018 by Wendy Thomas

Background Information:

DDI 3 Design Rules from version 3.1 specification

2.0 DDI 3 Design
DDI 3 adds a lot of complexity, because it is designed to support the entire statistical lifecycle, rather than just the archival part. This places a major emphasis on being able to identify, version, and maintain the metadata throughout that process.

Further, it allows for groups of studies to be documented in relation to each other, for comparison purposes or to track versions as the metadata grows throughout the lifecycle.

Modularity supports both requirements by allowing a tighter focus on metadata that is of interest to a specific application or user. While this may seem complex, once the basic design is understood, it allows for a much more exact expression of the metadata, and, in the long term, better management and processing of that metadata.

2.1 Design Rules
The demands of the changes noted above made it clear that DDI 3 needed to outline clear design rules to ensure consistency in the creation and development of DDI 3

• Persistent sections should be separate from dynamic information. What parts change when a data file moves from one “home” to another, or changes something like its physical storage structure?
• Information modules should follow the various life cycle paths
• Information used for discovery should be in non-specialized modules
• Links should be unidirectional to avoid loops and broken links as materials are repacked or versioned
• Links should point back in time with materials later in the lifecycle pointing to existing materials rather than going back and adding new links
• All comparisons are pair wise, comparing a source with a target.
• Groups inherit down the tree unless there is a clear local override provided
• Functionality of DDI 2.1 would be preserved
• Different types of XML elements will inherit from each other in XML schemes, to simplify programmatic processing of basic types which have many different variations throughout the lifecycle.
• Metadata will be expressed in ways which support both human-readability and machine-processing.