Closed TallTed closed 3 years ago
This would not be necessary if all the current links to
"INFRA#ordered-set"
instead went to our own discussion thereof, with the "order doesn't matter" declaration, and then linked out to the INFRA spec.
I would certainly prefer this than adding that extra note everywhere in the document (which would make reading fairly difficult).
I am not convinced it is necessary, though.
which both loudly hint that order is important for interop.
Hmm, depends on the sort of interop you're talking about... and that text is really speaking to "code running on different browsers when iterating over an Object over the years have tried to make sure they preserve insertion order"... which is very different than "ordering of the information model" (e.g., RDF Dataset Canonicalization).
I don't think we need to loudly declare this in the specification more than once. We should loudly declare it once, though. We're just saying -- you can't depend on order, so unless you have some ordering mechanism that you're sure works (like RDF Dataset Normalization)... don't assume that order is preserved.
I want to make a small to the text within that box ... but it's further away from the single-word change you made than github will allow me to make a suggestion on.
I'd change --
<p class="note" title="Ordering of values">
As a result of the <a href="#data-model">data model</a> being defined using
terminology from [[INFRA]], property values which can contain more than one
item, such as <a data-cite="INFRA#ordered-map">maps</a> and
<a data-cite="INFRA#ordered-set">sets</a>, are explicitly ordered. For the
purposes of this specification, unless otherwise stated, ordering is not
important and implementations are not expected to produce or consume
deterministically ordered values.
</p>
-- to --
<p class="advisement" title="Ordering of values">
As a result of the <a href="#data-model">data model</a> being defined using
terminology from [[INFRA]], property values which can contain more than one
item, such as <a data-cite="INFRA#ordered-map">maps</a> and
<a data-cite="INFRA#ordered-set">sets</a>, are explicitly ordered. (All
list-like value structures in [[INFRA]] are ordered, whether or not that
order is significant.) For the
purposes of this specification, unless otherwise stated, ordering is not
important and implementations are not expected to produce or consume
deterministically ordered values.
</p>
To be clear, I've added (All list-like value structures in [[INFRA]] are ordered, whether or not that order is significant.)
And I still think that all the links to "INFRA#ordered-set"
within the document should be changed to an internal description that includes something like "The order of values in this list-like structure isn't significant, even though INFRA says it is" before the reader gets to the INFRA site.
@msporny noted in #665 --
in reply to @TallTed:
And I still think that all the links to "INFRA#ordered-set" within the document should be changed to an internal description that includes something like "The order of values in this list-like structure isn't significant, even though INFRA says it is" before the reader gets to the INFRA site.
Will contemplate how to do this cleanly... you may want to raise an issue for it so we don't forget, @TallTed.
This (#656) remains that issue.
To be clear, I've added (All list-like value structures in [[INFRA]] are ordered, whether or not that order is significant.)
This was added to the spec a bit ago... forget which PR, but it's in there now along with more changes, to drive your point home @TallTed, in 218f6ffd8fe3e09fd5ba698552c629165a4e31d8. I also changed "ordered set" -> "set" to not convey that order is important for sets and cross-checked the entire specification to make sure we don't depend on set ordering anywhere (we don't).
I'm hesitant to belabor the point more in the spec. I'm marking this pending close, folks that don't feel like we have closure on this yet, feel free to object to closing.
I'll hope the sum of changes to date is sufficient. We'll find out!
I'm OK with closing this one.
I do not think the single note
<p class="note" title="Ordering of values">
about this is sufficient.I think adding such an inline declaration every time is important, because the INFRA doc to which every instance of "ordered set" links includes notes of --
-- and --
-- which both loudly hint that order is important for interop.
Could be as simple as adding
(although the order of elements is unimportant within DID Core, DID methods are free to specify an ordering algorithm that must be used for interop within that DID method)
or similar to allproperty MUST be ... an <a data-cite="INFRA#ordered-set">ordered set</a> ...
statements.This would not be necessary if all the current links to
"INFRA#ordered-set"
instead went to our own discussion thereof, with the "order doesn't matter" declaration, and then linked out to the INFRA spec.