This document was developed as a technical specification and is intended to be neither a user guide nor 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.

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.

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.

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

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.

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:

• a title of a section of document or a rule,
• a locally-defined term, often one that is not normatively defined, or
• is emphasized for importance or prominence.

Bold: A phrase appearing in bold is one of:

• a term being defined within a definition,
• a term that was bold in the original source text for a quote
• a heading, such as for a section, figure, definition, or rule, or
• a cross-reference within the document or to a reference to an outside document.

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:

<xs:complexType name="PersonType">
  ...
</xs:complexType>

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.

[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.

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 that the principal component of a NIEM message specification 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.

The term IEP conformance target is defined by [IEPD] 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 [IEPD] 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.

This document refers to an artifact that specifies NIEM-conformant information exchanges as a message specification. An information exchange package documentation (IEPD), as defined by [IEPD], is a form of message specification.

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.

[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].

[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.

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.

<nc:PersonFullName xmlns:nc="http://release.niem.gov/niem/niem-core/5.0/">
    Sherlock Holmes
</nc:PersonFullName>

@prefix nc:  <http://release.niem.gov/niem/niem-core/5.0/> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
_:b0    nc:PersonFullName  _:b1 .
_:b1    rdf:value  "Sherlock Holmes" .

{
    "nc" : "http://release.niem.gov/niem/niem-core/5.0/",
    "rdf" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "xs" : "http://www.w3.org/2001/XMLSchema"
}

{
  "nc:PersonFullName" : {
    "rdf:value": {
      "@value": "Sherlock Holmes",
      "@type": "xs:string"
    }
  }
}

{
  "nc:PersonFullName" : "Sherlock Holmes"
}

The literal-to-object conversion process forms the core of NIEM JSON Normalization, a process allowing for even briefer JSON expressions of NIEM data while maintaining a deterministic transformation to NIEM JSON-LD. The process consists of two steps:

1. Apply a context to map simple JSON names to fully qualified NIEM names
2. Iteratively convert each literal to an object

{
  "birth": {
    "date": "1978-01-01"
  }
}

{
  "nc": "http://release.niem.gov/niem/niem-core/5.0/",
  "birth": "nc:PersonBirthDate",
  "date": "nc:Date"
}

{
  "@context": {
    "nc": "http://release.niem.gov/niem/niem-core/5.0/"
  },
  "nc:PersonBirthDate": {
    "nc:Date": "1978-01-01"
  }
}

{
  "@context": {
    "nc": "http://release.niem.gov/niem/niem-core/5.0/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "xs": "http://www.w3.org/2001/XMLSchema"
  },
  "nc:PersonBirthDate": {
    "nc:Date": {
      "rdf:value": {
        "@value": "1978-01-01",
        "@type": "xs:date"
      }
    }
  }
}

<nc:PersonBirthDate xmlns:nc="http://release.niem.gov/niem/niem-core/5.0/">
  <nc:Date>1978-01-01</nc:Date>
</nc:PersonBirthDate>

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.