Naming and Design Rules Change History

The NIEM Naming and Design Rules Specification is updated with major NIEM releases, occurring every three years. The following highlights the changes that have been made.

NDR 5.0 Changes

The NIEM Naming and Design Rules (NDR) specification was updated from version 4.0 to version 5.0 in 2020, corresponding with the NIEM 5.0 major release.

Key changes include

  • Simplified the folder layout in the release package, removing version folders and unnecessary nesting (#140)

  • Changed the character encoding of the XML schemas from “US-ASCII” to “UTF-8” for better international support (#125)

  • Added attribute xml:lang to reference schemas (#153)

  • Updated structures and appinfo utility schemas to version 5.0 based on NDR updates (#157)

  • Reestablished the structures:sequenceID attribute (#154)

  • Updated the conformance targets to correspond with the new 5.0 version of the NDR

See highlighted changes of the specification text.

New rules

Several new rules have been added to the NDR for 5.0:

Rule 5-1 (INS): structures:uri denotes resource identifier

The interpretation of a conformant instance XML document MUST be consistent with an RDFS interpretation of the RDF graph composed of the RDF entailed by the XML document and the RDF entailed by the schema.

Rule 10-45 (REF, EXT): Schema component name has xml:lang

The name of an XML Schema component defined by the schema MUST be in the scope of an occurrence of attribute xml:lang that has a value that is not empty.

Rule 11-2 (REF, EXT): Only types have name ending in Type or SimpleType

A schema component with a name that ends in 'SimpleType' MUST be a simple type definition.

Rule 11-30 (REF, EXT): xs:documentation has xml:lang

An occurrence of xs:documentation within the schema MUST be in the scope of an occurrence of attribute xml:lang that has a value that is not empty.

Rule 12-10 (INS): Order of properties is expressed via structures:sequenceID

Given two properties of object $Object,If $Value1 is less than $Value2, then $Property1 MUST be interpreted as occurring before $Property2 within $Object.If $Value2 is less than $Value1, then $Property2 MUST be interpreted as occurring before $Property1 within $Object.The value of an attribute structures:sequenceID MUST be interpreted as an integer value. Comparisons between their values must be interpreted as comparisons between integers.The relative order of two properties, where either does not have attribute structures:sequenceID is unspecified. The relative order of two properties that have the same value for attribute structures:sequenceID is unspecified.

Modified rules

Modified rule conformance targets

In NDR 4.0, the following rule only applied to REF. In 5.0, it is now applied to EXT as well.

Rule 10-70 (REF, EXT): External adapter type indicator annotates complex type

The attribute {http://release.niem.gov/niem/appinfo/5.0/}externalImportIndicator MUST be owned by an element xs:import.

Modified rule numbers

Due to the addition of the new rules outlined above, inserted throughout the specification, some rule numbers from the NDR 4.0 version have shifted in the 5.0 version.

Expand to view the 93 adjusted rule numbers
NDR 4.0 NDR 5.0 Applicability Title
10-45 10-46 REF, EXT Schema component names have only specific characters
10-46 10-47 REF, EXT Punctuation in component name is a separator
10-47 10-48 REF, EXT Names use camel case
10-48 10-49 REF, EXT Attribute name begins with lower case letter
10-49 10-50 REF, EXT Name of schema component other than attribute and proxy type begins with upper case letter
10-50 10-51 REF, EXT Names use common abbreviations
10-51 10-52 REF, EXT Local term declaration is local to its schema document
10-52 10-53 REF, EXT Local terminology interpretation
10-53 10-54 REF, EXT Singular form is preferred in name
10-54 10-55 REF, EXT Present tense is preferred in name
10-55 10-56 REF, EXT Name does not have nonessential words
10-56 10-57 REF, EXT Element or attribute name follows pattern
10-57 10-58 REF, EXT Object-class term identifies concrete category
10-58 10-59 REF, EXT Property term describes characteristic or subpart
10-59 10-60 REF, EXT Name may have multiple qualifier terms
10-60 10-61 REF, EXT Name has minimum necessary number of qualifier terms
10-61 10-62 REF, EXT Order of qualifiers is not significant
10-62 10-63 REF, EXT Redundant term in name is omitted
10-63 10-64 REF, EXT Element with simple content has representation term
10-64 10-65 REF, EXT Element with complex content has representation term when appropriate
10-65 10-66 REF, EXT Element with complex content has representation term only when appropriate
10-66 10-67 REF, EXT Machine-readable annotations are valid
10-67 10-68 REF, EXT Component marked as deprecated is deprecated component
10-68 10-69 REF, EXT Deprecated annotates schema component
10-69 10-70 REF, EXT External import indicator annotates import
10-70 10-71 REF, EXT External adapter type indicator annotates complex type
10-71 10-72 REF, EXT appinfo:appliesToTypes annotates metadata element
10-72 10-73 SET appinfo:appliesToTypes references types
10-73 10-74 REF, EXT appinfo:appliesToElements annotates metadata element
10-74 10-75 SET appinfo:appliesToElements references elements
10-75 10-76 REF, EXT appinfo:LocalTerm annotates schema
10-76 10-77 REF, EXT appinfo:LocalTerm has literal or definition
10-77 10-78 REF, EXT, INS, SET Use structures consistent with specification
11-2 11-3 REF, EXT Base type definition defined by conformant schema
11-3 11-4 REF, EXT Name of simple type ends in SimpleType
11-4 11-5 REF, EXT Use lists only when data is uniform
11-5 11-6 REF, EXT List item type defined by conformant schemas
11-6 11-7 REF, EXT Union member types defined by conformant schemas
11-7 11-8 REF, EXT Name of a code simple type ends in CodeSimpleType
11-8 11-9 REF, EXT Code simple type corresponds to a code list
11-9 11-10 REF, EXT Attribute of code simple type has code representation term
11-10 11-11 REF, EXT Complex type with simple content has structures:SimpleObjectAttributeGroup
11-11 11-12 REF, EXT Element type does not have a simple type name
11-12 11-13 REF, EXT Element type is from conformant namespace
11-13 11-14 REF, EXT Name of element that ends in Abstract is abstract
11-14 11-15 REF, EXT Name of element declaration with simple content has representation term
11-15 11-16 SET Name of element declaration with simple content has representation term
11-16 11-17 REF, EXT Element substitution group defined by conformant schema
11-17 11-18 REF, EXT Attribute type defined by conformant schema
11-18 11-19 REF, EXT Attribute name uses representation term
11-19 11-20 REF, EXT Element or attribute declaration introduced only once into a type
11-20 11-21 REF, EXT Element reference defined by conformant schema
11-21 11-22 REF, EXT Referenced attribute defined by conformant schemas
11-22 11-23 REF, EXT Schema uses only known attribute groups
11-23 11-24 REF, EXT Data definition does not introduce ambiguity
11-24 11-25 REF, EXT Object class has only one meaning
11-25 11-26 REF, EXT Data definition of a part does not redefine the whole
11-26 11-27 REF, EXT Do not leak representation into data definition
11-27 11-28 REF, EXT Data definition follows 11179-4 requirements
11-28 11-29 REF, EXT Data definition follows 11179-4 recommendations
11-29 11-31 REF, EXT Standard opening phrase for augmentation point element data definition
11-30 11-32 REF, EXT Standard opening phrase for augmentation element data definition
11-31 11-33 REF, EXT Standard opening phrase for metadata element data definition
11-32 11-34 REF, EXT Standard opening phrase for association element data definition
11-33 11-35 REF, EXT Standard opening phrase for abstract element data definition
11-34 11-36 REF, EXT Standard opening phrase for date element or attribute data definition
11-35 11-37 REF, EXT Standard opening phrase for quantity element or attribute data definition
11-36 11-38 REF, EXT Standard opening phrase for picture element or attribute data definition
11-37 11-39 REF, EXT Standard opening phrase for indicator element or attribute data definition
11-38 11-40 REF, EXT Standard opening phrase for identification element or attribute data definition
11-39 11-41 REF, EXT Standard opening phrase for name element or attribute data definition
11-40 11-42 REF, EXT Standard opening phrase for element or attribute data definition
11-41 11-43 REF, EXT Standard opening phrase for association type data definition
11-42 11-44 REF, EXT Standard opening phrase for augmentation type data definition
11-43 11-45 REF, EXT Standard opening phrase for metadata type data definition
11-44 11-46 REF, EXT Standard opening phrase for complex type data definition
11-45 11-47 REF, EXT Standard opening phrase for simple type data definition
11-46 11-48 REF, EXT Same namespace means same components
11-47 11-49 REF, EXT Different version means different view
11-48 11-50 SET Reference schema document imports reference schema document
11-49 11-51 SET Extension schema document imports reference or extension schema document
11-50 11-52 REF, EXT Structures imported as conformant
11-51 11-53 REF, EXT XML namespace imported as conformant
11-52 11-54 SET Each namespace may have only a single root schema in a schema set
11-53 11-55 REF, EXT Consistently marked namespace imports
12-10 12-11 INS Metadata applies to referring entity
12-11 12-12 INS Referent of structures:relationshipMetadata annotates relationship
12-12 12-13 INS Values of structures:metadata refer to values of structures:id
12-13 12-14 INS Values of structures:relationshipMetadata refer to values of structures:id
12-14 12-15 INS structures:metadata and structures:relationshipMetadata refer to metadata elements
12-15 12-16 INS Attribute structures:metadata references metadata element
12-16 12-17 INS Attribute structures:relationshipMetadata references metadata element
12-17 12-18 INS Metadata is applicable to element

NDR 4.0 Changes

The NIEM Naming and Design Rules (NDR) specification was updated from version 3.0 to version 4.0 in 2017, corresponding with the NIEM 4.0 major release.

Updated version from 3.0 to 4.0, affecting:

  • Namespaces: structures, appinfo, NDR functions namespace
  • Conformance target identifiers: REF, EXT

Now managing specification on GitHub (https://github.com/NIEM/NIEM-NDR/) for:

  • Revisions/updates/errata: posted to the document repository
  • Comments/issues: posted as GitHub issues

NDR Section 2.4.2 - Schematron updates

  • Eliminated warning rules (sch:report) that always fire
  • Added attribute (role="warning") to warning rules
  • Broke apart overly-large rule on standard opening phrases into smaller rules

NDR Section 5 - RDF updates

  • Simplified RDF representation
    • RDF is much simpler than v3, with direct properties instead of reification
    • Allows for more direct JSON representation via JSON-LD
  • Removed RDF representation for metadata types

NDR Section 6 & 8 - XML processing and defaults

  • Improved discussion of infoset augmentation, fixed, and default
  • Allow use of fixed on attribute uses that are required in an instance

NDR Section 10 & 11 - Naming

  • Relaxed rules on component naming from MUST to SHOULD (USMTF)
  • Allow all valid ASCII characters in component names
    • Allowed: “A”-“Z”, “a”-“z”, “0”-“9”, “-“, “_”, “.”

NDR Section 10 & 11 - Codes

  • Allow code elements and code types to be represented by methods other than enumerations
  • Described as correspondence to a list of conceptual entities
  • Relaxed rules for structure/content of code elements and types
  • Relaxed naming rules for code elements and types

NDR Section 12 - Linked data approach

  • Added attribute structures:uri
  • Defined structures:id and structures:ref in terms of structures:uri (Appendix B)
  • Allow properties of objects to be distributed across multiple objects with the same identifier
    • Removed requirement that elements with structures:ref have no properties
  • Major rewrite to section 12.1, 12.2, addressing data’s meaning, identity, and references

Miscellaneous

  • Grammar, spelling, and narrative improvements
  • Moved content of the Local Terminology namespace (term) into the Application Information namespace (appinfo)
  • Explicitly allow structures namespace to be subset

(See full diffs)


NDR 3.0 Changes

The NIEM Naming and Design Rules (NDR) specification was updated from version 1.3 to version 3.0 in 2014, corresponding with the NIEM 3.0 major release.

Changes include:

  • Replaced conformant indicator with conformance targets for reference schema, extension schema, conformant schema document set and conformance instance XML document.

  • Updated the approach used for augmentations. Replaced the use of type substitution with element substitution, and added augmentation point elements to object and association types.

  • Added support for local vocabularies.

  • Added structures:ref and merged content and reference elements.

  • Added NDR Schematron rules to normatively define and validate conformance where possible.

  • Replaced ComplexObjectType with ObjectType and AssociationType.

  • Added multiple representations of code lists (code, literal).

  • Removed appinfo base.

  • Removed sequenceID, augmentation and metadata elements.

  • Replaced external adaptor type indicator with an attribute.

  • Added external import indicator.

  • Replaced applies-to element with substitution groups for augmentations and applies-to types and applies-to elements for metadata.

  • Replaced link metadata with relationship metadata.

  • Replaced appinfo annotation elements with attributes.

  • Replaced reference target annotations with XML schema type attribute.