-
Notifications
You must be signed in to change notification settings - Fork 19
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Proposed changes / additions to WAM #127
Comments
Off the top of my head, here is one possible breakdown of issues—which admittedly consists mostly of questions so might not be particularly helpful:
Even though we have discussed many of these questions before, it seems likely that they will have to be re-litigated, so to speak, due to the change in constituency. That is, when you add a bunch of people from Web Platform Working Group to the discussion you can't trust that prior consensus will hold. WAM has pre-existing stakeholders who need to be a part of the discussion before we decide what specific changes need to be made to the WAM spec. We also need to be open to the idea that some of these features will have to be primarily implemented as open source scripts on top of the web platform and don't need to be baked into the platform itself. Offline and reading order specifically look like issues that could be entirely solved by scripts. Possibly even the ToC. Linking to extended metadata could be done from the start_url without having to extend the WAM. Anyway, apologies for mostly having questions at this point. |
@baldurbjarnason those might be best filed as separate issues pointing here--as it's unlikely we can address all of them in a single issue. 😃 I think @TzviyaSiegman was looking for actionable proposals for changes and/or extensions to the Web App Manifest format and processing. |
Thanks @baldurbjarnason, but I was hoping we could identify individual items in WAM that we might need to change or expand upon. Would it be possible to point to specifics in WAM? I don't think (for example) that offline is a WAM issue. |
One key extension point that seems easy to imagine is an new value for the That property provides a statement of desired UX expectations. Current values are: One might imagine a |
Based on @HadrienGardeur's work on #118, we would recommend adding The creator member can appear 0 or more times and should be modeled on existing creator structures such as http://dublincore.org/documents/dcmi-terms/#elements-creator or http://schema.org/creator |
On adding a new value for the display member property: I worry that tying too many UI affordances to a single web app display mode will be unpopular because then you bring modality back to HTML itself. WAM display modes are more about dictating the chrome provided by the browser, leaving mode-relevant styling and behaviour up to the website itself using things like the display-mode media query. We might have more success with proposing a display-mode that only affects browser chrome (no page progression, state storage or the like). As in, the only change would be a change in display-mode that the website can detect and then implement publication things itself, as well as a button in the chrome that toggles you to and back from the ToC for that specific resource. The ToC could even be dictate on a resource by resource basis using a Couple that with In many ways such a solution would be independent to a more fully featured manifest like the Readium manifest. We could use something based on the Readium manifest format to configure the publication scripts and provide a long-term pathway towards specifying more publishing-oriented formats that aren't be directly tied to service workers and the WAM, like EPUB4. |
Further comments based on #118: |
This is not a proposal to move forward with this method. But, if we do propose changes to WAM, this is a place to list and discuss there merits. Please discuss whether to work with WAM in #32 |
@TzviyaSiegman |
WAM has an existing extension mechanism. (It also used to use JSON-LD, which is instrinsically extensible, but that was removed a while back.) For each missing use case here, WAM’s existing extension mechanism should be considered, versus modifying the WAM format itself. If the mechanism is inadequate, then requesting changes to the mechanism to make it more powerful may also be an option. |
First a note: Too bad that the JSON-LD extension mechanism (a W3C reco, part of the Web) was removed, it would be given clear guidelines for modeling extensions. The first evolution we could request would be to add a categorization property (which could be called "type") that will trigger specific behaviors of the user agent like:
Rationale: As a user, I want to be able to catalog publications in a specific screen of my user agent, which can be called a 'bookshelf'. I want to be able to classify, filter, sort publications using their exposed metadata. Opening a publication should trigger a reader mode, which will use my preferred user settings (font size etc., selected once for all publications I will read). |
The second evolution we must request is enhancement of the i18n feature of WAM. As expressed by our Japanese colleagues, even in an online environment where a query can request a selected language, several string properties - like the title of a publication - must be provided with alternative scripts: We've got 2 open issues on the subject: and ps: this is not related to the WAM use-case (online only), but we consider the manifest as a constituent of EPUB 4, i.e. a generic interchange format. In this use case, the capability to support N alternative languages expressions in one publication is a PWP must (and should be explicitly stated in the PWP requirement, by the way). |
I'm still working on the lifecycle branch of this repo, but @TzviyaSiegman do you want me to summarize all the things I've listed in #118 in a single Markdown document? I went through our infoset elements one by one, this should in theory cover all proposed additions/changes to the WAM. |
Like @js-choi said, WAM has an existing extension mechanism, so we need to think about where this can be used, and where this cannot. Basically, WAM’s extension model allows us to define new manifest members (and their processing logic). It doesn’t allow us to modify current members’ values, nor to change the obtaining/processing/applying/updating logic; we have to devise whether we’d need extending these non-extensible-by-design things, and where. My take on what we can envision: Possible changes in current WAM members
Possible new members
Extensions to the lifecycle?I’m not sure if we need any, TBD. For instance, Applying the manifest says the manifest is applied to a top-level browsing context, maybe that needs to be extended/modified to cater to reading systems’ requirements? (edited to add reading order and toc) |
Regarding the The At best, this could trigger the current reader mode available in browsers and enable affordances for user styles and TTS. |
@rdeltour can you detail what can be expected from the |
@rdeltour, I agree this is not about WAM modifications per se, but you omit to say that in we would still have to define the publication lifecycle, i.e. how a "publication" user agent must handle reading order, user settings, side-toc, pagination modes ... what make the reading experience specific. Not a small work, and we have to do it in any case. |
I absolutely agree,
Basically what the WAM says about
I would hope that viewing the publication in the browser would always be a reasonable fallback rather than showing a "no support" message!
Oh, absolutely. But as you say 1. it’s not the topic of this thread and 2. we have to do that anyway, so it’s not really an argument in favor or against using WAM (except for the part where WAM may provide a framework for this lifecycle logic). |
@rdeltour, thanks for the list. I believe we really ought to have a consensus on such list. Three things I would like to add/comment.
These are all normative additions or (slight) changes to the WAM spec. The translation of no. 3.i above into JSON is documented in the string-meta draft, and we also got to the same conclusion in #124. |
@iherman I agree with most of your suggestions, especially 1. and 3. Re. 2., I hope we are both in sync: we are designing a format which must be allow users to categorize, filter, sort publications locally (client-side). The format must therefore handle locally (in the manifest) metadata deemed as necessary for such functionalities. Only linking to external metadata (e.g. Onix, a B2B vocabulary) would a blocker for EDRLab. |
I may add that the ONIX for Books community has been already working on a schemo.org expression. So it's complexity may be somehow tamed with the help of schema.org in WPUB. |
@laudrain yes, but a schema.org version of ONIX may still be pretty huge... |
@llemeurfr hope we are sync indeed... JSON(-LD) being extensible, it is indeed possible to add additional metadata into the manifest (unless the WAM explicitly disallows it). However, we may have metadata that contains hundreds of terms, and it should be possible to add a "link" into the main manifest towards a dedicated, say, ONIX file that could then be retrieved separately and still processed on the client side. Is this a problem? If so, why exactly? |
@iherman, our perception is that Web Publications must define the minimal set of standard metadata useful for user manipulation (categorize, filter, sort) of Web Publications. We all know that interoperability matters: a link to "other" structures (ONIX, MARC ...) is a very useful extension mechanism, but does not bring much in terms of usage interoperability. Browser vendors will easily implement a minimal set of metadata, useful for end users. They will not implement the hundreds of ONIX terms, most of them crafted for another audience than the standard user, and they should not have to pick and choose by themselves some terms in such a rich vocabulary. |
@llemeurfr I think we are in sync. Obviously, there is a minimal set of metadata that we define (essentially the infoset, maybe some more that are missing) and those are part of the manifest. But we should probably keep that list relatively small. However, we must have the possibility in the manifest (and that may require an extension to the WAM) to link to the ONIX, MARC, etc. data. I believe we are saying the same thing:-) |
Do we really need this in the manifest, or could it be in the start_url file? (e.g., embedded or via link/@type=meta) The further away this information is from search crawlers, the more likely it's going to lead to duplication, or simply be done the way that is more effective for search. Might be a useful compromise if this information isn't critical for processing the manifest. |
@mattgarrish to take your words, the further away it is from the user agent, the more likely the user agent developer will not process it at all. |
If the information isn't important enough to be included as a manifest property, then what does that matter? What epub reading system uses linked records after all these years? The application that's more likely to use metadata like you'd express in schema.org or ONIX is a search engine. Also, if the web page that links to the manifest also contains/links to the metadata, why is it all the unlikely that the user agent will process one but not the other? |
@mattgarrish it seems that we don't understand each other. I'm saying, and @iherman is in sync with it, that there is a required set of metadata in the publication manifest (= the metadata part of the infoset currently under definition). These are the metadata useful for categorizing, filtering, sorting their personal bookshelf (call it a local search engine if you like). Links to other sets of metadata are an extension mechanism. But this discussion should not be continued in an issue that is about potential changes to the WAM. |
Updated version would look something like this:
|
@HadrienGardeur, you asked
I would prefer not, for purely admin reasons. Creating a separate document means, formally, have a new FPWD on a separate document, which leads to extra admin complications (re IPR policy). Let us try to keep everything in a single document for now. (Sorry for the late reply.) |
Here's a more detailed version of what I posted above then... 1. As-is
We can also use 2. Changes2.1. i18nTwo members from the WAM could be useful for the WP manifest if they added support for i18n: Both members are currently using a
2.2. Media type registrationThe current media type registration for Considering the large number of additions that our infoset requires, it would make a lot of sense to have a 3. Additions3.1. LinksThe current draft for WAM does not contain any generic element meant to represent links. The closest thing from a link is the The following requirements from our infoset could all rely on the same
This new 3.2. Default reading order and list of resourcesNone of the current members of the WAM are a good fit for core building blocks of the WP manifest: the default reading order and the list of resources. We would need to introduce two new members to the WAM: Like 3.3. TimestampsThe WP infoset contains two different timestamps: the publication date and the last modification date. Both of them would have to be added to the WAM, for example using 3.4. ContributorsListing contributors/creators is a very common requirement for publications, also expressed in our infoset. The WAM does not contain any element to indicate the creator of a Web App. We haven't discussed yet how roles should be expressed in our infoset, but we'll need to at least introduce one new member ( 3.5. Canonical identifierOur canonical identifier could be expressed using the new 3.6. Flag as publicationThe addition of a IMO this can't be handled by |
We will also need to consider the Navigation scope section. Currently, any link not "within scope" will open in the default browser and not in the customized browser launched by the icon made by the WAM. |
Right, navigation scope for a Web Publication would be quite different. Within scope for a WP = part of the reading order or list of resources |
Thanks, @HadrienGardeur. This is really helpful. I have some questions:
Would this mean that we would be losing some of the Native functionality of web app manifest? Would UAs even recognize our media-type?
|
My (personal) opinion is that we should limit ourselves to items "within scope" now. We may be able to expand in the future, but we cannot do everything at once. Let's figure out how to publish a single origin publication first. |
@TzviyaSiegman understand. It's just a current change from our current spec. Our current spec text uses the reading order list as the "scope" whereas WAM restricts them to sub-URLs of the value of If the Side note: this is only navigational scope, so presumably one could "fake" the navigation using |
With regard to @HadrienGardeur’s #127 (comment), where would readopting JSON-LD (as suggested by @iherman in #127 (comment)) be raised? Would it be in § 2.1 i18n and § 3.1 Links, or its own section? For what it’s worth, at least one developer (@hsivonen) of a major UA vendor (@mozilla) has expressed antipathy toward JSON-LD and implementing standards that use it (see mozilla/standards-positions#44 (comment) and “No Namespaces in JSON, Please”, 2017-05), even when processing for JSON-LD per se is not required (see 2017-05 article’s final section, “But You Can Ignore the Complexity!”). This may have ramifications for vendor inclination toward changes toward JSON-LD in WAM and, indeed, cross-browser implementation of any web standard that includes JSON-LD. |
@js-choi I've listed what I consider to be "must have" requirements to align with our current infoset. Support for JSON-LD IMO falls in a different category: "good to have". This would require support for JSON-LD is already widely implemented on the Web and it's pretty much a requirement for AMP as well. Our own use of JSON-LD would not require browsers to know anything about RDF, since the document would be parsable as normal JSON. |
@js-choi, maybe we should have a clear idea first on which terms we would have and which of those are really important in terms of JSON-LD metadata. The main argument for JSON-LD is that it links the manifest data to the Linked Data world, e.g., it potentially adds the metadata to the various knowledge graphs that are built on top of schema.org. Some of the manifest data, like the reading order, are not really relevant, for example. By having a clear idea on the terms we can build a better case for this. |
I don't think it would, but it's up to the browser to implement different behaviors. Right now, the WAM relies exclusively on the |
That should be enough reasons to disregard such antipathy in technical discussions (even when coming from a rather well-known developer of a well-known organisation). |
Antipathy toward technologies like XML, RDF (and especially RDF/XML), JSON (I also met people who hated HTML by the way) usually come from a lack of understanding of their "best playground", even when it's the position of very smart people.
As Ivan said in this thread, before putting forward a request for the WAM to adopt JSON-LD, as a "good to have", we'd better list & detail why we think it would be a good idea.
Ivan proposed that "The main argument for JSON-LD is that it links the manifest data to the Linked Data world, e.g., it potentially adds the metadata to the various knowledge graphs that are built on top of schema.org <http://schema.org/>."
But this may be very abstract to many people. I would suggest we put also forward also that:
- it offers the ability to model a JSON structure in a non ad-hoc way, therefore offers a cleaner model of extensibility (Hadrien already gave details about this and the RWPM is an expression of it).
- it offers the ability to annotate strings with their language (it should also offer a way to add directionality) and create multi-lingual properties (like the title) -> i18n compliance.
- it is a W3C standard (JSON is not).
and a JSON structure can be made JSON-LD compliant with minimal changes (in our case this is a MUST, e.g. we shouldn't propose that dates have an explicit dateTime type etc.)
Cordialement,
Laurent Le Meur
EDRLab
… Le 6 févr. 2018 à 21:31, Andreas Kuckartz ***@***.***> a écrit :
@js-choi <https://github.com/js-choi> For what it’s worth, at least one developer (...) of a major UA vendor (...) has expressed antipathy toward JSON-LD and implementing standards that use it (...), even when processing for JSON-LD per se is not required
That should be enough reasons to disregard such antipathy in technical discussions (even when coming from a rather well-known developer of a well-known organisation).
|
wrt i18n:
Maybe there’s an alternative solution to provide i18n support in a separate member (e.g. in a new See also the ongoing discussion on this issue by the TAG. |
@rdeltour I'd rather have our own |
Having spent some times reading through the WAM spec again, I have hit some questions. Maybe somebody can answer those:
I tried to find examples on the Web for Web Apps + WAM that also use the It may very well be that I missed something in the spec. Cc: @baldurbjarnason @rdeltour ? |
The User Agent. See also the note in "Conformance"
it isn’t (not mandated by the spec, and I don’t think it’s exposed by any UA).
The UA runs the script, as part of the installation process. The SW has no access (by API) to the processed manifest, but can always load it as JSON. |
Thanks @rdeltour. I was a bit afraid that this would be the answer:-( However, how can the WAM be used for our purposes then? I mean, we can of course reuse the vocabulary, but the full processing of the WAM, and the resulting structures, are unreachable for any script that we may need. Put it another way, any script we would need would have to reproduce those implementation steps... Or do I miss something? |
I think we will only be able to answer that question when "our purposes" is better defined, which is why several of us think we first have to work on affordances :-) In any case, I see WAM as part of the solution, and not the only thing that will solve it all. |
From Edge Feedback: |
Thanks @BCWalters for the feedback from the Edge team, we really need to figure things out with browsers on this one.
I don't think that we're currently expecting Web Publications to be installed side by side with Web Apps and we're clearly not thinking about making WPs responsible for their own offline experience either (we expect WPs to provide declarative information instead of defining their own caching logic based on a Service Worker).
We've talked about extensions as valid UAs before alongside browsers themselves or dedicated reading apps. |
Based on our decision on WAM, this issue is obsolete, and can be closed |
In #32 we discuss many reasons why Web App Manifest should or should not be extended. Let's use this issue to propose changes or extensions that PWG requires in order for us to adopt it for WPUB.
The text was updated successfully, but these errors were encountered: