API-01 ELN conventions

• Roughly the ELN File format (in terms of structure of the archive i.e. a zipped RO-Crate with .eln extension)
• Except, more informative types than Dataset (e.g. Book, Message, etc), instead of using the genre property to distinguish between ELN concepts.
• Possibility to have multiple @types e.g. [Book, Dataset], for best-effort compatibility with the ELN file format

Structure of a logbook

A logbook is a collection of messages. A message may have several comments. Both messages and comments may have attached files. We found the following schema.org types appropriate for these entities:

We note that all the above types inherit from CreativeWork.

How are the entities related?

• A Logbook (Book) has Messages through the hasPart property.
• A Message has Comments through the comment property.
• Messages and Comments have files (i.e. MediaObjects) through the hasPart property. (MediaObject is aliased to File in the ro-crate context)

Visually:

---
title: Logbook entity-relations
---
erDiagram
    Book ||--o{ Message : hasPart
    Message ||--o{ Comment : comment
    Message ||--o{ MediaObject : hasPart
    Comment ||--o{ MediaObject : hasPart
    Message ||--o| Person : author
    Comment ||--o| Person : author
    Book ||--o| Person : author

Properties of the entities

The Logbook is our container type. It has a title, author / creator, description, and create/update timestamps. We map these to following schema.org properties:

A message and comment have the same properties:

An author is a schema.org Person.

Finally, a File may have the usual metadata properties as described in the ELN file format.

How are attached files included?

Again, we follow the ELN file format - A Message or a Comment will have an @id of a local directory name. As directory nodes in RO-Crate are required to be Dataset, we will also have Dataset as an additional type in the @type array. All the files attached to the message/comment will be placed in the directory, and have local identifiers as well.

Example

export - 2025-11-25 10_24_50 GMT+1.eln contains an example logbook exported as ELN according to the spec above. We also include an HTML preview generated by ro-crate-html inside the ELN. The ro-crate-metadata.json file inside the example ELN is also pasted here:

Show/hide ro-crate-metadata.json

```json { "@context": [ "https://w3id.org/ro/crate/1.2/context", { "@vocab": "http://schema.org/" } ], "@graph": [ { "@id": "./", "@type": "Dataset", "name": "test", "description": "test logbook on dev-dacat-next", "hasPart": [ { "@id": "./68b7047b45f9f4795ee4ea60/" } ] }, { "@id": "ro-crate-metadata.json", "@type": "CreativeWork", "identifier": "ro-crate-metadata.json", "about": { "@id": "./" }, "conformsTo": { "@id": "https://w3id.org/ro/crate/1.2" } }, { "@id": "person://oidc-user@facility.com", "@type": "Person" }, { "@id": "./68b7047b45f9f4795ee4ea60/", "@type": [ "Book", "Dataset" ], "genre": "experiment", "name": "SciLog ELN export: test", "description": "test logbook on dev-dacat-next", "dateCreated": "2025-09-02T14:51:39.916Z", "author": { "@id": "person://oidc-user@facility.com" }, "hasPart": [ { "@id": "./68b7049445f9f4795ee4ea61/" }, { "@id": "./68c40473875fe08fd1a17d9d/" }, { "@id": "./68c803d981799be215e2e88e/" }, { "@id": "./68c8048281799be215e2e892/" }, { "@id": "./68ff7cc20bc2737a2e603c29/" }, { "@id": "./6915a689c4faee53f6b1437b/" } ] }, { "@id": "./68b7049445f9f4795ee4ea61/", "@type": [ "Message", "Dataset" ], "name": "Paragraph 68b7049445f9f4795ee4ea61", "text": "

Oi

", "dateCreated": "2025-09-02T14:52:04.126Z", "keywords": "newmesg", "encodingFormat": "text/html", "author": { "@id": "person://oidc-user@facility.com" } }, { "@id": "./68c40473875fe08fd1a17d9d/", "@type": [ "Message", "Dataset" ], "name": "Paragraph 68c40473875fe08fd1a17d9d", "text": "

Let's add some rich text here with bunch of formatting.
Let's add a table even:
 

abc	efg	hij
123	456	789
321	654	987

And now an image:

", "dateCreated": "2025-09-12T11:30:59.631Z", "keywords": "newmesg,acomment,secondcomment", "encodingFormat": "text/html", "author": { "@id": "person://oidc-user@facility.com" }, "hasPart": [ { "@id": "./68c40473875fe08fd1a17d9d/68c409c1bc32d2e650a9978c.png" } ], "comment": [ { "@id": "./68c803c181799be215e2e88d/" }, { "@id": "./68c8046981799be215e2e891/" } ] }, { "@id": "./68c40473875fe08fd1a17d9d/68c409c1bc32d2e650a9978c.png", "@type": "File", "encodingFormat": "image/png" }, { "@id": "./68c803c181799be215e2e88d/", "@type": [ "Comment", "Dataset" ], "name": "Comment 68c803c181799be215e2e88d", "text": "

Nice graphic, dude!

", "dateCreated": "2025-09-15T12:17:05.358Z", "keywords": "acomment", "encodingFormat": "text/html", "parentItem": { "@id": "./68c40473875fe08fd1a17d9d/" }, "author": { "@id": "person://oidc-user@facility.com" } }, { "@id": "./68c8046981799be215e2e891/", "@type": [ "Comment", "Dataset" ], "name": "Comment 68c8046981799be215e2e891", "text": "

a further comment

", "dateCreated": "2025-09-15T12:19:53.956Z", "keywords": "acomment,secondcomment", "encodingFormat": "text/html", "parentItem": { "@id": "./68c40473875fe08fd1a17d9d/" }, "author": { "@id": "person://oidc-user@facility.com" } }, { "@id": "./68c803d981799be215e2e88e/", "@type": [ "Message", "Dataset" ], "name": "Paragraph 68c803d981799be215e2e88e", "text": "

Oii mate

", "dateCreated": "2025-09-15T12:17:29.944Z", "keywords": "areply", "encodingFormat": "text/html", "author": { "@id": "person://oidc-user@facility.com" } }, { "@id": "./68c8048281799be215e2e892/", "@type": [ "Message", "Dataset" ], "name": "Paragraph 68c8048281799be215e2e892", "text": "

wassup

", "dateCreated": "2025-09-15T12:20:18.297Z", "keywords": "", "encodingFormat": "text/html", "author": { "@id": "person://oidc-user@facility.com" } }, { "@id": "person://account1@account1", "@type": "Person" }, { "@id": "./68ff7cc20bc2737a2e603c29/", "@type": [ "Message", "Dataset" ], "name": "Paragraph 68ff7cc20bc2737a2e603c29", "text": "

message

", "dateCreated": "2025-10-27T14:08:02.554Z", "keywords": "tags1,tag3", "encodingFormat": "text/html", "author": { "@id": "person://account1@account1" } }, { "@id": "./6915a689c4faee53f6b1437b/", "@type": [ "Message", "Dataset" ], "name": "Paragraph 6915a689c4faee53f6b1437b", "text": "

02 Introduction.pdfa pdf attachment and an image too:

", "dateCreated": "2025-11-13T09:36:09.034Z", "keywords": "", "encodingFormat": "text/html", "author": { "@id": "person://account1@account1" }, "hasPart": [ { "@id": "./6915a689c4faee53f6b1437b/6915a688945a3953740eb96f.png" }, { "@id": "./6915a689c4faee53f6b1437b/6915a688945a3953740eb971.pdf" } ] }, { "@id": "./6915a689c4faee53f6b1437b/6915a688945a3953740eb96f.png", "@type": "File", "encodingFormat": "image/png" }, { "@id": "./6915a689c4faee53f6b1437b/6915a688945a3953740eb971.pdf", "@type": "File", "encodingFormat": "application/pdf" } ] } ```