{"action":"created","issue":{"url":"https://api.github.com/repos/w3c/wpub/issues/94","repository_url":"https://api.github.com/repos/w3c/wpub","labels_url":"https://api.github.com/repos/w3c/wpub/issues/94/labels{/name}","comments_url":"https://api.github.com/repos/w3c/wpub/issues/94/comments","events_url":"https://api.github.com/repos/w3c/wpub/issues/94/events","html_url":"https://github.com/w3c/wpub/issues/94","id":272078084,"number":94,"title":"What does a WPub URL resolve to?","user":{"login":"prototypo","id":824236,"avatar_url":"https://avatars0.githubusercontent.com/u/824236?v=4","gravatar_id":"","url":"https://api.github.com/users/prototypo","html_url":"https://github.com/prototypo","followers_url":"https://api.github.com/users/prototypo/followers","following_url":"https://api.github.com/users/prototypo/following{/other_user}","gists_url":"https://api.github.com/users/prototypo/gists{/gist_id}","starred_url":"https://api.github.com/users/prototypo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/prototypo/subscriptions","organizations_url":"https://api.github.com/users/prototypo/orgs","repos_url":"https://api.github.com/users/prototypo/repos","events_url":"https://api.github.com/users/prototypo/events{/privacy}","received_events_url":"https://api.github.com/users/prototypo/received_events","type":"User","site_admin":false},"labels":[{"id":681866629,"url":"https://api.github.com/repos/w3c/wpub/labels/general%20structure","name":"general structure","color":"fbca04","default":false},{"id":664431230,"url":"https://api.github.com/repos/w3c/wpub/labels/priority:high","name":"priority:high","color":"f9d0c4","default":false},{"id":640757053,"url":"https://api.github.com/repos/w3c/wpub/labels/topic:identifiers","name":"topic:identifiers","color":"bfd4f2","default":false},{"id":640758057,"url":"https://api.github.com/repos/w3c/wpub/labels/topic:manifest","name":"topic:manifest","color":"1d76db","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":78,"created_at":"2017-11-08T05:22:35Z","updated_at":"2017-11-14T17:30:57Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"# Problem Statement\r\n\r\nWe have decided that a WPub with be identified with a URL. What should that URL resolve to?\r\n\r\nThis issue suggests four scenarios and evaluates their ramifications in the hopes of driving toward consensus. A conclusion section at the bottom of this post suggests an answer to the question posed.\r\n\r\n# Scenarios\r\n\r\nThe working group has considered several possible answers to this question. They mostly fall into one of four scenarios:\r\n\r\n1. A WPub URL resolves to a JSON manifest file\r\n2. A WPub URL resolves to an HTML file that contains both a table of contents (TOC) and other metadata\r\n3. A WPub URL resolves to an HTML file containing a TOC and which links to a JSON manifest file\r\n4. A WPub URL resolves to a binary package (e.g. a ZIP file or SQLite database file)\r\n\r\nEach of these scenarios are considered in turn as they would be viewed by four types of clients:\r\n\r\n- An existing search engine bot\r\n- A WPub aware search engine bot\r\n- A reader using an existing user agent\r\n- A reader using a WPub aware user agent\r\n\r\n## Scenario 1: JSON Manifest\r\n\r\nIf a WPub URL resolves to a JSON manifest file, the four clients may be expected to act like this:\r\n\r\n- An existing search engine bot (path 1A in the image below) will not index JSON files.\r\n- A WPub aware search engine bot (path 1B in the image below) will need to index all JSON files on the Web to determine which ones represent WPubs.\r\n- A reader using an existing user agent (path 1C in the image below) will be presented with a raw JSON representation.\r\n- A reader using a WPub aware user agent (path 1D in the image below) will be able to see and operate upon the WPub as intended.\r\n\r\nScenario 1 seems inconvenient for both old and new clients with the exception of new WPub aware user agents.\r\n\r\n![wpub-canonicalresourcejson](https://user-images.githubusercontent.com/824236/32531863-3599fdee-c3fb-11e7-8d93-e2261c34278c.png)\r\n\r\n## Scenario 2: HTML TOC & Metadata\r\n\r\nIf a WPub URL resolves to an HTML file that contains both a table of contents (TOC) and other metadata, the four clients may be expected to act like this:\r\n\r\n- An existing search engine bot (path 2A in the image below) will encounter and index the HTML page without modification.\r\n- A WPub aware search engine bot (path 2B in the image below) will be able to determine that the HTML page represents a WPub, but will need to parse the entire file in a WPub-specified manner to extract metadata.\r\n- A reader using an existing user agent (path 2C in the image below) will see a TOC containing links to the components of the WPub.\r\n- A reader using a WPub aware user agent (path 2D in the image below) will be able to see and operate upon the WPub as intended.\r\n\r\n![wpub-canonicalresourcehtml](https://user-images.githubusercontent.com/824236/32531901-774e1a5e-c3fb-11e7-92b9-420a266c7a5d.png)\r\n\r\nScenario 2 would be handled cleanly for old and new clients, but could cause difficulties when old clients are presented with metadata they cannot understand. There is also some danger of overloading or stretching the use of HTML to define the necessary metadata within an HTML document. New clients would need to parse the metadata out of the HTML to operate upon it.\r\n\r\n## Scenario 3: HTML TOC & JSON Manifest\r\n\r\nIf a WPub URL resolves to an HTML file containing a TOC and which links to a JSON manifest file, the four clients may be expected to act like this:\r\n\r\n- An existing search engine bot (path 3A in the image below) will encounter and index the HTML page without modification.\r\n- A WPub aware search engine bot (path 3B in the image below) will be able to determine that the HTML page represents a WPub, and follow the provided link to the metadata if it wishes.\r\n- A reader using an existing user agent (path 3C in the image below) will see a TOC containing links to the components of the WPub.\r\n- A reader using a WPub aware user agent (path 3D in the image below) will be able to see and operate upon the WPub as intended.\r\n\r\n![wpub-canonicalresourcehtmljson](https://user-images.githubusercontent.com/824236/32531914-8e03df40-c3fb-11e7-8ab0-59319829a0d0.png)\r\n\r\nScenario 3 seems to cleanly handle old and new clients in appropriate ways. Old clients could follow their noses to the components of a WPub, and new clients could easily load the JSON object to efficiently access metadata.\r\n\r\n## Scenario 4: Binary WPub\r\n\r\nIf a WPub URL resolves to a binary file, the four clients may be expected to act like this:\r\n\r\n- An existing search engine bot (path 4A in the image below) will either be aware of the MIME type for the binary file and attempt to handle it in an inappropriate manner, or it will need to be modified to handle a new MIME type.\r\n- A WPub aware search engine bot (path 4B in the image below) will either be confused by the overloading of an existing MIME type, or handle a new MIME type correctly.\r\n- A reader using an existing user agent (path 4C in the image below) will probably be asked to download the binary.\r\n- A reader using a WPub aware user agent (path 4D in the image below) will either be confused by the overloading of an existing MIME type, or handle a new MIME type correctly.\r\n\r\nScenario 4 could lead to confusion for both old and new clients unless a new MIME type is registered.\r\n\r\n![wpub-canonicalresourcebinary](https://user-images.githubusercontent.com/824236/32531923-9e4066f8-c3fb-11e7-8704-7c8c214c14c2.png)\r\n\r\n# My Conclusion\r\n\r\nGiven the various pros and cons, **Scenario 3** (the URL to a WPub resolves to an HTML TOC document, which in turn links to a JSON manifest) seems to most easily interoperate with the existing Web and provides a clean upgrade path to WPub-aware clients.\r\n\r\n# Acknowledgements\r\n\r\nThanks to @BigBlueHat @TzviyaSiegman @iherman @tcole3 @bdugas @GarthConboy and others from the Publishing WG for discussions which led to this issue and its discussion."},"comment":{"url":"https://api.github.com/repos/w3c/wpub/issues/comments/344335215","html_url":"https://github.com/w3c/wpub/issues/94#issuecomment-344335215","issue_url":"https://api.github.com/repos/w3c/wpub/issues/94","id":344335215,"user":{"login":"BigBlueHat","id":43209,"avatar_url":"https://avatars1.githubusercontent.com/u/43209?v=4","gravatar_id":"","url":"https://api.github.com/users/BigBlueHat","html_url":"https://github.com/BigBlueHat","followers_url":"https://api.github.com/users/BigBlueHat/followers","following_url":"https://api.github.com/users/BigBlueHat/following{/other_user}","gists_url":"https://api.github.com/users/BigBlueHat/gists{/gist_id}","starred_url":"https://api.github.com/users/BigBlueHat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/BigBlueHat/subscriptions","organizations_url":"https://api.github.com/users/BigBlueHat/orgs","repos_url":"https://api.github.com/users/BigBlueHat/repos","events_url":"https://api.github.com/users/BigBlueHat/events{/privacy}","received_events_url":"https://api.github.com/users/BigBlueHat/received_events","type":"User","site_admin":false},"created_at":"2017-11-14T17:30:56Z","updated_at":"2017-11-14T17:30:56Z","author_association":"MEMBER","body":"👍 to pushing ahead with #101 and making that the foundation going forward.\r\n\r\nOnce #101 is merged, I'd consider this particular issue closed and new ones (about All The Things) can be filed separately.\r\n\r\nGreat work as ever @mattgarrish!"}}
{"actor":{"display_login":"BigBlueHat"}}