diff --git a/Makefile b/Makefile index 8c52c361..af4d2092 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ all: dependencies release dependencies: node_modules/.bin/rochtml scripts/schema-context.py --version node_modules/.bin/rochtml --help - pip --exists-action=s install 'panflute<2' + pip --exists-action=s install 'panflute==2.1.3' pandoc --version xelatex --version @@ -89,32 +89,41 @@ release/ro-crate-${TAG}.md: dependencies release/ docs/_specification/${RELEASE} pandoc --from=markdown+gfm_auto_identifiers --to=markdown+gfm_auto_identifiers \ docs/_specification/${RELEASE}/.metadata.md \ `grep ^nav_order: docs/_specification/${RELEASE}/*.md | sort -n -k 2 | grep -v index.md| grep -v about.md | sed s/:.*//` \ - docs/_specification/${RELEASE}/appendix/*.md docs/_includes/references.liquid docs/_specification/${RELEASE}/.references.md |\ - grep -v '{%' > release/ro-crate-${TAG}.md + `grep ^nav_order: docs/_specification/${RELEASE}/appendix/*.md | sort -n -k 2 | sed s/:.*//` \ + docs/_includes/references.liquid docs/_specification/${RELEASE}/.references.md \ + > release/ro-crate-${TAG}.md # Our own rendering of Note/Warning/Tip - sed -i -E 's/\{: ?\.note ?\} \\>/**Note**:/g' release/ro-crate-${TAG}.md - sed -i -E 's/\{: ?\.warning ?\} \\>/**Warning**:/g' release/ro-crate-${TAG}.md - sed -i -E 's/\{: ?\.tip ?\} \\>/**Tip**:/g' release/ro-crate-${TAG}.md + sed -i -E 's/\{% include callout.html //g' release/ro-crate-${TAG}.md + sed -i -E 's/\" %}//g' release/ro-crate-${TAG}.md + sed -i -E 's/type=\"note\" content=\"/**Note**: /g' release/ro-crate-${TAG}.md + sed -i -E 's/type=\"warning\" content=\"/**Warning** :/g' release/ro-crate-${TAG}.md + sed -i -E 's/type=\"tip\" content=\"/**Tip**: /g' release/ro-crate-${TAG}.md + sed -i -E 's/type=\"important\" content=\"/**Important**: /g' release/ro-crate-${TAG}.md + # remove any remaining lines beginning with {% + sed -i -E 's/\{%.*//g' release/ro-crate-${TAG}.md # Skip intermediate table-of-contents sed -i -E 's/1..*\{:toc\}//g' release/ro-crate-${TAG}.md sed -i -E 's/## Table of contents//g' release/ro-crate-${TAG}.md sed -i -E 's/\{:[^}]*\}//g' release/ro-crate-${TAG}.md # Fix internal links to work in single-page - sed -i -E 's,]\(([^:)]*/)*([^:)]*)\.md\),](#\2),g' release/ro-crate-${TAG}.md - sed -i -E 's,]\([^):]*\.md#([^)]*)\),](#\1),g' release/ro-crate-${TAG}.md - + # first change links to website pages outside the spec, e.g. ../../tools -> https://www.researchobject.org/ro-crate/tools + sed -r -i -E 's,]\(\.\./\.\./([^:)]*)\),](https://www.researchobject.org/ro-crate/\1),g' release/ro-crate-${TAG}.md + sed -r -i -E 's,]\((\.\./)?([^:)]*\.(json|html))\),](https://www.researchobject.org/ro-crate/specification/${RELEASE}/\2),g' release/ro-crate-${TAG}.md + # change links without a #, e.g. appendix/jsonld to #jsonld + sed -r -i -E 's,]\(([^:)]*/)*([^:)]*)(\.md)?\),](#\2),g' release/ro-crate-${TAG}.md + # change links with a #, e.g. contextual-entities#people to #people + sed -r -i -E 's,]\([^):]*(\.md)?#([^)]*)\),](#\2),g' release/ro-crate-${TAG}.md release/ro-crate-${TAG}.html: dependencies release/ release/ro-crate-${TAG}.md egrep -v '^{:(\.no_)?toc}' release/ro-crate-${TAG}.md | \ pandoc --standalone --number-sections --toc --section-divs \ - --filter scripts/pandoc-admonition.py \ --metadata pagetitle="RO-Crate Metadata Specification ${RELEASE}" \ --from=markdown+gfm_auto_identifiers -o release/ro-crate-${TAG}.html release/ro-crate-${TAG}.pdf: dependencies release/ release/ro-crate-${TAG}.md egrep -v '^{:(\.no_)?toc}' release/ro-crate-${TAG}.md | \ pandoc --pdf-engine xelatex --variable=hyperrefoptions:colorlinks=true,allcolors=blue \ - --variable papersize=a4 --filter scripts/pandoc-admonition.py \ + --variable papersize=a4 \ --number-sections --toc --metadata pagetitle="RO-Crate Metadata Specification ${RELEASE}" \ --from=markdown+gfm_auto_identifiers -o release/ro-crate-${TAG}.pdf diff --git a/docs/_specification/1.2-DRAFT/appendix/changelog.md b/docs/_specification/1.2-DRAFT/appendix/changelog.md index 590cb1a5..f4523765 100644 --- a/docs/_specification/1.2-DRAFT/appendix/changelog.md +++ b/docs/_specification/1.2-DRAFT/appendix/changelog.md @@ -26,33 +26,33 @@ excerpt: List of changes in releases of this specifications --> -# APPENDIX: Changelog +# APPENDIX: Changelog {#changelog} * RO-Crate 1.2.0 * Clarified that the [RO-Crate Metadata Descriptor MUST have `@id` of `ro-crate-metadata.json`](../root-data-entity#ro-crate-metadata-descriptor) by removing conflicting statements elsewhere in the specification [#365](https://github.com/ResearchObject/ro-crate/pull/365) * Updated the Bioschemas namespace for properties from `https://bioschemas.org/ComputationalWorkflow#` to `https://bioschemas.org/properties/`. This change affects only the `input` and `output` properties in the [JSON-LD context](../ro-crate-metadata.json). - * **Change**: Replaced [name-based algorithm for finding root](../root-data-entity.html#finding-the-root-data-entity) [#198](https://github.com/ResearchObject/ro-crate/issues/198) [#365](https://github.com/ResearchObject/ro-crate/pull/365) - * Updated [algorithm to always use string filter to find root](../appendix/relative-uris.html#finding-ro-crate-root-in-rdf-triple-stores) [#189](https://github.com/ResearchObject/ro-crate/issues/189) - (see [algorithm](../root-data-entity.html#finding-the-root-data-entity)) - * **Change**: [Files on the web](../data-entities.html#embedded-data-entities-that-are-also-on-the-web) should now use `contentUrl` for direct download [#259](https://github.com/ResearchObject/ro-crate/issues/259) + * **Change**: Replaced [name-based algorithm for finding root](../root-data-entity#finding-the-root-data-entity) [#198](https://github.com/ResearchObject/ro-crate/issues/198) [#365](https://github.com/ResearchObject/ro-crate/pull/365) + * Updated [algorithm to always use string filter to find root](../appendix/relative-uris#finding-ro-crate-root-in-rdf-triple-stores) [#189](https://github.com/ResearchObject/ro-crate/issues/189) + (see [algorithm](../root-data-entity#finding-the-root-data-entity)) + * **Change**: [Files on the web](../data-entities#embedded-data-entities-that-are-also-on-the-web) should now use `contentUrl` for direct download [#259](https://github.com/ResearchObject/ro-crate/issues/259) * [Clarify entity terminology](../contextual-entities#contextual-vs-data-entities) [#204](https://github.com/ResearchObject/ro-crate/issues/204) * Update [JSON-LD context](../ro-crate-metadata.json) to [schema.org 22.0](https://github.com/schemaorg/schemaorg/tree/main/data/releases/22.0/). Note that upstream adds >230 terms, and removed terms `AuthenticContent` `MissingContext`, `constrainingProperty` (now `constraintProperty`), `measuredValue`, `observedNode` . [#263](https://github.com/ResearchObject/ro-crate/issues/263) [#274](https://github.com/ResearchObject/ro-crate/issues/274) * Remove custom mapping of `funding` for Bioschemas (now officially ) * Updated for [ComputationalWorkflow 1.0 profile](../workflows#complying-with-bioschemas-computational-workflow-profile) [#185](https://github.com/ResearchObject/ro-crate/issues/185) - * Clarified [Directories on the web format](../data-entities.html#directories-on-the-web-dataset-distributions) is a media type, not extension [#205](https://github.com/ResearchObject/ro-crate/issues/235) - * **New**: Extended [introduction](../introduction.html) with a running example [#227](https://github.com/ResearchObject/ro-crate/issues/227) [#215](https://github.com/ResearchObject/ro-crate/issues/215) [#219](https://github.com/ResearchObject/ro-crate/issues/219) -- see also [RO-Crate tutorials](https://www.researchobject.org/ro-crate/tutorials.html). + * Clarified [Directories on the web format](../data-entities#directories-on-the-web-dataset-distributions) is a media type, not extension [#205](https://github.com/ResearchObject/ro-crate/issues/235) + * **New**: Extended [introduction](../introduction) with a running example [#227](https://github.com/ResearchObject/ro-crate/issues/227) [#215](https://github.com/ResearchObject/ro-crate/issues/215) [#219](https://github.com/ResearchObject/ro-crate/issues/219) -- see also [RO-Crate tutorials](https://www.researchobject.org/ro-crate/tutorials.html). * **New**: Added section [Profiles](../profiles) and the concept _Profile Crate_ [#250](https://github.com/ResearchObject/ro-crate/issues/250) [#251](https://github.com/ResearchObject/ro-crate/issues/251) [#255](https://github.com/ResearchObject/ro-crate/issues/255) [#256](https://github.com/ResearchObject/ro-crate/issues/256) - * Define [terms for Profiles](../metadata.html#additional-metadata-standards) [#248](https://github.com/ResearchObject/ro-crate/issues/248) - * Added subsection for [grouping extensions in a profile](../appendix/jsonld.html#grouping-extensions-as-an-ro-crate-profile) [#233](https://github.com/ResearchObject/ro-crate/issues/233) [#233](https://github.com/ResearchObject/ro-crate/issues/252) - * [Allow more types on root](../root-data-entity.html#ro-crate-metadata-descriptor) [#182](https://github.com/ResearchObject/ro-crate/issues/182) [#223](https://github.com/ResearchObject/ro-crate/issues/223) - * Added subsection on [root data entity identifier](../root-data-entity.html#root-data-entity-identifier) [#183](https://github.com/ResearchObject/ro-crate/issues/183) + * Define [terms for Profiles](../metadata#additional-metadata-standards) [#248](https://github.com/ResearchObject/ro-crate/issues/248) + * Added subsection for [grouping extensions in a profile](../appendix/jsonld#grouping-extensions-as-an-ro-crate-profile) [#233](https://github.com/ResearchObject/ro-crate/issues/233) [#233](https://github.com/ResearchObject/ro-crate/issues/252) + * [Allow more types on root](../root-data-entity#ro-crate-metadata-descriptor) [#182](https://github.com/ResearchObject/ro-crate/issues/182) [#223](https://github.com/ResearchObject/ro-crate/issues/223) + * Added subsection on [root data entity identifier](../root-data-entity#root-data-entity-identifier) [#183](https://github.com/ResearchObject/ro-crate/issues/183) * **New**: Introduces distinction of [Attached/Detached RO-Crate](../structure) [#248](https://github.com/ResearchObject/ro-crate/issues/248) [#189](https://github.com/ResearchObject/ro-crate/issues/189) [#183](https://github.com/ResearchObject/ro-crate/issues/183) * Included Attached/Detached RO-Crate [in terminology](../terminology) [#248](https://github.com/ResearchObject/ro-crate/issues/248) * Rephrased description of [payload files](../structure#payload-files-and-directories-attached-ro-crates) [#183](https://github.com/ResearchObject/ro-crate/issues/183) [#189](https://github.com/ResearchObject/ro-crate/issues/189) * Describes [ro-crate-preview.html as entity](../structure#ro-crate-website-ro-crate-previewhtml-and-ro-crate-preview_files) [#106](https://github.com/ResearchObject/ro-crate/issues/106) [#210](https://github.com/ResearchObject/ro-crate/issues/210) * Added usage [of DefinedTerm; rdfs:label and comment optional; replaced example](jsonld#adding-new-or-ad-hoc-vocabulary-terms) [#232](https://github.com/ResearchObject/ro-crate/issues/232) [#208](https://github.com/ResearchObject/ro-crate/issues/208) [#106](https://github.com/ResearchObject/ro-crate/issues/106) - * Added section on [converting Attached/Detached RO-Crates](../appendix/relative-uris.html#converting-from-attached-to-detached-ro-crate) [#189](https://github.com/ResearchObject/ro-crate/issues/189) - * Added [Common principles for RO-Crate entities](../metadata.html#common-principles-for-ro-crate-entities) [#225](https://github.com/ResearchObject/ro-crate/issues/225) [#260](https://github.com/ResearchObject/ro-crate/issues/260) + * Added section on [converting Attached/Detached RO-Crates](../appendix/relative-uris#converting-from-attached-to-detached-ro-crate) [#189](https://github.com/ResearchObject/ro-crate/issues/189) + * Added [Common principles for RO-Crate entities](../metadata#common-principles-for-ro-crate-entities) [#225](https://github.com/ResearchObject/ro-crate/issues/225) [#260](https://github.com/ResearchObject/ro-crate/issues/260) * [RO-Crate 1.1.2](https://github.com/ResearchObject/ro-crate/releases/tag/1.1.2) * Typo fixes in [data entity section](../data-entities) [#177](https://github.com/ResearchObject/ro-crate/issues/177), [workflow section](../workflows) [#180](https://github.com/ResearchObject/ro-crate/issues/180), [metadata section](../metadata) [#181](https://github.com/ResearchObject/ro-crate/issues/181) * Correct namespace for `rdfs:comment` on [ad-hoc terms](jsonld#add-local-definitions-of-ad-hoc-terms) [#164](https://github.com/ResearchObject/ro-crate/issues/164) diff --git a/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md b/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md index 8498afb9..630016c7 100644 --- a/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md +++ b/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md @@ -24,7 +24,7 @@ nav_order: 21 limitations under the License. --> -# APPENDIX: Implementation notes +# APPENDIX: Implementation notes {#implementation-notes} {: .no_toc } ## Table of contents @@ -96,8 +96,7 @@ e1105ed0…5e13 data/chipseq_20200910.json 37fd3a02…bb95 data/results/pipeline_info/design_reads.csv ``` -{: .note } -> The SHA-512 checksums have been shortened in the above example. +{% include callout.html type="note" content="The SHA-512 checksums have been shortened in the above example." %} Creating the manifest file without using BagIt tools/libraries can be done using the equivalent of: @@ -128,10 +127,9 @@ b0556450…8802 bag-info.txt 000b27e3…c52e manifest-sha512.txt ``` -{: .warning } -The BagIt manifest is intended to detect "bit rot" and accidental damage, +{% include callout.html type="warning" content='The BagIt manifest is intended to detect "bit rot" and accidental damage, it does not provide proof the RO-Crate has not been deliberately -tampered with, as a malicious actor can also update the checksums. +tampered with, as a malicious actor can also update the checksums.' %} Guarding against such scenarious would require additional cryptographic measures, e.g. diff --git a/docs/_specification/1.2-DRAFT/appendix/index.md b/docs/_specification/1.2-DRAFT/appendix/index.md index 1cd5e820..45c3a777 100644 --- a/docs/_specification/1.2-DRAFT/appendix/index.md +++ b/docs/_specification/1.2-DRAFT/appendix/index.md @@ -24,4 +24,10 @@ has_children: true limitations under the License. --> -# Appendixes +# Appendixes {#appendix} + +## Contents +* [Changelog](changelog) +* [Handling relative URI references](relative-uris) +* [Implementation Notes](implementation-notes) +* [RO-Crate JSON-LD](jsonld) diff --git a/docs/_specification/1.2-DRAFT/appendix/jsonld.md b/docs/_specification/1.2-DRAFT/appendix/jsonld.md index cea91e54..5b16b46b 100644 --- a/docs/_specification/1.2-DRAFT/appendix/jsonld.md +++ b/docs/_specification/1.2-DRAFT/appendix/jsonld.md @@ -24,9 +24,7 @@ nav_order: 22 limitations under the License. --> -
- -# APPENDIX: RO-Crate JSON-LD +# APPENDIX: RO-Crate JSON-LD {#jsonld} {: .no_toc } ## Table of contents @@ -175,8 +173,7 @@ To check which RO-Crate version is used (in terms of properties and types expect RO-Crate consumers SHOULD NOT do the opposite substitution from an embedded context, but MAY use the [JSON-LD flattening] algorithm with _compaction_ to a referenced _RO-Crate JSON-LD context_ (see also notes on [handling relative URI references](relative-uris) below). -{: .tip } -> The [JSON-LD flattening & compaction](https://www.w3.org/TR/json-ld-api/#flattening-algorithm) algorithms can be used to rewrite to a different `@context`, e.g. to `https://schema.org/docs/jsonldcontext.jsonld` or a different version of the _RO-Crate JSON-LD Context_. +{% include callout.html type="tip" content="The [JSON-LD flattening & compaction](https://www.w3.org/TR/json-ld-api/#flattening-algorithm) algorithms can be used to rewrite to a different `@context`, e.g. to `https://schema.org/docs/jsonldcontext.jsonld` or a different version of the _RO-Crate JSON-LD Context_." %} ## RO-Crate JSON-LD Media type @@ -277,8 +274,7 @@ For projects that have their own web-presence, URIs MAY be defined there and SHO ``` -{: .tip } -> Ensure you have a consistent use of `http` or `https` (preferring https) as well as consistent path `/vocab` vs `/vocab/` vs `/vocab/index.html` (preferring the shortest that is also visible in browser). +{% include callout.html type="tip" content="Ensure you have a consistent use of `http` or `https` (preferring https) as well as consistent path `/vocab` vs `/vocab/` vs `/vocab/index.html` (preferring the shortest that is also visible in browser)." %} For ad hoc terms where the crate author does not have the resources to create and maintain an HTML page, authors may use the RO-Crate public namespace (`https://w3id.org/ro/terms/`) to reserve their terms. For example, an ad-hoc URI MAY be used in the form `https://w3id.org/ro/terms/some-project#myProperty` where `some-project` is acting as a _namespace_ for one or more related terms like `education`. Ad-hoc namespaces under `https://w3id.org/ro/terms/` are available on first-come-first-serve basis; to avoid clashes, namespaces SHOULD be registered by [submitting terms and definitions][ro-terms] to the RO-Crate terms project. @@ -314,8 +310,7 @@ Following the conventions used by Schema.org, ad-hoc terms SHOULD also include d ``` -{: .tip } -> It is **not** a requirement to use English for the terms, labels or comments. +{% include callout.html type="tip" content="It is **not** a requirement to use English for the terms, labels or comments." %} More information about the relationship of this term to other terms MAY be provided using [domainIncludes], [rangeIncludes], [rdfs:subClassOf], [rdfs:subPropertyOf], [sameAs] following the conventions used in the [Schema.org schema] -- *"Schema.org style schemas"*. For compatibility with RDFS/OWL tools, `name` and `description` SHOULD be duplicated using the RDFS properties `rdfs:label` and `rdfs:comment`: @@ -337,11 +332,9 @@ More information about the relationship of this term to other terms MAY be provi } ``` -{: .note } -> Schema.org also provides the types [Class] and [Property]. These MAY be used as an additional `@type` corresponding to `rdfs:Class` and `rdf:Property`, but as these are (for some reason) not used in Schema.org style schemas, they are also not required by RO-Crate. Likewise, an ontology defining such terms externally may be declaring properties there with more specific types like `owl:ObjectProperty` which do not need to be reflected in the RO-Crate reference. +{% include callout.html type="note" content="Schema.org also provides the types [Class] and [Property]. These MAY be used as an additional `@type` corresponding to `rdfs:Class` and `rdf:Property`, but as these are (for some reason) not used in Schema.org style schemas, they are also not required by RO-Crate. Likewise, an ontology defining such terms externally may be declaring properties there with more specific types like `owl:ObjectProperty` which do not need to be reflected in the RO-Crate reference." %} -{: .tip } -> For compatibility with the official schema.org JSON-LD context, make sure any referenced `@id` to schema.org terms starts with `http://` rather than `https://` as shown in the browser. +{% include callout.html type="tip" content="For compatibility with the official schema.org JSON-LD context, make sure any referenced `@id` to schema.org terms starts with `http://` rather than `https://` as shown in the browser." %} ## Grouping extensions as an RO-Crate profile diff --git a/docs/_specification/1.2-DRAFT/appendix/relative-uris.md b/docs/_specification/1.2-DRAFT/appendix/relative-uris.md index 0441f4b6..266f86fb 100644 --- a/docs/_specification/1.2-DRAFT/appendix/relative-uris.md +++ b/docs/_specification/1.2-DRAFT/appendix/relative-uris.md @@ -24,9 +24,7 @@ nav_order: 23 limitations under the License. --> -
- -# APPENDIX: Handling relative URI references +# APPENDIX: Handling relative URI references {#relative-uris} {: .no_toc } ## Table of contents @@ -161,8 +159,7 @@ To additionally save Web-based Data entities to become part of the Detached Crat As this procedure can be error-prone (e.g. a Web-based entity may not be accessible or may require authentication), the implementation should consider the new Attached Crate as a _fork_ and update `identifier` and `isDefinedBy` as specified above. -{: .tip } -> If you are archiving an [attached RO-Crate](../structure#attached-ro-crate) that is already on the Web, then first [establish the absolute URI](#establishing-absolute-uri-for-ro-crate-root) for the root, and retrieve all [payload](../structure#payload-files-and-directories-attached-ro-crates) files that are considered URI path-wise to be part the RO-Crate Root, creating corresponding local paths. In this scenario the above algorithm can be simplified and the rewriting of identifiers can be avoided if they are already relative URIs. +{% include callout.html type="tip" content="If you are archiving an [attached RO-Crate](../structure#attached-ro-crate) that is already on the Web, then first [establish the absolute URI](#establishing-absolute-uri-for-ro-crate-root) for the root, and retrieve all [payload](../structure#payload-files-and-directories-attached-ro-crates) files that are considered URI path-wise to be part the RO-Crate Root, creating corresponding local paths. In this scenario the above algorithm can be simplified and the rewriting of identifiers can be avoided if they are already relative URIs. " %} ## Handling relative URI references when using JSON-LD/RDF tools @@ -258,8 +255,7 @@ Results in a valid _RO-Crate JSON-LD_ (actual order in `@graph` may differ): } ``` -{: .note } -> The saved _RO-Crate JSON-LD_ SHOULD NOT include `{@base: null}` in its `@context`. +{% include callout.html type="note" content="The saved _RO-Crate JSON-LD_ SHOULD NOT include `{@base: null}` in its `@context`." %} ## Expanding/parsing JSON-LD keeping relative referencing @@ -361,11 +357,9 @@ Results in a [expanded form][JSON-LD expanded form] without `@context`, using ab ] ``` -{: .note } -> `@base: null` will not relativize existing absolute URIs that happen to be contained by the _RO-Crate Root_ (see section [Relativizing absolute URIs within RO-Crate Root](#relativizing-absolute-uris-within-ro-crate-root)). +{% include callout.html type="note" content="`@base: null` will not relativize existing absolute URIs that happen to be contained by the _RO-Crate Root_ (see section [Relativizing absolute URIs within RO-Crate Root](#relativizing-absolute-uris-within-ro-crate-root))." %} -{: .tip } -> Most RDF parsers supporting JSON-LD will perform this kind of expansion before generating triples, but not all RDF stores or serializations support relative URI references. Consider using an alternative `@base` as detailed in sections below. +{% include callout.html type="tip" content="Most RDF parsers supporting JSON-LD will perform this kind of expansion before generating triples, but not all RDF stores or serializations support relative URI references. Consider using an alternative `@base` as detailed in sections below." %} ## Establishing absolute URI for RO-Crate Root @@ -373,8 +367,7 @@ When loading _RO-Crate JSON-LD_ as RDF, or combining the crate's Linked Data int [base URI][JSON-LD base URI] to resolve URI references that are relative to the _RO-Crate Root_. -{: .note } -> When retrieving an RO-Crate over the web, servers might have performed HTTP redirections so that the base URI is different from what was requested. It is RECOMMENDED to follow section [Establishing a Base URI of RFC3986](http://tools.ietf.org/html/rfc3986#section-5.1) before resolving relative links from the _RO-Crate Metadata File_. +{% include callout.html type="note" content="When retrieving an RO-Crate over the web, servers might have performed HTTP redirections so that the base URI is different from what was requested. It is RECOMMENDED to follow section [Establishing a Base URI of RFC3986](http://tools.ietf.org/html/rfc3986#section-5.1) before resolving relative links from the _RO-Crate Metadata File_." %} For instance, consider this HTTP redirection from a permalink (simplified): @@ -458,8 +451,7 @@ When parsing a _RO-Crate Metadata File_ into [RDF triples], for instance uploadi * Web servers hosting `ro-crate-metadata.json` may not send the [JSON-LD _Content-Type_](jsonld#ro-crate-json-ld-media-type) * If base URI is not correct it may be difficult to find the corresponding file and directory paths from an RDF query returning absolute URIs -{: .tip } -> If the RDF library can parse the _RO-Crate JSON-LD_ directly by retrieving from a `http`/`https` URI of the _RO-Crate Metadata File_ it should calculate the correct base URI as detailed in section [Establishing absolute URI for RO-Crate Root](#establishing-absolute-uri-for-ro-crate-root) and you should **not** need to override the base URI as detailed here. +{% include callout.html type="tip" content="If the RDF library can parse the _RO-Crate JSON-LD_ directly by retrieving from a `http`/`https` URI of the _RO-Crate Metadata File_ it should calculate the correct base URI as detailed in section [Establishing absolute URI for RO-Crate Root](#establishing-absolute-uri-for-ro-crate-root) and you should **not** need to override the base URI as detailed here." %} If a web-based URI for the _RO-Crate root_ is known, then this can be supplied as a _base URI_. Most RDF tools support a `--base` option or similar. If this is not possible, then the `@context` of the `RO-Crate JSON-LD` can be modified by ensuring the `@context` is an array that sets the desired `@base`: @@ -598,8 +590,7 @@ Parsing this as RDF will generate triples including: Here consumers can assume `/` is the _RO-Crate Root_ and generating relative URIs can safely be achieved by search-replace as the arcp URI is unique. Saving _RO-Crate JSON-LD_ from the triples can be done by using the arcp URI to [relativize absolute URIs within RO-Crate Root](#relativizing-absolute-uris-within-ro-crate-root). -{: .tip } -> **Bagit**: The arcp specification suggests how [BagIt identifiers][ARCP BagIt] can be used to calculate the base URI. See also section [Combining with other packaging schemes](implementation-notes#combining-with-other-packaging-schemes) - note that in this approach the _RO-Crate Root_ will be the payload folder `/data/` under the calculated arcp base URI. +{% include callout.html type="tip" content="**Bagit**: The arcp specification suggests how [BagIt identifiers][ARCP BagIt] can be used to calculate the base URI. See also section [Combining with other packaging schemes](implementation-notes#combining-with-other-packaging-schemes) - note that in this approach the _RO-Crate Root_ will be the payload folder `/data/` under the calculated arcp base URI." %} ## Relativizing absolute URIs within RO-Crate Root @@ -688,7 +679,6 @@ Will output _RO-Crate JSON-LD_ with relative URIs: } ``` -{: .warning } -> This method would also relativize URIs outside the _RO-Crate Root_ that are on the same host, e.g. `http://example.com/crate255/other.txt` would become `../create255/other.txt` - this can particularly be a challenge with local `file:///` URIs. ` +{% include callout.html type="warning" content="This method would also relativize URIs outside the _RO-Crate Root_ that are on the same host, e.g. `http://example.com/crate255/other.txt` would become `../create255/other.txt` - this can particularly be a challenge with local `file:///` URIs. `" %} {% include references.liquid %} diff --git a/docs/_specification/1.2-DRAFT/contextual-entities.md b/docs/_specification/1.2-DRAFT/contextual-entities.md index 462063c4..b53f41fb 100644 --- a/docs/_specification/1.2-DRAFT/contextual-entities.md +++ b/docs/_specification/1.2-DRAFT/contextual-entities.md @@ -30,9 +30,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -
- -# Representing Contextual Entities +# Representing Contextual Entities {#contextual-entities} {: .no_toc } ## Table of contents @@ -53,8 +51,7 @@ RO-Crate distinguishes between _contextual entities_ and _data entities_. Some contextual entities can also be considered data entities -- for instance the [license](#licensing-access-control-and-copyright) property refers to a [CreativeWork] that can reasonably be downloaded, however a license document is not usually considered as part of research outputs and would therefore typically not be included in [hasPart] on the [root data entity](root-data-entity). -{: .tip } -> Files in the _RO-Crate Root_ are not necessarily data entities -- the [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) is a file in the _RO-Crate Root_, but is considered a _Contextual Entity_ as it is describing the RO-Crate, rather than being part of it. On the other hand, the [Root Data Entity](root-data-entity#root-data-entity) is a data entity within its own metadata file. +{% include callout.html type="tip" content="Files in the _RO-Crate Root_ are not necessarily data entities -- the [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) is a file in the _RO-Crate Root_, but is considered a _Contextual Entity_ as it is describing the RO-Crate, rather than being part of it. On the other hand, the [Root Data Entity](root-data-entity#root-data-entity) is a data entity within its own metadata file." %} Likewise, some data entities may also be described as contextual entities, for instance a `File` that is also a [ScholarlyArticle]. In such cases the _contextual data entity_ MUST be described as a single JSON object in the RO-Crate Metadata JSON `@graph` and SHOULD list both relevant data and contextual types in a `@type` array. @@ -299,8 +296,7 @@ The [Root Data Entity](root-data-entity) SHOULD have a [publisher] property. Thi To associate a research project with a [Dataset], the _RO-Crate JSON-LD_ SHOULD contain an entity for the project using type [Organization], referenced by a [funder] property. The project `Organization` SHOULD in turn reference any external [funder], either by using its URL as an `@id` or via a _Contextual Entity_ describing the funder. -{: .tip } -> To make it very clear where funding is coming from, the _Root Data Entity_ SHOULD also reference funders directly, as well as via a chain of references. +{% include callout.html type="tip" content="To make it very clear where funding is coming from, the _Root Data Entity_ SHOULD also reference funders directly, as well as via a chain of references." %} ```json diff --git a/docs/_specification/1.2-DRAFT/crate-focus.md b/docs/_specification/1.2-DRAFT/crate-focus.md index 0a5386d3..876b358f 100644 --- a/docs/_specification/1.2-DRAFT/crate-focus.md +++ b/docs/_specification/1.2-DRAFT/crate-focus.md @@ -26,8 +26,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -# The focus of an RO-Crate -
+# The focus of an RO-Crate {#crate-focus} In addition to simple data packaging, Crates may have a "main" entry point or topic (referenced with a singleton `mainEntity` property), or function as a bundle of one or more Contextual Entities referenced via the `mentions` property. diff --git a/docs/_specification/1.2-DRAFT/data-entities.md b/docs/_specification/1.2-DRAFT/data-entities.md index f89277c5..1a046535 100644 --- a/docs/_specification/1.2-DRAFT/data-entities.md +++ b/docs/_specification/1.2-DRAFT/data-entities.md @@ -23,7 +23,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -# Data Entities +# Data Entities {#data-entities} {: .no_toc } ## Table of contents @@ -228,8 +228,7 @@ Some generic file formats like `application/json` may be specialized using a _pr ``` -{: .tip } -Profiles expressed in formal languages (e.g. XML Schema for validation) can have their own `encodingFormat` and `conformsTo` to indicate their file format. +{% include callout.html type="tip" content="Profiles expressed in formal languages (e.g. XML Schema for validation) can have their own `encodingFormat` and `conformsTo` to indicate their file format." %} {: .note} The [Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) `ro-crate-metadata.json` is not a data entity, but is described with `conformsTo` to an _implicit contextual entity_ for the RO-Crate specification, a profile of [JSON-LD](appendix/jsonld). RO-Crates themselves can be specialized using [Profile Crates](profiles), specified with `conformsTo` on the root data entity. @@ -416,11 +415,9 @@ If the referenced RO-Crate B has an `identifier` declared as B's [Root Data Enti } ``` -{.tip } -> The `conformsTo` generic RO-Crate profile on a `Dataset` entity MUST be version-less. The referenced crate B is NOT required to conform to the same version of the RO-Crate specification as A's RO-Crate Metadata Document. +{% include callout.html type="tip" content="The `conformsTo` generic RO-Crate profile on a `Dataset` entity MUST be version-less. The referenced crate B is NOT required to conform to the same version of the RO-Crate specification as A's RO-Crate Metadata Document." %} -{.warning } -> It is NOT RECOMMENDED to declare the generic profile `https://w3id.org/ro/crate` on a referencing crate A's own [root data entity](root-data-entity.html#direct-properties-of-the-root-data-entity), see [metadata descriptor](root-data-entity.html#ro-crate-metadata-descriptor). +{% include callout.html type="warning" content="It is NOT RECOMMENDED to declare the generic profile `https://w3id.org/ro/crate` on a referencing crate A's own [root data entity](root-data-entity.html#direct-properties-of-the-root-data-entity), see [metadata descriptor](root-data-entity.html#ro-crate-metadata-descriptor). " %} Consumers that find a reference to a `Dataset` with the generic RO-Crate profile indicated MAY attempt to resolve the persistent identifier, but SHOULD NOT assume that the `@id` directly resolves to an RO-Crate Metadata Document. See section [Retrieving an RO-Crate](#retrieving-an-ro-crate) below for the recommended algorithm. @@ -457,8 +454,7 @@ If a referenced RO-Crate Metadata Document is known at a given URI or path, but } ``` -{.tip } -> Counter to [file format profile](data-entities.html#file-format-profiles) recommendations, the referenced RO-Crate metadata descriptor SHOULD NOT include its own `conformsTo` declarations to `https://w3id.org/ro/crate` or reference the dataset with `about`; this is to avoid confusion with the referencing RO-Crate's own [metadata descriptor](root-data-entity#ro-crate-metadata-descriptor). +{% include callout.html type="tip" content="Counter to [file format profile](data-entities.html#file-format-profiles) recommendations, the referenced RO-Crate metadata descriptor SHOULD NOT include its own `conformsTo` declarations to `https://w3id.org/ro/crate` or reference the dataset with `about`; this is to avoid confusion with the referencing RO-Crate's own [metadata descriptor](root-data-entity#ro-crate-metadata-descriptor). " %} ##### Profiles of referenced crates @@ -481,8 +477,7 @@ If the referenced crate conforms to a given [RO-Crate profile](profiles), this M } ``` -{.note} -> The profile declaration of a referenced crate is a hint. Consumers should check `conformsTo` as declared in the retrieved RO-Crate, as it may have been updated after this RO-Crate. +{% include callout.html type="note" content="The profile declaration of a referenced crate is a hint. Consumers should check `conformsTo` as declared in the retrieved RO-Crate, as it may have been updated after this RO-Crate." %} diff --git a/docs/_specification/1.2-DRAFT/introduction.md b/docs/_specification/1.2-DRAFT/introduction.md index 0618f7e7..6dfa3c1a 100644 --- a/docs/_specification/1.2-DRAFT/introduction.md +++ b/docs/_specification/1.2-DRAFT/introduction.md @@ -101,7 +101,7 @@ The preamble of `@context` and `@graph` are JSON-LD structures that help provide However, in the general case it should be sufficient to follow the RO-Crate JSON examples directly without deeper JSON-LD understanding. In short, an _RO-Crate metadata Document_ contains a flat list of _entities_ as objects in the `@graph` array. These entities are cross-referenced using `@id` identifiers rather than being deeply nested. -### RO-Crate Metadata descriptor +### RO-Crate Metadata Descriptor The first JSON-LD _entity_ in our example above has the `@id` `ro-crate-metadata.json`: @@ -130,8 +130,7 @@ We can visualise how the above entity references the **RO-Crate Root** as: By convention, in RO-Crate the `@id` value of `./` means that this document describes the directory of content in which the RO-Crate metadata is located as in the example above. This reference from `ro-crate-metadata.json` is therefore marking the `crate1` directory as being the RO-Crate root. -{: .note } -This example is a directory-based RO-Crate stored on disk. If the crate is being served from a Web service, such as a data repository or database where files are not organized in directories, then the `@id` might be an absolute URI instead of `"./"` -- see section [Root Data Entity](root-data-entity) for details +{% include callout.html type="note" content="This example is a directory-based RO-Crate stored on disk. If the crate is being served from a Web service, such as a data repository or database where files are not organized in directories, then the `@id` might be an absolute URI instead of `./` -- see section [Root Data Entity](root-data-entity) for details." %} ### About cross-references @@ -149,12 +148,11 @@ In _RO-Crate Metadata Documents_, entities are cross-referenced using `@id` refe The root is always typed `Dataset`, though it may have more than one type. It has several metadata properties that describe the RO-Crate as a whole, as a collection of resources. The section on [root data entity](root-data-entity) explores further the required and recommended properties of the root `./`. -### Data entities +### Data entities {#intro-data-entities} A main type of resources collected are _data_ -- simplifying, we can consider data as any kind of file that can be opened in other programs. These are aggregated by the Root Dataset with the `hasPart` property. In this example we have an array with a single value, a reference to the entity describing the file `data.csv`. -{: .tip} -RO-Crates can also contain data entities that are folders and Web resources, as well as non-File-like data like online databases -- see section on [data entities](data-entities). +{% include callout.html type="tip" content="RO-Crates can also contain data entities that are folders and Web resources, as well as non-File-like data like online databases -- see section on [data entities](data-entities)." %}
@@ -179,7 +177,7 @@ If we now follow the `@id` reference for the corresponding _data entity_ JSON bl For more information on describing files and directories, including their recommended and required attributes, see section on [data entities](data-entities). -### Contextual entities +### Contextual entities {#intro-contextual-entities} Moving back to the RO-Crate root `./`, the publisher of this Dataset should be indicated using the property `publisher` using a URI to identify the `Organization`, linking to what is known as a _Contextual Entity_ that provides some information about the Organization such as its name and web address. @@ -229,7 +227,7 @@ The rest of this specification is structured as follows: * Subsection [Digital Library and Repository content](provenance#digital-library-and-repository-content) details how records in an existing repository (which may reference files, but also physical objects) can be described and published using RO-Crate. * [Workflows and Scripts](workflows) explains how computional software and code can be added to an RO-Crate, possibly as part of explaining provenance, but also for providing potential usage and further processing of the data. * [Profiles](profiles) formalises how a set of RO-Crates can indicate they are conforming to a specific profile, which may add additional requirements beyond this general RO-Crate specification. Profiles may add additional terms from `schema.org` and other vocabularies, or require a certain type of data entity used in a particular research domain. Profiles can themselves be expressed as an RO-Crate, explored in this section. -* [Appendixes](appendix/) contain more technical references and suggestions for developers, e.g. for deciding on `@id` [in JSON-LD](appendix/jsonld#describing-entities-in-json-ld) or [extending RO-Crate terms](appendix/jsonld#extending-ro-crate). The appendix also explores how an RO-Crate can be [packaged with BagIt](appendix/implementation-notes#combining-with-other-packaging-schemes) or used as part of a repository. +* [Appendixes](appendix) contain more technical references and suggestions for developers, e.g. for deciding on `@id` [in JSON-LD](appendix/jsonld#describing-entities-in-json-ld) or [extending RO-Crate terms](appendix/jsonld#extending-ro-crate). The appendix also explores how an RO-Crate can be [packaged with BagIt](appendix/implementation-notes#combining-with-other-packaging-schemes) or used as part of a repository. Throughout the specifications you will find references to the keys and types reused from `schema.org` through the JSON-LD context, for instance [Dataset], which define many more properties than the ones highlighted by pages like [Root Data Entity](root-data-entity). The intention is that the RO-Crate specification gives a common minimum of metadata, and that producers of RO-Crate can use additional `schema.org` types and properties as needed. When some patterns emerge from such extensions they can be formalized in a published [profile](profiles) to ensure they are also used consistently. diff --git a/docs/_specification/1.2-DRAFT/metadata.md b/docs/_specification/1.2-DRAFT/metadata.md index c869f143..726f04c1 100644 --- a/docs/_specification/1.2-DRAFT/metadata.md +++ b/docs/_specification/1.2-DRAFT/metadata.md @@ -29,9 +29,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -
- -# RO-Crate Metadata +# RO-Crate Metadata {#metadata} {: .no_toc } ## Table of contents @@ -85,13 +83,11 @@ For all entities listed in an _RO-Crate Metadata Document_ the following princip [Schema.org] is the base metadata standard for RO-Crate. Schema.org was chosen because it is widely used on the World Wide Web and supported by search engines, on the assumption that discovery is likely to be maximized if search engines index the content. -{: .note } -> As far as we know there is no alternative, well-maintained linked-data schema for research data with the coverage needed for this project - i.e. a single standard for expressing all the examples presented in this specification. +{% include callout.html type="note" content="As far as we know there is no alternative, well-maintained linked-data schema for research data with the coverage needed for this project - i.e. a single standard for expressing all the examples presented in this specification." %} RO-Crate relies heavily on [Schema.org], using a constrained subset of [JSON-LD], and this specification gives opinionated recommendations on how to represent the metadata using existing [linked data] best practices. -{: .tip } -> The main principle of RO-Crate is to use a [Schema.org] whenever possible, even if its official definition may seem broad or related to every day objects. For instance, [IndividualProduct] can describe scientific equipment and instruments (see [Provenance of entities](provenance)). RO-Crate implementers are free to use additional properties and types beyond this specification (see also appendix [Extending RO-Crate(appendix/jsonld#extending-ro-crate)]). +{% include callout.html type="tip" content="The main principle of RO-Crate is to use a [Schema.org] whenever possible, even if its official definition may seem broad or related to every day objects. For instance, [IndividualProduct] can describe scientific equipment and instruments (see [Provenance of entities](provenance)). RO-Crate implementers are free to use additional properties and types beyond this specification (see also appendix [Extending RO-Crate(appendix/jsonld#extending-ro-crate)])." %} ### Differences from Schema.org @@ -101,8 +97,7 @@ Generally, the standard _type_ and _property_ names (_terms_) from [Schema.org] * `File` is mapped to which was chosen as a compromise as it has many of the properties that are needed to describe a generic file. Future versions of Schema.org or a research data extension may re-define `File`. * `Journal` is mapped to . -{: .warning } -> JSON-LD examples given on the [Schema.org] website may not be in _flattened_ form; any nested entities in _RO-Crate JSON-LD_ SHOULD be described as separate contextual entities in the flat `@graph` list. +{% include callout.html type="warning" content="JSON-LD examples given on the [Schema.org] website may not be in _flattened_ form; any nested entities in _RO-Crate JSON-LD_ SHOULD be described as separate contextual entities in the flat `@graph` list. " %} To simplify processing and avoid confusion with string values, the _RO-Crate JSON-LD Context_ requires URIs and entity references to be given in the form `"author": {"@id": "http://example.com/alice"}`, even where [Schema.org] for some properties otherwise permit shorter forms like `"author": "http://example.com/alice"`. @@ -118,8 +113,7 @@ RO-Crate also uses the _Portland Common Data Model_ ([PCDM] version - `hasFile` mapped to -{: .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 . +{% include callout.html type="note" content="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 ." %} 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: @@ -150,8 +144,7 @@ To support geometry in [Places](contextual-entities#places), these terms from th * `Geometry` mapped to * `asWKT` mapped to -{: .note } -> In this specification the proposed Bioschemas terms use the temporary namespace; future releases of RO-Crate may reflect mapping to the namespace. +{% include callout.html type="note" content="In this specification the proposed Bioschemas terms use the temporary namespace; future releases of RO-Crate may reflect mapping to the namespace." %} From [CodeMeta 3.0](https://w3id.org/codemeta/3.0): @@ -166,9 +159,8 @@ From [CodeMeta 3.0](https://w3id.org/codemeta/3.0): * `referencePublication` mapped to * `softwareSuggestions` mapped to -{: .warning } -> As of 2024-05-23, the CodeMeta URIs do not resolve correctly, but are used here to match the Codemeta JSON-LD context (issue [#275](https://github.com/ResearchObject/ro-crate/issues/275)). -> The CodeMeta terms `maintainer` and `funding` are not mapped, as these are already defined by schema.org. +{% include callout.html type="warning" content="As of 2024-05-23, the CodeMeta URIs do not resolve correctly, but are used here to match the Codemeta JSON-LD context (issue [#275](https://github.com/ResearchObject/ro-crate/issues/275)). +The CodeMeta terms `maintainer` and `funding` are not mapped, as these are already defined by schema.org." %} ## Summary of Coverage diff --git a/docs/_specification/1.2-DRAFT/profiles.md b/docs/_specification/1.2-DRAFT/profiles.md index 337f63c8..825c2f7a 100644 --- a/docs/_specification/1.2-DRAFT/profiles.md +++ b/docs/_specification/1.2-DRAFT/profiles.md @@ -25,7 +25,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -# RO-Crate profiles +# RO-Crate profiles {#profiles} While RO-Crates can be considered general-purpose containers of arbitrary data and open-ended metadata, in practical use within a particular domain, application or framework, it will be beneficial to further constrain RO-Crate to a specific **profile**: a set of conventions, types and properties that one minimally can require and expect to be present in that subset of RO-Crates. @@ -155,8 +155,7 @@ The rest of the [earlier requirements](#declaring-conformance-of-an-ro-crate-pro * SHOULD list related data entities using `hasPart` (see [below](#what-is-included-in-the-profile-crate)) * MAY list profile descriptors using `hasResource` (see [below](#declaring-the-role-within-the-crate)) -{: .tip} -> The base RO-Crate specification referenced by `isProfileOf` is a Profile Crate itself, see [ro-crate-metadata.json](ro-crate-metadata.json) or [ro-crate-preview.html](ro-crate-preview.html). +{% include callout.html type="tip" content="The base RO-Crate specification referenced by `isProfileOf` is a Profile Crate itself, see [ro-crate-metadata.json](ro-crate-metadata.json) or [ro-crate-preview.html](ro-crate-preview.html). " %} ### How to retrieve a Profile Crate @@ -173,8 +172,7 @@ If an RO-Crate declares conformance to a given profile crate with `conformsTo` o For instance, if a Profile Crate adds a `DefinedTerm` entity according to the [ad-hoc definitions](appendix/jsonld#adding-new-or-ad-hoc-vocabulary-terms), the term MAY be referenced in the conforming crate without making a contextual entity there. For archival purposes it MAY however still be preferrable to copy such entities across to each conforming crate. -{: .note } -> In the conforming crate, any terms defined in the profile using `DefinedTerm`, `rdfs:Class` and `rdf:Property` MUST either be used as full URIs matching the `@id`, or mapped to these URIs from the conforming crate's JSON-LD `@context`. Note that JSON-LD only expands keys from `@id` and `@type`. +{% include callout.html type="note" content="In the conforming crate, any terms defined in the profile using `DefinedTerm`, `rdfs:Class` and `rdf:Property` MUST either be used as full URIs matching the `@id`, or mapped to these URIs from the conforming crate's JSON-LD `@context`. Note that JSON-LD only expands keys from `@id` and `@type`." %} It is RECOMMENDED that `@id` of such shared entities are absolute URIs on both sides to avoid resolving relative paths, and that the profile's recommended [JSON-LD Context](#json-ld-context) used by conforming crates SHOULD have a mapping to the URIs, see section [Extending RO-Crate](appendix/jsonld#extending-ro-crate). @@ -403,10 +401,9 @@ Below are known schema types in their recommended media type, with suggested ide | OWL 2 (in RDF) | `text/turtle` | | | `vocabulary` | -{: .tip } -Some of the above schema languages are based on general data structure syntaxes +{% include callout.html type="tip" content="Some of the above schema languages are based on general data structure syntaxes like `application/json` and `text/turtle`, and therefore have a -generic `encodingFormat` with a specialized `conformsTo` _URI_, which itself is declared as a `Profile`. +generic `encodingFormat` with a specialized `conformsTo` _URI_, which itself is declared as a `Profile`." %} @@ -578,11 +575,10 @@ The JSON-LD Context entity: Note that the referenced context URI does _not_ have to match the `@context` of the Profile Crate itself. -{: .tip } -The `@context` MAY be the Profile Crate's Metadata JSON-LD file itself if +{% include callout.html type="tip" content="The `@context` MAY be the Profile Crate's Metadata JSON-LD file itself if it is [resolvable](appendix/jsonld#ro-crate-json-ld-media-type) as media type `application/ld+json` over HTTP. Make sure the crate includes the -defined terms both within its `@context` and ideally as entities in its `@graph`. +defined terms both within its `@context` and ideally as entities in its `@graph`." %} #### Multiple profiles diff --git a/docs/_specification/1.2-DRAFT/provenance.md b/docs/_specification/1.2-DRAFT/provenance.md index 06010d95..b3633953 100644 --- a/docs/_specification/1.2-DRAFT/provenance.md +++ b/docs/_specification/1.2-DRAFT/provenance.md @@ -23,9 +23,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -
- -# Detailing provenance of entities +# Detailing provenance of entities {#provenance} {: .no_toc } ## Table of contents @@ -147,8 +145,7 @@ In the below example, an image with the `@id` of `pics/2017-06-11%2012.56.14.jpg }, ``` -{: .tip } -> If representing command lines, double escape `\\` so that JSON preserves the `\` character. +{% include callout.html type="tip" content="If representing command lines, double escape `\\` so that JSON preserves the `\` character." %} If multiple [SoftwareApplication]s have been used in composition, such as from a script or workflow, then the `CreateAction`'s [instrument] SHOULD rather reference a [SoftwareSourceCode] which can be further described as explained in the [Workflows and scripts](workflows) section. @@ -242,11 +239,9 @@ A [Contextual Entity](contextual-entities) from a repository, representing an ab Objects MAY be grouped together in [RepositoryCollection]s with [hasMember] pointing to the [RepositoryObject]. -{: .note } -> The terms `RepositoryObject` and `RepositoryCollection` are renamed in RO-Crate 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 . +{% include callout.html type="note" content="The terms `RepositoryObject` and `RepositoryCollection` are renamed in RO-Crate 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 ." %} -{: .warning } -> PCDM specifies that files should have only technical metadata, not descriptive metadata, which is _not_ a restriction in RO-Crate. If the RO-Crate is to be imported into a strict PCDM repository, modeling of object/file relationships will be necessary. +{% include callout.html type="warning" content="PCDM specifies that files should have only technical metadata, not descriptive metadata, which is _not_ a restriction in RO-Crate. If the RO-Crate is to be imported into a strict PCDM repository, modeling of object/file relationships will be necessary." %} For example, this data is exported from an [Omeka] repository: diff --git a/docs/_specification/1.2-DRAFT/root-data-entity.md b/docs/_specification/1.2-DRAFT/root-data-entity.md index 356f4702..42ddf74a 100644 --- a/docs/_specification/1.2-DRAFT/root-data-entity.md +++ b/docs/_specification/1.2-DRAFT/root-data-entity.md @@ -23,7 +23,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -# Root Data Entity +# Root Data Entity {#root-data-entity} {: .no_toc } ## Table of contents @@ -67,17 +67,15 @@ property referencing the _Root Data Entity_'s `@id`. } ``` -{: .note} -> Even in [Detached RO-Crates](structure#detached-ro-crate) which do not have an _RO-Crate Metadata File_ present, the identifier `ro-crate-metadata.json` MUST be used. +{% include callout.html type="note" content="Even in [Detached RO-Crates](structure#detached-ro-crate) which do not have an _RO-Crate Metadata File_ present, the identifier `ro-crate-metadata.json` MUST be used." %} The [conformsTo] of the _RO-Crate Metadata Descriptor_ SHOULD be a versioned permalink URI of the RO-Crate specification that the _RO-Crate JSON-LD_ conforms to. The URI SHOULD start with `https://w3id.org/ro/crate/`. -{: .tip } -> The `conformsTo` property MAY be an array, to additionally indicate -specializing [RO-Crate profiles](profiles). +{% include callout.html type="tip" content="The `conformsTo` property MAY be an array, to additionally indicate +specializing [RO-Crate profiles](profiles)." %} ### Finding the Root Data Entity @@ -139,13 +137,11 @@ The _Root Data Entity_ MUST have the following properties: * `datePublished`: MUST be a single string value in [ISO 8601 date format][DateTime] and SHOULD be specified to at least the precision of a day, MAY be a timestamp down to the millisecond. * `license`: SHOULD link to a _Contextual Entity_ or _Data Entity_ in the _RO-Crate Metadata Document_ with a name and description (see section on [licensing](contextual-entities#licensing-access-control-and-copyright)). MAY, if necessary be a textual description of how the RO-Crate may be used. -{: .note } -> These requirements are stricter than those published -> for [Google Dataset Search](https://developers.google.com/search/docs/data-types/dataset) which -> requires a `Dataset` to have a `name` and `description`, +{% include callout.html type="note" content="These requirements are stricter than those published +for [Google Dataset Search](https://developers.google.com/search/docs/data-types/dataset) which +requires a `Dataset` to have a `name` and `description`," %} -{: .warning } -> The properties above are not sufficient to generate a [DataCite][DataCite Schema] citation. Advice on integrating with [DataCite] will be provided in a future version of this specification, or as an implementation guide. +{% include callout.html type="warning" content="The properties above are not sufficient to generate a [DataCite][DataCite Schema] citation. Advice on integrating with [DataCite] will be provided in a future version of this specification, or as an implementation guide." %} Additional properties of _schema.org_ types [Dataset] and [CreativeWork] MAY be added to further describe the RO-Crate as a whole, e.g. [author], [abstract], [publisher]. See sections [contextual entities](contextual-entities) and [provenance](provenance) for further details. @@ -158,15 +154,13 @@ If the `@id` of the Root Data Entity is an absolute URI, an _Attached RO-Crate_ 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. 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. +{% include callout.html type="note" content="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 and citation text 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](data-entities#retrieving-an-ro-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#publications-via-citation-property). +{% include callout.html type="tip" content='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#publications-via-citation-property).' %} Any entity which is a subclass of CreativeWork, including the _Root Data Entity_ MAY have a `creditText` property which provides a textual citation for the entity. diff --git a/docs/_specification/1.2-DRAFT/structure.md b/docs/_specification/1.2-DRAFT/structure.md index 6845e2e7..bbfec520 100644 --- a/docs/_specification/1.2-DRAFT/structure.md +++ b/docs/_specification/1.2-DRAFT/structure.md @@ -23,9 +23,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -
- -# RO-Crate Structure +# RO-Crate Structure {#structure} {: .no_toc } ## Table of contents @@ -82,13 +80,11 @@ These crates cannot carry their own data _payload_, but may reference data depos Any [data entities](data-entities) in a _Detached RO-Crate_ MUST be [Web-based Data Entities](data-entities.html#web-based-data-entities). -{: .warning } -> Using relative URI references like `example/data.txt` in a _Detached RO-Crate_ is NOT RECOMMENDED as this is considered ambigious and fragile. +{% include callout.html type="warning" content="Using relative URI references like `example/data.txt` in a _Detached RO-Crate_ is NOT RECOMMENDED as this is considered ambigious and fragile. " %} A _Detached RO-Crate_ can be identified by the [root data entity](root-data-entity) having an `@id` different from `./` in the JSON. -{: .note } -> [Finding the Root Data Entity](root-data-entity#finding-the-root-data-entity) can be harder for consumers of detached crates, particularly if the platform serving the _RO-Crate Metadata Document_ is unable to ensure the URI path ends with `…/ro-crate-metadata.json`. +{% include callout.html type="note" content="[Finding the Root Data Entity](root-data-entity#finding-the-root-data-entity) can be harder for consumers of detached crates, particularly if the platform serving the _RO-Crate Metadata Document_ is unable to ensure the URI path ends with `…/ro-crate-metadata.json`. " %} Note that a detached RO-Crate may still use `#`-based local identifiers for [contextual entities](contextual-entities). @@ -188,8 +184,7 @@ Metadata about parts of the _RO-Crate Website_ MAY be included in an RO-Crate as } ``` -{: .warning } -> In a _Detached RO-Crate_ it is **undefined** how to find the _RO-Crate Website_ from the _RO-Crate Metadata Document_ or vice versa; it is RECOMMENDED to describe both as contextual entities. +{% include callout.html type="warning" content="In a _Detached RO-Crate_ it is **undefined** how to find the _RO-Crate Website_ from the _RO-Crate Metadata Document_ or vice versa; it is RECOMMENDED to describe both as contextual entities." %} @@ -203,8 +198,7 @@ Payload files may appear directly in the _RO-Crate Root_ alongside the _RO-Crate A RO-Crate may also contain [Web-based Data Entities](data-entities.html#web-based-data-entities) that are not present as part of the payload and referenced using absolute URIs. These may require additional preservation measures. -{: .tip } -> A RO-Crate [packaged with BagIt](appendix/implementation-notes#adding-ro-crate-to-bagit) may be [referencing external files](appendix/implementation-notes#referencing-external-files) which are not present in the _RO-Crate Root_ hierarchy until the BagIt has been _completed_. This method can be used for files that are large, require authentication or otherwise inconvenient to transfer with the RO-Crate, but which should nevertheless still be considered part of the _payload_. +{% include callout.html type="tip" content="A RO-Crate [packaged with BagIt](appendix/implementation-notes#adding-ro-crate-to-bagit) may be [referencing external files](appendix/implementation-notes#referencing-external-files) which are not present in the _RO-Crate Root_ hierarchy until the BagIt has been _completed_. This method can be used for files that are large, require authentication or otherwise inconvenient to transfer with the RO-Crate, but which should nevertheless still be considered part of the _payload_." %} ## Self-describing and self-contained (_Attached RO-Crates_) diff --git a/docs/_specification/1.2-DRAFT/terminology.md b/docs/_specification/1.2-DRAFT/terminology.md index b7c6b740..3bbb0afb 100644 --- a/docs/_specification/1.2-DRAFT/terminology.md +++ b/docs/_specification/1.2-DRAFT/terminology.md @@ -23,7 +23,7 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> -# Terminology +# Terminology {#terminology} _RO-Crate_: A dataset, which is described in a JSON-LD _RO-Crate Metadata Document_. diff --git a/docs/_specification/1.2-DRAFT/workflows.md b/docs/_specification/1.2-DRAFT/workflows.md index 00c515a2..0664d748 100644 --- a/docs/_specification/1.2-DRAFT/workflows.md +++ b/docs/_specification/1.2-DRAFT/workflows.md @@ -24,12 +24,10 @@ parent: RO-Crate 1.2-DRAFT distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and - limitations under the License. + limitations under the License. --> -
- -# Workflows and Scripts +# Workflows and Scripts {#workflows} {: .no_toc } ## Table of contents @@ -234,8 +232,7 @@ A contextual entity conforming to the [FormalParameter profile][FormalParameter } ``` -{: .note } -> `input`, `output` and `FormalParameter` are at time of writing proposed by Bioschemas and not yet integrated in Schema.org +{% include callout.html type="note" content="`input`, `output` and `FormalParameter` are at time of writing proposed by Bioschemas and not yet integrated in Schema.org" %} ## Complete Workflow Example diff --git a/environment.yml b/environment.yml index d32556b7..e1c07999 100644 --- a/environment.yml +++ b/environment.yml @@ -11,10 +11,10 @@ dependencies: - sed=4.8 - python=3.8 - requests=2.24 - - panflute=1.12 + - panflute=2.1.3 - rb-jekyll=4.0 # for binary deps, use "bundle exec jekyll serve" for jekyll 5 - pandoc=2.11 - - nodejs=8.12 # for makehtml + - nodejs=14.8 # for makehtml # - gxx_linux-64=12.2 # - weasyprint=v51 # - xelatex 3.14159265-2.6-0.999991