Determine the possible values for a field

[robertovelasco]

There are some features missing from Hal-forms specification to be a complete hypermedia format.
One is to be able to determine the possible values for a field, for example, a select field with some options.

As pointed in the HAL mail list, there are three cases to support
(https://groups.google.com/d/msg/hal-discuss/bBi-i4FMdxk/8pzDwJFmAgAJ):

1. Supplying the possible values directly
2. Pointing to a data list in the same resource. For us, using _embedeed for this makes a lot of sense.
3. Provide a Url of another service that serves the list of options.

This metadata will be added per property in a new 'suggest' element.

Some samples of each case:

Supplying the possible values directly:

{"name":"priority", "value":"low", "prompt":"Priority", 
    "suggest": [
            {"value":"low", "prompt":"Low"}, 
            {"value":"med", "prompt":"Medium"}, 
            {"value":"high","prompt":"High"}
        ]
    }
}

Pointing to a data list in the same resource.

{"name":"priority", "value":"low", "prompt":"Priority", 
    "suggest": {
        “embedded” : "priorities",
        "prompt-field":"desc",
        "value-field":"id"
    }
}

And in the same resource:

"_embedded": {
    "priorities": [
      {"id":"low", "desc":"Low", "longdesc": "Low priority..."}, 
      {"id":"med", "desc":"Medium", "longdesc": "Medium priority..."}, 
      {"id":"high", "desc":"High", "longdesc": "High priority..."}
    ]
}

Provide a Url

{"name":"priority", "value":"low", "prompt":"Priority", 
    "suggest": {
        "href" : “http://api.example.org/priorities”,
        "prompt-field":"desc",
        "value-field":"id"
    }
}

And the response of the “http://api.example.org/priorities” call:

[
    {"id":"low", "desc":"Low", "longdesc": "Low priority..."}, 
    {"id":"med", "desc":"Medium", "longdesc": "Medium priority..."}, 
    {"id":"high", "desc":"High", "longdesc": "High priority..."}
]

In addition I think that the name of the "suggest" property is not very understandable. Maybe "options" name inspired in HTML could be easier to understand from my point of view.

[mamund]

@robertovelasco

looks pretty good. FWIW, i implemented this pattern for Cj recently (not yet published) and used almost identical elements (didn't use "embedded" property, but that's a minor thing).

suggest
also, not to "bikeshed" this, but since options has a specific meaning in HTML (different than select and checkbox, radio), I'd like to stick with a non-HTML identifier (suggest) that could be used to visually render varying UI elements (checkbox, select, multi-select, radio, etc).

render
one possibility to consider is to add support for a render property to give human-facing apps hints on how to render the content. example values for this property might be: select, multiSelect, radio, suggest (e.g. google-style key-stroke search). i'll point out the checkbox might be problematic (does unchecked represent a value to send?).

optional
another issue will be whether support for the suggest element will be REQUIRED or OPTIONAL for anyone implementing HAL-FORMS. i think it should be OPTIONAL. we can discuss.

these are my first comments. feel free to add/discuss here and/or on the HAL list.

[robertovelasco]

Thanks @mamund for the quick response.

suggest
I agree it is good to have an HTML independent name. suggest works quite well.

render
I think we can leave render details in UI developer's hands.

optional
suggest will be an OPTIONAL element, only some fields can determine possible values, for example select but other elements like text or textarea can't do it.

[mamund]

@robertovelasco

all cool with the above.

also, what i meant w/ saying that suggest is an optional element is that a HAL-FORMS processor (library, framework, etc.) would not be REQUIRED to support the suggest element and would still be Conditionally Compliant with the spec. These HAL-FORMS libraries would just ignore the suggest element.

[nickshanks]

suggest implies to me a "combo box" input. constrain might be better for a stricter input set (like HTML's SELECT)

[mamund]

@nickshanks

Note that the current implementation includes support for a google-style "type-ahead" UX.

From the human UI POV, the name/value pairs could be rendered as an HTML INPUT with type-ahead support (via javascript), HTML SELECT(including multi-select), RADIO, or CHECKBOX elements. The current version doesn't support servers sending hints to the client to TELL them how to render the metadata, tho.

Of course, this extension also works well for machine interfaces where the HTML-style rendering is not needed.

[anderruiz]

@mamund If we agree on this, would you mind including it as part of the specification?

[mamund]

not sure i see anything changed to the HAL-FORMS spec.

am i missing something?

[anderruiz]

In the spec when a form field is described, this is the text:

property
A JSON object that describes a state transition parameter. A property object has the following elements:
name : The parameter name. This is a valid JSON string. This is a REQUIRED element. If this attribute is missing or set to empty, the client SHOULD ignore this property object completely.

prompt: The human-readable prompt for the parameter. This is a valid JSON string. This is an OPTIONAL element. If this element is missing, clients MAY act as if the prompt value is set to the value in the name attribute.

readOnly: Indicates whether the parameter is read-only. This is a valid JSON boolean. This is an OPTIONAL element. If this element is missing, empty, or set to an unrecognized value, it SHOULD be treated as if the value of readOnly is set to ‘false’.

regex: A regular expression string to be applied to the value of the parameter. Rules for valid values are the same as the HTML5 pattern attribute. This is an OPTIONAL element. If this attribute missing, is set to empty, or is unparseable , it SHOULD be ignored.

required: Indicates whether the parameter is required. This is a valid JSON boolean. This is an OPTIONAL element. If this attribute is missing, set to blank or contains an unrecognized value, it SHOULD be treated as if the value of required is set to ‘false’.

templated : Indicate whether the value element contains a URITemplate string for the client to resolve. This is a valid JSON boolean. This is an OPTIONAL element. If this element is missing, set to empty, or contains unrecognized content, it SHOULD be treated as if the value of templated is set to ‘false’.

value: The parameter value. This is a valid JSON string. This string MAY contain a URITtemplate (see templated for details). This is an OPTIONAL element. If it does not exist, clients SHOULD act as if the value property is set to an empty string.

Isn't "Suggest" supposed to be there with some examples of its use?

[mamund]

suggest ah, yes!

sorry, we've spent so much time on other things!
yes, i'll add the suggest material as an OPTIONAL property.

i'll complete it this week.

[dschulten]

In the case of Pointing to a data list in the same resource the suggest object has an embedded attribute containing a rel string:

{"name":"priority", "value":"low", "prompt":"Priority", 
    "suggest": {
        “embedded” : "priorities",      <-- rel 'priorities'
        "prompt-field":"desc",
        "value-field":"id"
    }
}

this rel priorities points to a rel in an _embedded object:

"_embedded": {
    "priorities": [         <-- rel pointed to from $..suggest.embedded
      {"id":"low", "desc":"Low", "longdesc": "Low priority..."}, 
      {"id":"med", "desc":"Medium", "longdesc": "Medium priority..."}, 
      {"id":"high", "desc":"High", "longdesc": "High priority..."}
    ]
}

In the HAL google group posting, that corresponds to the second case where the descriptor

is pointing to a local (in the response) data list and identifying fields/properties of that list to use for text/value

Do I understand correctly that the local data list is in the HAL response, not the hal-forms document?

@mamund is there any chance to have an early look at the spec changes for suggest, even if it is just a branch of the hal-forms spec?

[anderruiz]

@dschulten Answering your previous question, I believe that the Suggest embedded field should be inside the HAL-FORMS document, it makes sense because the details may only be known at that moment, and it may be different for different resources for example. Moreover it will make it more complex for the client to process it if it has to maintain the HAL response to process HAL-FORMS later (just in case it appears in the Suggest fields)

[anderruiz]

@mamund We are testing different situations with Suggest and I discovered one situation that we are not covering right know, and it is the multiple values case. At some point in your discussion you suggested the use of a RENDER field, that could be an option, but I'm more in favor of including a new field like "multi=true" while defining the property.

Should we create a new issue for that?

[mamund]

Yes, add an issue. Good idea.
On May 26, 2016 01:45, "Joseba Ander Ruiz Ayesta" [email protected]
wrote:

@mamund https://github.com/mamund We are testing different situations
with Suggest and I discovered one situation that we are not covering right
know, and it is the multiple values case. At some point in your discussion
you suggested the use of a RENDER field, that could be an option, but I'm
more in favor of including a new field like "multi=true" while defining the
property.

Should we create a new issue for that?

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#9 (comment)

[anderruiz]

@mamund Did you have a chance to post the SPEC changes for Suggests?

[dschulten]

For the remote autosearch feature it probably makes sense to send values entered by the user. The href in that case could be a UriTemplate,:

{"name":"priority", "value":"low", "prompt":"Priority", 
    "suggest": {
        "href" : “http://api.example.org/priorities{?search}”,
        "prompt-field":"desc",
        "value-field":"id"
    }
}

The server could also construct a UriTemplate like this:

"href" : “http://api.example.org/priorities?priority={search}”,

How does the client know where to get the value of search? Should there be a special token in the spec, similar to the {rel} token defined by hal, which by definition takes the value entered into the autosearch field by the user and may be used for a "contains" like search by the server?

[anderruiz]

Good catch @dschulten !!

Currently we are using this for the search value:

"href": "http://localhost:9000/hdiv-ee-bank-services/api/alerts{?filter}"

The original post from @robertovelasco was an initial approach but as we implemented it we realized that it MUST be an UriTemplate to be usable. @mamund I forgot to mention that also on the Pull Request, would you mind including it or do you prefer me to do it?

Related with the {search} (or {filter}) definition, in our example we use it as a "contains" filter, however I believe this is an implementation matter that should not be part of the SPEC anyway.

Trying to answer your question about how the client knows the values in the server, in my opinion there are two approaches, leave it as it is, and assume that it is an implementation detail out of the SPEC, the other option could be to include a valid REL instead of the href

Links

"self": {
"href": "http://localhost:9000/hdiv-ee-bank-services/api/doc?rel=modify"
},
"halform:search": {
"href": "http://localhost:9000/hdiv-ee-bank-services/api/filter{?search}"
"templated": true
}

Property

"name": "subType",
"suggest": {
"link": "halforms:search",
"prompt-field": "text",
"value-field": "value"
}

I believe it is overcomplicated but it may work.

[anderruiz]

@mamund we have been discussing this matter with @olivergierke for the implementation of HAL-FORMS that we are trying to include in Spring HATEOAS. He cleverly pointed out the fact that a small change could make the specification even easier to understand. The idea is to replace the old suggested approach for supplying the value directly, instead of using:

"suggest": [
        {"value":"low", "prompt":"Low"}, 
        {"value":"med", "prompt":"Medium"}, 
        {"value":"high","prompt":"High"}
    ]

Replace it with:

"suggest" : {
    "values" : [ { firstname: "Oliver", id : 5 }, { firstname : "Ander", id : 6 } ]
    "prompt-field" : "firstname",
    "value-field" : "id"
}

With this change all the three suggest have the same structure (prompt-field + value-field + (values/embedded/href)

I will update the PR accordingly

[anderruiz]

I've just updated the PR

[osvaldopina]

What do you think about using jsonpath expressions in promp-field and value-field? I think that specially in the case of href it would be easier to work with documents that does not follow a predefined structure.

[odrotbohm]

What we thought about was allowing simple field references and optionally supporting JSON Path expressions in case the field value starts with a $.

[anderruiz]

If @mamund agrees we can include that in the PR also

[spaceone]

Maybe choices is a more appropriate name than suggest?

[odrotbohm]

Is there anything we (I) can do to help this move forward? I've added support for the latest additions in HAL FORMS to Spring HATEOAS and this here would be the last puzzle piece to move forward with HAL FORMS support in Spring Data REST. The latter is all about exposing default representations for a model connected by hypermedia elements and the suggest/choice feature would be crucial to edit relationships between representations, esp. the flavor using a URI to point to a resource that'd produce the available relationship targets.

Except the naming discussion, is there anything obvious that problematic with what Ander and me came up with here? If not, I could prepare a PR to suggest (haha!) some wording for the actual spec. Of course still to be reviewed and debated. I just don't want to start spending time on stuff you think is unlikely to ever make it.

To summarize (and slightly extend). What's suggested is:

"suggest" : {
    "values" : [
       { 
         "firstname" : "…", 
         "someId" : "…", 
         "_links" : { "self" : "…" }
       }, { 
         "firstname" : "…",
         "someId" : "…",
         "_links" : { "self" : "…" }
       } ],
    "prompt-field" : "firstname",
    "value-field" : "someId"
}

• suggest (name tbd) – a new property attribute to express that the value to be submitted for that field is supposed to be from a given superset of possible values.
• It contains one of values, embedded or href nested fields:
  • values – the values to select from explicitly.
  • embedded – the property or JSON Path expression pointing to a field in the current document
  • href – a templated URI providing the values to select from using an explicit call. The template can be expanded with the user input to limit the results returned.
• It contains a prompt-field that provides a field name or JSON Path expression to extract the value to be used as prompt from the source value, if that is an object. If not, the value itself is to be used.
• It contains a value-field that provides a field name or JSON Path expression to extract the value to be submitted from the source value, if that is an object. If not set it defaults to the self link of the values or the value itself in case it are scalar values.

Open questions:

• Template variables in the href attribute – should we define an explicit name (_q?) to be used for the input to allow additional template variables populated with values of properties of the original document? Or do we want to assume a single template variable only for now? Do we want to allow untemplated hrefs? Maybe href should rather be resource and a HAL link object?
• Cardinality – HAL FORMS currently doesn't allow specifying multiplicity of a field, i.e. e.g. an array of Strings is not supported. Does it make sense to do so? I guess that'd be another ticket?

Anything else I am missing?

[mamund]

all:

i finally merged the working document on options into the mainline HAL-FORMS spec. here are the results:

• latest: http://rwcbook.github.io/hal-forms/
• diff: 456063a...5b9c0f5

this may need some grammatical clean-up. and maybe i've missed a few corner cases we discussed here.

please check it out and let me know what you think.

hoping to get this finalized this week so we can give devs a chance to work with it a bit.

thanks to all for the contributions.

cheers.

[evert]

Great work! Thank you!

Currently implementing. If any issues come up, I'm going to start opening individual tickets for them so it's a bit easier to track and/or dismiss issues.

This is the typescript type I'm shipping with ketting:

https://github.com/evert/hal-types/blob/master/src/hal-forms.ts

It has some tweaks from the previous version, but is more accurate.

[mamund]

@evert:

looking good!

and, yes, open separate tickets as this thread is really unwielding now.

(i'll hold onto it until the final commit to spec, tho.)

[odrotbohm]

Some feedback from the work on support for this in Spring HATEOAS:

1. selectedValues implies ties to a resource in a given state ("The order currently has this shipment method selected") while everything else in the form is rather static information corresponding to the general structure of the representation. Does it make sense to slightly redefine the semantics of a missing selectedValues to encourage clients to match the surrounding document's attribute equal to the property to decide about the selection status? I.e. given a document like this:

   {
     "shipmentMethod" : "FedEx",
     …,
     "_templates" : {
       …,
       "properties" : [
         { "name" : "shipmentMethod", "options" : { "inline" : [ "FedEx", "DHL" ], … }, … }
       ]
     }
   }

   It would be nice if we encouraged clients to consider FedEx to be used as selected value as that would allow us to reuse the templates independent of the state of the resource which greatly improves cachability. If we insist on the selected values to be described explicitly, we effectively tie the form to resource state.

2. The spec currently doesn't speak about the template expansion for remote options. IIRC @evert asked about some guidelines here as well. I wonder if it makes sense to indicate that template variable names matching the property name mean that clients are encouraged to expand the template using the current form values. I.e., in the example above, if the options were using a link attribute instead of inline and the template containing a variable named shipmentMethod, clients are encouraged to issue the request expanding the template with the current value of the form field rendered for that property.

   {
     "_templates" : {
       …,
       "properties" : [ { 
         "name" : "shipmentMethod", 
         "options" : { 
           "link" : {
             "href" : "…{?shipmentMethod}",
             "templated" : true
           }, 
         }, 
       }]
     }
   }

3. Final, stylistic question: to me, link feels a bit weird, as I've always thought of a link as URI (tempalte) + link relation. We don't deal with link relations here. I thought that inline pairs up nicely with remote instead?

[mamund]

@odrotbohm

1. It would be nice if we encouraged clients to consider FedEx to be used as selected value as that would allow us to reuse the templates independent of the state of the resource which greatly improves cachability.

yes, there is nothing in the current spec that addresses how to "pre-populate" HAL-FORMS properties. the wording selectedValues exists to solve the problem of supporting a "selected" state for lists of possible data. i'm open to creating wording that continues to give people freedom (and guidance) on using existing property.value content when rendering forms.

2. I wonder if it makes sense to indicate that template variable names matching the property name mean that clients are encouraged to expand the template using the current form values.

yes, i can see that this would be desireable. AFAICT, both (1) and (2) are about optimizing the programmer's ability to relate resource-state, form-state, list-state in various ways. this can be tricky and i'll work on text for it. might end up as a general guidance note in the spec to cover both (1) and (2) here.

3. I thought that inline pairs up nicely with remote instead

naming & reuse is always a challenge. i'm not going to fight much on what this element is named as long as it doesn't confuse existing implementations or overly constrain future mods. link, remote, external, resource, etc. are all good enough for me. at this point i need some shared consensus (or at least i need to see some clear objections).

[evert]

Regarding: 2: Also feel the same as @odrotbohm . Having a clearer idea of what the actual use-case here is helpful. In my implementation I'm currently not implementing it, but expanding the templated URI with current form values does sound really cool tbh.

Regarding 3: Internally I've also chosen not to call it link. These are the 3 variation the ketting version will have:

1. options - inline
2. dataSource - link
3. linkSource - Not currently supported in HAL forms but see Ability to use links as the source for 'options' #74 if I can convince @mamund .

I'm trying to pick names for these features that I feel are the 'best general names' for this, and most likely to be applicable in other formats, so I'm diverging internally a lot though. (actions vs forms, fields vs properties, etc)

link feels like a bad name for me, because to me if there's no link relationship, it's not a weblink.

[mamund]

@evert

all good feedback. what i suspect is coming is a kind of "common practices" document of how people are using HAL-FORMS. i don't think we can bake too much implementation detail into the spec but we can definitely make sure we support as wide a set of use cases and implemementation patterns as is practical.

the more we share how we're using HAL-FORMS, the better the spec can become -- even if the specifics of implementation are not reflected in the spec directly.

[toedter]

I started implementing this in HAL Explorer. During implementation, I was wondering what the difference is between value and options.selectedValues. E.g. what would be the meaning of the following JSON?:

{
  "_templates" : {
    "default" : {
      ...
      "properties" : [
        {
          "name" : "shipping",
          "prompt" : "Select Shipping Method",
          "value": "UPS",
          "options" : {
            "selectedValues" : ["FedEx"],
            "inline" : ["FedEx","UPS","DHL"]
          }
        }
      ]
    }
  }

[mamund]

@toedter

good to see your feedback.

yes, the example you show is a misconfigured message. similar to the problems we can run into w/ other attribute combinations in HAL-FORMS (property.required:true & property.minLength:0 or property.options.maxItems:1 and property.required:false, and so on...). HTML has quite a few of these and (IIRC) even wrote up some general guidance on the matter.

SERIALIZING MESSAGES FROM CLIENT TO SERVER
right now the HAL-FORMS spec says use property.name and property.value to populate messages sent to the server. there is exception text to use property.options.selectedValues[] if it exists. to clear this up, we might need to have some spec text on which to use when serializing messages to the server (say, "use property.options.selectedValues[] if it exists and ignore the associated property.value" or something like that).

SERIALIZING MESSAGE FROM SERVER TO CLIENT
the other use for options.selectedValues[] to send one or more "pre-selected" values for the UI to render. think of cases where you are creating a new record and want the drop-down to be preselected w/ one or more values as defaults. in HTML, this is handled with a selected=true attribute.

[evert]

the other use for options.selectedValues[] to send one or more "pre-selected" values for the UI to render. think of cases where you are creating a new record and want the drop-down to be preselected w/ one or more values as defaults. in HTML, this is handled with a selected=true attribute.

"preselected" and a pre-existing value is the same thing no? it's just the current value of the form field.

[mamund]

it's just the current value of the form field.

if this is a new record (e.g. it doesn't existing in server storage and the user hasn't typed in anything yet) someone might want to emit a HAL-FORMS with some of the property values already filled in (not placeholder). in that case, if you want to "pre-fill" a property element with a multi-selected value you can fill in the options.selectedValues[] array with what you want pre-selected.

are we thinking about the same thing?

[carlobeltrame]

@mamund this confused me as well when reading the specification for the first time a few days ago. I think what @evert is describing is indeed the same use case as you're thinking of. However, I would find it more intuitive to define pre-filled multi-selects if we allowed the following structure:

{
  "_templates" : {
    "default" : {
      ...
      "properties" : [
        {
          "name" : "shipping",
          "prompt" : "Select Shipping Method",
          "type": "dropdown",
          "value": ["FedEx", "UPS"],
          "options" : {
            "inline" : ["FedEx","UPS","DHL"]
          }
        }
      ]
    }
  }
}

This requires to allow array content in the value of a property, which could be introduced as a backwards-compatible extension. The spec already says "If it does not exist, clients SHOULD act as if the value property is set to an empty string.". We could extend this sentence to say "If it does not exist, cannot be parsed or contains unrecognized content, clients SHOULD act as if the value property is set to an empty string."
Removing the selectedValues completely on the other hand might be a breaking change. But I think it would clear up some confusion and complexity.

@evert @toedter please correct me if I misunderstood you.

[toedter]

@carlobeltrame
I think there are two use cases:

1. The actual value is empty and we want to suggest preselected options for new values
2. The actual value is not empty and we also want to present it to the user as preselected.

If we want to make this distinction clear in the API, we would have to support both value and options.selectedValues .
In your concrete example, you could not express 1), when removing options.selectedValues completely.

[odrotbohm]

For 1. wouldn't the server just pre-populate the form with values, just like it would for any other non-options property?

I.e. if the server wants to prepopulate the destination city, it sets that in the value field, even for an empty document. Why shouldn't it be the same for options. HTML forms also don't distinguish between the two. Whether something is selected determined by the server independent of that's model state or a form for a an "empty" instance.

[carlobeltrame]

I agree with @odrotbohm.
If the actual value on the server is empty, but the user should be presented with suggested preselected options, what would you want to happen when the user hits submit? IMO the actual (empty) state from the server will be overwritten with the value from the form. The edit request does not need to care about the "old" value that is still on the server, it just needs to know what to present to the user. For other types of input, there is no way of specifying that either.

In case the client really needs to know the "server state" (e.g. to indicate whether the form field value has been changed), I'd assume that in most cases, that state is also available in some normal HAL endpoint, as normal primitive value:

{
  "shipping": [], // <-- here is the real current server state, empty in your use case 1.
  "comments": "To be delivered asap",
  "_links": {
    "self": { "href": "/orders/555" }
  }
  "_templates" : {
    "default" : {
      ...
      "properties" : [
        {
          "name" : "shipping",
          "prompt" : "Select Shipping Method",
          "type": "dropdown",
          "value": ["FedEx", "UPS"], // <-- this indicates the value to pre-fill in the form field
          "options" : {
            "inline" : ["FedEx","UPS","DHL"]
          }
        },
        {
          "name": "comments",
          "prompt": "Comments for delivery",
          "value": "/!\ Updated /!\ To be delivered asap",
          "type": "text"
        }
      ]
    }
  }
}

The same also works if you are not using inlined HAL-FORMS templates.

[toedter]

@odrotbohm @carlobeltrame
I would be ok with that.

[odrotbohm]

@mamund – Given that there are still hardly any implementations of the new additions out there, does it make sense to simply scratch selectedValues for now?

[mamund]

@odrotbohm @toedter @evert @carlobeltrame and others...

i've been quiet here for a couple weeks to allow folks to work through implementations and provide feedback.

what is the state of things now? is the feature "done"? are the broken things? missing things? not-needed things?

the real question I have here:

can we close this issue?

-- @mamund

[odrotbohm]

We're gonna ship support for the current draft in Spring HATEOAS 1.3 RC1 next Tuesday. We don't have support for selectedValues yet for the reasons cited above. I'd be fine with that being dropped. I guess more feedback coming from the community after the release. I assume we're going to prepare a working example for promotion as well.

[mamund]

@odrotbohm

thanks. this is all good. looking forward to continued feedback.

i'd be happy if it turns out no-one needs the added selectedValues[] element. as long as we can all get done what we need -- that's the goal.

[odrotbohm]

Yeah, nothing preventing us from putting it back in as optional element later if need arises.

[evert]

We are also shipping this, with some caveats:

• I kept the 'multiple' property, despite not in the spec. I think it's the only sane way to handle arrays-of-values.
• Not all our tooling will support the 'link' property. Ketting makes it available but our form renderer not yet.
• We do use selectedValues, but treat it the same as value. I would be fine with selectedValues dropped, as long as value can be extended contain an array. If value on property cannot contain an array, we have no way to indicate what the actual list of current values is on a form. So I kind of see selectedValues as a hack to work around the fact that value must maintain backwards compatibility. I think it has to be one or the other though. If selectedValues is dropped, please extend value to contain other types besides strings.
• Our internal data-model has a renderAs property that can contain dropdown, checkboxes, radios.

[mamund]

@evert

thanks for the update. AFACIT, the difference you have outlined are all local and non-breaking (right?) so no worries there.

your feedback on usage once it's your update gets wide use will be helpful, too.

[evert]

The one thing that makes us incompatible is the multiple property.

Otherwise, it will be a bit of a pain to model. The general rule (for us) is:

• If multiple is set to true, the value will always an array.
• If multiple is set to false, the value is always a single item (string, number, etc)

It is currently possible to infer this from minItems and maxItems, but this excludes some edge cases like "array of 1 item", and also is confusing around when "0 items" are selected (should it be null, empty string? Not appear? empty array).

The multiple just makes it dead-simple to specify whether a value will be serialized as an array or not, so I'm still hoping this can be re-considered.

[mamund]

@evert

understood about your use of multiple.

do you also support minItems and maxItems (both emit and consume them)?

[evert]

Do you also support minItems and maxItems (both emit and consume them)?

Yes, we support them when multiple is set to true

[mamund]

@evert

i see. so, for your implementation, support for multiple is required.

for example, the service can't just emit minItems and maxItems and expect them to be used unless that service also emits multiple:true, right?

[evert]

I missed your reply, apologies.

for example, the service can't just emit minItems and maxItems and expect them to be used unless that service also emits multiple:true, right?

We could definitely infer that multiple is intended if either minItems or maxItems appears. So that would be a potential alternative solution. Summarized:

• if minItems or maxItems appears, the value will be serialized as an array.
• If neither appears, serialize as a single (scalar) value.

It's a bit less explicit, but does solve the problem!