Properties

A property represents a concept, idea, or thing. It defines specific semantics and appears in exchanges as the tag or label for a field.

Properties may be more commonly known as as elements, attributes, fields, tags, keys, or keywords.

One of the properties defined in Core is PersonBirthDate. It represents a person’s birthday and will carry that value in an exchange.

  • The type of the property will define the value’s structure (e.g., free text or a specific date format).
  • The property itself is what gives this date value its meaning and distinguishes it from other kinds of dates that might appear, such as a driver license expiration date.

On its own, a property has meaning but no inherent structure.

Without a type, any kind of value could be provided for property PersonBirthDate above, like the following:

  • 06/30/1950
  • 1950-06-30
  • June 30th, 1950
  • green (without a type, any value is valid)

A property must have an assigned type in order to have both clear semantics and a well-defined structure.

Elements vs Attributes

In NIEM, there are two basic kinds of properties: elements and attributes.

Attributes can only ever be used to represent simple content (a value). They do not exist independently; they must be carried by an element.

Elements can be used to represent simple content (a value) or complex content (an object). In either case, an element can also carry attributes.

This example lists 5 elements (each beginning with nc:Person) and 2 attributes (structures:id and nc:personNameInitialIndicator):

<nc:Person>
  <nc:PersonName structures:id="a123">
    <nc:PersonGivenName>John</nc:PersonGivenName>
    <nc:PersonMiddleName nc:personNameInitialIndicator="true">Q</nc:PersonMiddleName>
    <nc:PersonSurName>Smith</nc:PersonSurName>
  </nc:PersonName>
</nc:Person>

Attributes cannot be extended, substituted, augmented, or have multiple occurrences. Additionally, because NIEM uses attributes for referencing and linking data, metadata, and security markup, elements should be used over attributes whenever possible in order to support these features. Over 99% of the properties in NIEM are elements.

The information on this page describes a general property in NIEM. Information about specific kinds of properties, their XML representations, and their JSON representations or alternatives appear as sub-pages under this section:

  • Elements

    An element represents a concept. In an instance, it acts as a container that may carry either a simple value or an object, and optionally attributes.

  • Abstract Elements

    An abstract element is an element defined as a placeholder in a schema that must be replaced with an appropriate substitution in an instance.

  • Substitutable Elements

    A substitutable element is one that can replace another element in an instance.

  • Attributes

    An attribute is a property that may carry a simple value only.

Modeling Guidance

Information about property names and definitions are provided separately in the pages that follow. Other rules and guidance for modeling properties are provided below.

Global

All properties must be declared globally as top-level elements in a schema. One of the key principles of NIEM is to maximize reuse. A local property cannot be reused outside of the one type in which it is defined.

Conformant type

A property type must be NIEM-conformant.

Only an abstract element may be defined without a type.

Naming

A single NIEM component name may consist of multiple terms. A term is a meaningful word, an abbreviation for a word, or an acronym.

The following provides rules and guidance for naming properties.

OED Terms

Besides the additional accepted terms listed below, terms should be real words as defined by the Oxford English Dictionary.

Spelling

For consistency, words should use the preferred U.S. spelling as defined in the Oxford English Dictionary.

Additional terms

Additional terms that may be used are:

  • ID, the authorized abbreviation for Identifier
  • URI, the authorized abbreviation for Uniform Resource Identifier
  • Local terminology, defined by a NIEM namespace.

Parts of a name

In accordance with IEC/ISO 11179 Part 5, terms that make up a NIEM property name are classified into four basic parts according to their placement and function:

  • Object
  • Qualifier
  • Property
  • Representation

Object term

An object term is the real world object or concept to which this name applies. This may be omitted if the property is very generic and no specific class applies.

  • AircraftFuselageColorCode - a color of the main body of an aircraft.
  • Aircraft is the object term. In this example, that is the object being modeled.

Qualifier term

A qualifier term indicates more specific information applicable to the object, property, or representation term.

  • Multiple qualifier terms may be used if needed.
  • Qualifiers are optional.
  • AircraftFuselageColorCode - a color of the main body of an aircraft.
  • Fuselage is a qualifier term. In this example, it describes what kind of color is expected.
  • A related element in NIEM is AircraftWingColorCode. Wing would be the qualifier term in that example.

Property term

A property term is the characteristic, or portion of the object, to which this name applies.

  • AircraftFuselageColorCode - a color of the main body of an aircraft.
  • Color is the property term. This is the primary characteristic of the property name. The value of this property will be a color.

Representation term

A representation term indicates the kind of value a property carries.

  • A representation term, if present, must appear as the final term of the name.
  • Representation terms are required for properties that carry a simple value, like a string or a number.
  • Representation terms are required for other properties with specific types.

See the Representation Terms and Definitions Phrases reference table on this page for the list of representation terms.

  • AircraftFuselageColorCode - a color of the main body of an aircraft.
  • Code is the representation term. It indicates the general kind of value to expect.

Restricted terms

Type

Avoid use of the term Type. Type is reserved as the representation term for NIEM types; it indicates a structure. Properties should use the term Category instead to represent type / category / kind.

NIEM does allow for exceptions when the use of the term Category causes confusion over very well-known concepts that use the term type. One such exception is for the element j:PersonBloodTypeCode.

Number

Avoid use of the term Number in data names. Its use is usually too generic to be meaningful or helpful. A number should usually be an ID (Identifier), Quantity, Numeric (or Value), Amount, Measure, or Duration (of time).

No double terms

Do not use double terms (i.e., consecutive identical or similar terms such as IDID or NumberNumeric). Double terms should be replaced with a single instance of the term if it makes sense to do so.

This can sometimes cause different parts of a name, like the property term and the representation term, to be combined into one.

ID vs Identification

In NIEM, ID is used as the abbreviation for Identifier. This term is used for simple properties; it represents a unique string or number.

NIEM uses Identification as the representation term for a complex representation of an ID. This term carries a unique string or number, and additional information, like expiration date and the issuer. It is typically used by properties with the type nc:IdentificationType.

Definitions

The following provides rules and guidance for constructing property definitions.

Required

All properties must have a definition.

Human-readable

Definitions are meant to be human-readable.

Informative

Definitions should provide more information than the terms in the property’s name, when possible.

In some cases, a property name may be so obvious (e.g., PersonHairColorText) that attempts to provide synonyms or alternate phrasing would be counterproductive. A definition does not have to be elaborate if the property name would be obvious to the general public.

Unique

Each data component definition must be unique from all others and distinguishable in meaning. No two definitions can be identical in wording or so close in meaning that they could refer to the same data component.

There is an exception for a property with multiple representations, like various substitutions of an abstract property. Since each substitution represents the same concept, they may each share the same definition.

No duplication

Definitions of a part do not need to redefine the whole.

Definitions for elements like nc:PersonHairColorText, nc:PersonName, and nc:PersonAgeMeasure do not need to each define what a person is. That should be defined once by element nc:Person.

No type info

Type information should not appear in a property definition

A property definition is intended to describe semantic meaning only and should be decoupled from specific representation or structure. The representation term of a property and the standard opening phrase of a definition provide enough context to determine if a property is a string, a date, an ID, etc.

More specific typing information usually belongs with the types (the structures) rather than the properties (the concepts). Things like patterns, code values, and the number of characters should usually not be embedded in property definitions.

There may be a few cases where providing such information is essential to the semantics of the property. In this case, it is permitted.

Standard opening phrases

Definitions of properties with simple content or designated types should use a standard opening phrase as defined by the NDR.

See the Representation terms and definition phrases reference table on this page for more.

Begin with “A(n)”

Property definitions almost always begin with an indefinite article (i.e., “a” or “an”), never a definite article (i.e., “the”). This is based on ISO 11179 guidance.

Follow ISO 11179-4

Definitions must follow 11179-4 requirements, and should follow its recommendations.

Representation terms and definition phrases

The tables below pair property representation terms (primary and alternates) with the recommended definition standard opening phrases.

Simple value properties

Rep Terms (Primary / Alt) Typical Uses Typical Data Types Definition Phrase
Amount Money nc:AmountType A(n) (optional adjectives) amount ...
BinaryObject Binary, Base64 encoding, hexadecimal encoding nc:BinaryType A(n) ...
- Graphic Diagram, graph, mathematical curve, etc. nc:ImageType A(n) ...
- Picture Picture, photo, image nc:ImageType A(n) (optional adjectives) (image/picture/photograph) ...
- Sound Sound nc:BinaryType A(n) ...
- Video Video nc:BinaryType A(n) ...
Code Code Set custom type A(n) ...
DateTime Date and time nc:DateType A(n) (optional adjectives) date and time ...
- Date Date nc:DateType A(n) (optional adjectives) date ...
- Time Time niem-xs:time A(n) (optional adjectives) time ...
- Duration Length of time niem-xs:duration A(n) ...
ID Unique identifier niem-xs:string A(n) (optional adjectives) identifier ...
- URI URL niem-xs:anyURI A(n) ...
Indicator True or False; Yes or No niem-xs:boolean True if ...; false (otherwise/if) ...
Measure Measured value with unit nc:MeasureType A(n) ...
Numeric Number, no unit nc:NumericType A(n) ...
- Value Calculated number nc:NumericType A(n) ...
- Rate Ratio comparing two numbers nc:NumericType A(n) ...
- Percent Ratio representing parts per hundred nc:PercentType A(n) ...
Quantity Numeric count (non-monetary) nc:QuantityType A(n) (optional adjectives) (count/number) ...
Text Character string, free text nc:TextType A(n) ...
- Name Word or term used for identification nc:TextType A(n) (optional adjectives) name...
- CategoryText Kind or type of something nc:TextType A kind of ...
- DescriptionText Free text description nc:TextType A description of ...
List Sequence of values for very large data sets various space-delimited lists A(n) ...

Other properties

Representation Terms Typical Uses Typical Data Types Definition Standard Opening Phrase
Abstract Substitution group head for code lists or alternative to xs:choice none A data concept ...
Association A relationship between elements ...AssociationType An (optional adjectives) (relationship/association) ...
Augmentation Additional information about an existing type ...AugmentationType Additional information about ...
AugmentationPoint A hook in a complex type to allow others to add additional information (augmentations) none An augmentation point ...
Identification An identifier plus related info (e.g., expiration date, category, status) nc:IdentificationType A(n) (optional adjectives) identification ...
Metadata Secondary data about information (e.g., source, last updated, info quality) ...MetadataType Metadata about ...
All other elements A(n) ...

NDR references

General property info

NDR 5.0
Rule Applicability Title
NDR 7-5 REF, EXT Component name follows ISO 11179 Part 5 Annex A
NDR 4.0
Rule Applicability Title
NDR 7-5 REF, EXT Component name follows ISO 11179 Part 5 Annex A

Name info

NDR 5.0
Rule Applicability Title
NDR 10-44 REF, EXT Schema component name composed of English words
NDR 10-46 REF, EXT Schema component names have only specific characters
NDR 10-47 REF, EXT Punctuation in component name is a separator
NDR 10-49 REF, EXT Attribute name begins with lower case letter
NDR 10-50 REF, EXT Name of schema component other than attribute and proxy type begins with upper case letter
NDR 10-53 REF, EXT Local terminology interpretation
NDR 10-54 REF, EXT Singular form is preferred in name
NDR 10-55 REF, EXT Present tense is preferred in name
NDR 10-56 REF, EXT Name does not have nonessential words
NDR 10-57 REF, EXT Element or attribute name follows pattern
NDR 10-58 REF, EXT Object-class term identifies concrete category
NDR 10-59 REF, EXT Property term describes characteristic or subpart
NDR 10-60 REF, EXT Name may have multiple qualifier terms
NDR 10-61 REF, EXT Name has minimum necessary number of qualifier terms
NDR 10-62 REF, EXT Order of qualifiers is not significant
NDR 10-63 REF, EXT Redundant term in name is omitted
NDR 4.0
Rule Applicability Title
NDR 10-44 REF, EXT Schema component name composed of English words
NDR 10-45 REF, EXT Schema component names have only specific characters
NDR 10-46 REF, EXT Punctuation in component name is a separator
NDR 10-47 REF, EXT Names use camel case
NDR 10-49 REF, EXT Name of schema component other than attribute and proxy type begins with upper case letter
NDR 10-50 REF, EXT Names use common abbreviations
NDR 10-53 REF, EXT Singular form is preferred in name
NDR 10-54 REF, EXT Present tense is preferred in name
NDR 10-55 REF, EXT Name does not have nonessential words
NDR 10-56 REF, EXT Element or attribute name follows pattern
NDR 10-57 REF, EXT Object-class term identifies concrete category
NDR 10-58 REF, EXT Property term describes characteristic or subpart
NDR 10-59 REF, EXT Name may have multiple qualifier terms
NDR 10-60 REF, EXT Name has minimum necessary number of qualifier terms
NDR 10-61 REF, EXT Order of qualifiers is not significant
NDR 10-62 REF, EXT Redundant term in name is omitted

Definition info

NDR 5.0
Rule Applicability Title
NDR 11-24 REF, EXT Data definition does not introduce ambiguity
NDR 11-25 REF, EXT Object class has only one meaning
NDR 11-26 REF, EXT Data definition of a part does not redefine the whole
NDR 11-27 REF, EXT Do not leak representation into data definition
NDR 11-28 REF, EXT Data definition follows 11179-4 requirements
NDR 11-29 REF, EXT Data definition follows 11179-4 recommendations
NDR 11-36 REF, EXT Standard opening phrase for date element or attribute data definition
NDR 11-37 REF, EXT Standard opening phrase for quantity element or attribute data definition
NDR 11-38 REF, EXT Standard opening phrase for picture element or attribute data definition
NDR 11-39 REF, EXT Standard opening phrase for indicator element or attribute data definition
NDR 11-40 REF, EXT Standard opening phrase for identification element or attribute data definition
NDR 11-41 REF, EXT Standard opening phrase for name element or attribute data definition
NDR 11-42 REF, EXT Standard opening phrase for element or attribute data definition
NDR 4.0
Rule Applicability Title
NDR 11-23 REF, EXT Data definition does not introduce ambiguity
NDR 11-24 REF, EXT Object class has only one meaning
NDR 11-25 REF, EXT Data definition of a part does not redefine the whole
NDR 11-26 REF, EXT Do not leak representation into data definition
NDR 11-27 REF, EXT Data definition follows 11179-4 requirements
NDR 11-28 REF, EXT Data definition follows 11179-4 recommendations
NDR 11-34 REF, EXT Standard opening phrase for date element or attribute data definition
NDR 11-35 REF, EXT Standard opening phrase for quantity element or attribute data definition
NDR 11-36 REF, EXT Standard opening phrase for picture element or attribute data definition
NDR 11-37 REF, EXT Standard opening phrase for indicator element or attribute data definition
NDR 11-38 REF, EXT Standard opening phrase for identification element or attribute data definition
NDR 11-39 REF, EXT Standard opening phrase for name element or attribute data definition
NDR 11-40 REF, EXT Standard opening phrase for element or attribute data definition