Draft section describing format and markup of acquisition links

[GoogleCodeExporter]

(Going to fill this in)
Description of the background of this problem

Use cases are

Please note that any discussion should happen on the mailing list rather
than the comments of the issue tracker.

Mailing list threads should reference the number of any open Issue in the
Subject line " (#ISSUE)".

Original issue reported on code.google.com by abdela...@gmail.com on 10 Mar 2010 at 4:19

[GoogleCodeExporter]

Two things we'd like to continue to support:
* Allow clients to filter OPDS Catalog Entries by the available content types
* Allow clients to filter OPDS Catalog Entries based on the whether the 
Acqusition Link requires a web browser

Here are two related Use Cases:
21. Acquisition portals should be able to allow readers to acquire free titles 
via OPDS 
Catalogs (download) {KHF}
22. Acquisition portals should be able to allow readers to acquire titles with 
payment 
via OPDS Catalogs (vend) {KHF}

And another:
38. Catalogs should be able to support multiple, alternative acquisition 
scenarios for 
each publication

There have been quite a few discussions of how to represent this on the mailing 
list 
that should be reviewed.

Original comment by abdela...@gmail.com on 10 Mar 2010 at 6:32

[GoogleCodeExporter]

Original comment by liza31337@gmail.com on 3 May 2010 at 3:34

[GoogleCodeExporter]

Liza: Please contribute a rough draft of this section before the 8am Pacific 
call tomorrow, 5 May 2010.

Original comment by abdela...@gmail.com on 4 May 2010 at 6:14

[GoogleCodeExporter]

I'm not sure we reached consensus on the issue about "this link leads to an 
HTML page which eventually 
leads to an EPUB" and how that should be represented, but I'll review the last 
discussion on the mailing list.

Original comment by liza31337@gmail.com on 4 May 2010 at 6:24

[GoogleCodeExporter]

Some terminology (either for the terminology section or within Acquisition 
Relations):

==== Acquisition Types ====

Additional terminology describes the acquisition scenario for a particular 
publication:

  * "Direct acquisition" - The Acquisition Link will return the actual bytes of the publication when 
traversed.
  * "Indirect acquisition" - The Acquisition Link will lead to one or more intermediate content-types before 
the publication is acquired.

The most typical indirect acquisition scenario is a link to an HTML page which 
prompts a user for 
authentication and/or payment.  When the transaction is satisfactorily 
completed, the publication bytes 
are eventually returned.

Original comment by liza31337@gmail.com on 5 May 2010 at 2:05

[GoogleCodeExporter]

Actually, a direct acquisition link could also lead to an HTTP redirect instead 
of the 
file itself. Should we clarify this or would it make things too complicated ?

Original comment by hadrien....@gmail.com on 5 May 2010 at 3:12

[GoogleCodeExporter]

  * "Direct acquisition" - The Acquisition Link will return the actual bytes of the publication when 
traversed, either directly or via an HTTP method such as a 301 redirect.

Original comment by liza31337@gmail.com on 5 May 2010 at 3:14

[GoogleCodeExporter]

Added a variant of the above to the spec draft under Terminology.

Original comment by liza31337@gmail.com on 6 May 2010 at 2:57

[GoogleCodeExporter]

In *Element Definitions*:

=== Acquisition Scenarios ===

In all "atom:link" elements with a rel attribute beginning 
"http://opds-spec.org/acquisition", the "type" 
attribute MUST be present and contain the media-type that will be encountered 
when the value of the 
"href" attribute is dereferenced.  The media-type value MUST conform to the 
syntax of a MIME media type 
[MIMEREG].

In a direct acquisition scenario, the "type" attribute on "atom:link" will 
contain the media-type of the 
publication.  The "atom:link" element MAY contain a "dc:format" element with 
the same media-type value, 
but in this scenario it is optional.

In an indirect acquisition scenario, the "type" attribute on "atom:link" MUST 
be present and contain the 
media-type of the target of the link.  The "atom:link" element MUST contain a 
"dc:format" element which 
describes the media-type of the publication which will ultimately be returned 
from a successful 
transaction.

OPDS Catalog clients which support only a subset of all possible publication 
types will need to filter on 
both "atom:link/@type" values for direct acquisition scenarios, as well as 
"atom:link/dc:format" elements 
for indirect acquisition scenarios, if supported.  OPDS Catalog clients MAY 
support indirect acquisition.

Original comment by liza31337@gmail.com on 6 May 2010 at 3:15

[GoogleCodeExporter]

Note that the above is different from the RNC fragment in "atom:link": 
http://code.google.com/p/openpub/wiki/CatalogSpecDraft?
ts=1273157781&updated=CatalogSpecDraft#The_"atom:link"_Element

...in which dc:format is listed as required in all cases.

Original comment by liza31337@gmail.com on 6 May 2010 at 3:16

[GoogleCodeExporter]

Re: use case 38:

Is there any reason not to require just one dc:format per indirect acquisition 
link?  Even if all the atom:link 
@hrefs resolve to the same host, it would simplify things if we required:

[atom:link href="http://ebooks-r-us.com/bundle" type="text/html"]
[dc:format]application/epub+xml[/dc:format]
[/atom:link]

[atom:link href="http://ebooks-r-us.com/bundle" type="text/html"]
[dc:format]application/pdf[/dc:format]
[/atom:link]

[atom:link href="http://ebooks-r-us.com/bundle" type="text/html"]
[dc:format]some-format[/dc:format]
[/atom:link]

rather than tried to specify something more complex.

Original comment by liza31337@gmail.com on 6 May 2010 at 4:06

[GoogleCodeExporter]

For indirect acquisitions, I agree that we SHOULD ask for at least one 
dc:format.

Original comment by hadrien....@gmail.com on 6 May 2010 at 4:10

[GoogleCodeExporter]

Original comment by abdela...@gmail.com on 10 May 2010 at 2:37

• Changed state: Started

[GoogleCodeExporter]

I added a whole bunch of examples, which I'd encourage folks to review, but 
what I'd really like is comments on the 
way I wrote up the acquisition thing.

You can see the whole diff here: 
http://code.google.com/p/openpub/source/diff?
spec=svn231&r=231&format=side&path=/wiki/CatalogSpecDraft.wiki

+= Acquiring Publications =

+The goal of OPDS Catalogs is to make Publications both discoverable and 
straightforward to acquire on a range of 
devices and platforms. To support that goal, this specification strives to 
provide a framework for describing how a 
Publication may be acquired while not attempting to constrain this very complex 
topic. Commonly-used acquisition 
scenarios may be specified in an update to this specification.

+All Acquisition Links MUST include a "type" attribute that advises clients on 
the media type of the representation 
that is expected to be returned when the value of the href attribute is 
dereferenced. Publications employing Digital 
Rights Management MUST include the drm parameter. See the Section The OPDS 
Catalog DRM Parameter. As with 
Atom, the value of the type attribute MUST conform to the syntax of a MIME 
media type `[MIMEREG]`.

+If the Publication is available using Direct Acqusition, the type attribute of 
the Acqusition Link MUST represent the 
media type of the Publication Resource itself. These Acquisition Link elements 
MAY contain a "dc:format" element, 
but in this scenario it is optional. For Acqusition Links using Direct 
Acqusition, the dc:format element MUST contain 
the same content value as the type parameter of its parent.

+If the Publication is available using Indirect Acqusition, the type attribute 
of the Acqusition Link SHOULD represent 
the media type of the first Resource a client must dereference to begin the 
acqusition. These Acqusition Link 
elements MUST contain one or more "dc:format" elements which describe the media 
type(s) of the Publication 
Resource(s) that will be available following a successful acqusition. This 
scenario may require human interaction to 
complete.

+OPDS Catalog clients may only support a subset of all possible Publication 
media types. These clients will need to 
filter both the type attribute and dc:format children of Acqusition Links to 
support both Direct and Indirect 
Acqusition. Support for Indirect Acqusition is OPTIONAL.

===

+  * atom:link elements with a rel attribute of 
"http://opds-spec.org/acquisition", "http://opds-
spec.org/acquisition/borrow", "http://opds-spec.org/acquisition/buy", 
"http://opds-
spec.org/acquisition/sample", or "http://opds-spec.org/acquisition/subscribe" 
MAY contain one or more dc:format 
elements.
svn s

===

+The simplest case is a Publication available by Direct Acquisition in one 
format:

+{{{
+  <link type="application/x-mobipocket-ebook" 
+        rel="http://opds-spec.org/acquisition" 
+        href="/content/free/4561.mobi"/>
+}}}

+If the Publication was available in multiple formats as unique Resources, they 
would simply be listed:

+{{{
+  <link type="application/x-mobipocket-ebook" 
+        rel="http://opds-spec.org/acquisition/borrow" 
+        href="/content/borrow/4561.mobi"/>
+  <link type="application/epub+zip" 
+        rel="http://opds-spec.org/acquisition/borrow" 
+        href="/content/borrow/4561.epub"/>
+}}}
+
+If the Publication is only available in a format with DRM, that parameter is 
added to the type attribute:
+
+{{{
+  <link type="application/pdf;drm=ns.adobe.com#adept"
+        rel="http://opds-spec.org/acquisition/sample" 
+        href="/content/samples/4561.pdf"/>
+}}}
+
+If the Publication is available using Indirect Acqusition, a dc:format element 
is required:
+
+{{{
+  <link type="text/html" 
+        rel="http://opds-spec.org/acquisition/sample"
+        href="/product/9781449381806.EBOOK/sample">
+    <dc:format>application/pdf</dc:format> 
+    <dc:format>application/x-mobipocket-ebook</dc:format> 
+    <dc:format>application/epub+zip</dc:format> 
+  </link> 
+}}}
+
+If the Publication is requires payment, an opds:price element is required:
+
+{{{
+  <link type="text/html" 
+        rel="http://opds-spec.org/acquisition/buy"
+        href="/product/9781449381806.EBOOK/buy">
+    <dc:format>application/pdf</dc:format> 
+    <dc:format>application/x-mobipocket-ebook</dc:format> 
+    <dc:format>application/epub+zip</dc:format> 
+    <opds:price currencycode="USD">17.99</opds:price> 
+  </link> 
+}}}
+

Original comment by abdela...@gmail.com on 13 May 2010 at 7:07

• Added labels: Priority-Critical
• Removed labels: Priority-Medium

[GoogleCodeExporter]

No blocking comments received.

Original comment by abdela...@gmail.com on 21 May 2010 at 5:27

• Changed state: Done

[GoogleCodeExporter]

Original comment by abdela...@gmail.com on 25 May 2010 at 5:44

• Added labels: Milestone-Release0.9