Why are description fields mandatory?

[mruge-shr]

Question

Description fields are validated with a min-occurs=1 for example

I feel many of the components do not need a description, for example, they are just referencing or including another document. Is there a reason or logic behind this?

Component Definition Example

  capabilities:

    - uuid: bf92dc8a-d8a9-4b85-92d6-8ce1c5e39780
      name: Overview
      description: ""
      incorporates-components:
        - component-uuid: 39c57559-3da4-4ed0-997d-c2da639fa498
          description: ""

[GaryGapinski]

That description is simultaneously required but allowed to be void was surfaced a while back. The current OSCAL v1.0.4 schema allows a void (i.e., no descendants) description.

The schema in the develop branch was changed to require non-void description but subordinate content can be void.

There are other elements which are required but can be void.

Another oddity is that description mandates structured content — a simple string of text is not allowed.

[wendellpiez]

Until we have concrete proposals for how to improve things, they are likely to go unimproved.

Regarding whether the element is optional is one discussion. Regarding its contents is (alas) another, if related.

... since noting (with @GaryGapinski) if you really hate the current usage, I'm not sure we can prevent

<description><p>&#A0;</p></description>

... whether a validator should report this as as error, being another question.

In other words, regarding these boundaries in general, while it may be evident there is discomfort with the rules given, it's hard to assess the impact of alternatives without actually looking at them.

One proposal might be to add a mandatory or optional title for a simple string or (short) description, providing an alternative to the all-or-nothing situation currently (where you either have no incorporates-component at all, or it has a meaningful description). If mandatory, such a sibling would warrant making description optional. Even if optional, such an element would relieve the need to include any ('long form') description at all (what this element, used elsewhere, is more or less for).

FWIW the main reason this element is required (historically) is a defensive rationale on the XML side (wishing to prevent elements -- in this case incorporates-component -- appearing empty 'by accident') -- which happens to provide no advantage on the JSON/object-modeling side.

Another way of putting this question is, if this element is optional, what then should indexers prefer as a navigational aid in display, to show what this thing is - what would show up in a ToC/manifest or other listing of "incorporated components"?

[aj-stein-nist]

We need to more formally answer the question:

I feel many of the components do not need a description, for example, they are just referencing or including another document. Is there a reason or logic behind this?

Today, it is required and there was a design decision, relied upon here and elsewhere, that needs to be properly documented. Given that design decision, it sounds like you are asking can we review that design decision and make description, in this location on the relevant models, completely optional (0 to unbounded, not 1 only)? If so, that is something we can consider.

[mruge-shr]

Yes, that is what i would suggest. I have a bunch of stanzas as ```yaml * title: title description: "" ``` Its not an important change, but seemed like a sign of a weird design Matthew Ruge Director of Emerging Technology SHR Consulting Group, LLC Accelerating Every Mission 8(a) | ISO 9001 | ISO 20000 | ISO 27001 | CMMI DEV/SVC ML3 www.shrgroupllc.com<https://www.shrgroupllc.com/>      [cid:5ae77c80-0ada-4d37-894b-cc2ae840ddef] This message and any attachment(s) herein, are Confidential and Proprietary to SHR Consulting Group, LLC. Contents may be privileged or otherwise protected by law. The information is solely intended for the individual or the entity it is addressed to. If you are not the intended recipient of this message, you are not authorized to read, forward, print, retain, copy, or disseminate this message or any part of it.

…

________________________________ From: A.J. Stein ***@***.***> Sent: Thursday, April 6, 2023 2:23 PM To: usnistgov/OSCAL ***@***.***> Cc: Matthew Ruge ***@***.***>; Author ***@***.***> Subject: Re: [usnistgov/OSCAL] Why are description fields mandatory? (Issue #1725) We need to more formally answer the question: I feel many of the components do not need a description, for example, they are just referencing or including another document. Is there a reason or logic behind this? Today, it is required and there was a design decision, relied upon here and elsewhere, that needs to be properly documented. Given that design decision, it sounds like you are asking can we review that design decision and make description, in this location on the relevant models, completely optional (0 to unbounded, not 1 only)? If so, that is something we can consider. — Reply to this email directly, view it on GitHub<#1725 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/A2X4ETZW3CRDP7IMODWUZJLW74CZ3ANCNFSM6AAAAAAWHAZQVI>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[GaryGapinski]

Worthy of note: subordinate description content consists of HTML-like elements. As such, those are useful solely for presentation and (the elements themselves) carry no other meaning than their HTML analogs. Content therein can only be interpreted as natural language prose.