RO-Crate Python Library

0.15.0 · active · verified Thu Apr 16

The ro-crate-py library provides tools for generating, parsing, and manipulating RO-Crate (Research Object Crate) metadata. RO-Crate is a community effort to package research data with their metadata, using schema.org types serialized as JSON-LD, and is designed to be human- and machine-readable. The library is actively maintained with frequent releases, currently at version 0.15.0.

Common errors

```
AttributeError: can't set attribute 'id'
```
cause Attempting to modify the `id` attribute of an `Entity` instance after `rocrate==0.10.0`.

fix The `id` attribute is read-only. Create a new `Entity` instance with the desired ID and update any references to it.
```
ModuleNotFoundError: No module named 'rocrate.model'
```
cause Incorrect import path for core RO-Crate classes like `Entity`, `File`, `Dataset`, or `Person`.

fix Ensure you are importing these classes directly from `rocrate.model`, e.g., `from rocrate.model import File`.
```
ValidationError: 1 validation error for ROCrate
```
cause Incompatible constructor options or schema validation failures due to stricter validation introduced in versions like `0.14.0`, often related to `pydantic`.

fix Review the traceback for specific field errors. Consult the latest documentation for `ROCrate` and entity constructors to ensure all arguments and properties conform to the expected schema and types for your `rocrate` version.
```
TypeError: ROCrate.__init__() got an unexpected keyword argument 'source'
```
cause Using outdated constructor arguments for `ROCrate`, or attempting to pass arguments not supported by the current version.

fix Check the `ROCrate` constructor signature in the documentation for your `rocrate` version. For example, to read an existing RO-Crate, use `ROCrate('/path/to/crate')` or `ROCrate(source=zip_file_object)` (if applicable) instead of `source` as a keyword argument.

Warnings

breaking The `id` attribute of `Entity` objects became read-only in version `0.10.0`. Attempts to modify `entity.id` directly after creation will raise an `AttributeError`.
Fix: Entity IDs must be set during instantiation. If you need a different ID, create a new `Entity` instance with the desired ID and update references accordingly.
gotcha From version `0.12.0`, contextual entity IDs are no longer automatically prepended with a hash (`#`) by default. If your code relied on this implicit hashing, the generated IDs will differ.
Fix: Review how contextual entity IDs are generated and referenced in your application. Ensure that IDs are consistent with the new explicit handling, or update your code to prepend the hash manually if required for specific uses.
deprecated Python 3.8 support was dropped in version `0.12.0`. Projects requiring `rocrate` `0.12.0` or newer must use Python 3.9 or higher.
Fix: Upgrade your Python environment to 3.9 or newer. If upgrading Python is not an option, you must pin `rocrate` to a version older than `0.12.0` (e.g., `rocrate<0.12.0`).
gotcha Version `0.15.0` introduced updates for reading data entities, especially for RO-Crate 1.2 specifications. While generally backward compatible, complex or non-standard RO-Crate 1.2 structures might require explicit handling or thorough testing.
Fix: When consuming RO-Crates, especially those conforming to RO-Crate 1.2, ensure your parsing logic is robust. Test with your specific RO-Crate structures to confirm compatibility, and refer to the `RO-Crate version selector` if encountering issues.

Install

pip install rocrate Install latest version

Imports

ROCrate
```
from rocrate.rocrate import ROCrate
```
Entity
```
from rocrate.model import Entity
```
File
```
from rocrate.model import File
```
Dataset
```
from rocrate.model import Dataset
```
Person
```
from rocrate.model import Person
```

Quickstart

This quickstart demonstrates how to create a basic RO-Crate, add a file (with content), add a contextual entity (a Person), link the file to the person, and then write the complete RO-Crate to a local directory.

from rocrate.rocrate import ROCrate
from rocrate.model import Person
import os

# Create a new RO-Crate
crate = ROCrate()

# Add a main entity (e.g., a README file)
readme_content = "# My Research Crate\nThis is a sample RO-Crate."
with open("README.md", "w") as f:
    f.write(readme_content)
readme_entity = crate.add_file("README.md")

# Add a person as a contextual entity
person = Person(crate, identifier="#john_doe", properties={
    "name": "John Doe",
    "affiliation": "University of Example"
})
crate.add(person)

# Link the README to the person
readme_entity['author'] = person

# Write the RO-Crate to a directory
output_dir = "my_first_crate"
crate.write(output_dir)

print(f"RO-Crate created at: {os.path.abspath(output_dir)}")
print(f"Contents: {os.listdir(output_dir)}")

view raw JSON →