search

FLOIP / flow-spec

7 stars 6 forks source link

Do not use JSON objects for Block configs that should have a stable key order #60

Closed smn closed 2 years ago

smn commented 2 years ago

The SelectOneResponse block definition states that the config should have a choices key with a mapping of tags to localized names for choices. The implementation uses a JSON object for the mapping. This is problematic because the JSON specification states that An object is an unordered set of name/value pairs.

Some languages may load these keys in the order that they're defined but that should be seen as a unintended side effect.

The language we're using translates JSON objects to Map structures of which the key order is non-deterministic. The unintended side effect of this is that when we're surfacing a SelectOneResponse as a multiple choice menu, the order of the choices is different from what the floip specification suggests.

Is there appetite to change the choices config to a list of objects with predictable keys or a list of tuples?

The current example from the documentation is

{
 ...
 "config": {
    "prompt": "42095857-6782-425d-809b-4226c4d53d4d",
    "choices": {
      "chocolate": "66623eff-fd17-4996-8edd-e41be3804bc8",
      "vanilla": "b0f6d3ec-b9ec-4761-b280-6777d965deab",
      "strawberry": "b75fa302-8ff7-4f49-bf26-8f915e807222"
    }
 }

My suggestion would be to either go with a list of objects:

{
 ...
 "config": {
    "prompt": "42095857-6782-425d-809b-4226c4d53d4d",
    "choices": [
      {"tag": "chocolate", "resource": "66623eff-fd17-4996-8edd-e41be3804bc8"},
      {"tag": "vanilla", "resource": "b0f6d3ec-b9ec-4761-b280-6777d965deab"},
      {"tag": "strawberry", "resource": "b75fa302-8ff7-4f49-bf26-8f915e807222"}
    ]
 }

Or a list of tuples:

{
 ...
 "config": {
    "prompt": "42095857-6782-425d-809b-4226c4d53d4d",
    "choices": [
      ["chocolate", "66623eff-fd17-4996-8edd-e41be3804bc8"],
      ["vanilla", "b0f6d3ec-b9ec-4761-b280-6777d965deab"],
      ["strawberry", "b75fa302-8ff7-4f49-bf26-8f915e807222"]
    ]
 }

There may be other areas where the spec is implicitly assuming that the order of keys in JSON Objects is stable.

markboots commented 2 years ago

Hi @smn , definitely agreed. Check out version 1.0.0-rc3 of the specification: https://floip.gitbook.io/flow-specification/v/drafts%2F1.0.0-rc3/layers/blocks-2#select-one-response-multiple-choice-question-block

Version rc3 changes choices to an array of choice objects, with properties name, prompt, and test. It also has much better support for mapping raw responses from end-users to choice selections, via the test property.

For your current work, are you following 1.0.0-rc3? The changelog is here, and there are some important sanity upgrades in it.

smn commented 2 years ago

Thank you! Will follow rc3 for this, thanks!