How do we identify a web publication and its components?

[dauwhe]

From @dauwhe on June 26, 2017 22:17

A Web Publication (WP) is a collection of one or more constituent resources, organized together in a uniquely identifiable grouping that may be presented using standard Open Web Platform technologies. A Web Publication is not just a collection of links— the act of publishing involves obtaining resources and organizing them into a publication, which must be “manifested” (in the FRBR sense) by having the resources available on a Web server. Thus the publisher provides an origin for the WP, and a URL that can uniquely identify that manifestation.

Perhaps the simplest possible answer to these questions is just a URL: https://www.example.com/MobyDick/ would both identify the publication and mean that everything whose URL starts with this is part of the publication.

So I guess that I’m looking for reasons to make this more complicated :)

Copied from original issue: w3c/publ-wg#10

[dauwhe]

From @GarthConboy on June 26, 2017 22:25

I think we'll need to point to the "manifest" -- we'll need to be able to download or package the entire publication and its constituent resources (given Brady's correct observation that with scripting scanning the markup can reliably determine what's really referenced). Also need to know what markup file should initially displayed and how to progress from there.

If your URL is a "directory root," one could say everything under it is inherently part of the publication (which could resolve the scanning the markup issue [maybe]), but one will still need to find the manifest to know where to start rendering and the reading order thereafter.

[dauwhe]

but one will still need to find the manifest to know where to start rendering and the reading order thereafter.

This reminds me of a concern about progressive enhancement. Say I point my browser at https://www.example.com/MobyDick/ but JS is disabled or the user agent doesn't yet support web publications. What should happen?

One option would be to give the first document you want displayed a special name, say, index.html. This file could also point to the manifest, or include it directly.

[dauwhe]

From @mattgarrish on June 26, 2017 22:56

The case usually given for complexity is open textbooks and course packs, where content is aggregated from different locations without having to actually amass the resources under a single domain/directory.

Does "everything" here only refer to html pages? How realistic is it that all the resources are going to be neatly stored together? What if my css is two levels higher up from the publication under a common folder? What if I'm pulling in css or scripts from another domain?

I'm all for simplification, don't get me wrong, but I'm not optimistic about a model that requires the user agent to traverse and parse all the documents to figure out what is in scope and needed, if that's where this is leading.

but one will still need to find the manifest to know where to start rendering and the reading order thereafter

Isn't this where we've considered using link/rel to establish the "belonging"? (And another case of why cross-domain publications get complicated quickly, since their parentage can only be established by starting at an author-controlled location, which then has to be maintained despite what the linked resources might indicate.)

[dauwhe]

The case usually given for complexity is open textbooks and course packs, where content is aggregated from different locations without having to actually amass the resources under a single domain/directory.

Do we need to design something that will support content documents ("spine items" in EPUB-speak) hosted on multiple origins?

https://www.example.com/MobyDick/chapter-001.html
https://www.foo.com/MasterAndMargarita/chapter-002.html

[dauwhe]

I think we'll need to point to the "manifest"

So the URL of the WP would point to the “manifest” rather than a directory? This would then imply (I believe) that the manifest be discoverable from some sort of file. So what sort of file? I would argue that pointing to HTML would be better than the alternatives, given all user agents know what to do with HTML files. But that leaves open the question of whether this HTML file contains the manifest, or just points to the manifest.

[dauwhe]

From @mattgarrish on June 27, 2017 1:40

Do we need to design something that will support content documents ("spine items" in EPUB-speak) hosted on multiple origins?

We need to consider it, at least. Intertwined with what I mentioned above is the problem of iframes and bringing in entire chunks of content below the level of the spine. We need to be open to how the web works and not just publications as we're used to making them.

The problem doesn't seem confined to content documents but affects their constituent resources, as well, so we need some solution.

Taking a publication offline is less of a problem than what happens to references in a packaged web pub. So while we can ignore the problem at this level, we probably do so at our own peril later. Or maybe we add rules farther down the chain that limit what a packaged web pub can reference? (That's kind of a nasty gotcha I'd hate to discover, though.)

[dauwhe]

From @GarthConboy on June 27, 2017 2:47

"I would argue that pointing to HTML would be better than the alternatives, given all user agents know what to do with HTML files. But that leaves open the question of whether this HTML file contains the manifest, or just points to the manifest." -- interesting. As long as the manifest was discoverable in a known location, I guess that would okay -- I think a browser might be interested in a first HTML page, whereas a Reading System would want to start with the manifest.

"Do we need to design something that will support content documents ("spine items" in EPUB-speak) hosted on multiple origins?" -- I would think "no".

[dauwhe]

From @iherman on June 27, 2017 7:27

@dauwhe

One option would be to give the first document you want displayed a special name, say, index.html. This file could also point to the manifest, or include it directly.

This is already how the Web works. We routinely use URLs to a directory, and it is up to the server setup on what this means in practice. It can return the index.html file in that directory, if available; in Apache one can actually set up a whole priority list of alternatives. Although not frequent, it can also return, as a first order index.svg (that may be useful for some documents).

Bottom line: I believe your first statement, whereby https://www.example.com/MobyDick/ is the identifier of a particular document is perfectly fine.

[dauwhe]

From @iherman on June 27, 2017 7:29

I think the scope notion of the Web App Manifest is interesting here. If we want to include content document from different "origins", then we may use a scope listing several documents. Although, for different reasons, I may be tempted to say that all directories listed in the scope should be on the same domain.

[dauwhe]

From @baldurbjarnason on June 27, 2017 22:13

The scope notion would play nicely with the proposed packaging spec which IIRC relies on it quite a bit.

Outlining how identification for web publications would work if it followed the expectations set by the rest of the web stack (e.g. web app manifests, atom/rss feeds, etc.):

1. Each HTML page that is a part of a publication links (with a specified link relation) to a manifest document of some sort to indicate the publication it is a part of.
2. That manifest then somehow indicates which resources are under its purview. This could be done using scope (like web app manifests) or an explicit listing of some sort, or both.
3. The manifest lists an authoritative url that identifies the publication it is describing. This might be done indirectly as simply the root URL for the scope it covers or directly as an explicit property. I think most web developers would prefer an explicit URL property but that's just a hunch not backed by data. That would also make the manifest more complementary to the packaging spec if that spec becomes a reality.
4. That identifying root URL has to return an HTML file that is within the manifest's scope and that file has to link back to the manifest as well.

This is the basic pattern used by feeds, web app manifests, service workers, etc: component files link to a central document with metadata, indication of scope, link to self, and an identifying URL. Even AMP uses a variation of this theme. And as I mentioned above sometimes the identifying URL and scope definitions are interrelated. E.g. atom feeds link to the URL whose updates they list (explicit id, implicit scope).

This pattern gives us discovery (direct links to chapters let you discover the publication ID, its metadata, and all related assets) as well as a single source of truth for the publication ID, publication-level metadata, and publication assets (the manifest). And this guarantees that the publication id is itself a URL to a human-readable HTML resource that in turn lets you discover the manifest.

Of course, this is just going from what you'd expect if you were coming at this from the web development community. I realise that they aren't the only constituency at play here.

And this does not necessarily dictate anything about the format of the manifest. Although, if we're going by the principle of least surprise, most web developers would at least expect a JSON file.

---

On service workers

Service workers achieve this process programmatically, but the pattern is very similar overall. Although a lot of service worker behaviour by necessity violates common developer expectations.

• Service workers scope defines the pages whose network access they control. Which (counter-intuitively for some) means that they can control cross origin requests for the pages they control.
• But the requests the service worker makes itself are no-cors by default (IIRC).
• You also have foreign fetch service workers who control the network requests for pages outside of their scope as their scope is defined by the resources being fetched not the pages doing the fetching.

Basically, even though service workers are awesome, they do also have a deserved reputation for being confusing (this is only scratching the surface) so anything we can do to avoid that complexity is a win. That means not letting the publication manifest claim scope over cross-domain resources and not letting it control requests in any way.

---

(Apologies for the brain dump. I didn't have time to edit this down to a concise note 😊)

[dauwhe]

From @HadrienGardeur on July 2, 2017 20:9

What you're describing is almost exactly what we do in Readium-2 @baldurbjarnason, there are only minor differences or observations that I need to add.

Each HTML page that is a part of a publication links (with a specified link relation) to a manifest document of some sort to indicate the publication it is a part of.

Ideally yes, but what if a resource is included in multiple Web Publications ? What if you can't change the HTML or HTTP headers for that resource ? IMO, such a link to a publication is an important part of how discovery is handled, but it's not an absolute requirement.

That manifest then somehow indicates which resources are under its purview. This could be done using scope (like web app manifests) or an explicit listing of some sort, or both.

In Readium-2 we list all resources under two separate collections: spine for the core resources that are listed in reading order and resources for other resources.

This has some clear benefits over a simple scope:

• since we know all the resources (URIs) necessary to render a resource, we can easily cache them however we want (Service Worker, App Cache Manifest, proxy, local cache storage for native apps)
• we also optimize the UX by preloading specific resources (fonts, JS, CSS) and prerendering some of them (using multiple webviews in our mobile apps)
• since our manifest is using JSON-LD + schema.org, a client that understands schema.org can index these resources as being part of the publication

The manifest lists an authoritative url that identifies the publication it is describing. This might be done indirectly as simply the root URL for the scope it covers or directly as an explicit property. I think most web developers would prefer an explicit URL property but that's just a hunch not backed by data. That would also make the manifest more complementary to the packaging spec if that spec becomes a reality.

That's one of our only requirements. In Readium-2 we always provide a link that points back to the manifest.

The other two requirements are:

• at least a title in the publication's metadata
• at least one resource in the spine

That identifying root URL has to return an HTML file that is within the manifest's scope and that file has to link back to the manifest as well.

That's pretty much the only difference between what you're describing and Readium-2/Readium Web Publication Manifest. The "root URL" (a link with self as its relation) points to the JSON manifest, not the first (or any document) from the spine.

One reason for that is tied to the fact that we'd like anyone to create a Web Publication by remixing content already available on the Web.

On Service Workers

I really don't think that Service Workers should in any way influence our design for Web Publications. There are many different ways that content can be cached, and Service Workers are only one method among others.

Let's keep our options open and let people use all the possibilities offered.

[dauwhe]

From @llemeurfr on July 3, 2017 12:58

So, to come back to the initial question, Readium-2 folks propose:

• an IRI as globally unique identifier for the publication, included in the manifest as one of the few mandatory metadata.
• a URL linking back the manifest to its origin.

[llemeurfr]

Correction of my previous comment, after discussion in #6: The unique identifier of the WP is the 'self' link (a URL) to the (original) WP manifest. If a WP is copied to a new server, it can be considered as a different WP, in which case its 'self" URL is modified. Or it may be considered as the same WP, in which case its 'self" URL isn't modified and points to the original WP. Moving a WP to new domain name implies creating a new WP (as the original URL would return a 404, a new 'self' URL is required).

[murata2makoto]

I think that it should be possible to reference any resource in a web publication (which is referenced by a URI) by URIs. To treat such resources as first-class citizens of the web, use of fragment identifiers should not be required. Moreover, fragment identifiers defined for resources media types should be usable.

An absolute-path reference (a relative reference beginning "/") in such resources should reference another resource in the web publication. Furthermore, the absolute URI constructed from the base URI (i.e., the absolute URI of the web package) and the absolute-path reference should reference the same resource.

When a resource belongs to multiple web publications, depending on which web publication is used a base URI, relative references in the resource should be resolved differently.

EPUBCFI does not satisfy these desiderata.

[mattgarrish]

An absolute-path reference (a relative reference beginning "/") in such resources should reference another resource in the web publication.

I still wonder about issues like this when multiple domains are involved. Not so much at the WP-level, but at the packaging level. How are such references resolved and domains preserved? Do we at some point need to decide whether multiple-domain publications are out of scope for a first release?

[dauwhe]

Do we at some point need to decide whether multiple-domain publications are out of scope for a first release?

Perhaps there are two questions. Having multiple domains for content documents seems problematic, and perhaps not worth the complexity. But what about things like fonts and scripts that might come from other origins?

But then our white paper suggests that the publisher has an obligation to provide an origin:

A Web Publication is not just a collection of links— the act of publishing involves obtaining resources and organizing them into a publication, which must be “manifested” (in the FRBR [frbr] sense) by having the resources available on a Web server. Thus the publisher provides an origin for the WP, and a URL that can uniquely identify that manifestation.

[mattgarrish]

Yes, it's a troubling question. I recall at one point we were discussing URL mapping in the DPIG, but even that's not quite enough, as there have to be rules about domain root independence.

If the manifest were to set a scope and all resources had to be below it, then the problems seemingly goes away, but it also greatly reduces what can be called a publication. Maybe that's not a bad thing, but it invalidates many of the possible applications.

[murata2makoto]

I think that "/" should always reference the web publication, no matter which resource "/" appears in. I updated my comment above for covering multiple web publications.

[mattgarrish]

But if we're not redefining how the web works today, how can that work for a publication with documents on different domains?

It can't even work unless the publication root is the domain root, otherwise we're redefining how to resolve a path that starts with a slash, no?

[murata2makoto]

I would like to begin with desiderata. If we reach consensus on desiderata, we can invent a solution.

But it is true that the domain root should reference a web package. In other words, the domain root of a resource-in-WP URI should contain the WP URI.

[HadrienGardeur]

I strongly object to limiting Web Publications to a single domain, this goes completely against the model of the Web.

On a modern website these days it's not uncommon to have:

• fonts served by a third party (say Google Fonts or Typekit)
• JS, CSS and images hosted on a CDN
• video embeds from services like Youtube or Vimeo

If we require content to be served from a single domain, we're no better than AMP and require a parallel Web to be built specifically for the constraints that we decide.

IMO this is perfectly unacceptable: Web Publications should work with content that exists on the Web today, on as many different domains as the content requires.

For Web Publication and its manifest, what's the issue with using absolute URIs? We can perfectly do whatever needs to be done (preload, cache, prerender...) with absolute URIs.

If you're talking specifically about the use case of transforming a WP into a PWP, that's a very different problem and the difficulty will be tied to the packaging and manifest formats that we select.

The Web Packaging proposal for instance can perfectly support resources across multiple domains: https://github.com/WICG/webpackage#multiple-origins-a-web-page-with-a-resources-from-the-other-origin

[murata2makoto]

Who suggested "limiting Web Publications to a single domain"? I didn't.

It is true that the path component of a resource-in-WP URI should be able to specify a different domain.

[mattgarrish]

If you're talking specifically about the use case of transforming a WP into a PWP

Right, and I was speculating about problems we'd face if '/' refers to the root of the publication even though the domain root is not the publication root. The content won't work when it's on the web. I'm not in favour of limiting publications to a domain, but it seems like the only way that could work.

[HadrienGardeur]

Who suggested "limiting Web Publications to a single domain"? I didn't.

I'll quote this thread twice:

From @mattgarrish

Do we at some point need to decide whether multiple-domain publications are out of scope for a first release?

From @dauwhe

Having multiple domains for content documents seems problematic, and perhaps not worth the complexity.

To be fair, @mattgarrish also said:

[...] it also greatly reduces what can be called a publication. Maybe that's not a bad thing, but it invalidates many of the possible applications.

While @dauwhe also pointed out:

But what about things like fonts and scripts that might come from other origins?

IMO, the potential design for PWP shouldn't affect WP in such a dramatic way. Aside from resources (CSS, JS, fonts, images, audio and video) which are often served from a different origin, being able to create a publication across multiple domains would also open up the possibility to remix content from the Web which I personally find compelling.

Even if a single publisher controls a publication, it might want to reuse content across different domains or sub-domains. Let's take an example, publisher A has:

• plenty of restaurants critics and reviews on food.publisherA.com
• it also has a separate website with a focus on traveling on travel.publisherA.com

Publisher A decides to remix content about a specific place (let's say Rome) and create a new publication together. It would make a whole lot of sense for this publication to simply point to content documents and resources on food.publisherA.com and travel.publisherA.com instead of being forced to re-publish them somehow.

[HadrienGardeur]

Right, and I was speculating about problems we'd face if '/' refers to the root of the publication even though the domain root is not the publication root. The content won't work when it's on the web. I'm not in favour of limiting publications to a domain, but it seems like the only way that could work.

I don't think that we need a publication root or the equivalent of the scope element in Web App Manifest.

We can either reference resources in the manifest using:

• an absolute URI (no problem working with those)
• or a relative URI, which would always be relative to the self link for that manifest

A scope works when you want to be vague about the constituent resources that are part of an app. If we take a different approach, one that's more declarative (spine, resources) than scripted (Service Worker), having a scope is completely redundant.

[murata2makoto]

Right, and I was speculating about problems we'd face if '/' refers to the root of the publication even though the domain root is not the publication root. The content won't work when it's on the web. I'm not in favour of limiting publications to a domain, but it seems like the only way that could work.

I think that we need a new URI scheme whose authority component can contain an absolute WP URI and whose path component can contain an absolute resource URI or a relative URI of a resource in the WP.

[mattgarrish]

it might want to reuse content across different domain or sub-domains

Right, I don't disagree. My point above was only that there's a lot of simplicity in not having to deal with the issues of multiple domains. I can see arguments for it.

I'm arguing for a decision, not necessarily advocating a position. Are there requirements we can start taking for granted as we weigh deeper into the issues so we know how to judge proposals.

Can we drop the idea of a scope and move ahead with an assumption of a declarative file set? Are there objections?

It doesn't mean we don't have to revisit our thinking later, but we can't stay open to all options.

[murata2makoto]

Can we drop the idea of a scope and move ahead with an assumption of a declarative file set? Are there objections?

I think that our referencing mechanism should be orthogonal to manifest formats. So, I agree to drop it.

[frivoal]

A few important points from my point of view:

1. the entry point of the publication is something that existing UAs can make sense of. They can (and will) fail to understand some aspects of it, since new features are not understood by old UAs of course, but it must degrade gracefully, otherwise we're not making something that is a first class citizen of the web. That pretty much means we need to start from an html document, although it is also fine if we can make it work with other things browsers can consume (svg...).
2. Whether links to other parts of the publication are embedded directly in that entry point, or bundled in a manifest of some sort that lives at the end of its own URL that is linked to from the entry point of the publication is something we'll need to decide about (I favor embedded directly), but neither choice is fundamentally at odds with the web. However we will absolutely need a scheme where the publication as a whole as a standalone URL (otherwise we're not making publications first class citizens), and where each constituent part of the publication also does (otherwise we're just designing a new file format, not a way to tie together a collection of resources).
3. URLs look hierarchical, but they aren't an actual directory/folder system, and it's way too late to start giving them this kind of semantics. www.example.com/foo/ is not (in the general case) a directory that contains www.example.com/foo/bar/. Assuming it is the case will break immediately, and requiring it to be the case going forward will not be obeyed by the web at large and will fail. Relatedly, there isn't a mime type for directories.
4. Putting cross-domain restrictions is acceptable when there are security concerns for doing so, but is best avoided otherwise. Introducing such a restriction as part of an attempt to make URLs a hierarchical file system would be a bad idea (see point 3).

[HadrienGardeur]

the entry point of the publication is something that existing UAs can make sense of. They can (and will) fail to understand some aspects of it, since new features are not understood by old UAs of course, but it must degrade gracefully, otherwise we're not making something that is a first class citizen of the web. That pretty much means we need to start from an html document, although it is also fine if we can make it work with other things browsers can consume (svg...).

I don't think that we need to limit things to a single entry point. A user should be able to discover any part of a publication on the Web and from there discover the rest of the publication.

All parts of a Web Publication (including an external manifest), should be referenceable using a URL.

Discovery can happen inside HTML (<link>) but also using HTTP headers (Link:) which work across a larger number of resource types.

URLs look hierarchical, but they aren't an actual directory/folder system, and it's way too late to start giving them this kind of semantics. www.example.com/foo/ is not (in the general case) a directory that contains www.example.com/foo/bar/. Assuming it is the case will break immediately, and requiring it to be the case going forward will not be obeyed by the web at large and will fail. Relatedly, there isn't a mime type for directories.

Fully agree, and giving semantics to how URLs are organized is a bad thing in general (everyone should read this dissertation by Roy Fielding).

We want to work with the Web as it exists today, and shouldn't require such conventions.

[murata2makoto]

URLs look hierarchical, but they aren't an actual directory/folder system, and it's way too late to start giving them this kind of semantics. www.example.com/foo/ is not (in the general case) a directory that contains www.example.com/foo/bar/. Assuming it is the case will break immediately, and requiring it to be the case going forward will not be obeyed by the web at large and will fail. Relatedly, there isn't a mime type for directories.

But "5.2.4. Remove Dot Segments" in RFC 3986 clearly mimics a directory/folder system. I agree that the path in an HTTP URL is not necessarily a directory or file. But an URL is not completely opaque.

[llemeurfr]

If we move away the discussion on multiple-origins for spine items, the core question of identifying a Web Publication seems have only 3 practical solutions:

1- a manifest file like https://www.example.com/MobyDick/manifest.json => reading systems will be happy, but current UAs won't do much with it.

2- an html file like https://www.example.com/MobyDick/cover.html => current UAs will present something, but reading systems will have to extract the manifest from this html file or follow the link in the html file and fetch the manifest; which is a loss of time and CPU.

3- a directory like https://www.example.com/MobyDick/, with 3 conventions: -- a manifest file with a stable name (maybe manifest.json) is found at https://www.example.com/MobyDick/manifest.json; reading systems will use this convention. -- a presentation file with a stable name (maybe cover.html) is found at https://www.example.com/MobyDick/cover.html -- the web server must redirect https://www.example.com/MobyDick/ to https://www.example.com/MobyDick/cover.html, to allow current UAs to present something. => conventions can be fragile, configuring a web server for generic redirects is a burden.

Shouldn't we focus on these three potential solutions, list the pros and cons and choose the less problematic one?

[HadrienGardeur]

I don't think we need to discuss this at all. My take on this issue is the following:

• we can point a UA to any resource within the publication, there's no single point of entry on the Web today and there shouldn't be either for a Web Publication
• we need to have clear support for discovering a manifest (IMO this should be through <link> in HTML, Link: in HTTP and embedding the manifest using a <script> element)
• UAs that do not support WP specifically will simply ignore the manifest, and browse a Web Publication like any other resource on the Web
• WP aware UAs will be able to extract the manifest, use the self link to identify that publication (and use the URI directly to the manifest in the future) and provide a number of additional features based on the content of the manifest

I know that at least @baldurbjarnason agrees about this.

[HadrienGardeur]

I think two separate concerns are getting mixed up:

• the URL that identifies a Web Publication
• and the URL that provides access to a Web Publication

IMO, the URL that identifies a Web Publication should be the one where I can get the manifest directly. In the case of an embedded manifest this means a URL to an HTML resource, in the case of a standalone/external manifest this means whatever media type we end up using for the manifest.

To provide access to a Web Publication (link to it, share it), any resource within the publication should be acceptable. I strongly believe that we don't need the equivalent of the start_url in Web App Manifest for the same reason we don't need a scope either. With a declarative approach, we know exactly which resources are part of a publication and discovery makes it possible anyway to start reading a publication using any resource within the publication and not just the "first" one.

[murata2makoto]

Shouldn't we focus on these three potential solutions, list the pros and cons and choose the less problematic one?

I disagree in two points. First, we have to agree on desiderata. They have to be written down in a single document and discussed. Second, I do not think that there are only 3 potential solutions.

[baldurbjarnason]

Yeah, I very much agree with what @HadrienGardeur said in https://github.com/w3c/wpub/issues/5#issuecomment-314418003

The problem we're facing isn't 'how do we best represent publications using web tech?' That approach leads you down the road to ePub. The problem is 'how do we make publications a part of the web?' and that leads us down the road of using existing web conventions and patterns even when that's more complicated than inventing something new. Being able to reuse pre-existing, debugged code beats having to write new, hypothetically simple code.

Another dimension to this is that we at Rebus are interested in providing some sort of publication experience in the browser as a form of progressive enhancement. Not as in a browser-based UA (though, that's still an option we're considering in addition to this) but for example a simple script a publisher can include in their publication HTML pages. This would provide some form of navigation across the publication and maybe some reading tools (e.g. display customisation and possibly bundling services like Hypothesis).

This means we'll have to figure out a way to make the script not load in UAs that fully support web publications. But I'm not particularly worried about that (also, way down the road, tbh, and not something that needs solving right now). E.g. you could try detecting publication-specific APIs, provide a clear, machine-readable method for the UA to remove unnecessary scripts, or just a convention where UAs should feel free to remove all scripts from that particular location, or all of the above.

I mention this because this kind of progressive enhancement (lightweight, script-based reading UI in the browser, native reading UI in native UA that supports publications) can easily be made pretty hard to pull off if we make the wrong decision at this stage.

The directory method with conventions is fragile, contravenes the 'url is an identifier' tradition, and make progressive enhancement like this harder.

Scope, while an interesting approach, would make this sort of progressive enhancement harder because it's better matched to the event-based model of service workers (i.e. because SWs are scripts, designed around events, they don't need explicit listings).

Delivering publication metadata in an HTML file would make this sort of progressive enhancement harder. Fetching and parsing HTML for its data is more involved and has more pitfalls than fetching and parsing JSON.

However if you follow the current trends in the web stack where manifest-style info like this is provided via JSON and the relationship between the documents and the manifest are structured using links, the publication-parsing aspect of providing a progressively enhanced reading experience becomes almost trivial, letting people focus their resources on making a nice UX.

[murata2makoto]

I have a feeling that we are discussing too many things in this thread. In particular, we are discussing requirements and solutions together. Furthermore, different people have different assumptions or bias. I worry that this discussion goes nowhere.

I will try to create a list of desiderata, although I am not optimistic.

[mattgarrish]

a manifest file with a stable name

I don't like relying on file naming conventions in an uncontrolled environment like the web. They eventually collide with other uses. It also sounds inelegant to have to check with every request if there happens to be a file in the same directory.

A declarative statement that a resource belongs to a publication would be preferable, IMO. If done in the HTTP headers it wouldn't require the indirection of a link element. For the average document publisher who won't understand how to do this, or not be able to, we'll still need the embedded link element option.

and embedding the manifest using a Githubissues.

Githubissues is a development platform for aggregating issues.