Merge pull request #255 from ResearchObject/cite-as

Specify how cite-as and Signposting should be used

docs/1.2-DRAFT/metadata.md

@@ -102,20 +102,23 @@ RO-Crate also uses the _Portland Common Data Model_ ([PCDM] version <https://pcd
 {: .note }
 > The terms `RepositoryObject` and `RepositoryCollection` are renamed to avoid collision between other vocabularies and the PCDM terms `Collection` and `Object`. The term `RepositoryFile` is renamed to avoid clash with RO-Crate's `File` mapping to <http://schema.org/MediaObject>.
 
-RO-Crate use the [Profiles Vocabulary](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/) to describe [profiles](../profiles) using these terms:
+RO-Crate use the [Profiles Vocabulary](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/) to describe [profiles](../profiles) using these terms and definitions:
 
-- `ResourceDescriptor` mapped to <http://www.w3.org/ns/dx/prof/ResourceDescriptor>
-- `ResourceRole` mapped to <http://www.w3.org/ns/dx/prof/ResourceRole>
-- `Profile` mapped to <http://www.w3.org/ns/dx/prof/Profile>
-- `hasArtifact` mapped to <http://www.w3.org/ns/dx/prof/hasArtifact>
-- `hasResource` mapped to <http://www.w3.org/ns/dx/prof/hasResource>
-- `hasRole` mapped to <http://www.w3.org/ns/dx/prof/hasRole>
+- `ResourceDescriptor` mapped to <http://www.w3.org/ns/dx/prof/ResourceDescriptor> ([definition](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/#Class:ResourceDescriptor))
+- `ResourceRole` mapped to <http://www.w3.org/ns/dx/prof/ResourceRole> ([definition](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/#Class:ResourceRole))
+- `Profile` mapped to <http://www.w3.org/ns/dx/prof/Profile>  ([definition](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/#Class:Profile))
+- `hasArtifact` mapped to <http://www.w3.org/ns/dx/prof/hasArtifact>  ([definition](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/#Property:hasArtifact))
+- `hasResource` mapped to <http://www.w3.org/ns/dx/prof/hasResource> ([definition](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/#Property:hasResource))
+- `hasRole` mapped to <http://www.w3.org/ns/dx/prof/hasRole> ([definition](https://www.w3.org/TR/2019/NOTE-dx-prof-20191218/#Property:hasRole))
 
 From [Dublin Core Terms](http://purl.org/dc/terms/) RO-Crate use:
 
 - `conformsTo` mapped to <http://purl.org/dc/terms/conformsTo>
 - `Standard` mapped to <http://purl.org/dc/terms/Standard>
 
+From the [IANA link relations] registry:
+- `cite-as` mapped to <http://www.iana.org/assignments/relation/cite-as> (defined by [RFC8574])
+
 These terms are being proposed by [Bioschemas profile ComputationalWorkflow 1.0-RELEASE][ComputationalWorkflow profile 1.0] and [FormalParameter 1.0-RELEASE][FormalParameter profile 1.0] to be integrated into Schema.org: 
 
 * `ComputationalWorkflow` mapped to <https://bioschemas.org/ComputationalWorkflow>

docs/1.2-DRAFT/root-data-entity.md

@@ -198,48 +198,58 @@ The root data entity's `@id` SHOULD be either `./` (indicating the directory of
 
 If the `@id` of the Root Data Entity is an absolute URI, an _Attached RO-Crate__ MAY contain both [data entities](data-entities.md) using relative URI references (relative to the _RO-Crate Root_, and [Web-based Data Entities](data-entities.html#web-based-data-entities) using absolute URIs but it is RECOMMENDED that data entities are referenced using absolute URIs.
 
-RO-Crates that have been assigned a _persistent identifier_ (e.g. a DOI) SHOULD indicate this using [identifier] on the root data entity using the approach set out in the [Science On Schema.org guides], that is through a `PropertyValue`. It is RECOMMENDED that resolving the identifier programmatically return the _RO-Crate Metadata Document_ or an archive (e.g. ZIP) that contain the _RO-Crate Metadata File_, using [content negotiation](profiles.md#how-to-retrieve-a-profile-crate) and/or [Signposting].
+RO-Crates that have been assigned a _persistent identifier_ (e.g. a DOI) SHOULD indicate this using [identifier] on the root data entity using the approach set out in the [Science On Schema.org guides], that is through a `PropertyValue`. 
 
 {: note}
-> Earlier RO-Crate 1.1 and earlier recommended `identifier` to be plain string URIs. Clients SHOULD be permissive of an RO-Crate `identifier` being a string (which MAY be a URI), or a `@id` reference, which SHOULD be represented as an `PropertyValue` entity which MUST have a human readable `value`, and SHOULD have a `url` if the identifier is Web-resolvable.
+> Earlier RO-Crate 1.1 and earlier recommended `identifier` to be plain string URIs. Clients SHOULD be permissive of an RO-Crate `identifier` being a string (which MAY be a URI), or a `@id` reference, which SHOULD be represented as an `PropertyValue` entity which MUST have a human readable `value`, and SHOULD have a `url` if the identifier is Web-resolvable. A citable representation of this persistent identifier MAY be given as a `description` of the `PropertyValue`, but as there are more than 10.000 known [citation styles], no attempt should be made to parse this string.
+
+#### Resolvable persistent identifiers
+
+It is RECOMMENDED that resolving the `identifier` programmatically return the _RO-Crate Metadata Document_ or an archive (e.g. ZIP) that contain the _RO-Crate Metadata File_, using [content negotiation](profiles.md#how-to-retrieve-a-profile-crate) and/or [Signposting]. With an RO-Crate identifier that is persistant and resolvable in this way from a URI, the root data entity SHOULD indicate this using the `cite-as` property according to [RFC8574]. Likewise, an HTTP/HTTPS server of the resolved RO-Crate Metadata Document or archive (possibly after redirection) SHOULD indicate that persistent identifier in its [Signposting] headers using `Link rel="cite-as"`. 
+
+{: tip}
+> The above `cite-as` MAY go to a repository landing page, and MAY require authentication, but MUST ultimately have the RO-Crate as a downloadable item, which SHOULD be programmatically accessible through content negotiation or [Signposting] (`Link rel="describedby"` for a _RO-Crate Metadata Document_, or `Link rel="item"` for an archive). To rather associate a textual scholarly citation for a crate (e.g. journal article), indicate instead a [publication via `citation` property](contextual-entities.md#publications-via-citation-property).
+
 
 ## Minimal example of RO-Crate
 
-The following _RO-Crate Metadata Document_ represents a minimal description of an _RO-Crate_. 
+The following _RO-Crate Metadata Document_ represents a minimal description of an _RO-Crate_ that also follows the identifier recommendations above. 
 
 ```json
 { "@context": "https://w3id.org/ro/crate/1.2-DRAFT/context", 
   "@graph": [
 
  {
-    "@type": "CreativeWork",
     "@id": "ro-crate-metadata.json",
+    "@type": "CreativeWork",
     "about": {"@id": "./"},
     "conformsTo": {"@id": "https://w3id.org/ro/crate/1.2-DRAFT"}
  },  
  {
     "@id": "./",
-    "identifier": {"@id": "https://doi.org/10.4225/59/59672c09f4a4b"},
     "@type": "Dataset",
+    "identifier": {"@id": "https://doi.org/10.4225/59/59672c09f4a4b"},
+    "cite-as": "https://doi.org/10.4225/59/59672c09f4a4b",
     "datePublished": "2017",
     "name": "Data files associated with the manuscript:Effects of facilitated family case conferencing for ...",
     "description": "Palliative care planning for nursing home residents with advanced dementia ...",
     "license": {"@id": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/"}
  },
  {
-  "@id": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/",
-  "@type": "CreativeWork",
-  "description": "This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/au/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.",
-  "identifier": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/",
-  "name": "Attribution-NonCommercial-ShareAlike 3.0 Australia (CC BY-NC-SA 3.0 AU)"
+    "@id": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/",
+    "@type": "CreativeWork",
+    "description": "This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/au/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.",
+    "identifier": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/",
+    "name": "Attribution-NonCommercial-ShareAlike 3.0 Australia (CC BY-NC-SA 3.0 AU)"
  }
  {
-        "@id": "https://doi.org/10.4225/59/59672c09f4a4b",
-        "@type": "PropertyValue",
-        "propertyID": "https://registry.identifiers.org/registry/doi",
-        "value": "doi:10.4225/59/59672c09f4a4b",
-        "url": "https://doi.org/10.4225/59/59672c09f4a4b"
-      }
+    "@id": "https://doi.org/10.4225/59/59672c09f4a4b",
+    "@type": "PropertyValue",
+    "propertyID": "https://registry.identifiers.org/registry/doi",
+    "value": "doi:10.4225/59/59672c09f4a4b",
+    "description": "Agar, M. et al., 2017. Data supporting \"Effects of facilitated family case conferencing for advanced dementia: A cluster randomised clinical trial\". https://doi.org/10.4225/59/59672c09f4a4b",
+    "url": "https://doi.org/10.4225/59/59672c09f4a4b"
+  }
  ]
 }
 ```

docs/_includes/references.liquid

@@ -97,7 +97,10 @@ and is also rendered into the end of the PDF.
 [Best Practice Recipes for Publishing RDF Vocabularies]: https://www.w3.org/TR/swbp-vocab-pub/
 [HTTP Content-negotiation]: https://httpd.apache.org/docs/2.4/content-negotiation.html
 [Science On Schema.org guides]: https://github.com/ESIPFed/science-on-schema.org/blob/1.3.1/guides/Dataset.md#identifier
-[Signposting]: https://signposting.org/adopters/#workflowhub
+[Signposting]: https://signposting.org/
+[IANA link relations]: https://www.iana.org/assignments/link-relations/
+[RFC8574]: https://www.iana.org/go/rfc8574
+[citation styles]: https://citationstyles.org/
 
 [Action]: http://schema.org/Action
 [ActionStatusType]: http://schema.org/ActionStatusType