diff --git a/docs/_includes/head.html b/docs/_includes/head.html index d71d5f01..692bab31 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -19,7 +19,7 @@ {%- assign subtitle = page.type | replace: "_", " " %} {%- endif %} {%- capture title %}{% if page.url == "/" %}{{site.title}}{% elsif page.title %}{% if subtitle %}{{subtitle}}: {% endif %}{{ page.title }} | {{ site.title }}{%- else %}{{ site.title }}{% endif %}{% endcapture %} - {%- capture description %}{% if page.url == "/" %}{{site.description}}{% elsif page.description %}{{ page.description | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% elsif page.summary %}{{ page.summary | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% else %}{{ page.content | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% endif %}{% endcapture %} + {%- capture description %}{% if page.url == "/" or page.url == "/index" %}{{site.description}}{% elsif page.description %}{{ page.description | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% elsif page.summary %}{{ page.summary | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% elsif page.excerpt %}{{ page.excerpt | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% else %}{{ page.content | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% endif %}{% endcapture %} {{title}} diff --git a/docs/_specification/1.0/index.md b/docs/_specification/1.0/index.md index cde5b10b..fc1d95f4 100644 --- a/docs/_specification/1.0/index.md +++ b/docs/_specification/1.0/index.md @@ -1,5 +1,7 @@ --- title: RO-Crate 1.0 +excerpt: | + This document specifies a method, known as _RO-Crate_ (Research Object Crate), of organizing file-based data with associated metadata, using [linked data] principles, in both human and machine readable formats, with the ability to include additional domain-specific metadata. redirect_from: - /1.0/ nav_exclude: true diff --git a/docs/_specification/1.1/appendix/jsonld.md b/docs/_specification/1.1/appendix/jsonld.md index c3525adf..2c179faa 100644 --- a/docs/_specification/1.1/appendix/jsonld.md +++ b/docs/_specification/1.1/appendix/jsonld.md @@ -3,6 +3,10 @@ title: RO-Crate JSON-LD redirect_from: - /1.1-DRAFT/appendix/jsonld - /1.1/appendix/jsonld +excerpt: | + It is not necessary to use [JSON-LD tooling] to generate or parse the _RO-Crate Metadata Document_, although JSON-LD tools may make it easier to conform to this specification, e.g. handling relative URIs. It is however RECOMMENDED to use [JSON tooling][JSON] to handle [JSON][RFC 7159] syntax and escaping rules. + + This appendix shows a brief JSON-LD introduction for complying with the _RO-Crate Metadata Document_ requirements. parent: Appendix grand_parent: RO-Crate 1.1 --- diff --git a/docs/_specification/1.1/appendix/relative-uris.md b/docs/_specification/1.1/appendix/relative-uris.md index 786bb543..987c4257 100644 --- a/docs/_specification/1.1/appendix/relative-uris.md +++ b/docs/_specification/1.1/appendix/relative-uris.md @@ -1,5 +1,11 @@ --- title: Handling relative URI references +excerpt: | + The _RO-Crate Metadata File_ use _relative URI references_ to identify files and directories + contained within the _RO-Crate Root_ and its children. As described in section + [Describing entities in JSON-LD](jsonld#describing-entities-in-json-ld) above, + relative URI references are also frequently used for + identifying _Contextual entities_. parent: Appendix grand_parent: RO-Crate 1.1 redirect_from: diff --git a/docs/_specification/1.1/data-entities.md b/docs/_specification/1.1/data-entities.md index 8b764a60..cf5682c8 100644 --- a/docs/_specification/1.1/data-entities.md +++ b/docs/_specification/1.1/data-entities.md @@ -3,6 +3,14 @@ title: Data Entities redirect_from: - /1.1-DRAFT/data-entities - /1.1/data-entities +excerpt: | + The primary purpose for RO-Crate is to gather and describe a set of _Data entities_ in the form of: + + * Files + * Directories + * Web resources + + The data entities can be further described by referencing [contextual entities](contextual-entities) such as persons, organizations and publications. nav_order: 6 parent: RO-Crate 1.1 --- diff --git a/docs/_specification/1.1/introduction.md b/docs/_specification/1.1/introduction.md index c661b9f3..0d50ec59 100644 --- a/docs/_specification/1.1/introduction.md +++ b/docs/_specification/1.1/introduction.md @@ -3,6 +3,8 @@ title: Introduction redirect_from: - /1.1-DRAFT/introduction - /1.1/introduction +excerpt: | + This document specifies a method, known as _RO-Crate_ (Research Object Crate), of aggregating and describing research data with associated metadata. RO-Crates can aggregate and describe any resource including files, URI-addressable resources, or use other addressing schemes to locate digital or physical data. RO-Crates can describe data both in aggregate and at the individual resource level, with metadata to aid in discovery, and for the re-use and long term management of data. Metadata provides the ability to describe the context of data and entities involved in its production, use and reuse. For example: who created it, using which equipment, software and workflows, under which license it can be re-used, where it was collected, and/or what it is *about*. nav_order: 1 parent: RO-Crate 1.1 --- diff --git a/docs/_specification/1.1/provenance.md b/docs/_specification/1.1/provenance.md index 5bf0a3b5..712bbeb7 100644 --- a/docs/_specification/1.1/provenance.md +++ b/docs/_specification/1.1/provenance.md @@ -3,6 +3,8 @@ title: Provenance of entities redirect_from: - /1.1-DRAFT/provenance - /1.1/provenance +excerpt: | + To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following case the equipment is a bespoke machine. The equipment SHOULD be described on a web page, and the address of the description SHOULD be used as its `@id`. nav_order: 8 parent: RO-Crate 1.1 --- diff --git a/docs/_specification/1.1/root-data-entity.md b/docs/_specification/1.1/root-data-entity.md index 9d5a5adc..26d73f32 100644 --- a/docs/_specification/1.1/root-data-entity.md +++ b/docs/_specification/1.1/root-data-entity.md @@ -3,6 +3,10 @@ title: Root Data Entity redirect_from: - /1.1-DRAFT/root-data-entity - /1.1/root-data-entity +excerpt: | + The **Root Data Entity** is a [Dataset] that represents the RO-Crate as a whole; + a _Research Object_ that includes the _Data Entities_ and the related + _Contextual Entities_. nav_order: 5 parent: RO-Crate 1.1 --- diff --git a/docs/_specification/1.1/structure.md b/docs/_specification/1.1/structure.md index 75fd629d..6dd0641c 100644 --- a/docs/_specification/1.1/structure.md +++ b/docs/_specification/1.1/structure.md @@ -3,6 +3,17 @@ title: RO-Crate Structure redirect_from: - /1.1-DRAFT/structure - /1.1/structure +excerpt: | + The structure an _RO-Crate_ MUST follow is: + + ``` + / + | ro-crate-metadata.json # RO-Crate Metadata File MUST be present + | ro-crate-preview.html # RO-Crate Website homepage MAY be present + | ro-crate-preview_files/ # MAY be present + | | [other RO-Crate Website files] + | [payload files and directories] # 0 or more + ``` nav_order: 3 parent: RO-Crate 1.1 --- diff --git a/docs/_specification/1.2/appendix/implementation-notes.md b/docs/_specification/1.2/appendix/implementation-notes.md index 2a7b9e8c..b04eec00 100644 --- a/docs/_specification/1.2/appendix/implementation-notes.md +++ b/docs/_specification/1.2/appendix/implementation-notes.md @@ -1,5 +1,6 @@ --- title: Implementation notes +description: Guidance on programming with JSON-LD, combining RO-Crate with other packaging schemes, and repository-specific identifiers redirect_from: - /1.2-DRAFT/appendix/implementation-notes - /specification/1.2-DRAFT/appendix/implementation-notes diff --git a/docs/_specification/1.2/appendix/jsonld.md b/docs/_specification/1.2/appendix/jsonld.md index 1cd862ea..0e841252 100644 --- a/docs/_specification/1.2/appendix/jsonld.md +++ b/docs/_specification/1.2/appendix/jsonld.md @@ -4,6 +4,10 @@ redirect_from: - /1.2-DRAFT/appendix/jsonld - /specification/1.2-DRAFT/appendix/jsonld - /specification/1.2-RC1/appendix/jsonld +excerpt: | + It is not necessary to use [JSON-LD tooling] to generate or parse the _RO-Crate Metadata Document_, although JSON-LD tools may make it easier to conform to this specification, e.g. handling relative URIs. It is however RECOMMENDED to use [JSON tooling][JSON] to handle [JSON][RFC 7159] syntax and escaping rules. + + This appendix shows a brief JSON-LD introduction for complying with the _RO-Crate Metadata Document_ requirements. parent: Appendix grand_parent: RO-Crate 1.2 nav_order: 22 diff --git a/docs/_specification/1.2/appendix/relative-uris.md b/docs/_specification/1.2/appendix/relative-uris.md index 289baf92..7781d4cc 100644 --- a/docs/_specification/1.2/appendix/relative-uris.md +++ b/docs/_specification/1.2/appendix/relative-uris.md @@ -4,6 +4,13 @@ redirect_from: - /1.2-DRAFT/appendix/relative-uris - /specification/1.2-DRAFT/appendix/relative-uris - /specification/1.2-RC1/appendix/relative-uris +excerpt: | + In an _Attached RO-Crate Package_, the _RO-Crate Metadata File_ use _relative URI references_ + to identify files and directories + contained within the _RO-Crate Root_ and its children. As described in section + [Describing entities in JSON-LD](jsonld#describing-entities-in-json-ld), + relative URI references are also frequently used for + identifying _Contextual entities_. parent: Appendix grand_parent: RO-Crate 1.2 nav_order: 23 diff --git a/docs/_specification/1.2/data-entities.md b/docs/_specification/1.2/data-entities.md index 633471d5..fd3fde7d 100644 --- a/docs/_specification/1.2/data-entities.md +++ b/docs/_specification/1.2/data-entities.md @@ -4,6 +4,11 @@ redirect_from: - /1.2-DRAFT/data-entities - /specification/1.2-DRAFT/data-entities - /specification/1.2-RC1/data-entities +excerpt: | + The primary purpose for RO-Crate is to gather and describe a set of _Data Entities_ in the form of: + + * Actual files which are datastreams available on the local file system or over the web -- when represented in the RO-Crate Metadata Document, these have the type `File`. + * Folders (or directories) of files -- represented using the type `Dataset`. nav_order: 6 parent: RO-Crate 1.2 --- diff --git a/docs/_specification/1.2/introduction.md b/docs/_specification/1.2/introduction.md index cfcfe591..eee89915 100644 --- a/docs/_specification/1.2/introduction.md +++ b/docs/_specification/1.2/introduction.md @@ -4,6 +4,8 @@ redirect_from: - /1.2-DRAFT/introduction - /specification/1.2-DRAFT/introduction - /specification/1.2-RC1/introduction +excerpt: | + This document specifies a method, known as _RO-Crate_ (Research Object Crate), of aggregating and describing data for distribution, re-use, publishing, preservation and archiving. RO-Crates aggregate data into a Dataset, and may describe any resource including files, URI-addressable resources, or use other addressing schemes to locate digital or physical data. Describing resources includes technical metadata such as file sizes and types as well as contextual information including how and where datasets and files were created, how they were collated and collected, who was involved in the process, what equipment and software was used, who funded the work, how to cite it, and crucially, how it may be reused, and by whom. nav_order: 1 parent: RO-Crate 1.2 --- diff --git a/docs/_specification/1.2/provenance.md b/docs/_specification/1.2/provenance.md index b4f9c564..96bab935 100644 --- a/docs/_specification/1.2/provenance.md +++ b/docs/_specification/1.2/provenance.md @@ -4,6 +4,8 @@ redirect_from: - /1.2-DRAFT/provenance - /specification/1.2-DRAFT/provenance - /specification/1.2-RC1/provenance +excerpt: | + To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following case the equipment is a bespoke machine. The equipment SHOULD be described on a web page, and the address of the description SHOULD be used as its `@id`. nav_order: 9 parent: RO-Crate 1.2 --- diff --git a/docs/_specification/1.2/root-data-entity.md b/docs/_specification/1.2/root-data-entity.md index cb9ec3f0..c67ebf47 100644 --- a/docs/_specification/1.2/root-data-entity.md +++ b/docs/_specification/1.2/root-data-entity.md @@ -4,6 +4,10 @@ redirect_from: - /1.2-DRAFT/root-data-entity - /specification/1.2-DRAFT/root-data-entity - /specification/1.2-RC1/root-data-entity +excerpt: | + The **Root Data Entity** is a [Dataset] that represents the RO-Crate as a whole; + a _Research Object_ that includes the _Data Entities_ and the related + _Contextual Entities_. nav_order: 5 parent: RO-Crate 1.2 --- diff --git a/docs/_specification/1.2/structure.md b/docs/_specification/1.2/structure.md index bafca1ad..9db18734 100644 --- a/docs/_specification/1.2/structure.md +++ b/docs/_specification/1.2/structure.md @@ -4,6 +4,18 @@ redirect_from: - /1.2-DRAFT/structure - /specification/1.2-DRAFT/structure - /specification/1.2-RC1/structure +excerpt: | + An [_RO-Crate Metadata Document_](#ro-crate-metadata-document-ro-crate-metadatajson) is used to package data in one of two ways: + + 1. An _Attached RO-Crate Package_ that defines an on-disk collection of data: + - It is defined within a file-system-like service as a directory (known as the _RO-Crate Root_) with the _RO-Crate Metadata Document_ saved in a file-like entity with a file name of `ro-crate-metadata.json`. + - References to files and directories in the _RO-Crate Metadata Document_ are present in the RO-Crate or available online as [Web-based Data Entities](data-entities.html#web-based-data-entities). + - Typically, software processing an _Attached RO-Crate Package_ would be passed a path to a directory or a zip file. + 2. A _Detached RO-Crate Package_: + - Is defined by a stand-alone _RO-Crate Metadata Document_ which may be stored in a file or distributed via an API. + - References to files and directories in the _RO-Crate Metadata Document_ are all Web-based Data Entities. + - If stored in a file, known as a _Detached RO-Crate Metadata File_, the filename SHOULD be `${prefix}-ro-crate-metadata.json` rather than `ro-crate-metadata.json` where the variable `${prefix}` is a human readable version of the dataset's ID or name, to signal that on disk, the presence of the file does not indicate an _Attached RO-Crate Data Package_. + - Typically, software processing a _Detached RO-Crate Package_ would be passed a path to a file, an absolute URI, or a JSON string or object, without a directory context. nav_order: 3 parent: RO-Crate 1.2 --- diff --git a/docs/_specification/1.3-DRAFT/appendix/jsonld.md b/docs/_specification/1.3-DRAFT/appendix/jsonld.md index 0bfe0442..3e475806 100644 --- a/docs/_specification/1.3-DRAFT/appendix/jsonld.md +++ b/docs/_specification/1.3-DRAFT/appendix/jsonld.md @@ -2,6 +2,11 @@ title: RO-Crate JSON-LD redirect_from: - /1.3-DRAFT/appendix/jsonld +excerpt: | + It is not necessary to use [JSON-LD tooling] to generate or parse the _RO-Crate Metadata Document_, although JSON-LD tools may make it easier to conform to this specification, e.g. handling relative URIs. It is however RECOMMENDED to use [JSON tooling][JSON] to handle [JSON][RFC 7159] syntax and escaping rules. + + This appendix shows a brief JSON-LD introduction for complying with the _RO-Crate Metadata Document_ requirements. + parent: Appendix grand_parent: RO-Crate 1.3-DRAFT nav_order: 22 diff --git a/docs/_specification/1.3-DRAFT/appendix/relative-uris.md b/docs/_specification/1.3-DRAFT/appendix/relative-uris.md index 31c8a466..8b7f5de5 100644 --- a/docs/_specification/1.3-DRAFT/appendix/relative-uris.md +++ b/docs/_specification/1.3-DRAFT/appendix/relative-uris.md @@ -2,6 +2,13 @@ title: Handling relative URI references redirect_from: - /1.3-DRAFT/appendix/relative-uris +excerpt: | + In an _Attached RO-Crate Package_, the _RO-Crate Metadata File_ use _relative URI references_ + to identify files and directories + contained within the _RO-Crate Root_ and its children. As described in section + [Describing entities in JSON-LD](jsonld#describing-entities-in-json-ld), + relative URI references are also frequently used for + identifying _Contextual entities_. parent: Appendix grand_parent: RO-Crate 1.3-DRAFT nav_order: 23 diff --git a/docs/_specification/1.3-DRAFT/data-entities.md b/docs/_specification/1.3-DRAFT/data-entities.md index 62389b28..68148420 100644 --- a/docs/_specification/1.3-DRAFT/data-entities.md +++ b/docs/_specification/1.3-DRAFT/data-entities.md @@ -2,6 +2,11 @@ title: Data Entities redirect_from: - /1.3-DRAFT/data-entities +excerpt: | + The primary purpose for RO-Crate is to gather and describe a set of _Data Entities_ in the form of: + + * Actual files which are datastreams available on the local file system or over the web -- when represented in the RO-Crate Metadata Document, these have the type `File`. + * Folders (or directories) of files -- represented using the type `Dataset`. nav_order: 6 parent: RO-Crate 1.3-DRAFT --- diff --git a/docs/_specification/1.3-DRAFT/introduction.md b/docs/_specification/1.3-DRAFT/introduction.md index 25b459f0..d203fefb 100644 --- a/docs/_specification/1.3-DRAFT/introduction.md +++ b/docs/_specification/1.3-DRAFT/introduction.md @@ -2,6 +2,8 @@ title: Introduction redirect_from: - /1.3-DRAFT/introduction +excerpt: | + This document specifies a method, known as _RO-Crate_ (Research Object Crate), of aggregating and describing data for distribution, re-use, publishing, preservation and archiving. RO-Crates aggregate data into a Dataset, and may describe any resource including files, URI-addressable resources, or use other addressing schemes to locate digital or physical data. Describing resources includes technical metadata such as file sizes and types as well as contextual information including how and where datasets and files were created, how they were collated and collected, who was involved in the process, what equipment and software was used, who funded the work, how to cite it, and crucially, how it may be reused, and by whom. nav_order: 1 parent: RO-Crate 1.3-DRAFT --- diff --git a/docs/_specification/1.3-DRAFT/provenance.md b/docs/_specification/1.3-DRAFT/provenance.md index cd9d0d5b..6c83fe5c 100644 --- a/docs/_specification/1.3-DRAFT/provenance.md +++ b/docs/_specification/1.3-DRAFT/provenance.md @@ -2,6 +2,8 @@ title: Provenance of entities redirect_from: - /1.3-DRAFT/provenance +excerpt: | + To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following case the equipment is a bespoke machine. The equipment SHOULD be described on a web page, and the address of the description SHOULD be used as its `@id`. nav_order: 9 parent: RO-Crate 1.3-DRAFT --- diff --git a/docs/_specification/1.3-DRAFT/root-data-entity.md b/docs/_specification/1.3-DRAFT/root-data-entity.md index 306759af..72b91456 100644 --- a/docs/_specification/1.3-DRAFT/root-data-entity.md +++ b/docs/_specification/1.3-DRAFT/root-data-entity.md @@ -2,6 +2,10 @@ title: Root Data Entity redirect_from: - /1.3-DRAFT/root-data-entity +excerpt: | + The **Root Data Entity** is a [Dataset] that represents the RO-Crate as a whole; + a _Research Object_ that includes the _Data Entities_ and the related + _Contextual Entities_. nav_order: 5 parent: RO-Crate 1.3-DRAFT --- diff --git a/docs/_specification/1.3-DRAFT/structure.md b/docs/_specification/1.3-DRAFT/structure.md index 3ee45b5e..c0b6380d 100644 --- a/docs/_specification/1.3-DRAFT/structure.md +++ b/docs/_specification/1.3-DRAFT/structure.md @@ -2,6 +2,18 @@ title: RO-Crate Structure redirect_from: - /1.3-DRAFT/structure +excerpt: | + An [_RO-Crate Metadata Document_](#ro-crate-metadata-document-ro-crate-metadatajson) is used to package data in one of two ways: + + 1. An _Attached RO-Crate Package_ that defines an on-disk collection of data: + - It is defined within a file-system-like service as a directory (known as the _RO-Crate Root_) with the _RO-Crate Metadata Document_ saved in a file-like entity with a file name of `ro-crate-metadata.json`. + - References to files and directories in the _RO-Crate Metadata Document_ are present in the RO-Crate or available online as [Web-based Data Entities](data-entities.html#web-based-data-entities). + - Typically, software processing an _Attached RO-Crate Package_ would be passed a path to a directory or a zip file. + 2. A _Detached RO-Crate Package_: + - Is defined by a stand-alone _RO-Crate Metadata Document_ which may be stored in a file or distributed via an API. + - References to files and directories in the _RO-Crate Metadata Document_ are all Web-based Data Entities. + - If stored in a file, known as a _Detached RO-Crate Metadata File_, the filename SHOULD be `${prefix}-ro-crate-metadata.json` rather than `ro-crate-metadata.json` where the variable `${prefix}` is a human readable version of the dataset's ID or name, to signal that on disk, the presence of the file does not indicate an _Attached RO-Crate Data Package_. + - Typically, software processing a _Detached RO-Crate Package_ would be passed a path to a file, an absolute URI, or a JSON string or object, without a directory context. nav_order: 3 parent: RO-Crate 1.3-DRAFT --- diff --git a/docs/pages/about/about_ro_crate.md b/docs/pages/about/about_ro_crate.md index 0349b664..1ef9e0c4 100644 --- a/docs/pages/about/about_ro_crate.md +++ b/docs/pages/about/about_ro_crate.md @@ -1,5 +1,6 @@ --- title: About RO-Crate +description: What RO-Crate is, how RO-Crate makes research FAIR, and how to get started sidebar: about --- diff --git a/docs/pages/community/blog.md b/docs/pages/community/blog.md index 35e33a12..4a9c1807 100644 --- a/docs/pages/community/blog.md +++ b/docs/pages/community/blog.md @@ -1,5 +1,6 @@ --- title: Blog +description: Latest updates from the RO-Crate community permalink: /blog sidebar: blog --- diff --git a/docs/pages/community/community.md b/docs/pages/community/community.md index e9ce204b..e11c34a0 100644 --- a/docs/pages/community/community.md +++ b/docs/pages/community/community.md @@ -1,5 +1,6 @@ --- title: Community +description: The RO-Crate team, community meetings, and how to get in touch ---