search

oasis-tcs / openc2-oc2ls

OASIS OpenC2 TC: GitHub repository used to propose and track changes to the OpenC2 Language Specification as new working draft level revisions are created and the associated CSDs mature
https://github.com/oasis-tcs/openc2-oc2ls
Other
15 stars 19 forks source link

References, schemas, and NSIDs #342

Open davaya opened 5 years ago

davaya commented 5 years ago

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:

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.

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 commented 4 years ago

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 commented 4 years ago

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 commented 2 years ago

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

dlemire60 commented 2 years ago

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

dlemire60 commented 9 months ago

Two Architecture repo PRs record our current thinking for namespaces:

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 commented 7 months ago

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