OSCAL
OSCAL copied to clipboard
usnistgov
Add support for definition list
User Story:
As an OSCAL catalog producer, I would like guidance on how to incorporate definitions such as:
- list of acronyms / initialisms
- defined terms
An example of these is provided in the Australian ISM - see https://www.cyber.gov.au/ism/cyber-security-terminology for the section.
Goals:
As above. Acceptable implementations would be that this is just more prose which would be represented as:
<group>
<title>Glossary of abbreviations</title>
<part>
<table>
<tr>
<th>Abbreviation</th><th>Meaning</th>
<td>3DES</td><td>Triple Data Encryption Standard</td>
...
or it could be defined using <annotation> or some new structure (e.g. in metadata or back-matter)
Dependencies:
(none identified)
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.
- [ ] An example is included in the sample data set.
For mixing in with prose (i.e., mixed with paragraph/list/table structures), in principle I would be happy to see a generic def list structure, however the obvious question is, how to map it to markdown or otherwise deal with it in the context of JSON / object models. Perhaps a complete proposal would include a pretty-plain-text notation plus a survey of where Markdown(s) is/are with def lists.
However I like the idea of adapting annotation to this use. I can also imagine a simple model for a true glossary-like structure in OSCAL, which could be useful - although it could not be embedded in stretches of prose.
The poor-person's version of this is part with class and implicit constraints over the contents.
Maybe just adding support for <dl> elements in prose in XML ... which when formatted as JSON is turned into a simple Object with key value pairs, where the values are always strings?
e.g.
<part>
<dl>
<dt>ACMA</dt>
<dd>Australian Communications and Media Authority</dd>
</dl>
</part>
"part": {
"glossary": {
"ACMA": "Australian Communications and Media Authority"
}
}
https://www.markdownguide.org/extended-syntax/#definition-lists describes a markdown syntax for this, although support appears patchy.
It is not in github flavored markdown, or in commonmark.
It is in quite a lot of other formats though, survey from 2014: https://talk.commonmark.org/t/description-list/289/12?u=chrisalley
The same concept is supported in NISO: http://jats.niso.org/1.1/Pumpkin1_1/Pumpkin1_1-elem-def-list.html
@anweiss Unfortunately, there is a clean line in OSCAL between markdown-serializable 'prose' which does not map to JSON except as markdown strings, and honest OSCAL objects, which map to elements in the XML and objects in the JSON. A deflist could be either of these. We could also have both - a markdown serialization presumably with an HTML dl/dd/dt mapping, to drop into the middle of a sequence of paragraphs, and a more structured glossary object that would render as a real object in the JSON not just a hunk-o-magic-text, which you could put next to prose, but not in the midst of it.
On the other hand, today we can already make mixed sets of parts with names, props and annotations, and create the same effect with an OSCAL microformat. Although this doesn't have the benefit of everyone's knowing in advance to do it the same way, this might not be much of a problem for something really simple.
We need to be careful not to stray too far into the generic document tagset domain. We made an early decision in OSCAL to create microformats to model the semantics of assessment information, instead of creating a general purpose documentation tag set.
We could consider adding a generalized definition list in the back-matter. This would avoid complicating the prose model used in parts, remarks, etc.
Something like the following might work: https://jats.nlm.nih.gov/extensions/bits/tag-library/2.0/element/def-list.html.
Marking this for further discussion.
@david-waltermire-nist I have some ideas about this and how we might expedite this. Given our discussions I think a minimalistic but serviceable model would be fairly straightforward, and I could perhaps find some examples to work from with the help of @bradh or others.
However, I also wonder whether a def-list or other similar generalized structures (i.e. not part of semantics surrounding control-based assessment as such, but some more generalized document semantics) shouldn't go into a more open-ended appendix element that could also support other kinds of arbitrary prose, not only glossaries.
As you recall, early versions of OSCAL modeled more of the documents in which control catalogs are generally embedded; then we decided we needed a more "object-oriented" approach. However, we could probably swing the pendulum back that away a little.
In many ways, it is a question of how self-contained OSCAL documents seek to be. If they have features for this sort of general-use modeling, they have less need for attachments and other callouts to non-machine-readable resources.
To be sure, the callouts could also be to machine-readable formats for these purposes, so one (alternative) line to take is "you should be using [X] for that" where X is NISO STS, or DITA, or something else entirely. In that case, perhaps we should not model definition lists, but OSCAL's back matter and/or metadata should have even richer ways of describing a document's resource dependencies (and their dependencies, such as what flavors of formats they might happen to be).
Having OSCAL offer ways to capture this information helps more people in more ways, but is also open-ended and not trivial to operationalize (in any standard way) beyond simple display semantics. Glossaries or terms/definitions make a good boundary case for things that can definitely provide leverage in the field, but that are also difficult to generalize across use cases. Plus, slippery slope ... into territory that has already been charted (see above). Do we support figures with captions? (Answer is, yeah sure, if you're willing to use part for that if not Markdown.) Footnotes? (Well not as such, but I could show you how to fake it up.)
I'd also be grateful for other opinions on this strategic question especially @brianrufgsa and @bradh. If def-list then why not also appendix with sections, intro and the rest of it? Is there a principled or even pragmatic/utilitarian way to draw the line here? (I am not even asking about how we would specify purported linking semantics into out-of-line resources such as glossaries.)
@david-waltermire-nist if we had an example glossary I could straightforwardly show how to model a glossary using part assemblies.
{ "parts": [
{ "name": "glossary",
"title": "Glossary",
"parts": [
{
"name": "entry",
"title": "JSON",
"prose": "Javascript Object Notation..."
},
{
"name": "entry",
"title": "XML",
"prose": "eXtensible stylesheet language...."
}
]
}
] }
equivalent to
<part name="glossary">
<title>Glossary</title>
<part name="entry"><title>JSON</title>
<p>Javascript Object Notation...</p>
</part>
<part name="entry"><title>XML</title>
<p>eXtensible stylesheet language....</p>
</part>
</part>
Does this appeal as a lightweight way to meet the requirement without more extensive engineering?
This issue has received little feedback since its creation. As a result I am pushing this to OSCAL 1.2.
This issue has received little feedback since its creation. As a result I am pushing this to OSCAL 1.2.
Ironically, I was just thinking about how I need this to discover I have not been following update emails too closely and you had pushed it back ten days ago.
I have some more precise usecase needs I described in Gitter, but I guess this can wait. :-(
