References, schemas, and NSIDs

[davaya]

The first "Release" of the LS, https://github.com/oasis-tcs/openc2-oc2ls/releases/tag/v1.0-csprd01, contained this description of imported type definitions:

---

3.3.3 Imported Data
In addition to the targets, actuators, arguments, and other language elements defined in this specification, OpenC2 messages may contain data objects imported from other specifications and/or custom data objects defined by the implementers. The details are specified in a data profile which contains:

• a prefix indicating the origin of the imported data object is outside OpenC2:
  x_ (profile)
• a unique name for the specification being imported, e.g.:
  For shortname x_kmipv2.0 the full name would be oasis-open.org/openc2/profiles/kmip-v2.0,
  For shortname x_sfslpf the full name would be sfractal.com/slpf/v1.1/x_slpf-profile-v1.1
• a namespace identifier (nsid) - a short reference, e.g., kmipv2.0, to the unique name of the specification
• a list of object identifiers imported from that specification, e.g., Credential
• a definition of each imported object, either referenced or contained in the profile

---

This isn't perfect, but CS 1.0 has gone off the rails:

---

3.1.4 Extensions
Each Actuator profile has a unique name used to identify the profile document and a short reference called a namespace identifier (NSID). The NSID is used to separate extensions from the core language defined in this specification.

All extensions MUST be identified with a short namespace reference, called a namespace identifier (NSID).

For example, the OASIS standard Stateless Packet Filtering actuator profile has:

Unique Name: http://docs.oasis-open.org/openc2/oc2slpf/v1.0/oc2slpf-v1.0.md
NSID: slpf

---

The problem is that schemas do not have NSIDs.

Schemas are identified by their unique name and referenced by their unique name. JSON Schema uses the $id keyword to identify a schema, and the $ref keyword to reference a definition, either in the current schema with a fragment #/definitions/Action or in a separate schema with a full path starting with the unique name http://oasis-open.org/openc2/oc2ls/v1.0/definitions/Action.

NSIDs do not exist in JSON Schema.

NSIDs do exist in XML Schema using the name "prefix":

1.3.1 XSD Namespaces
1.3.1.1 The Schema Namespace (xs)
The XML representation of schema components uses a vocabulary identified
by the namespace name http://www.w3.org/2001/XMLSchema. For brevity,
the text and examples in this specification use the prefix xs: to stand for this
namespace; in practice, any prefix can be used."

https://www.w3.org/TR/xmlschema11-1

And NSIDs exist in JADN as defined in CSDPR01 - "a short reference to the unique name of a specification", having the identical meaning as the XML Schema "prefix".

The LS description of schemas must be re-written to be compatible with JSON and JSON Schema, and any description of NSIDs in JADN property tables must be compatible with the XML definition of prefixes.

• NSIDs are short (8 chars is more than sufficient)
• NSIDs are used in JADN property tables ONLY to refer to Types: ls:Action is an exact synonym for and can always be replaced by http://oasis-open.org/openc2/oc2ls/v1.0/definitions/Action.
• NSIDs are never property names and never appear in OpenC2 messages.
• NSIDs are local to a single schema - one schema could use ls: to refer to the language spec, and others could use lspec:, oc2ls:, or abc:.

If we want to talk about property names used in OpenC2 JSON messages and map keys used in OpenC2 CBOR messages, we'll need to call them something other than NSIDs. The front matter of the LS, or the "Architecture" doc, can describe an OpenC2 profile registry containing entries like:

 ID   Name   Profile Unique Name                         Description
----  ----   ------------------------------------------  ----------------------------------
1024  slpf   http://oasis-open.org/openc2/oc2slpf/v1.0   Stateless Packet Filtering Profile
2001  x_fam  http://oasis-open.org/openc2/cap/fam/v1.0   File Anti-malware Custom Profile

[Vasileios-Mavroeidis]

I assume that Section 3.1.4 will be moved to the architecture spec. Nevertheless, I wanted to capture that we haven't updated the URI of SLPF in the example.

[davaya]

The namespace registry contains text that will go in the architecture spec. The existing section 3.1.4 needs to be replaced, by either incorporating or referencing the registry text (since we don't yet have an architecture doc).

Then the incorrect examples will need to be replaced. The examples we have been using are incorrect because JSON itself does not have namespaces - using a colon-delimited prefix on JSON property names is both meaningless according to the JSON standard and confusing because it implies that JSON supports something that it does not.

The purpose of this issue is to clearly articulate that a colon character has no special meaning in JSON. Calling something like slpf:rule_number an "NSID" implies that there is some magic behavior that is different from a property called slpf_rule_number. Unlike XML, JSON has no special treatment of colons in property names. In our haste to get a version 1.0 out the door that incorrect and confusing terminology made it into the Language Spec, this issue is to pull it back out and fix the examples that use it.

The way to do namespacing in JSON is to use standard JSON Pointer (RFC 6901) syntax: "slpf/rule_number" when pointing to objects defined in other documents. The slash (/) character does have special meaning defined by the RFC: "slpf" is a Language Spec property whose value is an object property "rule_number" defined in the SLPF profile.

It is worth noting that Target is the only OpenC2 field using incorrect examples. The Actuator, Args, and Results examples are all correct: "slpf" is the name of the property that contains SLPF-defined values.

[dlemire60]

This issue appears to be still valid and in need of resolution. Recommend triage outcome of "resolve in LS v1.1".

[dlemire60]

Discussed at triage, @davaya to propose text for next version (probably already an action).

[dlemire60]

Two Architecture repo PRs record our current thinking for namespaces:

• 92: Update registry namespaces (Update registry namespaces  openc2-oc2arch#92)
• 93: Appendix F update (Appendix F update openc2-oc2arch#93)

Need to ensure that LS content associated with namespaces is adjusted accordingly.

LS PR #432 has a minor update to section 3.3.1.3. for a location change of the namespace registry document.

[dlemire60]

I believe PR #434 addresses this issue. Adding candidate for closure tag.