Enable Production of JSON Schemas with References by Path

[rgauss]

User Story:

As a Metaschema consumer via OSCAL JSON schemas, I want the resulting $ref values in those schemas to be by path rather than $id.

Goals:

We would like to be able to reference OSCAL JSON schemas directly in OpenAPI specifications. However, reference by $id rather than path seems to only be supported in OpenAPI v3.1 (and Swagger UI hasn't caught up to that yet).

You should be able to see an example of the issue we're encountering through an example which uses a simple example gist OpenAPI file:

1. Open Swagger editor with the example OpenAPI spec
2. Click on OSCALCatalog under Schemas
3. You'll see several errors about not being able to resolve references

Dependencies:

Relates to usnistgov/OSCAL#933

Acceptance Criteria

• All website and readme documentation affected by the changes in this issue have been updated. Changes to the website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[rgauss]

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

[david-waltermire]

This appears to have been fixed already. See usnistgov/OSCAL#948.