Informative and structural "properties" are relationships

[mattgarrish]

To separate this discussion away from #421, I find a bit awkward that we lump the resource relationships into the properties. These should really be a separate section, for example:

2.7 Resource Relationships

2.7.1 Informative Relationships
2.7.1.1 Accessibility Report
2.7.1.2 Privacy Policy

2.7.2 Structural Relationships
2.7.2.1 Cover
2.7.2.2 Page List
2.7.2.3 Table of Contents

The extensibility of relationships is also different from properties, since we expect these to be standardized in IANA.

[mattgarrish]

This might also solve some of my concern with properties and relationships having different naming conventions. IANA mixes all kinds of naming conventions, but so far we only adopt "privacy-policy" and "contents" from the relations. Perhaps properties can remain camelcased and we can hyphenate relationships for consistency?

This would mean only "pagelist" might potentially need to change to "page-list" (which would match EPUB but not DPUB-ARIA, though that hardly matters in this context). But leaving it as-is would fit just as well within the relations, too.

[iherman]

Yes, I think separating those relationships to a different "thing" (table, list, or whatever) is a good idea. The quick reference may include property terms that come either from schema.org or from our own vocabulary, and it is unnecessary to refer to them as URL-s because they are only used as terms by the author. The relationship, alas!, is different.

(Unfortunately, I am not sure we can get around using URL-s for those at least for now...)

[iherman]

(We should probably merge #425 before doing any change...)

[mattgarrish]

Ya, this is a confusing one to piece apart. What we've done for some of these is define properties based on the relations, so we're not actually realizing that there is a property until the canonicalization step (although even that isn't clear for all).

In other words, what starts off as:

{
    "url": "toc.html",
    "rel": "contents"
}

after processing becomes:

{
   ...
   "contents": "html markup here",
   ...
}

since there are rules for compiling the table of contents, but they're not in canonicalization section.

But what about a resource that identifies itself as a privacy policy, does it become:

{
   ...
   "privacy-policy": "https://example.com/privacy.html",
   ...
}

If so, we're effectively minting new properties for every link relation that we compile up. But processing of privacy policy, cover and accessibility report is not detailed in the canonicalization steps, either, so when and where does it occur? Or are these supposed to be separate entities that a user agent might make itself aware of?

At any rate, this changes the dynamic of what I was proposing.

We can (maybe?) keep the current groupings, since we (maybe?) need properties eventually, but it raises a number of questions:

1. do all these properties spring into existence through canonicalization if they aren't set manually, or only page list and toc? If not, we should detail why only some do and move the others out of the properties section. We should figure out a better place to define the steps for compiling the toc and page list during canonicalization.
2. how does canonicalization work for other relations we haven't listed? I assume we need a method for compiling only certain relations into properties?
3. do we have to keep the link relation names as the property names to avoid having to maintain a map of what goes to what? This would have the unfortunate consequence of leaving our mixed-bag property naming intact.

[iherman]

@mattgarrish

I do not understand what you mean by:

{
   "url": "toc.html",
   "rel": "contents"
}

after processing becomes:

{
   ...
  "contents": "html markup here",
  ...
}

Canonicalization does not involve generating HTML markup...

As for

If so, we're effectively minting new properties for every link relation that we compile up. But processing of privacy policy, cover and accessibility report is not detailed in the canonicalization steps, either, so when and where does it occur? Or are these supposed to be separate entities that a user agent might make itself aware of?

yes, I think that is how the processing of rel is supposed to be, but that is a general way the Web does things: you get (via HTTP or otherwise) the content (or the URL thereof) and the separate rel value which tells the user agent how to display/process that stuff. We are no different...

So the overall answer is that canonicalization has nothing to do with these. A canonical version of the manifest is a bona fide 'authored' manifest, with all the shortcuts resolved. A full and automatic authoring system for WPUB could bypass canonicalization altogether; the canonicalization is only there because some manifests will be produced by human, and we make their life easier.

[mattgarrish]

Canonicalization does not involve generating HTML markup...

That's what I was expecting, but that's not what the specification currently seems to say.

We have a table of contents relationship defined here: https://w3c.github.io/wpub/#pub-table-of-contents

And a process for creating contents and toc properties (conflicting names) that involves extracting the HTML toc without exactly explaining when this process happens: https://w3c.github.io/wpub/#wp-table-of-contents

To add to the confusion, the process to extract the toc nav ends by saying:

If this process does not result in a link to the table of contents, the publication does not have a table of contents and this property MUST NOT be included in the canonical manifest.

Which makes no sense, as the process results in the toc markup.

The only interpretation I could make is that the HTML has to be added to the manifest property and this either happens before or during canonicalization. The same is true of page-list.

My expectation before reading the spec was that the rel values were intended to do nothing more than identify resources that could be used after canonicalization, but it's not what I found.

Assuming I was right to begin with, though, and that the rel values just allow a user agent to identify resources and do things independent of canonicalization (i.e., there is no property computation), then I can continue what I was originally intending.

But, if that's true, I also need to go through and rewrite the toc and pagelist sections, as they're confusing the hell out of me.

[iherman]

Hah! I think the confusion in the TOC section comes from this thing:

The table of contents property identifies the digital publication's table of contents. It MAY be used either to embed a table of contents within the manifest or to identify a resource that contains the table of contents. How the table of contents has to be represented is determined by the digital publication format.

That was left pending due to an open issue (whose number I do not remember) but is now out, because we agreed that the only way a TOC is represented is in HTML, and the Manifest simply refers to the TOC via a URL. The paragraph is simply wrong; only the first sentence is true. It is up to the user agent what it does with the extracted TOC.

[mattgarrish]

because we agreed that the only way a TOC is represented is in HTML, and the Manifest simply refers to the TOC via a URL

Okay, that makes more sense; it is just a rel identifier.

I'll keep pushing ahead with what I think needs changing and then see if you agree with the PR.

[mattgarrish]

Closing as this was addressed in #428.