usnistgov / oscal-reference Goto Github PK

While working on the mapping feature branches, I encountered a few issues that aren't really bugs, but dev experience improvements that we might need to consider. It is possible I could have overlooked setting an environment variable to address some of this.

1. When generating documentation, it would be nice if I could just generate it for a single branch of OSCAL.
2. When I am working on a local branch that has not been published, it would be useful to be able to point to the local branch.
3. Optionally, it would be useful to supply the list of branches in the event I have multiple local branches, or published branches that I want to review.

My workaround

In order to accomplish this:

• I edited list_revisions.sh and echoed my own branch names, and commented out the other branches.
• I symlinked support/OSCAL to my local OSCAL repo.
• After working on OSCAL I ran:

  $ make clean 
  $ make site 
  $ make serve
  

• I reviewed documentation for the branches that I listed.

If there is a way to use the environment variables to accomplish this, it might just need to be added to the README. It looks like OSCAL_DIR and REVISIONS would be the ones, but not sure if they truly support being passed from the command line.

A community member discovered that reference pages follow the format OSCAL-Reference/models/v1.1.0/complete/json-outline/ but tend to link to other reference pages in the format OSCAL-Reference/models/v1.1.0/complete/json-outline.html.

This Hugo misconfiguration causes reference pages not to link to each other properly. Hugo's generated URLs need to be corrected (and aliased to both options).

To reproduce:

1. Visit https://pages.nist.gov/OSCAL-Reference/models/v1.1.0/complete/json-outline/
2. Click any of the model links.

Noticed that the last update date is not set on pages generated from the models.

Shows:

This page was last updated on January 1, 0001.

If it's not a quick fix, we might need to comment out.

Describe the bug

There are many places in the OSCAL documentation lists incorrect values for the @name attribute on the prop field.

For example, prop[@name='marking'] is only supposed to be valid in the //metadata of each model; however, it is also incorrectly listed in the documentation as valid in many other places.

A search of the Catalog documentation shows eight additional occurrences of prop[@name='marking'] in places such as:

• //metadata/revisions/prop
• //metadata/role/prop
• //metadata/location/prop
• //metadata/party/prop
• //metadata/responsible-party/prop
• //param/prop (root, group, and control levels)
• //control/prop (root, group, and control levels)
• //part/prop (group and control levels)
• //group/prop
• //back-matter/resource/prop

Who is the bug affecting

Developers trying to properly implement OSCAL properties.

What is affected by this bug

Documentation

How do we replicate this issue

1. Visit the documentation page for any model.
2. Search the page for "marking" (three occurrences of marking per entry)
3. Observe prop[@name='marking'] as valid in places other than //metadata/prop

Expected behavior (i.e. solution)

Documentation for prop in each context should include only the actual accepted values for @name.

Other comments

This issue has existed since the pre 1.0.0 release candidates. To my knowledge no issue was created for it. I could not find one among the open issues.

Revisions

No response

We already talked about this, but did not see an issue anywhere. Apologies if duplicated. The initial page of the OSCAL reference could use a landing page-style format that gives an overview of the content and audience of the site. We might assume some people will see this as their first encounter with OSCAL and provide a little guidance to the other locations for content.

Also noticed that we need the link set in Settings for the pages URL that displays on the github project.

Following the v1.1.0 release, the location users must use to download schemas has changed.

As an OSCAL user, I would like a convenient URL that I can use to access the latest version of a given release asset.

GitHub's releases API allows users to retrieve the latest release, but does not provide a convenient way to link directly to the latest version of a release asset. This poses a problem for direct links in READMEs and OSCAL Pages content.

CI infrastructure should mirror the linkchecker as configured in OSCAL Pages

For the work that is ongoing in DEFINE on mapping and shared responsibility/CRM, it would be useful for us to publish the draft reference material so that the public can review without generating the content locally. It would also encourage use of the branches for evaluation and feedback.

I intended to merge draft metaschema code into the prototype-* branches that I created in OSCAL for mapping and CRM. I'm not particularly attached to the prefix, but these are not exactly feature branches since they may contain multiple features (merges) for consideration. If we could choose an appropriate prefix to publish automatically as model drafts or experimental branches, it would be very helpful.

Steps:

• Discuss with team and agree to prefix: agreed to prototype.
• Adjust list_revisions.sh to include branches and/or generate_modeldoc.sh to build branches with the prefix.
• Adjust the GitHub Actions workflow to support workflow_dispatch to interactively call the updated code in GitHub Actions and build updated versions of the site
  • Strech goal: perhaps allow to filter that list in the GitHub interface and intentionally add/remove filters not detected by the script?

The generated site no longer generates release assets as of 028e0e1, likely as a side-effect of the Lychee linkchecking PR.

Test issue please ignore

Per after we complete #19, we have discussed adding back experimental models that are not part of a tagged release. For this issue, after #19 is complete, we will want to modify the style of the site so that, when generating a branch that is not a tagged release (v1.0.0, v1.0.1, v1.1.0 et cetera) and it has a predetermined prefix (see #19), there is a notice or watermark indicating the models and supporting documentation are experimental

As reported by @JustKuzya in #6 (comment), the reference pages still link to internalized OSCAL data types incorrectly after the website migration.

An example link (now incorrect) to a copy of the data types on the OSCAL site is below.

https://pages.nist.gov/OSCAL-Reference/reference/datatypes/#uri-reference

An updated correct example (and all those like it) will point to the correct upstream link, such as the one below.

https://pages.nist.gov/metaschema/specification/datatypes/#uri-reference

The OSCAL profile resolution specification currently lives in OSCAL-Pages, however the source SpecML markup still lives in the OSCAL repository.

This duplication is not ideal. Following the completion of usnistgov/OSCAL#1699, for example, a subsequent PR to OSCAL Pages will be filed replicating these changes.

Benefits

• Users can view historical versions of the profile resolution spec

Some nested items of the outline pages are not given enough space, causing elements to overlap.

Example link: https://pages.nist.gov/OSCAL-Reference/models/v1.1.0/system-security-plan/json-reference/#/system-security-plan/system-characteristics/security-sensitivity-level

Also visible on the page, these titles are generally too close together and feel cramped.