niem / niem-json-spec Goto Github PK

Spec looks good.

Regarding the use of Lax conformance. "Lax conformance enables the use of vocabularies that are defined by NIEM schemas or IEPDs via linked data and linked open data methods. It establishes that exchanges with NIEM-conformant vocabularies use those vocabularies properly; this allows data to be more flexible, and to combine terms from NIEM-conformant vocabularies with terms from other vocabularies."

Is this intended to apply to adapter implementations to establish compatible exchanges? If so, please consider including an example to provide context to the readers. Also consider changing "Lax Conformance" to "Adaptive Conformance" or "Compatible Conformance".

Literal-to-object conversions needs examples and a description of exactly what happens.

Does a valid JSON instance have to have a single top-level property? Or can it have multiple top-level properties? An XML document has to have a single XML element as the document element. A JSON instance could be an object that has multiple properties at the top level.

Do we require valid JSON to correspond to a single valid XML document with a single root element?

So far, we've said that the JSON-LD must correspond to valid XML, but we haven't said the lexical structure of the JSON had to correspond to the lexical structure of the XML.

Describe document conventions, based on the NDR's documentation conventions (https://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/niem-ndr-4.0.html#section_2).

Request in #16 was to add example of a date type.

See the wiki for an example of how this is done.

• section 2.3, para 3: Should be "The principal component of...", not "principle".

• section 2.3: The first two definitions as quoted are obviously circular. We should include the NDR sentences about conforming to all the rules of the specification,

• section 4.1, para 1: Second sentence should begin "For this reason..."

• rule 4-2: Perhaps "this rule does not provide or require a translation algorithm from JSON to XML; it only requires that the equivalent XML document is somehow available". So far as we're concerned the tooth fairy could leave it under your pillow.

v4 has reference to MPD spec. Update to revised IEPD spec.

In v4.0alpha1 rule 4-2, use better terminology than "equal to" for RDF equivalency.

The doc uses "message description" and "IEPD".

Prefer term "message specification".

Clarify that a message should conform to one or more message specifications that it's constructed to satisfy.

Text is currently "conform to the relevant message descriptions".

Issue derived from #16.

Currently these two definitions are too copy-pasted, which makes the difference unclear. Modify normalization definition for clarity.

post 4.0 JSON spec on reference.niem.gov

From #16.

The changelog at https://github.com/NIEM/NIEM-JSON-Spec/releases/tag/v4.0beta1 refers several times to 4.2 and 4.3. It should be 5.2 and 5.3.

Explain the conversion to @type, potentially including rdf type mapping information.

We currently have literal-to-object conversion as a step for normalizing a JSON file to be conformant JSON-LD.

We don't want to require attaching contexts to runtime data, in most cases.

Consider expanding the literal-to-object conversion to be a stage for JSON-LD normalization, which would include literal-to-object conversion, as well attaching a context as provided my a message specification.

This may involve a new conformance target, for a de-normalized JSON instance.

See https://github.com/NIEM/NIEM-JSON-Spec/wiki/NIEM-JSON-normalization for an explanation.

We need to handle ordered contents somehow, long term.

JSON-LD and RDF have lists; we used to have sequence ID. We need to figure out how to bridge the two. Maybe "ordered" is a property of a an element ref, indicating that its ordered content implies a list.

I would like to have more time to look at the spec, but I keep getting dragged on to other tasks. I used mark-up in the document to add some notes.

NIEM JSON Specification.docx

Instead of presuming all external content is conforming, perhaps we could have a rule similar to XML Schema's strict/lax/skip conformance for wildcards.

• strict: The JSON is NIEM-conforming if and only if there is a separate conformance test for all external content AND all external content satisfies the corresponding test

• lax: The JSON is NIEM-conforming UNLESS there is a separate conformance test for some external content AND external content which fails that test

• skip: Forget it, Jake, it's Chinatown

rule 4-4: We don't have this RDFS-interpretation rule for NIEM XML. Do we need it in the NDR? Is it necessarily satisfied in XML?

In 4.0alpha1 (acdde20) Rule 4-3 should apply to LAX and STRICT.

Capture what's said here: https://json-ld.org/spec/latest/json-ld-api-best-practices/#unordered-values Best practice 6: assume arrays are unordered

maybe add an interpretation rule that captures this.

1.1 Audience
The primary target of this guidance is the tool developer implementing tools to generate JSON instances (messages) that conform with the NIEM.

Developers looking to develop NIEM message specifications (IEPDs) including JSON representations, should refer instead to the Non-Normative Guidance in Using NIEM with JSON document.

Rule 5-2 should reference the new normalization section rather than literal-to-object conversion.

Literal-to-object conversion turns something like:

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

Into

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

Should it go a step farther, by assigning type information where appropriate? Like properly handling dates? For example, turn this:

{
  "nc:Date": "1970-01-01"
}

…into this:

{
  "nc:Date": {
    "rdf:value": {
      "@value": "1970-01-01",
      "@type": "xs:date"
    }
  }
}

Clarify that interpretation rules have requirements levels.

At "An enforceable rule".

Derived from #16.

Figure 5-4 is incorrectly referencing rdf:type. Look to figure 5-9 for correct structure.

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