Attach references to specific decision point selections instead of to the overall selection object?

[ahouseholder]

Extending a comment from #821. "them" is referring to the references and resources fields in the ssvc.selection.Selections object.

I'm wondering whether it would make more sense to have them attached to a single decision point (as optional element) or to both (using $ref). If I'm an analyst trying to convey, why I made a certain decision, I might want to document it completely so that I have all my notes there for the next review board. Also, that could help with the reuse of certain decisions (or their pre-computation). Thoughts?

Originally posted by @tschmidtb51 in #821 (comment)

[ahouseholder]

I am against this suggestion.

references and resources both at the Selections object level

This is the current status quo as of #821. Each list of Selections has an optional list of references and resources.

In other words, the status quo allows you to state:

resources: Here are links to resources about the decision points we're assessing

here the links could be to specific details about one specific decision point, or possibly a link to a document that outlines a larger set of decision points in a namespace.

And

references: We chose A=1 and B=3 and C=29 because [ref1, ref2,...].

where the links could be reports that imply values for A alone, A and B, or all three.

Both of these seem like reasonable things to do, so I don't see any reason to remove resources or references at the Selections level.

That leaves the question of whether or not to add them at the individual Selection level.

resources at the Selection level

A resource at a Selection level would imply that the link is specifically pertinent to the interpretation of the corresponding decision point. So it might provide additional clarity regarding what a specific resource is relevant to.
It does not, however, easily convey the "here's a link to a description of multiple decision points in a namespace" thing that is possible at the Selections level.

Unless you were to include the same link for each evaluated decision point (E.g. uri=link-to-namespace-doc, `summary="Details about the namespace") but that gets redundant quickly.

references at the Selection level.

On the other hand, our intent with Selections is that it represents a single evaluation of at least one, but potentially multiple decision points at a single point in time by a single entity. Therefore, I think we would expect the evidence for why the selections that are being asserted were made (which is what we intend references to reflect) to be uniform across the selections.

Now that doesn't preclude wanting to express:

We chose A=1 because ref1 and we chose B=3 and C=29 because ref2.

But you couldn't express that mechanistically unless you actually moved references to the Selection level as in:

We chose A=1 because ref1 and we chose B=3 because ref2 and C=29 because ref2

This also seems like it gets redundant quickly when you're potentially asserting a lot of facts (decision point selections) based on a small number of references.

In the extreme, one might even argue that we should consider

references at the Value level

Attaching a reference at the value level would further allow you to be really specific, as in:

We chose A=1 because ref1, and (also) could not rule out A=2 because ref2

This starts to feel like "Well, yes, you could have references at the Selections, Selection, and Value level."

But should we?

Explaining all this in documentation and expecting users to get it right seems more than we could reasonably expect. More likely, in my opinion, would be that you'd end up with references scattered across all three levels, and not really be able to unabmbigiuously interpret whether they actually intended to convey semantic information by including them at one level instead of another, or if they misunderstood the intended usage.

Having the resources and references all at the top (Selections) level avoids any information implied by structure, and leaves it open for the content producer to add an explanatory summary value to explain what the reference or resource link is relevant to. This seems to be the simplest solution, so I'm in favor of invoking YAGNI and avoiding adding references or resources at either the individual Selection or Value level until we have a stronger use case for them.

[j---]

In other words, the status quo allows you to state:

resources: Here are links to resources about the decision points we're assessing

here the links could be to specific details about one specific decision point, or possibly a link to a document that outlines a larger set of decision points in a namespace.
And

references: We chose A=1 and B=3 and C=29 because [ref1, ref2,...].

I agree with the intention to separate resources about how a decisions should / could be made with specific references to how a specific decision was made about a specific case.

If we want that to be clear, how do we make the data structures reinforce the intention? I might imagine that what we are calling resources actually only has a place in documentation about the decision point or table, and references is the only thing that is documenting selections. If we don't want to rely on the distinction between resources and references to carry meaning, then they probably shouldn't be able to appear in the same part of the data structure. Am I understanding the problem correctly?

[tschmidtb51]

@ahouseholder I understand you conclusion. I though that decision_point_resource at selection item level would point directly to the description of this specific decision point (not the overall specification. References at selection item level would point directly to the line(s) of code / paragraph of text that lead the analyst to the conclusion. I understand that might be confusion and agree to table it until there is a strong desire / wish for it.