results_group naming syntax

[adamb-kpmg]

{Please enter your question.}
Is it intentional that assessment-results/results_group:

1. has an underscore in the name instead of the dash
2. is called results_group instead of results?

If not, I propose that this be named results to be consistent with the other names in this structure (e.g., "findings" is a group of "finding" objects). Also propose reviewing naming syntax for collections throughout the schema to align the naming.

[brian-ruf]

@adamb-kpmg while the name can't be identical, it certainly doesn't have to be an underscore. In fact, I believe I intended a dash and the underscore is a typo. It's an easy fix, which I'll make when I address a few related items in the very near future.

I'll have to defer to @david-waltermire-nist and/or @wendellpiez as to the explanation of why the name can't be identical. I know it's a JSON-only issue and doesn't apply to XML.
Normally we just convert a singular to a plural, but that doesn't work with "results", which is why "group" is appended.

Count on it being changed to "results-group"

[wendellpiez]

In this particular case I wonder if we could have result as the singular name and results the grouping name. This is really a semantic question about the data, not a consequence of our working rule to keep singular and plural names distinct. (@brianrufgsa ?)

[brian-ruf]

@wendellpiez I suppose we could if we accepted that a single "result" could have many observations and/or risks.

I also see risk if we change "results" to "result", then change "results_group" to "results" because for people who have already implemented, we aren't eliminating "results" we are re-purposing it. So I'd rather change "results_group" to "results-group", but am open to feedback as to whether this concern is unfounded.

[wendellpiez]

Indeed - after hitting "Comment" yesterday I think I remembered this was at issue. I also think "results" and "result" look very similar, whereas the ideal or perfect grouping name looks enough like the singular name for the relation to be clear, but not so similar that it is confusing. E.g. "properties" as grouping name for "prop". Of the options we have considered so far, I think "results-group" passes this test the best.

[adamb-kpmg]

Sorry if I missed the logic…but are we doing this across the board, so a plural will be the singular + “group”? So objectives turns into objectives-group, assets becomes asset-group, test-methods becomes test-methods-group, etc? My 2 cents is objectives, assets, etc. looks better, and this should be results. Adam From: Wendell Piez <notifications@github.com> Sent: Tuesday, September 29, 2020 7:09 AM To: usnistgov/OSCAL <OSCAL@noreply.github.com> Cc: Brand, Adam <adambrand@KPMG.com>; Mention <mention@noreply.github.com> Subject: [EXTERNAL] Re: [usnistgov/OSCAL] results_group naming syntax (#717) Indeed - after hitting "Comment" yesterday I think I remembered this was at issue. I also think "results" and "result" look very similar, whereas the ideal or perfect grouping name looks enough like the singular name for the relation to be clear, but not so similar that it is confusing. E.g. "properties" as grouping name for "prop". Of the options we have considered so far, I think "results-group" passes this test the best. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#717 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AQJXJ65NQ343TXDLLFWEC23SIHS6TANCNFSM4POHJ5TQ>.

…

________________________________ CAUTION: This email originated from outside KPMG. Do not click links, open attachments or forward unless you recognize the sender, the sender’s email domain and you know the content is safe. Forward suspicious emails as an attachment to US-KPMG SPAM Collection Mailbox (spam@KPMG.com<mailto:spam@KPMG.com>). ********************************************************************** The information in this email is confidential and may be legally privileged. It is intended solely for the addressee. Access to this email by anyone else is unauthorized. If you are not the intended recipient, any disclosure, copying, distribution or any action taken or omitted to be taken in reliance on it, is prohibited and may be unlawful. When addressed to our clients any opinions or advice contained in this email are subject to the terms and conditions expressed in the governing KPMG client engagement letter. ***********************************************************************

[brian-ruf]

@adamb-kpmg we are only discussing this change relative to results/results_group, and the standard has been simply the singular/plural (objective/objectives, asset/assets, etc.)

I'm sold. The change will be result/results instead of results/results_group unless someone raises a good reason to do otherwise before I get to the change.

I have a few other syntax tweaks to make and intend to batch them together, as soon as I get a few other work items addressed.

[wendellpiez]

@brianrufgsa I think we can explain in docs that "result" can include multiple findings (observation|risk or as the case may be). This is also evident from their cardinality, but we can spell it out that this is a wrapper for the outcome of an assessment.

As you have also pointed out, there may be house rules governing whether and how risks (and observations) can be grouped. Calling the grouping a single "result" (which enables consolidating all the features common to a group of risks, say) may actually help with that.