Clarification about Map ordering

[xoofx]

The spec should probably clarify the order of the map so that it doesn't rely on e.g. implementation dependent order. I would expect that the order is following the order of declaration (not the alphabetical order) to allow precise control of how things should be displayed (e.g. for help) or processed (e.g. for arguments in specific order)

But things could be declared differently as well with the List<SpecItem> where we can have different aspects declared in order with subclassing of SpecItem for the different element type (command, inline text in help, options...etc.). But will create a separate discussion for this.

[patriksvensson]

@xoofx I'm not sure that I understand completely. Do you mean that the specification should clarify that it's the order in the OpenCLI Description that is normative?

Looking forward to reading about your second thought as well 👍

[xoofx]

Do you mean that the specification should clarify that it's the order in the OpenCLI Description that is normative?

Yes. If Map is used (instead of what I will propose separately), then it would be preferrable if Map implies that the order declared in the spec file of items in the map is preserved.

[baronfel]

We had similar issues in the dotnet CLI with our JSON output format - we either needed to note the integer ordering on the Argument (not option) entries, or we needed to change the declaration of the arguments to be an array and use the implicit ordering there.

[patriksvensson]

@justenwalker wrote in #22

An alternative idea to #10

In some languages, map ordering is not preserved, and will make tooling more difficult and error prone to construct.
In Go for example, map[string]Type traversal order is randomized. Also, the encoding
specification for JSON doesn't guarantee that object keys are ordered

An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array.

Given this, my expectation when using Maps is that order doesn't matter: they are a lookup table

So, if you want things to be well-ordered, then use a data structure where order is guaranteed: namely a List/Array.

Prior Art: This is something that the Kuberentes project encourage when designing resources:

❌ BAD

env:
ENV_NAME: ENV_VALUE

✅ GOOD

env:

• name: ENV_NAME
  value: ENV_VALUE

@baronfel Wrote in #22

And alternative to this (and what the dotnet CLI has implemented for our home-grown version of OpenCLI that we'd like to migrate) is keeping a map and adding an explicit property for the order of the argument. Either approach works, I'm mostly +1'ing that keeping ordering information is essential.

[patriksvensson]

Ordering seems to be important, so I've moved your comments over from #22 to this discussion to keep everything in one place.

The only problem I see with order as a property is that it would need to be required. Perhaps having an Array of items, where the order is normative, is the way to go?

[justenwalker]

The only problem I see with order as a property is that it would need to be required. Perhaps having an Array of items, where the order is normative, is the way to go?

If you make order a required field, you can still have an ambiguous ordering:

mapping:
  aaaa:
   order: 1
  cccc:
   order: 1
  bbbb:
   order: 1

And if you fall back to the order it was defined in the serialized form; then we are still in trouble since you need to care about insert order again anyway.

With an Array of items; the order is explicit and unambiguous always.

[patriksvensson]

Yes, but that would make it an invalid OpenCLI Description.

[patriksvensson]

I want to rethink this a little bit.

The only thing where ordering is essential would be for arguments, and they already have an ordinal parameter which describes the argument order in relation to other arguments. I want this to become a required parameter to make it explicit.

For what use cases is order important, except for arguments?

[patriksvensson]

Another thought:

I don't think we should conflate the specification with implementation details of a specific ecosystem. If a Map[string]Foo in Go, or a Dictionary<string, Foo> in C# iterates in a specific way, that should not influence the specification.

It's up to the different implementations to make sure that they use a data structure that is compatible with the specification, not the other way around.

[xoofx]

For what use cases is order important, except for arguments?

It depends what you want to achieve with such specs. If it is just for interoperability, then they are not necessary.

If you want to extend the usage of the specs for covering e.g.:

• Producing a textual help format based on the specs (but lighter, exactly how the tool itself would generate through --help)
• Using the specs to generate most of the skeleton of the implementation code, leaving the binding part to be user implemented.

Then Map is not capable of expressing such details and it would require a solution like described in #17

[justenwalker]

Discounting any language-specific issues with Map ordering.

The representation of the spec will be written in JSON or YAML presumably; where both of them indicate that objects are an un-ordered collection of keys:

• In JSON RFC-7159, the specification explicitly says objects are unordered:

  An object is an unordered collection of zero or more name/value pairs...

• The YAML Specification additionally says map keys are unordered:

  In the representation model, mapping keys do not have an order. ... In every case where node order is significant, a sequence must be used.

So, regardless of language, the library used to parse JSON or YAML would have to do some spec-incompatible parsing in order to preserve this ordering.

Adding the ordinal parameter to each value "fixes" this, but makes reading and editing the spec more surprising.

Consider:

arguments:
  "COMMAND":
    ordinal: 2
  "FILENAME":
    ordinal: 1

reading the spec; my eyes see COMMAND comes before FILENAME, and thus is my expectation.
However, since the first argument says its ordinal 2 and the second is ordinal 1; they are actually ordered wrong in the spec.
Its pretty easy to tell this is wrong in the toy example; but imagine several arguments with a large list of properties where some of them scroll off the page -- at a glance it would be difficult to notice the order in the file doesn't match the ordinal number given. I think any human editing the spec could get into this situation unknowingly if they are cutting/pasting arguments around and forgetting to update the ordinal.

Perhaps tooling like linting/formatting can help re-order these maps w/ ordinals.

But you could do

arguments:
  - name: COMMAND
  - name: FILENAME

and now the representation matches your spec without the added baggage.

[patriksvensson]

Ok, my suggestion is that we change the Map<T> to a [T], and specify in the documentation that ordering is normative to the order of declaration. Does that sound OK?

@xoofx @baronfel @justenwalker

[baronfel]

Great by me!

[patriksvensson]

Created issue: #27

[patriksvensson]

Added in #29