OSCAL icon indicating copy to clipboard operation
OSCAL copied to clipboard

Clarify Distinction Between OSCAL Data Types `token` and `NCName` in Website

Open aj-stein-nist opened this issue 3 years ago • 3 comments

User Story:

As an OSCAL tool developer, in order to best understand the requirements and constraints for given data types in OSCAL, I would like more clarification in docs around the difference between the token and NCName data types in the OSCAL website documentation.

Goals:

It should be more clear how the datatypes work, specifically how they are different, as both data types have the exact same.

The OSCAL datatypes page is a bit outdated and needs some maintenance. The following additional work needs to be done.

  • [x] empty should be removed as a datatype.
  • [ ] NCName should be removed as a datatype.
  • [ ] Need to add any missing data types
  • [x] Sync the patterns with what is implemented in JSON and YAML. Each datatype should be clear in how the type is addressed in JSON and XML.

Background

This came up during the review of usnistgov/OSCAL#941, particularly in https://github.com/usnistgov/OSCAL/pull/941#discussion_r787164054, as it references part of the data types page and the two data types have identical information, without much clarity. This was rolled out as part of usnistgov/OSCAL#911, but the docs are still not clear around the whitespace enforcement.

Dependencies:

N/A

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.

aj-stein-nist avatar Jan 25 '22 20:01 aj-stein-nist

This work requires usnistgov/metaschema#191, which won't be ready until OSCAL 1.1. Moving the milestone accordingly.

david-waltermire avatar Mar 09 '22 17:03 david-waltermire

This is partially addressed by PR #1161.

david-waltermire avatar May 02 '22 17:05 david-waltermire

The documentation still needs to be updated to differentiate the syntactical differences.

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

This was reviewed and completed in the previous sprint, but not merged despite approval. This is a useful but low-risk documentation improvement into develop, so I am merging away and closing this issue. Thanks, Dave!

aj-stein-nist avatar Oct 04 '22 15:10 aj-stein-nist