Enhancing 'link' to indicate internal targets in a 'resource'

[wendellpiez]

User Story:

Sometimes I need my data to point not just to a document, but to a location inside that document, as in <link href="target.xml#id1"/> to point to an element with id="id1" in a document found at target.xml.

This doesn't work, however, when using an indirect link via resource inside an OSCAL file:

<link href="#xxxxx">Chapter 3 in <i>Document Title</i></link>
...
<resource uuid="xxxxx">
   <title>[Document Title]</title>
   <rlink href="https://link/to/document.html"/>
</resource>

By OSCAL link traversal, a link to a resource resolves into a link to the resource itself. However, this does not help us to target an identified location inside that resource.

Goals:

One simple solution would be to provide link with a new flag such as ref-id, to indicate the ID of a target within a linked resource.

<link href="#xxxxx" ref-id="ch3">Chapter 3 in <i>Document Title</i></link>

@ref-id would effectively alias the href # fragment identifier syntax inside @href values, but would also work on targets indicated by reference to resource elements.

If "ref-id" is too ambiguous (it should not be the ID of the resource but a string representing an ID inside the document it references) we could come up with another name.

This idea would be much easier for developers to support than the proposal outlined in #567 addressing the same requirement.

Dependencies:

This proposal addresses the requirement described in Issue #567, albeit with a different mechanism. (Instead of extending the W3C-defined href linking syntax, we use OSCAL). If this proposal is adopted, we can close #567 and spin part of its effort (describing / documenting link construction) into a separate one.

Additionally, this Issue could be included in the work for #597 (an epic covering model enhancements).

Also, update the document, model, or constraint additions with changes in PR associated with #1023 following its approval and merge in the context of this work, although not an explicit dependency. See #1023 (comment) for more details.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL 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.

[david-waltermire]

The following are two possible ways to address this issue.

1. extra fragment

<link rel="some-relation" href="#backmatter-uuid#uuid"/>

In the above the backmatter-uuid would point to the back-matter/resource, while the uuid will point to an identifier within the content associated with that resource.

This approach complicates writing constraints that enforce the link to back-matter resource relation. It also complicates resource resolution, since the two fragments will need to be pre-parsed.

2. Extra flag

<link rel="some-relation" href="#backmatter-uuid" resource-fragment="#uuid"/>

In the above the backmatter-uuid would point to the back-matter/resource, while the uuid will point to an identifier within the content associated with that resource.

This approach requires handling the fragment outside the href, which may complicate resource resolution.

Which to choose?

We are interested in feedback on these options. Thoughts?

[GaryGapinski]

Neither of the two ways accommodates a backmatter/resource with an rlink specifying a URI with a fragment. Nor a backmatter/resource with multiple rlink elements.

[david-waltermire]

During the 8/5 model meeting, there was discussion of back-matter chaining related to resolving resources (potentially across referenced documents). We need an example and clearer specification around how to handle this.

@david-waltermire-nist will work up some examples to illustrate such cases.

[tuckerzp]

I think that option number 2 seems a lot cleaner. When actually implementing the back matter links, I think having to parse the href string would be slightly more tedious than just having an extra flag.

[david-waltermire]

Issue #567 was an earlier issues exploring this topic, with some suggestions around a way forward.

[wendellpiez]

Perhaps if we provided @uuid not only on resource but on rlink.

Then multitudinous rlink children for a given resource could point to locations (targets) "belonging to" that resource, and anchors and links in the instance could point to an rlink to indicate a specific link for the resource.

This is not a perfect solution but builds cleanly on what we have, and it avoids a number of potential complications in both link and resource maintenance (given that resources may be both 'abstract', and have multiple representations available).

[david-waltermire]

@wendellpiez One thought... If a specific rlink matters that much, why not just create a new resource that includes the single rlink? Then the uuid reference to the resource is non ambiguous.

This would avoid a case where we would need multiple coordinates to select the resource and rlink. This simplifies the link structure and processing model.

[wendellpiez]

True, that is one potential solution, i.e. break out the links. Don't try and provide the "link base" functionality in a resource.

As to that, perhaps we need to clarify how the "role" of an rlink in a resource is distinguished, if there are multiple (such as JSON and XML versions of the "same document", or backup copies). I.e. which kinds of (over)loading of rlinks into a resource are legit, vs which ones you're on your own with.

One reason why extending the notation at the other end is that an element-id pointer only works on XML targets, for example. But what if the document you are linking to is in JSON? a pointer syntax has to work for either doesn't it?