Re: Response data should always be in a top-level "value" property.

Alright. Since we seem to be in broad consensus, I've put up a PR for this:
https://github.com/w3c/webdriver/pull/345

Cheers,

Simon

On Tue, Oct 4, 2016 at 10:48 AM, Simon Stewart <simon.m.stewart@gmail.com>
wrote:

> Bottom posted
>
> On Mon, Oct 3, 2016 at 10:01 PM, James Graham <james@hoppipolla.co.uk>
> wrote:
>
>> On 03/10/16 21:00, Jason Juang wrote:
>>
>>> I don't disagree with this proposal.
>>>
>>> Worth noting that this was previously litigated at TPAC 2014
>>> <https://www.w3.org/2014/10/30-testing-minutes.html#item05>, where there
>>> were two related resolutions:
>>>
>>>> resolution: remove response body and just send back dictionary
>>>> resolution: use 'value' key for primitives
>>>>
>>>
>>> I think the order of events was:
>>> - the response used to have a "status" field and a "value" field
>>> - the "status" field was removed in favor of using HTTP status codes
>>> - the "value" field was removed for non-primitive responses because it
>>> seemed redundant to wrap the response in '{"value": ... }'
>>>
>>> I can't quite recall whether there were other arguments for "unwrapping"
>>> the response, other than that it seemed unnecessary at the time.
>>>
>>> I think the consistency argument (#2) alone is more compelling than
>>> that. Point #3 is also kind of nice; it allows for future protocol
>>> modifications to add additional fields, should that become necessary.
>>>
>>
>> I don't really think the consistency argument has that much value. In
>> either case you need to know which type to coerce to, which you can only
>> know if you know the command. Blindly coercing to a type on the remote end
>> would be a spec violation (because unknown fields must be ignored), and I
>> would expect clients to behave the same way. Needlessly wrapping just
>> produces another layer of indirection.
>
>
> In Selenium there's a pipeline for decoding a response. The first step
> involves taking the raw json encoded as a string and decoding that to a
> JSON object of some kind. Response values are then pulled out of the json
> and pushed into a selenium's own "Response" object, with the value having
> been coerced to an exception if necessary, or left as a raw map, list, or
> primitive type. The next stage of the pipeline populate the object returned
> to the user of the local end.
>
> There is a need to wrap primitive types, as Andreas has pointed out that
> some JSON parsers get grumpy if presented with something that isn't an
> object to decode.
>
>
>> I also don't care for the extensibility argument; spec extensions can
>> avoid collisons simply by picking a new name and intermediaries or vendor
>> extensions should vendor-prefix any field names using a reserved character
>> (there is an issue about using colon for this purpose so that you get
>> vendor:foo properties).
>>
>
> This is the same problem that we faced with "element": we don't know which
> fields are safe and which are not. Putting the value being returned into a
> "value" property means that it's possible to safely decorate responses
> without worrying about clashing namespaces. Without doing this, it's not
> possible to guarantee no clashing with values being returned to the user.
>
>
>> In any case this seems like a rather large change to propose after
>> agreeing a short timetable to reach PR. I don't intend to block the
>> proposal if it's something that everyone agrees is right, but I would
>> encourage anyone else wanting to propose fundamental changes to things that
>> have been explicitly agreed and in the spec for several years to do so
>> sooner rather than later otherwise I fear Mike is going to have a hard time
>> making a credible case that we will ever actually finish anything.
>>
>
> Fortunately, most commands already return their value in a top-level
> "value" property. Those that don't are mostly to do with window sizing and
> positioning. In the geckodriver, there are places in the spec that claim
> the return value should be serialised, but where nonetheless the actual
> implementation puts the data into a "value" property anyway ("Get Active
> Element" would be one of those places). So it seems that this also makes
> the spec more conformant to actual existing implementations.
>
> Simon
>
>