Schema requirements

[davaya]

The OpenC2 Language Specification and Actuator Profiles each previously included a Schema annex containing the formal syntax for that specification.

OpenC2 Producer and Consumer products may support one or more profiles, and may support none, some, or all of the optional fields defined in those specifications, and must support all required fields. OpenC2 defined a "query features schema" command and response to allow Producers to discover the specific profiles and optional fields supported by a particular Consumer. A process for combining schemas from the LS and one or more profiles is described in https://github.com/oasis-open/openc2-custom-aps/tree/master/Schema-Template.

The schema annexes and the schema query were removed prior to publication of v1.0, and there is now discussion of restoring them, including what schema formats should be published with the specifications and/or returned in response to a query. The decision should be based on requirements:

• The primary purpose of schema annexes or artifacts is as the authoritative definition of the syntax of the core language and of each profile's language elements. These schemas are building blocks that can be combined to validate commands and responses.
• The primary purpose of a schema query is to allow Producers to discover the commands recognized by a Consumer directly rather than by trial and error. This implies that the Producer will make decisions on what to send based on information received from the query, analogous to a human using information from a "help" command to decide what to type next.

The candidate schema formats are:

• JSON Schema - the de-facto standard for validating JSON data structures. The latest set of specifications is https://json-schema.org/specification-links.html#2019-09-formerly-known-as-draft-8
• JSON Abstract Data Notation (JADN) - the format-independent language created and used to define OpenC2 property tables and validate data structures in JSON, XML, CBOR, and other formats. The latest specification is https://github.com/oasis-tcs/openc2-jadn/blob/working/jadn-v1.0-wd01.md
• OpenC2 currently publishes examples only in JSON format. If in the future additional examples in formats such as XML or CBOR are published, schema languages such as XSD or CDDL would become relevant.

[sparrell]

I see no need to ever to XML. I could change my mind if someone has an actual need for it. I am against doing it 'for completeness'. I don't think we should make more options than necessary.

[sparrell]

I do see the need for CBOR. If we agree to include CBOR, how does that affect?

[davaya]

If we start modeling data objects such as SBOMs instead of carrying them as opaque blobs, XML will be required. I agree that we need a use case to justify it.

[dlemire60]

discussed at triage, next version issue, create non-normative appendix to LS describing use of JADN create JADN schema for LS first, once that's published as CS can begin adding to APs.

[dlemire60]

Proposed outline for non-normative Appendix:

• Brief summation of what JADN is
• Explanation how JADN schema enables other schemas & serializations
• Illustration with small subset of OpenC2 language
  • JIDL for some basic and complex types
  • Corresponding JSON data in JADN format
  • JADN translation to JSON schema
  • JADN translation to CBOR/CDDL
• Reference to OpenC2 JADN schema external artifact

[dlemire60]

The draft appendix from PR #408 still has two sections that need to be populated / completed:

D.3.3 Translation To JSON Schema

TBD: JADN translation to JSON schema

D.4 Additional Information

TBD: Reference to, description of OpenC2 JADN schema external artifact

[dlemire60]

I believe this issue is OBE. PR #428 addresses many of the concerns and the addition of a JADN Schema for LS v2.0 should complete the process. Recommend closing.

[dlemire60]

This issue is now closed, per consensus at the 10 January 2024 working meeting.