Re: [w3ctag/design-reviews] Web Publications review (#344)

@dbaron,

I would like to react on your comments related to WebIDL.

> It's a little disturbing to see section 2.3 refer to WebIDL as a representation of a data structure, rather than as an API for accessing the representation of a data structure.

To step back a bit: the reason of using WebIDL (or, shall we say, something like WebIDL) is actually related to another question of yours:

> the use of JSON-LD: are implementations expected to interpret it as JSON, or to interpret the underlying RDF data model? (I prefer the former.)

Our view was that applications should be indeed able to access the data represented in the manifest based on the JSON structure only. To make this precise, we have to specify exactly what data structures to extract from JSON, taking into account the fact that the manifest definition itself allows for some ambiguity. (For example, while the value of an "editor" is supposed to be an object with at least a property called a "name", we allow the author of the manifest to put directly that name as a value of "editor". This is not unlike the similar feature schema.org has.)

We were looking for a formalism to express that data structure, and we did not find any better than WebIDL. We were influenced by, e.g., the [Web App Manifest's usage of WebIDL](https://w3c.github.io/manifest/#idl-index) which is _mostly_ a series dictionaries expressing the underlying data (there are only a few API definitions which are related to event handling and such and not to the data expressed in the JSON manifest). We were considering other options (JavaScript, TypeScript, JSON schemas), but none of these seemed satisfactory in terms of readability, stability, or independence of implementation choices. We also considered the separate discussion in https://github.com/whatwg/infra/issues/159.

(B.t.w., we do provide a separate, a [non-normative JSON schema](https://github.com/w3c/wpub/tree/master/schema) for the manifest. But, as also mentioned in https://github.com/whatwg/infra/issues/159, those are not really easy to read. Besides, the JSON Schema is still evolving, could not be used as a stable reference.)

All that being said, I understand and share your unease about the usage of WebIDL; I think we would be happy to consider an alternative. We just did not find any...

> The repeated use of WebIDL "partial" to amend the same interface within a single specification feels like a bad practice; it makes it hard to understand the interface. 

To be honest, I am not sure why that would be bad practice, at least in this case. First of all, there is an [appendix with the full WebIDL](https://w3c.github.io/wpub/#idl-index) where all partials are "merged", i.e., the full WebIDL is available. On the other hand, it sounds like a good practice to put the formal data structure definition close to where the corresponding term is defined, described in English, and where, in general, examples are also provided. This is the structure we followed throughout the document. Can you elaborate why you think that is a bad practice?




-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/344#issuecomment-491025385