OSCAL
OSCAL copied to clipboard
Clarify Distinction Between OSCAL Data Types `token` and `NCName` in Website
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.
This work requires usnistgov/metaschema#191, which won't be ready until OSCAL 1.1. Moving the milestone accordingly.
This is partially addressed by PR #1161.
The documentation still needs to be updated to differentiate the syntactical differences.
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!