Re: Working Group Visibility and Spec Documentation

On 24/09/2019 12:42, Christian Bromann wrote:

>   * have a swagger editor (like https://editor.swagger.io/) with all
>     WebDriver endpoints for easier discoverability
>       o I already ported our spec into such swagger definition:
>         https://app.swaggerhub.com/apis-docs/christian-bromann/webdriver/2.0.0

I'm not opposed to making parts of the spec more machine readable — 
indeed I would advocate for it — but I'm somewhat concerned about 
publishing this kind of thing as an adjunct to the spec. For a start, 
the status of swagger is unclear to me; it claims to have a 
specification but it's very very thin, and attempts to monkey patch JSON 
schema (which has a much more detailed spec) to describe schema for HTTP 
bodies. In addition any non-normative material needs to be clearly 
marked as such and there needs to be a clear commitment to keeping it up 
to date with the spec. Otherwise there is a problem whenever the 
normative requirements and non-normative descriptions don't match (for 
example: that swagger definition doesn't match the spec for New Session, 
which is one of the first endpoints I looked at).

I would much prefer an approach where we actually replace spec prose 
with e.g. JSON Schema in the normative requirements. Once that happens 
it will be easier to build tools to generate non-normative descriptions 
from the spec itself and solve the update problem.

Received on Tuesday, 24 September 2019 12:36:23 UTC