Current jsonschema objects (and documentation) appear to have elements which are not in the document definition.

[butler54]

Describe the bug

In trying to autogenerate code of the latest release (1.0.0rc1) I ran to the fact that a number of objects were defined in the json schema, however, were never referenced in the structure that gets assembled from the root object (e.g. catalog or system-security-plan )

With json schema as currently setup there are two types of objects:

1. Top level objects that are defined in ``{"definitions:[]}" in the json schema.
2. Embedded definitions that are within those top level object.

Given this I wrote a script gist here which searched for 'top level' definitions that were never referenced with a "$ref" within the json schema.

These elements (and potentially some of the child elements beneath them) are therefore not part of the model:

Examinining: oscal_ssp_schema.json
Examinining: oscal_catalog_schema.json
id #/definitions/role-id not in use
id #/definitions/responsible-role not in use
Examinining: oscal_assessment-results_schema.json
id #/definitions/parameter not in use
id #/definitions/set-parameter not in use
id #/definitions/system-id not in use
id #/definitions/import-ssp not in use
id #/definitions/assessment-method not in use
Examinining: oscal_assessment-plan_schema.json
id #/definitions/parameter not in use
id #/definitions/set-parameter not in use
id #/definitions/system-id not in use
id #/definitions/assessment-method not in use
id #/definitions/objective-status not in use
id #/definitions/observation not in use
id #/definitions/risk not in use
Examinining: oscal_profile_schema.json
id #/definitions/role-id not in use
id #/definitions/responsible-role not in use
Examinining: oscal_component_schema.json
id #/definitions/system-component not in use
id #/definitions/system-user not in use
id #/definitions/inventory-item not in use
id #/definitions/system-id not in use
Examinining: oscal_poam_schema.json
id #/definitions/parameter not in use
id #/definitions/system-user not in use
id #/definitions/set-parameter not in use
id #/definitions/local-objective not in use
id #/definitions/assessment-method not in use
id #/definitions/activity not in use
id #/definitions/action not in use
id #/definitions/assessment-assets not in use
id #/definitions/objective-status not in use

Root cause at this stage is unknown. This appears to affect xml from my examination on the website as well, however, I have not tested.

Who is the bug affecting?

• Mostly those auto-generating code and data structures from code (today)
• May affect users in that they may use elements which are not meant to be in the schema.

What is affected by this bug?

All schema objects excluding SSP.

When does this occur?

When using 1.0.0rc1 codebase.

How do we replicate the issue?

Issue should be observable from code itself. Downloading the gist and running:

python3 gist.py path/to/OSCAL/json/schema

should allow the reproduction of the results.

Note: pip install ilcli may be required.

Expected behavior (i.e. solution)

Remove models which are not included from the root schema.

Other Comments

This may not be an issue. It just looked super strange and feel free to correct me if I am wrong.

[wendellpiez]

This appears to me to be related to a known issue with identifiers in JSON Schema, addressed (potentially) by PR usnistgov/metaschema#111 - but needs discussion.

We are agreed that with the new design, naming these definitions after the source (Metaschema) definitions (alone) is not robust; we have not determined how we would like to provide them with identifiers that are both legible, and unique to the object.

[butler54]

Great - just FYI this is not a blocker for the work we are doing. It just introduces some 'dead code' for us.

[wendellpiez]

At one point there was a filter that removed definitions that are not descended from assemblies defined with root-name, i.e. designated to be valid roots. It was disabled due to conflicts with the 'local' definition feature (since resolved). So it is related to usnistgov/metaschema#31.

This filter needs to be restored and tested. This work is happening with usnistgov/metaschema#117 and other Metaschema work items.

[wendellpiez]

We have re-introduced the filter (mentioned above) to be more assertive in removing unused definitions from both XSD and JSON Schemas. Next, testing to see whether this actually addresses the problems here.