Closed romanojd closed 11 months ago
I'm going to leave it up to the LSC to merge this pull request. I would recommend merging it to the working branch as the initial schema and then everybody can suggest more changes and improvements to it at that point.
You could also include separate Command and Response schema files that reference the core schema file. I have examples here:
The JSON schema automatically generated from the property tables, using the standard Python validator (jsonschema v3.0.2, Julian Berman) correctly rejects empty object and empty array: commands/bad/empty_array: Fail: [] is not of type 'object' commands/bad/empty_object: Fail: 'action' is a required property responses/bad/empty_array: Fail: [] is not of type 'object' responses/bad/empty_object: Fail: 'status' is a required property
commands/bad/query_features_ext_args_nox-.json: Fail: Additional properties are not allowed ('mycompany' was unexpected) responses/bad/results_unknown_profile: Fail: Additional properties are not allowed ('mycompany' was unexpected)
The goal is schizophrenic here - it intends to be generic but it rejects profiles like slpf
and mycompany
unless they are explicitly shown in the property tables. As written, the LS shows slpf as an example but does not show mycompany as an example, so slpf messages are accepted and mycompany messages are rejected using the automatically generated JSON Schema. The schema used by every OpenC2 product MUST list all profiles that it supports in the property tables. But if there is an intent to create a generic schema then profiles not shown in the property tables should also be accepted.
responses/bad/results_asdouble: Brian has mischaracterized this as a bad response.
Unlike CBOR, JSON doesn't have an integer type, so 200.0 is the same number as 200. JSON Schema section 6.3 says "For consistency, integer JSON numbers SHOULD NOT be encoded with a fractional part.", but if the encoder doesn't follow that advice, the decoder has no choice but to accept it as a valid number.
commands/good/query_features_extension_args_number: The property table JSON schema accepts x-395 as a valid property name (it is not an NSID - see https://github.com/oasis-tcs/openc2-oc2ls/issues/342) if it is listed in the property tables and rejects it if it is not listed. If a schema is intended to be generic, then it should accept any property name.
responses/good/results_empty: Brian has mischaracterized this as a good response. The language spec requires at least one result, and the auto-generated schema correctly fails this "good" response: Fail: {} does not have enough properties.
responses/good/results_ext_multiple:
responses/good/results_ext_single: According to the property tables, these are bad responses. But 201 Create
is used often enough that we should add it to the property tables.
This PR was discussed at the 7 Oct 2020 L-SC meeting. Consensus was to leave the PR open, but it should be reviewed / revisited / updated by currently active TC members. @davaya noted that more flexibility is needed, to request the desired schema.
Meeting notes in Lucid, under agenda item 2.0: https://meet.lucidmeetings.com/lucid/meeting/264285.
This PR has become OBE with the publication of the JADN specification & CN. Per discussion / agreement at 29 Nov '23 working meeting it is being closed w/o merging.
I validated the oc2ls schema against the test messages that Brian Berliner developed: https://github.com/bberliner/openc2-json-schema/tree/master/src/test/resources. I did not have a chance to validate it against Danny Martinez's test messages.
The results are as follows:
fail/bberliner/commands/empty_object.json fail/bberliner/commands/empty_array.json fail/bberliner/responses/empty_object.json fail/bberliner/responses/empty_array.json
{}
) and empty array ([]
) don't fail like they should, but I think that is an issue with the python validator that I am using.fail/bberliner/commands/query_features_ext_args_nox-.json
fail/bberliner/responses/results_unknown_profile.json
{..., "results": {"mycompany": {}}}
). The oc2ls schema validation will PASS because the oc2ls schema doesn't know anything about the valid Actuator Profile results.fail/bberliner/responses/status_asdouble.json
pass/bberliner/commands/query_features_extension_args_number.json pass/bberliner/commands/query_features_ext_args_all.json
[A-Za-z]\\w*
[A-Za-z_]\\w*
[A-Za-z0-9]\\w*
\\w+
pass/bberliner/responses/results_empty.json
results
property of a Response is optional, but if present, it should contain a minimum of one property.pass/bberliner/responses/results_ext_single.json pass/bberliner/responses/results_ext_multiple.json
My validation code can be found at https://github.com/romanojd/openc2-schema-test.