search

EasyDynamics / oscal-rest

An initial OpenAPI definition of an OSCAL REST API.
Creative Commons Attribution Share Alike 4.0 International
38 stars 13 forks source link

Change REST API JSON Schemas to NIST GitHub References #32

Open rgauss opened 2 years ago

rgauss commented 2 years ago

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.

rgauss commented 2 years ago

Migrated from Jira

flickerfly commented 2 years ago

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

rgauss commented 2 years ago

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.

rgauss commented 2 years ago

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.

laurelmay commented 2 years ago

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.

brian-comply0 commented 9 months ago

@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?

brian-comply0 commented 6 months ago

Made good progress on the collection of issues. This one will be addressed in sprint 68.

mpemy commented 6 months ago

Current NIST meta schemas are only available in xml. I was not able to locate json versions.

Image

mpemy commented 6 months ago

Got some new insights from @brian-comply0, will address the remaining issue in sprint 69.

brian-comply0 commented 5 months ago

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.

brian-comply0 commented 5 months ago

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: