Aligned WebIDL proposal with recent discussions

[HadrienGardeur]

Based on the F2F and post-F2F calls, I’ve aligned the WebIDL a bit more with schema.org.

This PR also contains a first take on handling the TOC in the WebIDL, using a tree structure and a single WebIDL dictionary.

---

Preview | Diff

[HadrienGardeur]

For now, I'm still using type instead of fileFormat (http://schema.org/fileFormat) in PublicationLink, which is the core element used in the default reading order, the list of resources and the table of contents.

Should we align on this term as well?

[iherman]

@HadrienGardeur :

• Yes, I believe it would be better to align the 'type' terms as well, just for the purpose of consistency
• I was wondering yesterday whether 'name' or 'description' is the proper term to use here (both are possible). The examples that come to my mind are all for a link that require, eg, an alt text for a11y, in which case 'description' may be more appropriate...
• I do not remember having talked about 'children', and I am not sure we will need this. The values used in resources or readingOrder are all a single layer list, no hierarchies there.
  The only reason I could see is for the purposes of hierarchical TOC-s. But are we sure we would use the same structures for the representation of TOC?

[iherman]

(Admin remark: I wonder whether it wouldn't be better to merge this PR with #221) as on bigger PR; the two are fairly closely related... Or merge them into the master pretty much one after the other.

@TzviyaSiegman @GarthConboy , what do you think?

[HadrienGardeur]

@iherman when I first drafted the WebIDL, I mostly thought about this structure as a link.

For me, a link is a more natural fit than similar structures in schema.org.

In HTTP, HTML, Atom or even EPUB, the link element remains mostly the same thing with only small differences.
That's why the initial WebIDL had href, rel, title and type.

If we align with the schema.org terms, then I agree that we should fully align. That said, these terms feel more awkward to me than what we had before: I prefer title over name and type over fileFormat.

Right now, this structure is used for:

• publication-level links
• the default reading order
• the list of resources
• the table of contents

We could have separate structures for each of these elements, but I don't think there's a strong case for it.

The only differences between readingOrder/resources and toc are:

• we only need children for toc (plus similar navigation lists being discussed in Other navigation elements beyond ToC #223)
• we might not need a rel for toc (but it could be useful)
• name might or might not be required for the toc

For the rest:

• url remains required
• type remains optional

I would prefer keeping a single structure for now and only divide things into two different structures once we have a strong case for it.

[iherman]

@HadrienGardeur o.k. let us have one structure on the WebIDL level. (And yes, I was/am also a bit uncomfortable using name for what is a title, for example, but we turned out to be happy with it at the F2F discussion, so we should run with this now.)

That being said, if I translate this to JSON-LD structures, adding the children may be unnecessary. On the manifest level the TOC is 'just' a link to an HTML element somewhere, meaning that it does not have any 'structure' on the JSON-LD level.

I will try to find some more time expanding #221 to include that, which would mean defining the reading order and the resources a breeze, except that the issue of where the rel values come from may still remain open (would we try to extend that by IANA? would we use URL-s for non-IANA relations).

[dauwhe]

On the manifest level the TOC is 'just' a link to an HTML element somewhere, meaning that it does not have any 'structure' on the JSON-LD level.

I was wondering about this. In the infoset TOC is clearly a link to an HTML table of contents, but in the IDL the TOC member is described as "Contains the table of contents."

[HadrienGardeur]

@iherman WebIDL and JSON-LD are not necessarily meant to be the same.

For the ToC specifically, in WebIDL we'll end up with the results of parsing an HTML document.

Regarding rel values:

• I think we should definitely align with the IANA link registry
• URLs for extensions is the usual extension mechanism for rel
• we need to allow for more than a single rel, this has been problematic in Atom for example in the past

[iherman]

@HadrienGardeur I have the impression we are violently agreeing:-)

[iherman]

@HadrienGardeur looking that schema.org definition of name and description (which are both very shallow...) I still wonder whether we should not use description either additionally or instead of name. description seems to be a better fit for, e.g., the alternate text description of an image used for a cover (something that came up on the discussion yesterday...).

[BCWalters]