Added new section that provides an example of literal-to-object conve…

…rsion. Closes #4.
NIEM · May 19, 2020 · 967412f · 967412f
1 parent 8e2c7ad
commit 967412f
Show file tree

Hide file tree

Showing 17 changed files with 442 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@
 /config.log
 /config.status
 /run
+/resources/literal-to-object-conversion/tmp
diff --git a/publish/niem-json-spec.html b/publish/niem-json-spec.html
diff --git a/publish/niem-json-spec.txt b/publish/niem-json-spec.txt
@@ -196,6 +196,63 @@ Rule 4-4. JSON interpreted based on schema
 
       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.
 
+4.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 4-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 4-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 4-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 4-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 4-5: JSON-LD example using literals
+
+
+      {
+        "nc:PersonFullName" : "Sherlock Holmes"
+      }
+
+
+   [Literal-to-object conversion] is the transformation from Figure 4-5, JSON-LD example using literals, above, to Figure 4-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.
+
 4.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].

diff --git a/resources/literal-to-object-conversion/Makefile b/resources/literal-to-object-conversion/Makefile
@@ -0,0 +1,14 @@
+
+xml_files = example-1.xml
+xml_valid_tokens = ${xml_files:%.xml=tmp/valid/%.xml}
+
+.PHONY: valid
+valid: ${xml_valid_tokens}
+
+tmp/valid/%.xml: %.xml
+	xs-validate -c niem/xml-catalog.xml $<
+	mkdir -p ${dir $@}
+	touch $@
+
+
+
diff --git a/resources/literal-to-object-conversion/example-1-context.jsonld b/resources/literal-to-object-conversion/example-1-context.jsonld
@@ -0,0 +1,4 @@
+{
+  "nc" : "http://release.niem.gov/niem/niem-core/4.0/",
+  "rdf" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+}
diff --git a/resources/literal-to-object-conversion/example-1-converted.jsonld b/resources/literal-to-object-conversion/example-1-converted.jsonld
@@ -0,0 +1,9 @@
+{
+  "@context": {
+    "nc" : "http://release.niem.gov/niem/niem-core/4.0/",
+    "rdf" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+  },
+  "nc:PersonFullName" : {
+    "rdf:value": "Sherlock Holmes"
+  }
+}
diff --git a/resources/literal-to-object-conversion/example-1.jsonld b/resources/literal-to-object-conversion/example-1.jsonld
@@ -0,0 +1,6 @@
+{
+  "@context": {
+    "nc" : "http://release.niem.gov/niem/niem-core/4.0/"
+  },
+  "nc:PersonFullName" : "Sherlock Holmes"
+}
diff --git a/resources/literal-to-object-conversion/example-1.xml b/resources/literal-to-object-conversion/example-1.xml
@@ -0,0 +1,3 @@
+<nc:PersonFullName
+  xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/"
+  >Sherlock Holmes</nc:PersonFullName>
diff --git a/resources/literal-to-object-conversion/niem/niem-core/4.0/niem-core.xsd b/resources/literal-to-object-conversion/niem/niem-core/4.0/niem-core.xsd
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<xs:schema targetNamespace="http://release.niem.gov/niem/niem-core/4.0/" version="1" xsi:schemaLocation="http://release.niem.gov/niem/appinfo/4.0/ ../../utility/appinfo/4.0/appinfo.xsd http://release.niem.gov/niem/conformanceTargets/3.0/ ../../utility/conformanceTargets/3.0/conformanceTargets.xsd" ct:conformanceTargets="http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/#ReferenceSchemaDocument" xmlns:appinfo="http://release.niem.gov/niem/appinfo/4.0/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/" xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/" xmlns:niem-xs="http://release.niem.gov/niem/proxy/xsd/4.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:structures="http://release.niem.gov/niem/structures/4.0/">
+  <xs:annotation>
+    <xs:documentation>NIEM Core.</xs:documentation>
+  </xs:annotation>
+  <xs:import schemaLocation="../../proxy/xsd/4.0/xs.xsd" namespace="http://release.niem.gov/niem/proxy/xsd/4.0/"/>
+  <xs:import schemaLocation="../../utility/structures/4.0/structures.xsd" namespace="http://release.niem.gov/niem/structures/4.0/"/>
+  <xs:complexType name="PersonNameTextType">
+    <xs:annotation>
+      <xs:documentation>A data type for a name by which a person is known, referred, or addressed.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleContent>
+      <xs:extension base="nc:ProperNameTextType"/>
+    </xs:simpleContent>
+  </xs:complexType>
+  <xs:complexType name="ProperNameTextType">
+    <xs:annotation>
+      <xs:documentation>A data type for a word or phrase by which a person or thing is known, referred, or addressed.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleContent>
+      <xs:extension base="nc:TextType"/>
+    </xs:simpleContent>
+  </xs:complexType>
+  <xs:complexType name="TextType">
+    <xs:annotation>
+      <xs:documentation>A data type for a character string.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleContent>
+      <xs:extension base="niem-xs:string"/>
+    </xs:simpleContent>
+  </xs:complexType>
+  <xs:element name="PersonFullName" type="nc:PersonNameTextType" nillable="true">
+    <xs:annotation>
+      <xs:documentation>A complete name of a person.</xs:documentation>
+    </xs:annotation>
+  </xs:element>
+</xs:schema>
diff --git a/resources/literal-to-object-conversion/niem/proxy/xsd/4.0/xs.xsd b/resources/literal-to-object-conversion/niem/proxy/xsd/4.0/xs.xsd
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<xs:schema targetNamespace="http://release.niem.gov/niem/proxy/xsd/4.0/" version="1" xsi:schemaLocation="http://release.niem.gov/niem/appinfo/4.0/ ../../../utility/appinfo/4.0/appinfo.xsd http://release.niem.gov/niem/conformanceTargets/3.0/ ../../../utility/conformanceTargets/3.0/conformanceTargets.xsd" ct:conformanceTargets="http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/#ReferenceSchemaDocument" xmlns:appinfo="http://release.niem.gov/niem/appinfo/4.0/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/" xmlns:niem-xs="http://release.niem.gov/niem/proxy/xsd/4.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:structures="http://release.niem.gov/niem/structures/4.0/">
+  <xs:annotation>
+    <xs:documentation>Proxy types that carry dictionary metadata and have XML data type simple contents.</xs:documentation>
+  </xs:annotation>
+  <xs:import schemaLocation="../../../utility/structures/4.0/structures.xsd" namespace="http://release.niem.gov/niem/structures/4.0/"/>
+  <xs:complexType name="string">
+    <xs:annotation>
+      <xs:documentation>A data type for character strings in XML.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleContent>
+      <xs:extension base="xs:string">
+        <xs:attributeGroup ref="structures:SimpleObjectAttributeGroup"/>
+      </xs:extension>
+    </xs:simpleContent>
+  </xs:complexType>
+</xs:schema>
diff --git a/resources/literal-to-object-conversion/niem/utility/appinfo/4.0/appinfo.xsd b/resources/literal-to-object-conversion/niem/utility/appinfo/4.0/appinfo.xsd
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<xs:schema
+    targetNamespace="http://release.niem.gov/niem/appinfo/4.0/"
+    version="4.0"
+    xmlns:appinfo="http://release.niem.gov/niem/appinfo/4.0/"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+  <xs:annotation>
+    <xs:documentation>The appinfo schema provides support for high level data model concepts and additional syntax to support the NIEM conceptual model and validation of NIEM-conformant instances.</xs:documentation>
+  </xs:annotation>
+
+  <xs:attribute name="deprecated">
+    <xs:annotation>
+      <xs:documentation>The Deprecated element provides a method for identifying schema components as being deprecated. A deprecated component is one that is provided, but the use of which is not recommended.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleType>
+      <xs:restriction base="xs:boolean">
+        <xs:pattern value="true"/>
+      </xs:restriction>
+    </xs:simpleType>
+  </xs:attribute>
+
+  <xs:attribute name="appliesToTypes">
+    <xs:annotation>
+      <xs:documentation>The appliesToTypes attribute appears on the element declaration of a metadata element. It indicates a set of types to which the metadata element may be applied. The metadata element will also be applicable to any type that is derived from a listed type.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleType>
+      <xs:list itemType="xs:QName"/>
+    </xs:simpleType>
+  </xs:attribute>
+
+  <xs:attribute name="appliesToElements">
+    <xs:annotation>
+      <xs:documentation>The appliesToElements attribute appears on the element declaration of a metadata element. It indicates a set of elements to which the metadata element may be applied. The metadata element will also be applicable to any element that is in the substitution group of a listed element.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleType>
+      <xs:list itemType="xs:QName"/>
+    </xs:simpleType>
+  </xs:attribute>
+
+  <xs:attribute name="externalAdapterTypeIndicator">
+    <xs:annotation>
+      <xs:documentation>The externalAdapterTypeIndicator attribute indicates that a complex type is an external adapter type. An external adapter type is composed of elements and attributes from non-NIEM-conformant schemas.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleType>
+      <xs:restriction base="xs:boolean">
+        <xs:pattern value="true"/>
+      </xs:restriction>
+    </xs:simpleType>
+  </xs:attribute>
+
+  <xs:attribute name="externalImportIndicator">
+    <xs:annotation>
+      <xs:documentation>The externalImportIndicator attribute is true if and only if a namespace identified via xs:import is expected to be non-conformant.</xs:documentation>
+    </xs:annotation>
+    <xs:simpleType>
+      <xs:restriction base="xs:boolean">
+        <xs:pattern value="true"/>
+      </xs:restriction>
+    </xs:simpleType>
+  </xs:attribute>
+
+  <xs:element name="LocalTerm">
+    <xs:complexType>
+      <xs:sequence>
+	<xs:element name="SourceText" type="appinfo:NonemptyStringSimpleType" 
+                    minOccurs="0" maxOccurs="unbounded" form="qualified"/>
+      </xs:sequence>
+      <xs:attribute name="term" type="appinfo:NonemptyStringSimpleType" use="required"/>
+      <xs:attribute name="literal" type="appinfo:NonemptyStringSimpleType"/>
+      <xs:attribute name="definition" type="appinfo:NonemptyStringSimpleType"/>
+      <xs:attribute name="sourceURIs">
+        <xs:simpleType>
+          <xs:restriction>
+            <xs:simpleType>
+              <xs:list itemType="xs:anyURI"/>
+            </xs:simpleType>
+            <xs:minLength value="1"/>
+          </xs:restriction>
+        </xs:simpleType>
+      </xs:attribute>
+    </xs:complexType>
+  </xs:element>
+
+  <xs:simpleType name="NonemptyStringSimpleType">
+    <xs:restriction base="xs:string">
+      <xs:minLength value="1"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+</xs:schema>
diff --git a/...s/literal-to-object-conversion/niem/utility/conformanceTargets/3.0/conformanceTargets.xsd b/...s/literal-to-object-conversion/niem/utility/conformanceTargets/3.0/conformanceTargets.xsd
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<xs:schema
+    targetNamespace="http://release.niem.gov/niem/conformanceTargets/3.0/"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+  <xs:attribute name="conformanceTargets">
+    <xs:simpleType>
+      <xs:list itemType="xs:anyURI"/>
+    </xs:simpleType>
+  </xs:attribute>
+
+</xs:schema>
diff --git a/resources/literal-to-object-conversion/niem/utility/structures/4.0/structures.xsd b/resources/literal-to-object-conversion/niem/utility/structures/4.0/structures.xsd
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<xs:schema
+    targetNamespace="http://release.niem.gov/niem/structures/4.0/"
+    version="4.0"
+    xmlns:structures="http://release.niem.gov/niem/structures/4.0/"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+    <xs:attribute name="id" type="xs:ID"/>
+    <xs:attribute name="ref" type="xs:IDREF"/>
+    <xs:attribute name="uri" type="xs:anyURI"/>
+    <xs:attribute name="metadata" type="xs:IDREFS"/>
+    <xs:attribute name="relationshipMetadata" type="xs:IDREFS"/>
+
+    <xs:attributeGroup name="SimpleObjectAttributeGroup">
+        <xs:attribute ref="structures:id"/>
+        <xs:attribute ref="structures:ref"/>
+        <xs:attribute ref="structures:uri"/>
+        <xs:attribute ref="structures:metadata"/>
+        <xs:attribute ref="structures:relationshipMetadata"/>
+        <xs:anyAttribute namespace="urn:us:gov:ic:ism urn:us:gov:ic:ntk" processContents="lax"/>
+    </xs:attributeGroup>
+
+    <xs:complexType name="ObjectType" abstract="true">
+        <xs:sequence>
+            <xs:element ref="structures:ObjectAugmentationPoint" minOccurs="0" maxOccurs="unbounded"/>
+        </xs:sequence>
+        <xs:attribute ref="structures:id"/>
+        <xs:attribute ref="structures:ref"/>
+        <xs:attribute ref="structures:uri"/>
+        <xs:attribute ref="structures:metadata"/>
+        <xs:attribute ref="structures:relationshipMetadata"/>
+        <xs:anyAttribute namespace="urn:us:gov:ic:ism urn:us:gov:ic:ntk" processContents="lax"/>
+    </xs:complexType>
+
+    <xs:element name="ObjectAugmentationPoint" abstract="true">
+        <xs:annotation>
+            <xs:documentation>An augmentation point for ObjectType</xs:documentation>
+        </xs:annotation>
+    </xs:element>
+
+    <xs:complexType name="AssociationType" abstract="true">
+        <xs:sequence>
+            <xs:element ref="structures:AssociationAugmentationPoint" minOccurs="0" maxOccurs="unbounded"/>
+        </xs:sequence>
+        <xs:attribute ref="structures:id"/>
+        <xs:attribute ref="structures:ref"/>
+        <xs:attribute ref="structures:uri"/>
+        <xs:attribute ref="structures:metadata"/>
+        <xs:attribute ref="structures:relationshipMetadata"/>
+        <xs:anyAttribute namespace="urn:us:gov:ic:ism urn:us:gov:ic:ntk" processContents="lax"/>
+    </xs:complexType>
+
+    <xs:element name="AssociationAugmentationPoint" abstract="true">
+        <xs:annotation>
+            <xs:documentation>An augmentation point for AssociationType</xs:documentation>
+        </xs:annotation>
+    </xs:element>
+
+    <xs:complexType name="MetadataType" abstract="true">
+        <xs:attribute ref="structures:id"/>
+        <xs:attribute ref="structures:ref"/>
+        <xs:attribute ref="structures:uri"/>
+        <xs:anyAttribute namespace="urn:us:gov:ic:ism urn:us:gov:ic:ntk" processContents="lax"/>
+    </xs:complexType>
+
+    <xs:complexType name="AugmentationType" abstract="true">
+        <xs:attribute ref="structures:id"/>
+        <xs:attribute ref="structures:ref"/>
+        <xs:attribute ref="structures:uri"/>
+        <xs:attribute ref="structures:metadata"/>
+        <xs:anyAttribute namespace="urn:us:gov:ic:ism urn:us:gov:ic:ntk" processContents="lax"/>
+    </xs:complexType>
+
+</xs:schema>
diff --git a/resources/literal-to-object-conversion/niem/wantlist.xml b/resources/literal-to-object-conversion/niem/wantlist.xml
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<w:WantList w:release="4.2" w:product="NIEM" w:nillableDefault="true"
+  xmlns:w="http://niem.gov/niem/wantlist/2.2" xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/">
+  <w:Element w:name="nc:PersonFullName" w:isReference="false" w:nillable="true"/>
+</w:WantList>
diff --git a/resources/literal-to-object-conversion/niem/xml-catalog.xml b/resources/literal-to-object-conversion/niem/xml-catalog.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+  <uri name="http://release.niem.gov/niem/appinfo/4.0/" uri="utility/appinfo/4.0/appinfo.xsd"/>
+  <uri name="http://release.niem.gov/niem/conformanceTargets/3.0/" uri="utility/conformanceTargets/3.0/conformanceTargets.xsd"/>
+  <uri name="http://release.niem.gov/niem/niem-core/4.0/" uri="niem-core/4.0/niem-core.xsd"/>
+  <uri name="http://release.niem.gov/niem/proxy/xsd/4.0/" uri="proxy/xsd/4.0/xs.xsd"/>
+  <uri name="http://release.niem.gov/niem/structures/4.0/" uri="utility/structures/4.0/structures.xsd"/>
+</catalog>
diff --git a/src/aspell-exceptions.txt b/src/aspell-exceptions.txt
@@ -24,16 +24,20 @@ NDR
 NIEM
 NTAC
 Niklas
+PersonFullName
+PersonName
 RDF
 RDFS
 Sporny
 cardinality
 conformant
 json
 namespace
+nc
 normatively
 pre
 rdf
 satisfiable
 schemas
 subgraph
+xmlns