Merge pull request #138 from IIIF/0008-rights

Recipe #8 — Rights

_includes/links.md

@@ -4,6 +4,7 @@
 [0002]: {{site.baseurl}}/recipe/0002-mvm-audio/ "Simplest Manifest - Audio"
 [0003]: {{site.baseurl}}/recipe/0003-mvm-video/ "Simplest Manifest - Video"
 [0007]: {{site.baseurl}}/recipe/0007-string-formats/ "Embedding HTML"
+[0008]: {{site.baseurl}}/recipe/0008-rights/ "Rights"
 
 [0068]: {{site.baseurl}}/recipe/0068-newspaper/ "A newspaper"
 

index.md

@@ -31,7 +31,7 @@ _The corresponding 2.1 test fixture(s) is given like this, where appropriate: ..
 * Image Service for single image (24,25)
 * Multiple values and languages (3,4,6)
 * [Embedding HTML in descriptive properties][0007] (64)
-* Rights statement(s) (7)
+* [Rights statement\(s\)][0008] (7)
 * thumbnail algorithm / discussion
 * Book (simplest, > 1 canvas) (19)
 * Book (viewingDirection variations) (11,12,13,14)

recipe/0008-rights/index.md

@@ -1,44 +1,43 @@
 ---
-title: Rights Statements
+title: Rights statement
 id: 8
 layout: recipe
-tags: [tbc]
-summary: "tbc"
+tags: [text, presentation]
+summary: "You want to assert a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image."
 ---
 
+## Use Case
 
+You are able to implement the inclusion of a license, rights, or other important statement about a resource (e.g. a Manifest's JSON or an image's pixels) by using the `rights`, `requiredStatement`, and `metadata` properties. This recipe will focus on the first two; see [the Presentation 3.0 spec on `metadata`](https://iiif.io/api/presentation/3.0/#metadata) for more information about that property.
 
-## Use Case
+While you may use `rights` and `requiredStatement` similarly for the function of asserting certain important information (e.g. reproduction rights, ownership, collection name), the properties do have material differences. These are the most salient:
++ **Content**: The `rights` value must be a Creative Commons license URI, a RightsStatements.org URL, or added through the extension process. The `requiredStatement` value, on the other hand, can be any content, such as a copyright or institutional URI or text.
++ **Rendering**: Clients must render `requiredStatement` content on every resource type (even if hidden at first), but `rights` content may or may not be rendered visibly.
++ **Property Value**: The `rights` property value must be a string, and must be a URI defined by Creative Commons or RightsStatement.org if you are using one of those specifications. On the other hand, the `requiredStatement` value must be a single JSON object with `label` and `value` properties; `metadata` values must be an array of JSON objects, where each object has the `label` and `value` properties.
++ **Resource Applicability**: Any resource type may have `rights` or `requiredStatement`. However, `rights` is only for license or rights to the resource, while `requiredStatement` can be any text the publishing organization deems critical to display to the user.
 
-Why is this pattern is important?
+If user visibility of the information or a publisher-defined label is paramount, use `requiredStatement` or `metadata`. Resources may include all three properties.
 
 ## Implementation notes
 
-How does one implement the pattern?
+Because the `rights` property may not necessarily be visible to the user, it should be considered primarily machine-oriented. Therefore, URIs in this property should use target entities' machine-actionable URIs and their appropriate protocols. In the cases of Creative Commons licenses or RightsStatements.org statements, those protocols are HTTP, not HTTPS. Note, though, that clients may rewrite the content to use HTTPS if and as the URIs are made visible to users.
+
+Conversely, since `requiredStatement` values must be displayed or easily displayable to the user, URIs in this property should use target entities' human-readable URIs. For Creative Commons licenses or RightsStatements.org statements, URIs for human-readable content use HTTPS.
 
 ## Restrictions
 
-When is this pattern is usable / not usable? Is it deprecated? If it uses multiple specifications, which versions are needed, etc.? (Not present if not needed.)
+None known.
 
 ## Example
 
-Describe in prose and provide examples, e.g.: 
+{% include manifest_links.html viewers="UV, Mirador" manifest="manifest.json" %}
 
-``` json-doc
-{
-  "@context": [
-    "http://www.w3.org/ns/anno.jsonld",
-    "http://iiif.io/api/presentation/{{ page.major }}/context.json"
-  ],
-  "id": "https://example.org/iiif/book1/manifest",
-  "type": "Manifest" 
-}
-```
+{% include jsonviewer.html src="manifest.json" config='data-line="15-27"' %}
 
 # Related recipes
 
-Provide a bulleted list of related recipes and why they are relevant.
-
+* [Simplest Manifest - Single Image File][0001]
+* [Embedding HTML][0007] (Nearly identical manifest, but focusing on a different part of the spec.)
 
 {% include acronyms.md %}
 {% include links.md %}

recipe/0008-rights/manifest.json

@@ -0,0 +1,48 @@
+{
+    "@context": "http://iiif.io/api/presentation/3/context.json",
+    "id": "{{ id.url }}",
+    "type": "Manifest",
+    "label": { "en": [ "Picture of Göttingen taken during the 2019 IIIF Conference" ] },
+    "summary": { "en": [ "<p>Picture taken by the <a href=\"https://github.com/glenrobson\">IIIF Technical Coordinator</a></p>" ] },
+    "rights": "http://creativecommons.org/licenses/by-sa/3.0/",
+    "requiredStatement": {
+      "label": { "en": [ "Attribution" ] },
+      "value": { "en": [ "<span>Glen Robson, IIIF Technical Coordinator. <a href=\"https://creativecommons.org/licenses/by-sa/3.0\">CC BY-SA 3.0</a> <a href=\"https://creativecommons.org/licenses/by-sa/3.0\" title\"CC BY-SA 3.0\"><img src=\"https://licensebuttons.net/l/by-sa/3.0/88x31.png\"/></a></span>" ] }
+    },
+    "items": [
+      {
+        "id": "{{ id.path }}/canvas/p1",
+        "type": "Canvas",
+        "height": 3024,
+        "width": 4032,
+        "items": [
+          {
+            "id": "{{ id.path }}/page/p1/1",
+            "type": "AnnotationPage",
+            "items": [
+              {
+                "id": "{{ id.path }}/annotation/p0001-image",
+                "type": "Annotation",
+                "motivation": "painting",
+                "body": {
+                  "id": "https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen/full/max/0/default.jpg",
+                  "type": "Image",
+                  "format": "image/jpeg",
+                  "height": 3024,
+                  "width": 4032,
+                  "service": [
+                    {
+                    "id": "https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen",
+                    "profile": "level1",
+                    "type": "ImageService3"
+                    }
+                  ]
+                },
+                "target": "{{ id.path }}/canvas/p1"
+              }
+            ]
+          }
+        ]
+      }    
+    ]
+}