NIEM JSON Specification
Version 4.0beta1
May 29, 2020
NIEM Technical Architecture Committee (NTAC)
Abstract

The NIEM JSON Specification establishes the technical basis for using JavaScript Object Notation (JSON) as a data format for exchange of information consistent with NIEM-conformant schemas and information exchange package documentations (IEPDs).

NIEM-conformance of JSON data is primarily focused on the relationship between the data in the JSON file and the definitions established by a NIEM-conformant schema, e.g., the schema defined by a NIEM IEPD. There are two forms of conformance of a NIEM JSON document to a NIEM-conformant schema:

Authors

Webb Roberts, Georgia Tech Research Institute (<webb.roberts@gtri.gatech.edu>), Lead author

Document status

This document is a draft of a specification product of the NIEM Technical Architecture Committee (NTAC).

Updates, revisions, and errata for this specification are posted to https://github.com/NIEM/NIEM-JSON-Spec. Please submit comments on this specification as issues at https://github.com/NIEM/NIEM-JSON-Spec/issues.

Table of contents
1. Introduction

The NIEM JSON Specification establishes the technical basis for using JavaScript Object Notation (JSON) as a data format for exchange of information consistent with NIEM-conformant schemas and information exchange package documentations (IEPDs).

NIEM-conformance of JSON data is primarily focused on the relationship between the data in the JSON file and the definitions established by a NIEM-conformant schema, e.g., the schema defined by a NIEM IEPD. There are two forms of conformance of a NIEM JSON document to a NIEM-conformant schema:

1.1. Audience

This document was developed as a technical specification, and is not intended to be a user guide or an introduction to the use of JSON for NIEM. Its intended audience is developers of tools that work with NIEM and NIEM JSON, or other individuals who require an understanding of the details of the alignment between NIEM JSON and other representations of NIEM data.

Developers of NIEM message formats with a JSON representation may prefer to read the NIEM JSON documentation at https://niem.github.io/json/, specifically the NIEM JSON Tutorial, which proceeds step-by-step from data requirements to a conforming JSON representation. Developers of systems that read and write NIEM JSON messages should conform to the relevant message descriptions.

2. Document conventions and normative content

This document uses formatting and syntactic conventions to clarify meaning and avoid ambiguity.

2.1. Document references

This document relies on references to many outside documents. Such references are noted by bold, bracketed inline terms. For example, a reference to RFC 2119 is shown as [RFC 2119]. All reference documents are recorded in Appendix A, References, below.

2.2. Normative and informative content

This document includes a variety of content. Some content of this document is normative, while other content is informative. In general, the informative material appears as supporting text, description, and rationales for the normative material.

[Definition: normative]

The term normative is as defined by [ConfReq] Section 7.2, Conformance by key words, which states:

NORMATIVE — statements provided for the prescriptive parts of the specification, providing that which is necessary in order to be able to claim conformance to the specification.

[Definition: informative]

The term informative is as defined by [ConfReq] Section 7.2, Conformance by key words, which states:

INFORMATIVE (NON-NORMATIVE) — statements provided for informational purposes, intended to assist the understanding or use of the specification and shall not contain provisions that are required for conformance.

Definitions within this document are normative, and are given special formatting.

[Definition: <term>]

A formal definition of a word or phrase.

Uses of these terms are given special formatting, using raised dots to identify the term. For example the use of the term conformance target has special formatting.

2.2.1. Rules

A rule states a specific requirement on a conformance target or on the interpretation of a conformance target. The classes of conformance target are enumerated in Section 4, Conformance targets, below. Rules are normative. Human-readable text in rules uses [BCP 14] terminology as described in Section 3.1, IETF Best Current Practice 14 terminology, below, for normative requirements and recommendations.

[Rule <section>-<number>] (<applicability>) (<classification>)

An enforceable rule.

Each rule has a classification, which is either Constraint or Interpretation. If the classification is Constraint, then the rule is a constraint rule. If the classification is Interpretation, then the rule is an interpretation rule.

[Definition: constraint rule]

A constraint rule is a rule that sets a requirement on an artifact with respect to its conformance to a conformance target.

[Definition: interpretation rule]

An interpretation rule is a rule that sets the methodology, pattern, or procedure for understanding some aspect of an instance of a conformance target.

Each rule identifies its applicability. This identifies the conformance targets to which the rule applies. Each entry in the list is a code from Table 4-1, Codes representing conformance targets, below. If a code appears in the applicability list for a rule, then the rule applies to the corresponding conformance target. For example, a rule with applicability (STRICT) is applicable to NIEM JSON document strictly conformant to a schema.

Rules are numbered according to the section in which they appear and the order in which they appear within that section. For example, the second rule in Section 4 is Rule 4-2.

2.3. Additional formatting

In addition to the special formatting above, this document uses additional formatting conventions.

Courier: All words appearing in Courier font are values, objects, keywords, or literal XML text.

Italics: A phrase appearing in italics is one of:

Bold: A phrase appearing in bold is one of:

Throughout the document, fragments of code appear, including XML, RDF, and JSON-LD. These fragments are specially formatted in Courier font and appear in text boxes. An example of such a fragment follows:

Figure 2-1: Example of an XML fragment
<xs:complexType name="PersonType">
  ...
</xs:complexType>
3. External terminology

This document uses terminology from other documents. This section identifies sources and definitions of externally-defined terminology.

3.1. IETF Best Current Practice 14 terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14] [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

3.2. Conformance Targets Attribute Specification

[CTAS] defines several terms used normatively within this specification.

The term conformance target is defined by [CTAS] Section 3.1, Conformance Target Defined which states:

A conformance target is a class of artifact, such as an interface, protocol, document, platform, process or service, that is the subject of conformance clauses and normative statements. There may be several conformance targets defined within a specification, and these targets may be diverse so as to reflect different aspects of a specification. For example, a protocol message and a protocol engine may be different conformance targets.

The term conformance target identifier is defined by [CTAS] Section 3.1, Conformance Target Defined, which states:

A conformance target identifier is an internationalized resource identifier that uniquely identifies a conformance target.

The term effective conformance target identifier is defined by [CTAS] Section 4, Semantics and Use, which states:

An effective conformance target identifier of a conformant document is an internationalized resource identifier reference that occurs in the document’s effective conformance targets attribute.

3.3. NIEM Naming and Design Rules

The term conformant schema document set is a conformance target defined by the [NIEM NDR] Section 4.1.3, Schema document set, which states:

A conformant schema document set is a collection of schema documents that together are capable of validating a conformant instance XML document.

Note the principal component of a NIEM exchange definition (an information exchange package documentation, or IEPD) is a conformant schema document set.

The term conformant instance XML document is a conformance target defined by the [NIEM NDR] Section 4.1.4, Instance documents and elements, which states:

A conformant instance XML document is an XML document that is [an] instance document valid to a conformant schema document set.

Although the above definitions for the conformance targets conformant schema document set and conformant instance XML document reference each other, each conformance target is supported by a set of rules. Each artifact (i.e., document set or XML document) must conform to all rules for its conformance target in order to conform to the conformance target.

The term reference schema document is a conformance target defined by the [NIEM NDR] Section 4.1.1, Reference schema document, which states:

A reference schema document is a schema document that is intended to provide the authoritative definitions of broadly reusable schema components.

The term extension schema document is a conformance target defined by the [NIEM NDR] Section 4.1.2, Extension schema document, which states:

An extension schema document is a schema document that is intended to provide definitions of schema components that are intended for reuse within a more narrow scope than those defined by a reference schema document.

The term external schema document is defined by the [NIEM NDR] Section 10.2.3, External adapter types and external components, which states:

An external schema document is any schema document that is not one of

  • a reference schema document,
  • an extension schema document, or
  • a schema document that has the structures namespace as its target namespace.
3.4. Model Package Description Specification

The term IEP conformance target is defined by [MPD] Section 5.6, Defining Information Exchange Packages. An IEP conformance target defines a set of conformance criteria for a class of information exchange package (IEP).

The term information exchange package is defined by [MPD] Section 3.2.3, IEP Conformance Targets. An information exchange package (IEP) is an XML document that conforms to the criteria defined for an IEP conformance target.

3.5. JSON

The term JSON text is defined by [RFC8259] Section 2, JSON Grammar, which defines it as a single serialized JSON value.

The term JSON document, when used within this document, is synonymous with JSON text.

3.6. JSON-LD

[JSON-LD] defines JSON-LD, a JSON-based format to serialize linked data. [JSON-LD] defines the term JSON-LD document. [JSON-LD] Section 7, Data Model provides a summary of what constitutes a JSON-LD document. [JSON-LD] Section 8, JSON-LD Grammar states:

A JSON-LD document MUST be a valid JSON document as described in [RFC4627].

[JSON-LD] leverages [RFC4627] as a normative definition of JSON. That specification has been superseded by [RFC8259]. Consequently, this specification uses [RFC8259] as its normative definition of JSON.

[JSON-LD] normatively references the term JSON document in [RFC4627], which does not define that term. We interpret this to be a reference to JSON text as defined by [RFC8259].

The evaluation of a JSON-LD document as Resource Description Framework (RDF) is specified by [JSON-LD-API].

3.7. RDF and RDF Schema

[RDF-Concepts] Section 3, RDF Graphs defines the term RDF graph:

An RDF graph is a set of RDF triples.

[RDF-Concepts] Section 1.7, Equivalence, Entailment and Inconsistency defines the term equivalent:

Two RDF graphs A and B are equivalent if they make the same claim about the world. A is equivalent to B if and only if A entails B and B entails A.

[RDF-Schema] describes RDF Schema (RDFS), which provides a data-modeling vocabulary for RDF data. [NIEM NDR] defines components of NIEM-conformant schema document sets in terms of RDF Schema.

Property rdf:value is defined by [RDF-Schema] Section 5.4.3, rdf:value. This property is used within an object to carry a simple value with no additional meaning.

4. Conformance targets

This document defines multiple conformance targets. Each conformance target is defined normatively by this specification. Each conformance target has an associated abbreviation, which appears in rules to identify to which conformance targets a rule applies.

Table 4-1: Codes representing conformance targets
CodeConformance target
STRICTNIEM JSON document strictly conformant to a schema
LAXNIEM JSON document laxly conformant to a schema
4.1. NIEM JSON document strictly conformant to a schema
[Definition: NIEM JSON document strictly conformant to a schema]

A NIEM JSON document strictly conformant to a schema is a JSON-LD document that may be assigned a one-to-one correspondence to a conformant instance XML document valid against a conformant schema document set. It is a conformance target of this specification. A NIEM JSON document strictly conformant to a schema MUST conform to all rules of this specification that apply to this conformance target. The conformance target identifier for this conformance target is http://reference.niem.gov/niem/specification/niem-json-spec/4.0/#Strict.

4.2. NIEM JSON document laxly conformant to a schema
[Definition: NIEM JSON document laxly conformant to a schema]

A NIEM JSON document laxly conformant to a schema is a JSON-LD document that may be interpreted using the RDF vocabulary defined by a conformant schema document set. It is a conformance target of this specification. A NIEM JSON document laxly conformant to a schema MUST conform to all rules of this specification that apply to this conformance target. The conformance target identifier for this conformance target is http://reference.niem.gov/niem/specification/niem-json-spec/4.0/#Lax.

5. Rules
Rule 5-1. File must be a JSON-LD file
Rule 5-2. Strictly conformant JSON corresponds to valid XML
[Rule 5-2] (STRICT) (Constraint)

The RDF graph entailed by a NIEM JSON document strictly conformant to a schema MUST be equivalent to the RDF graph entailed by a corresponding conformant instance XML document instance of the schema, accounting for literal-to-object conversion and the omission of external content.

Within this rule, the schema includes a conformant schema document set, and will include all other constraints of an IEP conformance target defined by an IEPD. The RDF graph entailed by a candidate JSON document is described by [JSON-LD-API]. The RDF graph entailed by an XML document is described by [NIEM NDR]. This rule does not provide or require a translation of JSON to XML, although such a translation may be helpful in validating this rule.

Rule 5-3. JSON is satisfiable with schema
[Rule 5-3] (STRICT, LAX) (Constraint)

The RDF graph consisting of the union of:

  1. the RDF graph entailed by the JSON document and
  2. the RDF graph entailed by the schema

MUST be RDFS satisfiable, accounting for literal-to-object conversion and the omission of external content.

Within this rule, a schema is a conformant schema document set. The RDF entailed by a JSON-LD document is defined by [JSON-LD-API]. The RDF entailed by a schema is defined by [NIEM NDR]. The term RDFS satisfiable is defined by [RDF-Semantics].

Rule 5-4. JSON interpreted based on schema
[Rule 5-4] (STRICT, LAX) (Interpretation)

A NIEM JSON document strictly conformant to a schema or NIEM JSON document laxly conformant to a schema MUST be interpreted as an RDFS interpretation of the RDF graph composed of the RDF entailed by the JSON document together with the RDF entailed by the schema.

Within this rule, a schema is a conformant schema document set. The RDF entailed by a JSON-LD document is defined by [JSON-LD-API]. The RDF entailed by a schema is defined by [NIEM NDR]. The term RDFS interpretation is defined by [RDF-Semantics].

5.1. Literal-to-object conversion

Although all NIEM elements have values that are complex types, which by [NIEM NDR] Section 5.6.3.2, Element instance entail an RDF object (rather than a literal value), JSON syntax for objects with simple values is cumbersome. For this reason, NIEM JSON instances may use a shorthand syntax, in which any element with only a simple value may be represented as a literal, rather than as an object with a value carried by rdf:value. To accommodate these cases, conformant JSON documents are evaluated based on the results of literal-to-object conversion, a process that yields a JSON object in which literal values are converted to idiomatic objects when appropriate.

[Definition: literal-to-object conversion]

Within this document, literal-to-object conversion is a process by which a JSON value is transformed from a value of false, null, true, number, or string, into an object containing only the property rdf:value. Evaluation of conformance of a JSON document is conducted on the results of literal-to-object conversion of that document.

5.1.1. Example of literal-to-object conversion

This section provides an example of literal-to-object conversion. It shows the conversion of a simple XML instance document to a corresponding simple JSON-LD object. The following is a simple XML instance document:

Figure 5-1: XML representation of simple example
<nc:PersonFullName xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/"
  >Sherlock Holmes</nc:PersonFullName>

[NIEM NDR] Section 5.6.3.2, Element instance specifies that each element that is defined by a NIEM-conformant schema carries an object value, not a literal value. The value of the above element nc:PersonName is an object with a single simple value, which is reflected by the following RDF, in Turtle format:

Figure 5-2: RDF representation of simple example
@prefix nc:  <http://release.niem.gov/niem/niem-core/4.0/> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
_:b0    nc:PersonFullName  _:b1 .
_:b1    rdf:value  "Sherlock Holmes" .

The JSON-LD versions of the example use the following JSON-LD context:

Figure 5-3: JSON-LD context for simple example
{
    "nc" : "http://release.niem.gov/niem/niem-core/4.0/",
    "rdf" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
}

The JSON-LD version of the above instance includes the object, with the literal name as an rdf:value property:

Figure 5-4: JSON-LD representation of simple example
{
  "nc:PersonFullName" : {
    "rdf:value": "Sherlock Holmes"
  }
}

Users of NIEM JSON have expressed a preference for a representation of data that is less verbose than the above. By converting from an object to a literal, the JSON-LD may be simplified:

Figure 5-5: JSON-LD example using literals
{
  "nc:PersonFullName" : "Sherlock Holmes"
}

Literal-to-object conversion is the transformation from Figure 5-5, JSON-LD example using literals, above, to Figure 5-4, JSON-LD representation of simple example, above. Users may express NIEM data using a brief format, with the knowledge that it represents the more verbose use of objects instead of bare literals.

5.2. External content omission

NIEM provides a mechanism for data that is not NIEM-conformant to be included within NIEM data. Such data is called external content (see [NIEM NDR] Section 10.2.3, External adapter types and external components). External content includes any content with a namespace defined by an external schema document, or with any namespace not defined by a reference schema document or extension schema document.

NIEM provides a mapping from NIEM-conformant XML content and XML Schemas to RDF (see [NIEM NDR] Section 5, The NIEM conceptual model). The NDR rules do not provide a mapping from external content to RDF.

An object carried by an external element (i.e., an instance of an element that is in a namespace not defined by NIEM-conformant schema documents) may be part of a subgraph of resources and properties that are not described by NIEM-conformant schemas. Such an object may be mapped to a resource that is assigned an IRI that is a blank node (described by [NIEM NDR] Section 5.4, Unique identification of data objects), or may be given a more meaningful resource identifier.

Since the structure and content of such a subgraph is not described by NIEM-conformant schemas, its structure and content are not material to the conformance of a JSON document by this specification. Such content may effectively be omitted from consideration of its validity against a schema, as regards conformance to this specification. Other specifications may introduce introduce additional rules, but that is outside the scope of this specification.

Appendix A. References

[BCP 14]: Internet Engineering Task Force Best Current Practice 14. Available from https://www.ietf.org/rfc/bcp/bcp14.txt. BCP 14 is composed of:

[RFC 2119]: Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, BCP 14, RFC 2119, March 1997. Available from http://www.ietf.org/rfc/rfc2119.txt.

[RFC 8174]: Leiba, B., Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words, BCP 14, RFC 8174, May 2017. Available from https://www.ietf.org/rfc/rfc8174.txt.

[ConfReq]: Lynne Rosenthal, and Mark Skall, eds. Conformance Requirements for Specifications v1.0. The Organization for the Advancement of Structured Information Standards (OASIS), March 15, 2002. https://www.oasis-open.org/committees/download.php/305/conformance_requirements-v1.pdf.

[CTAS]: Roberts, Webb. NIEM Conformance Targets Attribute Specification, Version 3.0. NIEM Technical Architecture Committee, July 31, 2014. http://reference.niem.gov/niem/specification/conformance-targets-attribute/3.0/NIEM-CTAS-3.0-2014-07-31.html.

[JSON-LD]: Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, and Niklas Lindström. JSON-LD 1.0, A JSON-Based Serialization for Linked Data, W3C Recommendation. Edited by Manu Sporny, Gregg Kellogg, and Markus Lanthaler. W3C, January 16, 2014. https://www.w3.org/TR/2014/REC-json-ld-20140116/.

[JSON-LD-API]: Dave Longley, Gregg Kellogg, Markus Lanthaler, and Manu Sporny. JSON-LD 1.0 Processing Algorithms and API. Edited by Markus Lanthaler, Gregg Kellogg, and Manu Sporny. W3C, January 16, 2014. https://www.w3.org/TR/2014/REC-json-ld-api-20140116/.

[MPD]: NIEM Technical Architecture Committee. National Information Exchange Model Model Package Description Specification, Version 3.0.1, April 27, 2015. https://reference.niem.gov/niem/specification/model-package-description/3.0.1/model-package-description-3.0.1.html.

[NIEM NDR]: Roberts, Webb. National Information Exchange Model Naming and Design Rules, Version 4.0. NIEM Technical Architecture Committee, November 7, 2017. http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/niem-ndr-4.0.html.

[RDF-Concepts]: Richard Cyganiak, David Wood, and Markus Lanthaler, eds. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation. The World Wide Web Consortium (W3C), February 25, 2014. https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/.

[RDF-Schema]: Dan Brickley, and R.V. Guha, eds. RDF Schema 1.1. The World Wide Web Consortium (W3C), February 25, 2014. http://www.w3.org/TR/2014/REC-rdf-schema-20140225/.

[RDF-Semantics]: Patrick J. Hayes, and Peter F. Patel-Schneider, eds. RDF 1.1 Semantics. The World Wide Web Consortium (W3C), February 25, 2014. http://www.w3.org/TR/2014/REC-rdf11-mt-20140225/.

[RFC4627]: D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON) (RFC 4627). July 2006. RFC. http://www.ietf.org/rfc/rfc4627.txt

[RFC8259]: Bray, T., Ed., The JavaScript Object Notation (JSON) Data Interchange Format, STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, https://www.ietf.org/rfc/rfc8259.txt.

Appendix B. Index of definitions
Appendix C. Index of rules