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

The problem is if there is a clash between any of the property names of any
object ever returned by any command in the spec now or in future revisions
and the JSON object being returned. We worried long and hard about this
with elements, which is why we moved from Selenium's "ELEMENT" name to the
pseudo-GUID we have now. Also, if we ever return a map of hash from any
method, there's no way to distinguish "returned by the driver" from "added
as decoration"

By pushing the value to always be in the "value" property of the JSON
object, we can easily make this distinction, thus allowing us to more
properly return intended values.

I'd like to point out again that this is a far more consistent way of doing
things, especially since the spec is currently a mixture of "return a raw
object", "return a raw object as a value property" and "return a raw
primitive as a value property". As a developer, that lack of consistency
makes me consider the wealth of interesting bugs and edge cases that might
occur.

Simon

On Tue, Oct 4, 2016 at 2:55 PM, David Burns <dburns@mozilla.com> wrote:

> Consensus will really require Microsoft and Apple to have an opinion too.
> Since we discussed this as a group and agreed we need to agree as a group
> for this change.
>
> I do have questions though:
>
> If we are following Postels Law, how does, using getElementRect as an
> example, change anything. JSON below. Instead of taking it off the top we
> need to go one level down.
>
> {
>    'value': {'x': 10, y: 10, 'width': 10, 'height': 10},
>    'somethingExtra': {},
>    'AndAnotherThing':"someString"
>
> }
>
> {
>    'x': 10, y: 10, 'width': 10, 'height': 10,
>    'somethingExtra': {},
>    'AndAnotherThing':"someString"
> }
>
> The spec says we should only be taking the items we need off the object so
> surely the clients/intermediaries should be doing that too?
>
> On 4 October 2016 at 11:16, Simon Stewart <simon.m.stewart@gmail.com>
> wrote:
>
>> 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
>>>
>>>
>>
>