diff --git a/docs/_specification/1.2-DRAFT/data-entities.md b/docs/_specification/1.2-DRAFT/data-entities.md index a556907d..faea08bd 100644 --- a/docs/_specification/1.2-DRAFT/data-entities.md +++ b/docs/_specification/1.2-DRAFT/data-entities.md @@ -34,9 +34,9 @@ parent: RO-Crate 1.2-DRAFT The primary purpose for RO-Crate is to gather and describe a set of _Data entities_ in the form of: -* Files +* Files which are datastreams available on the local file system or over the web * Directories -* Web resources + The data entities can be further described by referencing [contextual entities](contextual-entities) such as persons, organizations and publications. @@ -44,15 +44,15 @@ The data entities can be further described by referencing [contextual entities]( Where files and folders are represented as _Data Entities_ in the RO-Crate JSON-LD, these MUST be linked to, either directly or indirectly, from the [Root Data Entity](root-data-entity) using the [hasPart] property. Directory hierarchies MAY be represented with nested [Dataset] _Data Entities_, or the Root Data Entity MAY refer to files anywhere in the hierarchy using [hasPart]. -_Data Entities_ representing files MUST have `"File"` as a value for `@type`. `File` is an RO-Crate alias for . The term _File_ includes: -- _Attached_ resources where `@id` is a URI (path) relative to the _RO-Crate Root_ which MUST resolve to a file. -- _Detached_ "downloadable" resources where `@id` is an absolute URI which resolves to a single datastream that can be downloaded and saved as a file. _Detached_ Files SHOULD NOT reference intermediate resources such as splash-pages, search services or web-based viewer applications. +_Data Entities_ representing files: MUST have `"File"` as a value for `@type`. `File` is an RO-Crate alias for . The term _File_ includes: +- _Attached_ resources which are available locally and +- _Detached_ "downloadable" resources which can be can be downloaded and saved as a file. -_Data Entities_ representing directories MUST have `Dataset` as a value for `@type`. The term _directory_ here includes HTTP file listings where `@id` is an absolute URI, however "external," _Detached_ directories SHOULD have a programmatic listing of their content (e.g. another RO-Crate). It follows that the _RO-Crate Root_ is itself a data entity. +The rules for the `@id` property of Files are set out below. -_Data Entities_ can also be other types, for instance an online database. These SHOULD have a `@type` of [CreativeWork] (or one of its subtypes) and typically have a `@id` which is an absolute URI. +_Data Entities_ representing directories MUST have `Dataset` as a value for `@type`. The term _directory_ here includes HTTP file listings where `@id` is an absolute URI, however "external," _Detached_ directories SHOULD have a programmatic listing of their content (e.g. another RO-Crate). It follows that the _RO-Crate Root_ is itself a data entity. -In all cases, `@type` MAY be an array in order to also specify a more specific type, e.g. `"@type": ["File", "ComputationalWorkflow"]` +In all cases, `@type` MAY be an array to also specify a more specific type, e.g. `"@type": ["File", "ComputationalWorkflow"]` There is no requirement to represent _every_ file and folder in an RO-Crate as _Data Entities_ in the _RO-Crate JSON-LD_. Reasons for not describing files would include that the files: - are described in some other way, for example a manifest or another package management system, @@ -63,9 +63,64 @@ There is no requirement to represent _every_ file and folder in an RO-Crate as _ In any of the above cases where files are not described, a directory containing a set of files _MAY_ be described using a `Dataset` _Data Entity_ that encapsulates the files with a `description` property that explains the contents. If the RO-Crate file structure is flat, or files are not grouped together, a `description` property on the _Root Data Entity_ may be used, or a `Dataset` with a local reference beginning with `#` (e.g. to describe a certain type of file which occurs throughout the crate). This approach is recommended for RO-Crates which are to be deposited in a long-term archive. +## Core Metadata for Data Entities + + +### Encoding file paths + +Note that all `@id` [identifiers must be valid URI references](appendix/jsonld#describing-entities-in-json-ld), care must be taken to express any relative paths using `/` separator, correct casing, and escape special characters like space (`%20`) and percent (`%25`), for instance a _File Data Entity_ from the Windows path `Results and Diagrams\almost-50%.png` becomes `"@id": "Results%20and%20Diagrams/almost-50%25.png"` in the _RO-Crate JSON-LD_. + +In this document the term _URI_ includes international *IRI*s; the _RO-Crate Metadata Document_ is always UTF-8 and international characters in identifiers SHOULD be written using native UTF-8 characters (*IRI*s), however traditional URL encoding of Unicode characters with `%` MAY appear in `@id` strings. Example: `"@id": "面试.mp4"` is preferred over the equivalent `"@id": "%E9%9D%A2%E8%AF%95.mp4"` + + +### File Data Entity {#file-data-entity} + +A [File] _Data Entity_ MUST have the following properties: + +* `@type`: MUST be `File`, or an array where `File` is one of the values. +* `@id`: MUST be a relative or absolute URI. + +A [File] MAY have also a `contentURL` property which links to an online copy of the file. + +Further constraints on the `@id` are dependent on whether the [File] entity is being considered as part of an _Attached RO-Crate Package_ or _Detached RO-Crate Package_. + +If an `@id` is a relative URI then it is treated as a `filePath`, which is calculated by appending the `@id` to the `RO-Crate Root`. + +Both `@id` and and `contentURL` may be used in a variety of combinations: + +1. For a _Attached RO-Crate Package_: + * If a `contentUrl` is present `@id` MUST be a A valid relative URI reference and `contentURL` must be an absolute URI. In this case a file may or may not be present at `filePath`. If it is not present then the presence of the `contentUrl` property is an indication that the File content may be sourced from that URL. + * If no `contentURL` is present `@id` MUST be one of either: + a. A relative URI indicating that an file MUST be present at `filePath` when validating a package. + b. An Absolute URI indicating that the entity is a [Web-based Data Entity](#web-based-data-entity). + +2. For a _Detached RO-Crate Package_ all [File] Data Entities are [Web-based Data Enties](#web-based-data-entity) + * If a `contentUrl`is present: `@id` MUST be a A valid relative URI reference and `contentURL` must be an absolute URI. The presence of the `contentUrl` property is an indication that the File content may be sourced from that URL and if the _Detached RO-Crate Package_ were to be converted to an _Attached RO-Crate Package_ the `@id` indicates the `filePath` to use for saving a local copy of the [File]. + * If there is no `contentUrl`: `@id` MUST be an Absolute URI + + + + +Additionally, `File` entities SHOULD have: + +* [name] giving a human readable name (not necessarily the filename) +* [description] giving a longer description, e.g. the role of this file within this crate +* [encodingFormat] indicating the the IANA [media type] as a string (e.g. `"text/plain") and/or a reference to [file format](#adding-detailed-descriptions-of-encodings) contextual entity. +* [conformsTo] to a contextual entity of type [Profile], that indicate a [profile](profiles) of the encoding format, if applicable +* [contentSize] with the size of the file in bytes + +RO-Crate's `File` is an alias for schema.org type [MediaObject], any of its properties MAY also be used (adding contextual entities as needed). [Files on the web](#embedded-data-entities-that-are-also-on-the-web) SHOULD also use `identifier`, `url`, `subjectOf`, and/or `mainEntityOfPage`. + + +{.note} +> It is up to implementers to decide whether to offer some form of URL "link checker" service [Web-based Data Entities](#web-based-data-entity) for both attached and Detached RO-Crate Packages. If `contentUrl` has more than one value then a checker service SHOULD try each provided value until one resolves, and returns a correct [contentSize]. + -### Example linking to a file and folders + +### _Attached RO-Crate Package_ + + Example linking to a file and folders ``` / @@ -123,7 +178,7 @@ An example _RO-Crate JSON-LD_ for the above would be as follows: If the dataset contained a large number of `*.ai` files which were spread throughout the crate structure and which did not have `File Data Entities` then a approach to describing them would be: -``` +```json { "@id": "./", "@type": [ @@ -234,43 +289,25 @@ Some generic file formats like `application/json` may be specialized using a _pr 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. -## Core Metadata for Data Entities - - -### Encoding file paths - -Note that all `@id` [identifiers must be valid URI references](appendix/jsonld#describing-entities-in-json-ld), care must be taken to express any relative paths using `/` separator, correct casing, and escape special characters like space (`%20`) and percent (`%25`), for instance a _File Data Entity_ from the Windows path `Results and Diagrams\almost-50%.png` becomes `"@id": "Results%20and%20Diagrams/almost-50%25.png"` in the _RO-Crate JSON-LD_. - -In this document the term _URI_ includes international *IRI*s; the _RO-Crate Metadata Document_ is always UTF-8 and international characters in identifiers SHOULD be written using native UTF-8 characters (*IRI*s), however traditional URL encoding of Unicode characters with `%` MAY appear in `@id` strings. Example: `"@id": "面试.mp4"` is preferred over the equivalent `"@id": "%E9%9D%A2%E8%AF%95.mp4"` - - -### File Data Entity - -A [File] _Data Entity_ MUST have the following properties: - -* `@type`: MUST be `File`, or an array where `File` is one of the values. -* `@id`: MUST be either a _URI Path_ relative to the _RO-Crate root_ which MUST resolve to a file that is present in the _RO-Crate Root_, or an absolute URI. - -Additionally, `File` entities SHOULD have: - -* [name] giving a human readable name (not necessarily the filename) -* [description] giving a longer description, e.g. the role of this file within this crate -* [encodingFormat] indicating the the IANA [media type] as a string (e.g. `"text/plain") and/or a reference to [file format](#adding-detailed-descriptions-of-encodings) contextual entity. -* [conformsTo] to a contextual entity of type [Profile], that indicate a [profile](profiles) of the encoding format, if applicable -* [contentSize] with the size of the file in bytes -RO-Crate's `File` is an alias for schema.org type [MediaObject], any of its properties MAY also be used (adding contextual entities as needed). [Files on the web](#embedded-data-entities-that-are-also-on-the-web) SHOULD also use `identifier`, `url`, `subjectOf`, and/or `mainEntityOfPage`. -### Directory File Entity +### Directory Data Entity A [Dataset] (directory) _Data Entity_ MUST have the following properties: * `@type` MUST be `Dataset` or an array where `Dataset` is one of the values. * `@id` MUST be either: - * a _URI Path_ relative to the _RO Crate root_ which MUST resolve to a directory that is present in the _RO-Crate Root_. The id SHOULD end with `/`. + * a _URI Path_ that SHOULD end with `/`. * an absolute URI * a local reference beginning with `#` +For an _Attached RO-Crate Package_: +* The `@id` MUST be a relative path that resolves to a directory that is present in the _RO-Crate Root_. + +For a _Detached RO-Crate Package_: +* If the `@id` is a _URI Path it MAY be used to create a directory and MAY resolve to a service which returns a list of files +* If the `@id` is a URL then it SHOULD resolve to a service which returns a list of files + Additionally, `Dataset` entities SHOULD have: * [name] giving a human readable name (not necessarily the directory name) @@ -283,7 +320,7 @@ Any of the properties of schema.org [Dataset] MAY additionally be used (adding c ## Web-based Data Entities -While one use-case of RO-Crates is to describe _files_ contained within the _RO-Crate Root_ directory, RO-Crates can also gather resources from the web identified by _absolute URIs_ instead of relative _URI paths_, i.e. Web-based data entities. + Using Web-based data entities can be important particularly where a file can't be included in the _RO-Crate Root_ because of licensing concerns, large data sizes, privacy, or where it is desirable to link to the latest online version. @@ -331,6 +368,7 @@ Example of an RO-Crate including a _File Data Entity_ external to the _RO-Crate } ``` + Additional care SHOULD be taken to improve persistence and long-term preservation of web resources included in an RO-Crate, as they can be more difficult to archive or move along with the _RO-Crate Root_, and may change intentionally or unintentionally, leaving the RO-Crate with incomplete or outdated information. @@ -373,7 +411,9 @@ These MAY be included for File Data Entities as additional metadata, regardless * [subjectOf] to a [CreativeWork] (or [WebPage]) that mentions this file or its content (but also other resources) * [mainEntityOfPage] to a [CreativeWork] (or [WebPage]) that primarily describes this file (or its content) -Note that if a local file is intended to be packaged within an _Attached RO-Crate_, the `@id` property MUST be a _URI Path_ relative to the _RO Crate Root_, for example `survey-responses-2019.csv` as in the example below, where the content URL points to a download endpoint as a string. +If a [contentUrl] is present, then in an _Attached RO-Crate Package_ the file MAY be omitted from the packages, for example if it is very large or if of peripheral interest. Core files should NOT be omitted. + +Note that if a local file is intended to be packaged within an _Attached RO-Crate Package_, the `@id` property MUST be a _URI Path_ relative to the _RO Crate root_, for example `survey-responses-2019.csv` as in the example below, where the content URL points to a download endpoint as a string. ```json { @@ -523,38 +563,6 @@ Similarly, the _RO-Crate Root_ entity (or a reference to another RO-Crate as a ` In all cases, consumers should be aware that a `DataDownload` is a snapshot that may not reflect the current state of the `Dataset` or RO-Crate. -#### Retrieving an RO-Crate - -To resolve a reference to an RO-Crate, but where `subjectOf` or `distribution` is unknown (e.g. an RO-Crate is cited from a journal article), the below approach is recommended to retrieve its [RO-Crate Metadata Document](structure#ro-crate-metadata-document-ro-crate-metadatajson): - -1. Assuming the URI is a permalink, after following HTTP redirects without content negotiation, try [Signposting] to look for `Link` headers that reference `Link rel="describedby"` for an _RO-Crate Metadata Document_, or `Link rel="item"` for a distribution archive -- in either case prefer a link with `profile="https://w3id.org/ro/crate"` declared. For example, signposting for `https://doi.org/10.48546/workflowhub.workflow.120.5` leads to the archive `https://workflowhub.eu/workflows/120/ro_crate?version=5` as: - - ``` - curl --location --head https://doi.org/10.48546/workflowhub.workflow.120.5 - - HTTP/2 302 - Location: https://workflowhub.eu/workflows/120?version=5 - - HTTP/2 200 - Content-Type: text/html; charset=UTF-8 - Link: ; - rel="item" ; type="application/zip" ; - profile="https://w3id.org/ro/crate" - ``` -2. [HTTP Content-negotiation] for the [RO-Crate media type](appendix/jsonld#ro-crate-json-ld-media-type), for example: - - Requesting `https://w3id.org/workflowhub/workflow-ro-crate/1.0` with HTTP header - `Accept: application/ld+json;profile=https://w3id.org/ro/crate` redirects to the _RO-Crate Metadata file_ - `https://about.workflowhub.eu/Workflow-RO-Crate/1.0/ro-crate-metadata.json` - -3. The above approaches may fail or return a HTML page, e.g. for content-delivery networks that do not support content-negotiation. -4. An optional heuristic fallback is to try resolving the path `./ro-crate-metadata.json` from the _resolved_ URI (after permalink redirects). For example: -If permalink `https://w3id.org/workflowhub/workflow-ro-crate/1.0` redirects to `https://about.workflowhub.eu/Workflow-RO-Crate/1.0/index.html` (a HTML page), then -try retrieving `https://about.workflowhub.eu/Workflow-RO-Crate/1.0/ro-crate-metadata.json`. -5. If the retrieved resource is a ZIP file (`Content-Type: application/zip`), then extract `ro-crate-metadata.json`, or, if the archive root only contains a single folder (e.g. `folder1/`), extract `folder1/ro-crate-metadata.json` -6. If the retrieved resource is a [BagIt archive](appendix/implementation-notes#combining-with-other-packaging-schemes), e.g. containing a single folder `folder1` with `folder1/bagit.txt`, then extract and verify BagIt checksums before returning the bag's `data/ro-crate-metadata.json` -7. If the returned/extracted document is valid JSON-LD and has a [root data entity](root-data-entity#finding-the-root-data-entity), this is the RO-Crate Metadata File. -{% include callout.html type="tip" content="Some PID providers such as DataCite may respond to content-negotiation and provide their own JSON-LD, which do not describe an RO-Crate (the `profile=` was ignored). The use of Signposting allows the repository to explicitly provide the RO-Crate." %} {% include references.liquid %} diff --git a/docs/_specification/1.2-DRAFT/introduction.md b/docs/_specification/1.2-DRAFT/introduction.md index b8797818..2a8d984c 100644 --- a/docs/_specification/1.2-DRAFT/introduction.md +++ b/docs/_specification/1.2-DRAFT/introduction.md @@ -23,6 +23,8 @@ parent: RO-Crate 1.2-DRAFT limitations under the License. --> + + # Introduction 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. diff --git a/docs/_specification/1.2-DRAFT/root-data-entity.md b/docs/_specification/1.2-DRAFT/root-data-entity.md index 246ff7e9..63873702 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 for a _Valid RO-Crate Dataset_ {#root-data-entity} {: .no_toc } ## Table of contents @@ -45,7 +45,7 @@ The _RO-Crate Metadata Document_ MUST contain a self-describing **RO-Crate Metadata Descriptor** with the `@id` value `ro-crate-metadata.json` (or `ro-crate-metadata.jsonld` in legacy crates for RO-Crate 1.0 or older) and `@type` [CreativeWork]. This descriptor MUST have an [about] -property referencing the _Root Data Entity_'s `@id`. +property with a single value referencing the _Root Data Entity_'s `@id`. ```json @@ -67,20 +67,19 @@ property referencing the _Root Data Entity_'s `@id`. } ``` -{% 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." %} +{: .note} +> Even in [Detached RO-Crates](structure#detached-ro-crate-packages) 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/`. +The [conformsTo] property of the _RO-Crate Metadata Descriptor_ +MUST have a single value which is a reference to a versioned permalink URI of the RO-Crate specification starting with `https://w3id.org/ro/crate/`. -{% include callout.html type="tip" content="The `conformsTo` property MAY be an array, to additionally indicate -specializing [RO-Crate profiles](profiles)." %} +{% include callout.html type="tip" content="In RO-Crate 1,2 The `conformsTo` property MAY not have more than one value, to additionally indicate +specializing [RO-Crate profiles](profiles) - these SHOULD be referenced from the _Root Data Entity_." %} ### Finding the Root Data Entity -In most cases, consumers processing the RO-Crate as a JSON-LD graph can thus -reliably find the _Root Data Entity_ by following this algorithm: +Consumers processing the RO-Crate as a JSON-LD graph can +find the _Root Data Entity_ by following this algorithm: 1. For each entity in `@graph` array 2. .. if the `@id` is `ro-crate-metadata.json` @@ -93,7 +92,7 @@ reliably find the _Root Data Entity_ by following this algorithm: 9. .. if the entity has an `@id` URI that matches a non-null _legacyroot_ return it 10. Fail with unknown root data entity. -Note that the above can be implemented efficiently by first building a map `entity_map` of +Note that the above can be implemented efficiently by first building a map (`entity_map`) of all entities using their `@id` as keys (which is typically also helpful for further processing) and then performing a series of lookups. Ignoring the legacy case for now, this lookup code could be: @@ -109,8 +108,8 @@ See also the appendix on ### Purpose of Metadata Document To ensure a base-line interoperability between RO-Crates, and for an RO-Crate to -be considered a _Valid RO-Crate_, a minimum set of metadata is required for the -_Root Data Entity_. As [stated earlier](structure#self-describing-and-self-contained-attached-ro-crates), +be considered a _Valid RO-Crate Dataset_, a minimum set of metadata is required for the +_Root Data Entity_. As [stated earlier](structure#self-describing-and-self-contained-local-ro-crate-packages) the _RO-Crate Metadata Document_ is not an exhaustive manifest or inventory, that is, it does not necessarily list or describe all files in the package. For this reason, there are no minimum @@ -128,7 +127,7 @@ be minimally valid. ## Direct properties of the Root Data Entity -The _Root Data Entity_ MUST have the following properties: +The _Root Data Entity_ of a _Valid RO-Crate Dataset_ MUST have the following properties: * `@type`: MUST be [Dataset] or an array that contains `Dataset` * `@id`: SHOULD be the string `./` or an absolute URI (see [below](#root-data-entity-identifier)) @@ -136,6 +135,7 @@ The _Root Data Entity_ MUST have the following properties: * `description`: SHOULD further elaborate on the name to provide a summary of the context in which the dataset is important. * `datePublished`: MUST be a single string value in [ISO 8601 date format][DateTime], SHOULD be specified to at least the precision of a day, and 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. +* `conformsTo` with a value of {"@id": "https://w3id.org/ro/crate/1.2-DRAFT#ro-crate-dataset"} (may be an array with multiple values) {% 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 @@ -148,13 +148,13 @@ Additional properties of _schema.org_ types [Dataset] and [CreativeWork] MAY be ### Root Data Entity identifier -The root data entity's `@id` SHOULD be either `./` (indicating the directory containing `ro-crate-metadata.json` is the [RO-Crate Root](structure)), or an absolute URI (indicating a [detached RO-Crate](structure#detached-ro-crate)). +The root data entity's `@id` SHOULD be either `./` (indicating the directory of `ro-crate-metadata.json` is the [RO-Crate Root](structure)), or an absolute URI. -If the `@id` of the Root Data Entity is an absolute URI, an _Attached RO-Crate_ MAY contain both [data entities](data-entities) 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`. - -{% include callout.html type="note" content="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." %} +{: note} +> RO-Crates that have been assigned a _persistent identifier_ (e.g. a DOI) MAY 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` or MAY use a full persistent URL as the `@id` for the _Root Data Entity_. +> +> 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 @@ -166,7 +166,7 @@ Any entity which is a subclass of [CreativeWork], including [Dataset]s like the ## Minimal example of RO-Crate -The following _RO-Crate Metadata Document_ represents a minimal description of an _RO-Crate_ that also follows the identifier recommendations above. +The following _RO-Crate Metadata Document_ represents a minimal description of an _RO-Crate_ that also follows the identifier recommendations above for use in a _Local RO-Crate Package_. ```json { "@context": "https://w3id.org/ro/crate/1.2-DRAFT/context", @@ -207,4 +207,24 @@ The following _RO-Crate Metadata Document_ represents a minimal description of a } ``` +Alternatively the following is also valid: + +```json + { + "@id": "ro-crate-metadata.json", + "@type": "CreativeWork", + "about": {"@id": "https://doi.org/10.4225/59/59672c09f4a4b"}, + "conformsTo": {"@id": "https://w3id.org/ro/crate/1.2-DRAFT"} + }, +{ + "@id": "https://doi.org/10.4225/59/59672c09f4a4b", + "@type": "Dataset", + "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/"}, + "creditText": "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" + } +``` {% include references.liquid %} diff --git a/docs/_specification/1.2-DRAFT/structure.md b/docs/_specification/1.2-DRAFT/structure.md index a834e621..89892cfa 100644 --- a/docs/_specification/1.2-DRAFT/structure.md +++ b/docs/_specification/1.2-DRAFT/structure.md @@ -34,30 +34,68 @@ parent: RO-Crate 1.2-DRAFT ## Types of RO-Crate -There are two classes of RO-Crate detailed below: +An _RO-Crate Metadata Document_ is typically used or processed in one of three main ways: -**Attached RO-Crate** -: A crate that is present in a file-system context which has an _RO-Crate Root directory_ and can carry an **explicit payload** of local [data entities](data-entities) as regular files (combined with [Web-based Data Entities](data-entities.html#web-based-data-entities) where needed). This type of RO-Crate can be suitable for packaging a data payload for long-term preservation, transfer and publishing, as the _RO-Crate Metadata Document_ is stored in an _RO-Crate Metadata File_ alongside the crate's payload. See further definition of [attached RO-Crate](#attached-ro-crate) below. +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). +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. + - If stored in a file, known as a _Detached RO-Crate Metadata File_, the filename SHOULD be `${slug}-ro-crate-metadata.json` where the variable `$slug` is a human readable version of the dataset's ID or name, to signal that the document should be interpreted as part of an _Attached RO-Crate Data Package_. +3. As a stand-alone document as part of a tool such as a website generator or crate vizualizer, where data entities are not processed. -**Detached RO-Crate** -: A crate without a defined payload directory. In this kind of crate, all data references are absolute. This approach may be suitable for use with dynamic web service APIs and repositories that can't preserve file paths. As the data of these crates can only be [Web-based Data Entities](data-entities.html#web-based-data-entities), the **payload is implicit** and must be preserved/transferred/archived independent of the _RO-Crate Metadata Document_. See further definition of [detached RO-Crate](#detached-ro-crate) below. -In both types of crates the metadata is completed with [contextual entities](contextual-entities) that further describe the relationships and context of the data to form a _Research Object_. +{.note} + >Client software may provide modes which force a particular packaging mode to be assumed - for example if the software is passed a directory then it would assume that is processing an _Attached RO-Crate Package_, while being passed a path to a file it could work in _Detached RO-Crate Package_ mode, and attempt to resolve _Web Based Data Entities_ OR provide a mode to simply parse the document and process it without referencing or validating Data entities in any special way. -## Attached RO-Crate +In all crates the metadata is completed with [contextual entities](contextual-entities) that further describe the relationships and context of the data to form a _Research Object_. -An **Attached RO-Crate** is used to contain and describe a _payload_ of files and directories, among with their contextual information. +## RO-Crate Metadata Document (`ro-crate-metadata.json`) + +[JSON-LD](https://json-ld.org/) is a structured form of [JSON] that can represent a _Linked Data_ graph. + + +* The _RO-Crate Metadata Document_ MUST contain _RO-Crate JSON-LD_; a valid [JSON-LD 1.0] document in [flattened] and [compacted] form +* The _RO-Crate JSON-LD_ MUST use the _RO-Crate JSON-LD Context_ by reference. + + +The graph in a _Valid RO-Crate Object_ MUST describe: + +1. The [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) +2. The [Root Data Entity](root-data-entity#direct-properties-of-the-root-data-entity) +3. Zero or more [Data Entities](data-entities) +4. Zero or more [Contextual Entities](contextual-entities) + +Any referenced _contextual entities_ SHOULD also be described in the _RO-Crate Metadata Document_ with the same identifier. Similarly any _contextual entity_ in the _RO-Crate Metadata Document_ SHOULD be linked to from at least one of the other entities using the same identifier. -An _Attached RO-Crate_ can be stored and published in multiple ways depending on its use: +The appendix [RO-Crate JSON-LD](appendix/jsonld) details the general structure of the JSON-LD that is expected in the _RO-Crate Metadata Document_. In short, the rest of this specification describe the different types of entities that can be added as `{}` objects to the _RO-Crate JSON-LD_ `@graph` array below: + +```json +{ "@context": "https://w3id.org/ro/crate/1.2-DRAFT/context", + "@graph": [ + + ] +} +``` + + +## Attached RO-Crate Package + +An **Attached RO-Crate Package** is used to contain and describe an optional _payload_ of files and directories as well as web-based data entities among with their contextual information. + +When processing an _Attached RO-Crate Package_ the _RO-Crate Metadata Document_ MUST be present, named `ro-crate-metadata.json` and appear in the _RO-Crate Root_. + + +An _Attached RO-Crate Package_ can be stored and published in multiple ways depending on its use: * On a typical hierarchical _file system_ (e.g. `/files/shared/crates/my-crate-01/`) * Exposed as a _Web resource_ within a folder structure (e.g. ) * [_Packaged_](appendix/implementation-notes#combining-with-other-packaging-schemes) within a ZIP file, BagIt archive or OCFL structure * _Archived_ as a set of named files in other ways (e.g. Zenodo deposit) -A valuable feature of the _Attached RO-Crate_ approach is that the metadata is preserved when a crate is transferred between these types of storage/publication systems. +A valuable feature of the _Attached RO-Crate Package_ approach is that the metadata is preserved when a crate is transferred between these types of storage/publication systems. -The file path structure a _Attached RO-Crate_ MUST follow is: +The file path structure an _Attached RO-Crate Package_ MUST follow is: ``` / @@ -71,76 +109,36 @@ The name of the _RO-Crate root_ directory is not defined, but a root directory i The payload directory (and its child directory) contains files and directories that SHOULD be described within the _RO-Crate Metadata File_ as [Data Entities](data-entities). Additional [Web-based Data Entities](data-entities.html#web-based-data-entities) MAY also be described, but are not considered part of the payload. +The `@id` of a an _Attached RO-Crate Package_ MUST be either `./` or be a URI, such as a DOI URL or other persistent URL which is considered to be the main identifier of the Attached RO-Crate Package. -## Detached RO-Crate - -A _Detached RO-Crate_ is an RO-Crate without a defined root directory, where the _RO-Crate Metadata Document_ and/or _RO-Crate Website_ content is accessed independently (e.g. as part of a programmatic API). - -These crates cannot carry their own data _payload_, but may reference data deposited separately, or purely reference [contextual entities](contextual-entities). - -Any [data entities](data-entities) in a _Detached RO-Crate_ MUST be [Web-based Data Entities](data-entities.html#web-based-data-entities). - -{% 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. - -{% 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 } +> Earlier versions of RO-Crate mandated an `@id` of `./` as a convention for identifying the _Root Data Entity_, but the use of the _RO-Crate Metadata Descriptor_ means that this is no longer required, freeing-up the _Root Data Entity_ `@id` to be used to indicate what should be considered the canonical URI for an RO_Crate Package. Other mechanisms for specifying the 'main identifier' involve multiple JSON-LD entities and may be ambiguous. -Note that a detached RO-Crate may still use `#`-based local identifiers for [contextual entities](contextual-entities). +### Payload files and directories +These are the actual files and directories that make up the **payload** of the dataset being described in an _Attached RO-Crate Package_. -## RO-Crate Metadata Document (`ro-crate-metadata.json`) - -* In an _Attached RO-Crate_ the _RO-Crate Metadata Document_ MUST be present, named `ro-crate-metadata.json` and appear in the _RO-Crate Root_ - - If an RO-Crate conforming to version 1.0 or earlier contains a file named `ro-crate-metadata.jsonld` but not `ro-crate-metadata.json`, then processing software should treat this as the _RO-Crate Metadata File_. If the crate is updated, the file SHOULD be renamed to `ro-crate-metadata.json` and the _RO-Crate Metadata Descriptor_ SHOULD be updated to reference it, with an up to date [conformsTo] property naming an appropriate version of this specification. -* In a _Detached RO-Crate_ the _RO-Crate Metadata Document_ is a JSON-LD document served over an API or loaded via other means. -* The _RO-Crate Metadata Document_ MUST contain _RO-Crate JSON-LD_; a valid [JSON-LD 1.0] document in [flattened] and [compacted] form -* The _RO-Crate JSON-LD_ SHOULD use the _RO-Crate JSON-LD Context_ by reference. - - -[JSON-LD](https://json-ld.org/) is a structured form of [JSON] that can represent a _Linked Data_ graph. - -A valid _RO-Crate JSON-LD_ graph MUST describe: - -1. The [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) -2. The [Root Data Entity](root-data-entity#direct-properties-of-the-root-data-entity) -3. Zero or more [Data Entities](data-entities) -4. Zero or more [Contextual Entities](contextual-entities) - -It is RECOMMENDED that any referenced _contextual entities_ are also described in the _RO-Crate Metadata Document_ with the same identifier. Similarly it is RECOMMENDED that any _contextual entity_ in the _RO-Crate Metadata Document_ is linked to from at least one of the other entities using the same identifier. +The base RO-Crate specification makes no assumptions about the presence of any specific files or folders beyond the reserved RO-Crate files described above. -The appendix [RO-Crate JSON-LD](appendix/jsonld) details the general structure of the JSON-LD that is expected in the _RO-Crate Metadata Document_. In short, the rest of this specification describe the different types of entities that can be added as `{}` objects to the _RO-Crate JSON-LD_ `@graph` array below: +Payload files may appear directly in the _RO-Crate Root_ alongside the _RO-Crate Metadata File_, and/or appear in sub-directories of the _RO-Crate Root_. Each file and directory MAY be represented as [Data Entities](data-entities) in the _RO-Crate Metadata File_. -```json -{ "@context": "https://w3id.org/ro/crate/1.2-DRAFT/context", - "@graph": [ +An 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. - ] -} -``` +{% include callout.html type="tip" content="An 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_.". RO-Crate has a similar mechanism for referencing such external files using both an `@id` to reference a local path and [contentUrl] property to indicate a source for that data. See the section on [File Data Entities](data-entities#file-data-entity) %} -## RO-Crate Website (`ro-crate-preview.html` and `ro-crate-preview_files/`) +### RO-Crate Website (`ro-crate-preview.html` and `ro-crate-preview_files/`) for Packages -In addition to the machine-oriented _RO-Crate Metadata Document_, the RO-Crate MAY include a human-readable HTML rendering of the same information, known as the _RO-Crate Website_. If present, the _RO-Crate Website_ MUST be a file named `ro-crate-preview.html` in the root directory, which MAY serve as the entry point to other web-resources, which MUST be in `ro-crate-preview_files/` in the root directory. +In addition to the machine-oriented _RO-Crate Metadata Document_ _Attached RO-Crate Packages_ MAY include a human-readable HTML rendering of the same information, known as the _RO-Crate Website_. If present, the _RO-Crate Website_ MUST be a file named `ro-crate-preview.html` in the root directory, which MAY serve as the entry point to other web-resources, which MUST be in `ro-crate-preview_files/` in the root directory. -If present in the root directory of a _Attached RO-Crate_ as `ro-crate-preview.html`, (or otherwise served in a _Detached RO-Crate_), the RO-Crate Website MUST: +If present in the root directory of an _Attached RO-Crate Package_ as `ro-crate-preview.html`, (or otherwise served in a _Detached RO-Crate Package_), the RO-Crate Website MUST: * Be a valid [HTML 5] document * Be useful to users of the RO-Crate - this will vary by community and intended use, but in general the aim to assist users in reusing data by explaining what it is, how it was created how it can be used and how to cite it. One simple approach to this is to expose *all* the metadata in the _RO-Crate Metadata Document_. -* Contain a copy of the _RO-Crate JSON-LD_ in a `script` element of the `head` element of the HTML, for example: - ```html - - ``` `ro-crate-preview.html` SHOULD: -* Display at least the metadata relating to the _Root Data Enity_ as static HTML without the need for scripting. It MAY contain extra features enabled by JavaScript. +* Display at least the metadata relating to the _Root Data Entity_ as static HTML without the need for scripting. It MAY contain extra features enabled by JavaScript. * When a _Data Entity_ or _Contextual Entity_ is referenced by its ID: - If it has a [name] property, provide a link to its HTML version. - If it does not have a name (e.g. a [GeoCoordinates] location), show it embedded in the HTML for the entity. @@ -148,7 +146,11 @@ If present in the root directory of a _Attached RO-Crate_ as `ro-crate-preview.h * For keys that resolve in the `RO-Crate JSON-LD Context` to a URI, indicate this (the simplest way is to link the key to its definition). * If there are additional resources necessary to render the preview (e.g. CSS, JSON, HTML), link to them in a subdirectory `ro-crate-preview_files/` -The _RO-Crate Website_ is not considered a part of the RO-Crate, but serves as a way to make metadata available in a user-appropriate format. The `ro-crate-preview.html` file and the `ro-crate-preview_files/` directory and any contents SHOULD NOT be included in the `hasPart` property of the _Root Data Entity_ or any other `Dataset` entity within an RO-Crate. +{.note} +> Previous versions of the Specification recommended that the _RO-Crate Website_ should contain a redundant copy of the RO-Crate Metadata Document but there is no evidence that this has been useful and is no longer recommended. + + +The _RO-Crate Website_ is not considered a part of the RO-Crate payload in an _Attached RO-Crate Package_, but serves as a way to make metadata available in a user-appropriate format. The `ro-crate-preview.html` file and the `ro-crate-preview-files/` directory and any contents SHOULD NOT be included in the `hasPart` property of the _Root Dataset_ or any other `Dataset` entity within an RO-Crate. Metadata about parts of the _RO-Crate Website_ MAY be included in an RO-Crate as in the following example. Metadata such as an `author` property, `dateCreated` or other provenance can be included, including details about the software that created them, as described in [Software used to create files](./provenance.html#software-used-to-create-files)). @@ -184,35 +186,38 @@ Metadata about parts of the _RO-Crate Website_ MAY be included in an RO-Crate as } ``` -{% 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." %} +### Self-describing and self-contained +_Attached RO-Crates Packages_ SHOULD be self-describing and self-contained. +A minimal _Attached RO-Crate Package_ is a directory containing a single _RO-Crate Metadata Document_ stored as an [RO-Crate Metadata File](root-data-entity) `ro-crate-metadata.json`. -## Payload files and directories (_Attached RO-Crates_) +At the basic level, an Attached RO-Crate Package is a collection of files and resources represented as a Schema.org [Dataset], that together form a meaningful unit for the purposes of communication, citation, distribution, preservation, etc. The _RO-Crate Metadata Document_ describes the RO-Crate, and MUST be stored in the _RO-Crate Root_. -These are the actual files and directories that make up the **payload** of the dataset being described in a _Attached RO-Crate_. +While RO-Crate is well catered for describing a _Dataset_ as files and relevant metadata that are _contained_ by the RO-Crate in the sense of living within the same root directory, RO-Crates can also reference external resources which are stored or accessed separately, via absolute URIs. This is particularly recommended where some resources cannot be co-hosted for practical or legal reasons, or if the RO-Crate itself is primarily web-based. -The base RO-Crate specification makes no assumptions about the presence of any specific files or folders beyond the reserved RO-Crate files described above. +It is important to note that the _RO-Crate Metadata Document_ is **not necessarily an exhaustive manifest** or inventory, that is, it is not required to list or describe all files in the package. Rather it is focused on providing sufficient amount of metadata to understand and use the content, and is designed to be compatible with existing and future approaches that _do_ have full inventories / manifest and integrity checks, e.g. by using checksums, such as [BagIt] and Oxford Common File Layout [OCFL Objects][OCFL Object]. -Payload files may appear directly in the _RO-Crate Root_ alongside the _RO-Crate Metadata File_, and/or appear in sub-directories of the _RO-Crate Root_. Each file and directory MAY be represented as [Data Entities](data-entities) in the _RO-Crate Metadata File_. +The intention is that RO-Crates can work well with a variety of archive file formats, e.g. tar, zip, etc., and approaches to capturing file manifests and file fixity, such as [BagIt], [OCFL] and [git] (see also appendix [Combining with other packaging schemes](appendix/implementation-notes#combining-with-other-packaging-schemes)). An RO-Crate can also be hosted on the web or mainly refer to web resources, although extra care to ensure persistence and consistency should be taken for archiving such RO-Crates. -An 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. -{% include callout.html type="tip" content="An 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_." %} +## Detached RO-Crate Package -## Self-describing and self-contained (_Attached RO-Crates_) +A _Detached RO-Crate Package_ is an RO-Crate, defined in an _RO-Crate Metadata Document_ without a defined root directory, where the _RO-Crate Metadata Document_ content is accessed independently (e.g. as part of a programmatic API). -RO-Crates SHOULD be self-describing and self-contained. -A minimal Attached RO-Crate is a directory containing a single _RO-Crate Metadata Document_ stored as an [_RO-Crate Metadata File_](root-data-entity) `ro-crate-metadata.json`. +Unlike an _Attached RO-Crate Package_ a _Detached RO-Crate Package_ is not processed in a file-system context and thus does not carry a data _payload_ in the same sense, but may reference data deposited separately, or purely reference [contextual entities](contextual-entities). -At the basic level, an Attached RO-Crate is a collection of files and resources represented as a Schema.org [Dataset], that together form a meaningful unit for the purposes of communication, citation, distribution, preservation, etc. The _RO-Crate Metadata Document_ describes the RO-Crate, and MUST be stored in the _RO-Crate Root_. +In a _Detached RO-Crate Package_ the [root data entity](root-data-entity) SHOULD have an `@id` which is a URL that resolves to the _RO-Crate Metadata Document_. -While RO-Crate is well catered for describing a _Dataset_ as files and relevant metadata that are _contained_ by the RO-Crate in the sense of living within the same root directory, RO-Crates can also reference external resources which are stored or accessed separately, via absolute URIs. This is particularly recommended where some resources cannot be co-hosted for practical or legal reasons, or if the RO-Crate itself is primarily web-based. +Any [data entities](data-entities) in a _Detached RO-Crate Package Package_ are assumed to be [Web-based Data Entities](data-entities.html#web-based-data-entities). -It is important to note that the _RO-Crate Metadata Document_ is **not an exhaustive manifest** or inventory, that is, it does not necessarily list or describe all files in the package. Rather it is focused on providing sufficient amount of metadata to understand and use the content, and is designed to be compatible with existing and future approaches that _do_ have full inventories / manifest and integrity checks, e.g. by using checksums, such as [BagIt] and Oxford Common File Layout [OCFL Objects][OCFL Object]. +A Detached RO-Crate Package may still use `#`-based local identifiers for [contextual entities](contextual-entities). + +The concept of an _RO-Crate Website_ is undefined for a _Detached RO-Crate Package_. + +To distribute a _Detached RO-Crate Package_ and optionally to provide an RO-Crate Website, any _Detached RO-Crate Package_ can be saved in a directory (and zipped or otherwise bundled) and will function as an _Attached RO-Crate Package_ with no payload data. -The intention is that RO-Crates can work well with a variety of archive file formats, e.g. tar, zip, etc., and approaches to capturing file manifests and file fixity, such as [BagIt], [OCFL] and [git] (see also appendix [Combining with other packaging schemes](appendix/implementation-notes#combining-with-other-packaging-schemes)). An RO-Crate can also be hosted on the web or mainly refer to web resources, although extra care to ensure persistence and consistency should be taken for archiving such RO-Crates. {% include references.liquid %} diff --git a/docs/_specification/1.2-DRAFT/terminology.md b/docs/_specification/1.2-DRAFT/terminology.md index 70f27abc..4db1beaf 100644 --- a/docs/_specification/1.2-DRAFT/terminology.md +++ b/docs/_specification/1.2-DRAFT/terminology.md @@ -28,15 +28,19 @@ parent: RO-Crate 1.2-DRAFT _RO-Crate_: A dataset, which is described in a JSON-LD _RO-Crate Metadata Document_. -_RO-Crate Metadata Document_: A JSON-LD document that describes the _RO-Crate_ with structured data in form of _RO-Crate JSON-LD_. This may be stored in a file-system as an _RO-Crate Metadata File_ or served via an API. +_RO-Crate Metadata Document_: A JSON-LD document that describes the _RO-Crate_ with structured data in form of _RO-Crate JSON-LD_. This may be stored in a file-system as an _RO-Crate Metadata File_, served via web site or via an API. -_RO-Crate Metadata File_: An _RO-Crate Metadata Document_ stored in a file named `ro-crate-metadata.json` in the _RO-Crate Root_. See section [RO-Crate Metadata Document](structure#ro-crate-metadata-document-ro-crate-metadatajson). +_RO-Crate Metadata File_: An _RO-Crate Metadata Document_ stored in a file named `ro-crate-metadata.json` in the _RO-Crate Root_ of a _Local RO-Crate Package_. See section [RO-Crate Metadata Document](structure#ro-crate-metadata-document-ro-crate-metadatajson). -_Attached RO-Crate_: An RO-Crate that contains a payload of one or more files, stored/published on a typical file system with an _RO-Crate Metadata File_:. See section [Types of RO-Crate](structure#types-of-ro-crate). +_Attached RO-Crate Package_: A file system directory, indicated by the presence of the _RO-Crate Metadata File_ which functions as a packaged dataset. A _Local RO-Crate Package_ carries a payload of zero or more files. See section [Types of RO-Crate](structure#types-of-ro-crate). -_Detached RO-Crate_: An RO-Crate described by an _RO-Crate Metadata Document_ without a payload of files, not having its own _RO-Crate Root_. See section [Types of RO-Crate](structure#types-of-ro-crate). +_Detached RO-Crate Package_: A stand alone _RO-Crate Metadata Document_ which defines a virtual data package by referencing online materials. A _Detached RO-Crate Package_ does not have a payload See section [Types of RO-Crate](structure#types-of-ro-crate). -_RO-Crate Root_: The top-level directory of a _Attached RO-Crate_, indicated by the presence of the _RO-Crate Metadata File_ `ro-crate-metadata.json`. See section [RO-Crate structure](structure) + +_Detached RO-Crate Metadata File_: An _RO-Crate Metadata Document_ stored in a file named `${prefix}-ro-crate-metadata.json` or `ro-crate-metadata.json` where `$prefix`, if present is a file-system safe version identifier or name for the RO-Crate. + + +_RO-Crate Root_: The top-level directory of an _RO-Crate Package_. See section [RO-Crate structure](structure) _RO-Crate Metadata Descriptor_: A _Contextual Entity_ of type [CreativeWork], which describes the _RO-Crate Metadata Document_ and links it to the _Root Data Entity_. See section [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor)