JSON Schema References are Incorrect

[rgauss]

Describe the bug

Many of the $ref values in the JSON schema seem to be incorrect. As just one example, the catalog metadata revision property specifies an array of items with type "$ref" : "#/definitions/oscal-metadata-revision" but I believe the definition has been renamed to oscal-catalog-oscal-metadata-revision.

These new object-specific definitions, such as oscal-catalog-oscal-metadata-revision, will also make it much more difficult to address an issue like #731 where we'd like to see common schemas for elements reused across different models, i.e. the profile model defines oscal-profile-oscal-metadata-revision.

Who is the bug affecting?

Anyone trying to resolve/leverage the JSON schema, this seems to affect all models.

What is affected by this bug?

The ability to properly parse/resolve the schema.

When does this occur?

Always

[butler54]

I just wanted to add a plus one on the object specific definitions - I understand the logic in that these are unique, however, I think referencing back to #731 it just spins the problem in a different way.

Today from a final data point of view is oscal-metadata-version consistent - yes. Is it defined 7 times with different labels yes.

This complexity makes it harder to use tooling like openapi efficiently. I think the ideal outcome is that the json schema object (from a json schema users perspective) can be generated as one global OSCAL schema. It does not have to be generated as a global schema, however, the names do need to be consistent such that a user could merge and do so themselves without creating a mess.

[rgauss]

@butler54, OpenAPI is exactly one of the reasons we're pursing this.

We hope to put forward a proposal for the beginnings of an OSCAL REST OpenAPI definition (in a time frame closely aligned with OSCAL's 1.0 final release) that starts to explore how real world systems could map the relationships within and between the different OSCAL models.

As part of this discussion though, we need to have clear schema definitions of which objects are in fact shared vs unique, not just based on name. For example, a component-definition's component's control-implementation objects and the implemented-requirement objects contained within them are identically named and extremely similar to a system-security-plan's control-implementation objects and the implemented-requirement objects contained within them, but they are intentionally distinct objects.

[butler54]

If you are interested (or okay with) python this may be of interest (I won't claim it's perfect but we did get to an object model and at least you are able to build APIs quickly): https://github.com/IBM/compliance-trestle-flask-demo

(Could not help the little plug for https://github.com/IBM/compliance-trestle)

[david-waltermire]

This was addressed by PR #948, which has added support for a combined XML and JSON schema, along with model specific schema views.

[rgauss]

While this fix looks correct after a quick 'manual' spot check of the changes it unfortunately won't solve our issue since $ref by $id rather than path seems to only be supported in OpenAPI v3.1 (and Swagger UI hasn't caught up to that yet).

It would be nice if $ref in the schemas could point to a path rather than by $id, but I understand it that might be difficult with the pipeline/tooling being used to generate the schema.

[wendellpiez]

@rgauss would you be able to open a new ticket in the usnistgov/metaschema repo for this, possibly with a (tiny) mockup? We would gladly consider options and feasibility. There is a possibility that the Metaschema design would preclude doing this, but alternatively, maybe it is actually super-easy or could be made to be. We have to look. Thanks!

[rgauss]

@wendellpiez, submitted usnistgov/metaschema#160. Thanks!

[rgauss]

(tiny) mockup?

Here's an example of what the result might look like (and works with Swagger UI).