Design (small) manifest format to support mapping file name (key) :: resource?

[wendellpiez]

User Story:

One issue we have in OSCAL is to see to it that references to XML resources appearing in an OSCAL XML file, must be replaced in conversion to JSON by references to analogous JSON resources, perhaps on the premise that they can always be trusted to be there.

We have discussed providing a catalog lookup mechanism - something like XML Catalog but available in JSON as well (so: Metaschema-based?) - which would provide us to offer addressing (by dereferencing keys) coupled with resource management.

Then an OSCAL process such as Profile Resolution could, by making reference to this "OSCAL resource manifest", work much more robustly, as its dependent resources would no longer have to be hard-coded in the file, but could be supported by lookup. (Perhaps an optional feature in Profile Resolution.)

This infrastructure should be as lightweight as possible so as not to encumber. However, it is very open-ended in its applications and should also be useful when it comes to validating data integrity across document boundaries, not just referencing between documents.

It is also tempting to think about whether even lightweight, it could also support other nice-to-haves such as providing fallbacks - if my resource isn't found in location X, go look in Y. Etc.

Goals:

A small prototype / PoC demonstration of resource lookup for purposes of resource mapping across the JSON/XML divide, with OSCAL as an example.

This entails both some sort of managed resource list or manifest, and also a keying mechanism we could use to call it from documents. (Specialized flag on rlink?) The latter could be supported in Metaschema to provide tools with hooks.

As a secondary goal, it would be good also to demonstrate some sort of content validation relying on this manifest for input, to help users and tools ensure the integrity of their process inputs.

If the addressing mechanism is abstracted sufficiently, we can also demonstrate its use in (for example) profile resolution....

Finally, an additional requirement is worth considering: the ability to substitute, such as providing for fallback (when resources are not available) or for providing a cached profile resolution result (catalog) in place of a profile, for process optimization.

Dependencies:

See #567 and #581 for background.

DW first sketched a solution on this page.

For prior art: see XML Catalog and DITA maps.

Question: do we wish to support Formal Public Identifiers (or DOIs or ISBNs or any other universal naming schemes)? Maybe only implicitly as an implementation option.

Another question: in OSCAL data will there be a specialized flag, or an alternative protocol in links? What will the representation look like?

Some redundancy may be fine.

<resource>
  <title>My Catalog</title>
  <rlink href="catalog/on.the.net" rref="my_catalog"/>
...

where @rref (semantically, a lookup) can work alongside of, or switch in, for href (wired to an http retrieval).

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.

[wendellpiez]

In discussion, @david-waltermire-nist is advocating use of XML Catalog for many of the features we need to address here. Also there may be a dependency on ongoing Metaschema work.

Suggest we circle back to this one?

[david-waltermire]

This is the desired solution for #481.

[aj-stein-nist]

I would like to bring this up for Further Analysis as it seems we have plenty of rel and prop abilities since 2020 to make this issue is possibly obsolete. I will mark as Needs Triage for upcoming discussion with the group with a proposal to assign interested parties to volunteer and transition this to Further Analysis Needed.

/cc @Arminta-Jenkins-NIST