[w3c/manifest] Use WebIDL to describe the manifest data structure (#611)

There isn't really a formal specification of the manifest data structure. Instead, each member has its own section which describes the format of that member in prose. This makes it hard to discuss (e.g., in Ken's [shortcut proposal](https://gist.github.com/kenchris/0acec2790cd38dfdff0a7197ff00d1de), we'd like to be able to say "`sequence<IconInfo> icons;`" but there's no name for "the dictionary that describes a Manifest icon" because it's described in prose.

I think we should add a WebIDL section that contains a dictionary definition for the full manifest, as a first step (I can do it).

As a second step, I think this would allow us to simplify the language in each individual member. The "steps for processing a manifest" algorithm could be replaced with "Parse the JSON into an IDL dictionary value, then [convert it into an ECMAScript object](https://www.w3.org/TR/WebIDL-1/#es-dictionary)" (which automatically applies all of the IDL type conversion rules).

Then, for example, this text:

> The steps for processing the short_name member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.
>
> 1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "`short_name`".
> 2. If Type(*value*) is not "string":
>     1. If Type(*value*) is not "undefined", issue a developer warning that the type is not supported.
>     2. Return `undefined`.
> 3. Otherwise, Trim(*value*) and return the result.

could be replaced by this (assuming `short_name` is a `DOMString`):

> The steps for processing the short_name member is given by the following algorithm. The algorithm takes a manifest [referring to the processed ECMAScript object] as an argument. This algorithm returns a string or undefined.
>
> 1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "`short_name`".
> 2. If Type(*value*) is not "string", return *value*.
> 3. Otherwise, Trim(*value*) and return the result.

Were it not for the call to Trim, this would make almost all the processing steps trivial. Unfortunately, almost all of them do Trim their strings, which makes things more complicated. Perhaps we could make a global rule that Manifest strings are trimmed, then we wouldn't really need any processing steps at all.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/issues/611