OSCAL icon indicating copy to clipboard operation
OSCAL copied to clipboard

Provide guidance around relative URI handling for href instances

Open david-waltermire opened this issue 2 years ago • 2 comments

User Story:

As an OSCAL developer, I would like to have consistent guidance around relative URI handling within href in OSCAL.

Goals:

Update the OSCAL docs references with consistent guidance, including /profile/metadata/link/@href and /profile/back-matter/resource/rlink/@href.

  • [ ] Ensure each instance of model reference documentation clearly indicates if an href requires a URI reference or an abolute URI.

This issue builds on the work to review the OSCAL models (#1066 #1331).

Dependencies:

none

Acceptance Criteria

  • [ ] The guidance addresses when relative URIs are supported and not.
  • [ ] 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 avatar May 10 '22 14:05 david-waltermire

Need to address this TODO.

david-waltermire avatar Jul 22 '22 15:07 david-waltermire

Relative URIs should be supported. Are there any scenarios in which they should not be supported?

URIs which are relative may, or may not, have a scheme, as do absolute URIs. An example for a sibling document href="file:sibling" is interpreted as a sibling document relative to the base URI of the containing document. This seems to be a bit at odds with RFC 3986 though it seems commonly supported.

An href which begins with a # is a URI fragment, not a URI.

See RFC 3986 sections 4 and 5 for related information.

GaryGapinski avatar Jul 26 '22 11:07 GaryGapinski

@GaryGapinski Check out this comparison which shows all the edits I made to clarify URI handling. Does this address your concerns? If not, please comment here or on PR #1263.

david-waltermire avatar Aug 25 '22 00:08 david-waltermire