From 9a1a0d67f7a84897998ba866abc164f2adac273f Mon Sep 17 00:00:00 2001 From: Nicolas CARPi Date: Thu, 9 Jan 2025 21:05:59 +0100 Subject: [PATCH 1/2] doc: packaging: add ELN implementation note in appendix Add a note about the ELN file format and how it contains a valid RO-Crate inside a ZIP archive. --- docs/_includes/references.liquid | 1 + .../1.2-DRAFT/appendix/implementation-notes.md | 16 ++++++++++++---- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/_includes/references.liquid b/docs/_includes/references.liquid index 6051b338..3e97af07 100644 --- a/docs/_includes/references.liquid +++ b/docs/_includes/references.liquid @@ -26,6 +26,7 @@ and is also rendered into the end of the PDF. [DataCite Schema]: https://schema.datacite.org/ [DataCite Schema v4.0]: https://schema.datacite.org/meta/kernel-4.0/metadata.xsd [DCAT]: https://www.w3.org/TR/vocab-dcat/ +[ELN]: https://the.elnconsortium.org/ [Exif]: https://en.wikipedia.org/wiki/Exif [Flattened Document Form]: https://json-ld.org/spec/latest/json-ld/#flattened-document-form [FRAPO]: http://www.sparontologies.net/ontologies/frapo diff --git a/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md b/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md index 630016c7..b3059624 100644 --- a/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md +++ b/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md @@ -46,7 +46,15 @@ When implementing tools to work with RO-Crate it is not necessary to use JSON-LD ## Combining with other packaging schemes -RO-Crates may co-exist with other packaging schemes, such as [BagIt] using two general approaches; either (a) _adding_ RO-Crate into a package as part of the payload or (b) _wrapping_ another kind of package. Examples using BagIt follow. +RO-Crates may co-exist with other packaging schemes, such as [BagIt] or [ELN] using two general approaches; either (a) _adding_ RO-Crate into a package as part of the payload or (b) _wrapping_ another kind of package. + +### ELN examples + +An "ELN" archive (with file extension **.eln**, see [IANA assignment](https://www.iana.org/assignments/media-types/application/vnd.eln+zip) and [specification](https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md)), is a valid RO-Crate packaged in a certain way. It is a ZIP file that contains a folder, and this folder _is_ the RO-Crate and contains the `ro-crate-metadata.json` file. See [Structure of the archive](https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md#structure-of-the-archive) from the specification. + +As such, when processing a **.eln** file, one needs to extract the ZIP archive, look for the only folder present at root directory of the ZIP archive, and process its content as a normal RO-Crate. + +### BagIt examples BagIt is described in [RFC 8493]: @@ -59,7 +67,7 @@ BagIt is described in [RFC 8493]: BagIt and RO-Crate have largely separate concerns - RO-Crate is focussed on rich metadata, the semantics of data, while BagIt is about reliable transfer. -### Adding RO-Crate to Bagit +#### Adding RO-Crate to Bagit RO-Crate can be combined with BagIt simply by placing the RO-Crate files within the BagIt payload (`data/`) directory. @@ -136,14 +144,14 @@ measures, e.g. `gpg --detach-sign --armor --output tagmanifest-sha512.txt.asc tagmanifest-sha512.txt` in combination with a secure PGP key exchange or equivalent trust network. -#### Base URI in BagIt +##### Base URI in BagIt The arcp specification suggests how [BagIt UUID identifiers] can be used to calculate the base URI of a bag, see section [Establishing a base URI inside a ZIP file](relative-uris#establishing-a-base-uri-inside-a-zip-file). For this purpose it is RECOMMENDED that `bag-info.txt` includes a fresh UUID like: External-Identifier: urn:uuid:24e51ca2-5067-4598-935a-dac4e327d05a -#### Referencing external files +##### Referencing external files The [BagIt fetch file](https://www.rfc-editor.org/rfc/rfc8493.html#section-2.2.3) MAY be used to reference files to be downloaded into particular `data/` paths From 14f630047fd55b816946fe7b6c276891f84250f8 Mon Sep 17 00:00:00 2001 From: Nicolas CARPi Date: Fri, 10 Jan 2025 11:39:18 +0100 Subject: [PATCH 2/2] address comments by @elichad --- .../1.2-DRAFT/appendix/implementation-notes.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md b/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md index b3059624..1b7dfc8a 100644 --- a/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md +++ b/docs/_specification/1.2-DRAFT/appendix/implementation-notes.md @@ -46,13 +46,13 @@ When implementing tools to work with RO-Crate it is not necessary to use JSON-LD ## Combining with other packaging schemes -RO-Crates may co-exist with other packaging schemes, such as [BagIt] or [ELN] using two general approaches; either (a) _adding_ RO-Crate into a package as part of the payload or (b) _wrapping_ another kind of package. +RO-Crates may co-exist with other packaging schemes, such as [BagIt] or [ELN] (Electronic Lab Notebook) using two general approaches; either (a) _adding_ RO-Crate into a package as part of the payload or (b) _wrapping_ another kind of package. ### ELN examples -An "ELN" archive (with file extension **.eln**, see [IANA assignment](https://www.iana.org/assignments/media-types/application/vnd.eln+zip) and [specification](https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md)), is a valid RO-Crate packaged in a certain way. It is a ZIP file that contains a folder, and this folder _is_ the RO-Crate and contains the `ro-crate-metadata.json` file. See [Structure of the archive](https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md#structure-of-the-archive) from the specification. +An "ELN" archive (with file extension `.eln`, see [IANA assignment](https://www.iana.org/assignments/media-types/application/vnd.eln+zip) and [specification](https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md)), is a valid RO-Crate packaged in a certain way. It is a ZIP file that contains a folder, and this folder is the _RO-Crate Root_ containing the `ro-crate-metadata.json` file. See [Structure of the archive](https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md#structure-of-the-archive) from the specification. -As such, when processing a **.eln** file, one needs to extract the ZIP archive, look for the only folder present at root directory of the ZIP archive, and process its content as a normal RO-Crate. +As such, when processing a `.eln` file, one needs to extract the ZIP archive, look for the only folder present at root directory of the ZIP archive, and process its content as a normal RO-Crate. ### BagIt examples @@ -190,7 +190,7 @@ reference a downloadable file by relative paths within `data/`, even if this file is not itself described in the RO-Crate metadata. -#### Snapshots of external files +##### Snapshots of external files As an alternative to the above, [web-based data entities](../data-entities#web-based-data-entities) can be used in the RO-Crate: @@ -217,7 +217,7 @@ primarily pointing at a web resource which is allowed to change without causing a BagIt checksum error. -### Example of wrapping a BagIt bag in an RO-Crate +#### Example of wrapping a BagIt bag in an RO-Crate Alternatively, an RO-Crate can _wrap_ a BagIt bag, so that the RO-Crate metadata is outside of the bag directory and can be changed without changing the payload's checksums.