oscal-rest
oscal-rest copied to clipboard
EasyDynamics
Change REST API JSON Schemas to NIST GitHub References
As part of a previous issue, it was found that the JSON schemas NIST produces contain $ref elements by $id rather than path which seems to only be supported in OpenAPI v3.1 (and Swagger UI hasn't caught up to that yet). See GitHub comment
We’ve also submitted a feature request to another NIST repo that facilitates the pipeline that creates the OSCAL JSON schemas: usnistgov/metaschema#160
As a result, in we forked the NIST OSCAL repo and 'manually' changed the JSON schemas to ref by path.
If/when NIST updates their JSON schemas or Swagger supports OpenAPI v3.1 we should revert the OSCAL REST API definition to reference NIST GitHub JSON schemas rather than our fork.
I actually started a discussion at NIST OSCAL's repo on this as I was trying to figure out what was going on. https://github.com/usnistgov/OSCAL/discussions/1057
I actually started a discussion at NIST OSCAL's repo on this as I was trying to figure out what was going on. usnistgov/OSCAL#1057
Thanks @flickerfly, just added another comment there.
Adding comments from a duplicate issue #48:
NIST is working on updating the JSON schema to support path refs.
We have created a PoC branch that points to those changes which seems to render appropriately in the Swagger Editor.
Once those changes have been finalized we should update our references.
and
Looks like the gist has been updated and we'll need to make some tweaks.
To provide an update on this, as of today, neither the OSCAL schemas have been updated nor has Swagger editor gotten support for OpenAPI v3.1. We will have to continue to point to our fork for now.
It does look like the Metaschema change has been added to the 0.9.0 milestone which is their "current" milestone.
@mpemy did you experience this. Now that we've are producing OpenAPI 3.1 syntax, which is now supported by the new Swagger, are we able to close this issue? If not, is this something you can have your OpenAPI generator application address automatically?
Made good progress on the collection of issues. This one will be addressed in sprint 68.
Current NIST meta schemas are only available in xml. I was not able to locate json versions.
Got some new insights from @brian-comply0, will address the remaining issue in sprint 69.
A few versions back, NIST moved away from publishing the JSON schemas in the repo and only making them available as download assets. Unfortunately this prevents us from linking to those files "in place" from the OpenAPI file.
The OpenAPI file needs to link to the schema files in a reliable and publicly accessible location. As a result, we moved clean copies of the NIST OSCAL v1.1.2 JSON schema files into this repo's develop branch via PR #95 , such that the OpenAPI file can use https://raw.githubusercontent.com/EasyDynamics/oscal-rest/develop/oscal-schema/v1.1.2/oscal_[model-name]_schema.json where the NIST schema needs to be referenced.
After review with @mpemy we have learned that the published NIST OSCAL JSON schema definitions continue to be incompatible as references for the OpenAPI definition as-is.
We will continue using the manually adjusted version of those files for the foreseeable future, and will place this issue back on hold.
Possible future steps include:
- creating a script that will auto-modify all NIST schema files for our needs.
- continue exploring the OpenAPI 3.1 specification for alternative syntax or approaches that enable us to use the NIST JSON schema files as-is