ro-crate-interoperability-profile/0.2.x/lib/python/lib-ro-crate-schema/QUICKSTART.md

Quick Start Guide

Get started with lib-ro-crate-schema in 5 minutes!

Installation

pip install lib-ro-crate-schema

Your First RO-Crate

Create a file called my_first_crate.py:

from lib_ro_crate_schema import SchemaFacade, ro_crate_schema, Field
from pydantic import BaseModel

# 1. Define your data model with decorators
@ro_crate_schema(ontology="https://schema.org/Person")
class Person(BaseModel):
    name: str = Field(ontology="https://schema.org/name")
    email: str = Field(ontology="https://schema.org/email")

# 2. Create some data
alice = Person(name="Alice Smith", email="alice@example.com")

# 3. Create and export an RO-Crate
facade = SchemaFacade()
facade.add_all_registered_models()  # Register your models
facade.add_model_instance(alice, "person_001")  # Add data
facade.write("my_first_crate")  # Export!

print("✅ RO-Crate created in ./my_first_crate/")

Run it:

python my_first_crate.py

This creates a folder my_first_crate/ containing:

• ro-crate-metadata.json - Your data and schema in JSON-LD format
• Proper RDF/OWL type definitions
• Schema.org vocabulary mappings

Next Steps

Add Files to Your Crate

# Add a data file before writing
facade.add_file("data.csv", 
                name="Experimental Data",
                description="Raw measurements")
facade.write("my_crate")

Define Related Objects

@ro_crate_schema(ontology="https://schema.org/Organization")
class Organization(BaseModel):
    name: str = Field(ontology="https://schema.org/name")

@ro_crate_schema(ontology="https://schema.org/Person")
class Person(BaseModel):
    name: str = Field(ontology="https://schema.org/name")
    affiliation: Organization = Field(ontology="https://schema.org/affiliation")

# Create related objects
mit = Organization(name="MIT")
alice = Person(name="Alice", affiliation=mit)

# Export both
facade = SchemaFacade()
facade.add_all_registered_models()
facade.add_model_instance(mit, "org_001")
facade.add_model_instance(alice, "person_001")
facade.write("my_crate")

Import and Modify Existing Crates

from lib_ro_crate_schema import SchemaFacade

# Load existing crate
facade = SchemaFacade.from_ro_crate("existing_crate")

# Modify it
# (add more instances, files, etc.)

# Export modified version
facade.write("modified_crate")

What Just Happened?

When you use @ro_crate_schema:

1. Your Pydantic model is registered as an RO-Crate type
2. Field annotations map to ontology properties (like Schema.org)
3. The library generates proper RDF/OWL definitions
4. Your data is packaged following the RO-Crate specification

More Examples

Check out the examples/ directory:

• decorator_example.py - More complex schemas
• full_example.py - Scientific workflow with files
• minimal_import_example.py - Working with existing crates

Common Patterns

Optional Fields

from typing import Optional

@ro_crate_schema(ontology="https://schema.org/Person")
class Person(BaseModel):
    name: str = Field(ontology="https://schema.org/name")
    email: Optional[str] = Field(default=None, ontology="https://schema.org/email")

Lists

from typing import List

@ro_crate_schema(ontology="https://schema.org/Dataset")
class Dataset(BaseModel):
    name: str = Field(ontology="https://schema.org/name")
    authors: List[Person] = Field(ontology="https://schema.org/author")

Dates and Times

from datetime import datetime

@ro_crate_schema(ontology="https://schema.org/Event")
class Event(BaseModel):
    name: str = Field(ontology="https://schema.org/name")
    date: datetime = Field(ontology="https://schema.org/startDate")

Need Help?

• Full Documentation: See README.md
• API Reference: Browse the src/lib_ro_crate_schema/ directory
• Examples: Check examples/ for real-world usage
• Issues: Report bugs at GitHub Issues

Understanding RO-Crate

RO-Crate (Research Object Crate) is a standard for packaging research data with metadata. It uses:

• JSON-LD: Linked data format
• Schema.org: Standard vocabulary for describing things
• RDF/OWL: Semantic web technologies

This library makes it easy to create RO-Crates from Python without needing to understand all these technologies!

---

Ready for more? Check out the full README.md for advanced usage and API details.