RO-Crate Machine Actionable Schemas and Profile (Proof of concept)

About this repo

This repository is for the development of RO-Crate Schemas and Profiles (RO-Crate-MASP) which implements the requirements set out in The Notes for RO-Crate Schemas and Machine Actionable Profiles.

We have some discussion here on how this solution addresses The Notes.

This work builds on previous prototyping by PT Sefton under the banner "SoSS+". This work is hosted on a branch on the Language Data Commons RO-Crate-Schema-Tools repo. That branch has a variety of bits of code and prototype schemas and profiles that are in various states of repair.

Now that the work is more advanced, I'm moving it to this repository as a "clean" copy where people will be able to try out working code in a more predictable environment on the main branch.

If this work goes forward then this repository will probably turn into the home of a javascript/Node implementation of an RO-Crate based RO-Crate Machine Actionable Profiles and Schemas spec.

Published Profiles and Schemas

These are the published GitHub Pages versions of the current profiles and schemas:

• Schema: Records in Context (Ported from OWL): https://language-research-technology.github.io/ro-crate-masp/schemas/ric/schema-crate/index.html
• Profile: RO-Crate 2 Profile (NEW): https://language-research-technology.github.io/ro-crate-masp/profiles/ro-crate-2/profile-crate/index.html
• Profile: RO-Crate MASP Profile: https://language-research-technology.github.io/ro-crate-masp/profiles/ro-crate-masp/profile-crate/index.html
• Profile: RO-Crate Profile: https://language-research-technology.github.io/ro-crate-masp/profiles/ro-crate/profile-crate/index.html
• Profile: Workflow Profile: https://language-research-technology.github.io/ro-crate-masp/profiles/workflow/profile-crate/index.html
• Profile: LDAC Profile: https://language-research-technology.github.io/ro-crate-masp/profiles/ldac/profile-crate/index.html
• Profile: CCA Demo Profile: https://language-research-technology.github.io/ro-crate-masp/profiles/cca-demo/profile-crate/index.html
• Schema: Schema.org Schema: https://language-research-technology.github.io/ro-crate-masp/schemas/schema-org/schema-crate/index.html
• Schema: LDAC Schema: https://language-research-technology.github.io/ro-crate-masp/schemas/ldac/schema-crate/index.html
• Schema: AusTalk Schema: https://language-research-technology.github.io/ro-crate-masp/schemas/austalk/schema-crate/index.html
• Schema: Template Schema: https://language-research-technology.github.io/ro-crate-masp/schemas/template/schema-crate/index.html

What is here

This repository contains:

• Draft Profiles and Schemas, according to the definitions in The Notes which are packaged as RO-Crates, with schema rules included as Contextual Entities
  • Start Here: There is a draft profile for RO-Crate Machine Actionable Schemas and Profile which acts as an introduction.
  • We have a complete copy of Schema.org's schema - which imports without change into RO-Crate-MASP -- here's the Schema.org documentation
• Code (with unit tests) to demonstrate
  • Generating Profile or Schema documentation from a ROC-MASP crate.
  • Validating candidate RO-Crates against a ROC-MASP crate (initial implementation is as Unit-tests only)
    • TODO: Command line validator
  • TODO: Generating Editor (Crate-O) configuration from ROC-MASP crates we have code but it is out of date

Things to look at

• Port of the Workflow RO-Crate Profile 1.0. Experimental New Version. The markdown document lists its own provenance like so:

  This document was compiled using generate-soss-docs.js, based on profiles/workflow/profile-text.md using a SoSS+ Schema defined in profiles/workflow/profile-crate/ro-crate-metadata.json.

  See the Excel version of the Profile rules.

• Profile for the small number of metadata requirements for RO-Crate itself: Experimental new version.

  This document was compiled using generate-soss-docs.js, based on profiles/ro-crate/profile-text.md using a SoSS+ Schema defined in profiles/ro-crate/profile-crate/ro-crate-metadata.json.

We would love to see alternative implementations of this proof of concept code. Particularly other approaches to validation -- can ROC-MASP schemas and classes be transformed into SHACL?

Architecture of the solution

The core of this proposed ROC-MASP solution is to use RO-Crates to package Profiles (or Schemas -- which can be authored in the same way but which would typically be more permissive).

This ROC-MASP Crate can be used in combination with textual summary of the Profile to create documentation with an automatically generated summary of what should be in conformant crates.

Constraint Modeling Note

Rule constraints that assert literal values are modeled via PropertyValue entities referenced from a property's rangeIncludes.

• Do not put constraint literals directly on rdf:Property rules using a value field.
• Define a PropertyValue entity with a clear name and its value (literal, @id object, or regex literal string).
• Reference that PropertyValue from the relevant property rule through rangeIncludes.

This pattern is now the canonical way to express fixed and pattern-based value constraints in this repository.

Running the tests

npm test                                   # run all tests (~38)
npx mocha test/ldac-validator.test.js      # run a single test file

Tests use real profile crates from profiles/ and sample crates from test_data/, so changes to either will affect test results.

Building documentation

To run this, choose one of the examples from the implementations section below. E.g. to generate the documentation for the RO-Crate Workflow profile example, run:

npm run build:workflow-profile

Or to validate an example workflow crate:

npm run validate:workflow 

To get the full validation report (which is a work in progress):

npm run validate:workflow:json

NOTE: At the moment these scripts are passing in the profile to validate against. TOTO: In future the code will support fetching or matching local copies of profiles by IRI on a conformsTo property.

Similarly, validators can use a ROC-MASP crate as a set of rules:

Building Profile and Schema documentation

This repository includes several profiles and schemas that can be built using npm scripts. Each build command generates documentation from the RO-Crate metadata.

Available Build Commands

• Workflow Profile: npm run build:workflow-profile
• RO-Crate Profile: npm run build:ro-crate-profile
• Language Data Commons (LDAC) Profile: npm run build:ldac-profile
• Language Data Commons (LDAC) Schema: npm run build:ldac-schema
• AusTalk Schema: npm run build:austalk-schema
• Records in Context (RiC-O) Schema: npm run build:ric-schema

Usage note: rocxl synchronisation

• Flag: -x or --rocxl — when running generate-masp-docs for profiles or schemas, you can pass -x to run rocxl first and ensure ro-crate-metadata.json and ro-crate-metadata.xlsx are synchronised. The generator will choose the newer of the two files and update the other; if only the spreadsheet exists, the JSON will be created from it. It will then generate documentation from the JSON file as usual.

Example:

npm exec -- generate-masp-docs -- profiles/ldac/profile-crate/ro-crate-metadata.json profiles/ldac/profile-text.md profiles/ldac/profile-crate/profile-documentation.md -x

Each build command runs the generate-soss-docs.js script with three arguments:

1. Path to the ro-crate-metadata.json file
2. Path to the profile/schema text markdown file
3. Path to the output documentation markdown file

Converting an OWL ontology to a MASP schema

scripts/owl-to-masp.py converts an OWL ontology (RDF/XML, Turtle, or JSON-LD) into a MASP schema crate — see scripts/owl-to-masp.spec.md for the full design spec and mapping rules. It's a Python script run via uv rather than Node, since OWL/RDF parsing is much better supported there (rdflib) than in the JS ecosystem the rest of this repo uses.

This is a one-off, manually-run tool — it's deliberately not wired into package.json (there's no build:*/generate:* script for it), since converting a new ontology is a rare, deliberate action you review by hand afterwards, not something that should re-run on every npm run build.

To convert an ontology, point it at the source file (a path or URL) and an output directory under schemas/:

uv run scripts/owl-to-masp.py \
  --input https://www.ica.org/standards/RiC/RiC-O_1-1.rdf \
  --output-dir schemas/ric \
  --namespace "https://www.ica.org/standards/RiC/ontology#" \
  --name "Records in Context Ontology"

This is exactly the command used to generate schemas/ric (the Records in Context Ontology, RiC-O) from its published OWL source. --namespace restricts conversion to terms defined by the ontology itself, excluding anything it imports from other vocabularies (SKOS, Dublin Core, etc.) — without it, the converter would also try to re-mint schema entities for every imported term. The generated schema-crate/ directory bundles the original OWL file alongside ro-crate-metadata.json, along with a CreateAction recording that this script produced the crate from that file, so the result is self-contained and its provenance is traceable without depending on the source URL remaining live.

After conversion, review the generated schema-text.md stub and fill in a proper description, then build documentation as usual — for RiC-O that's npm run build:ric-schema (see Available Build Commands above), which also runs rocxl (-x) to produce an Excel copy of the rules alongside the JSON.

The converter's own test suite (test/owl-to-masp/test_owl_to_masp.py, run via npm run test:owl-to-masp) runs against a small fixture ontology, not the full RiC-O file — see the spec for why, and for the workflow used to extend it when converting a new ontology surfaces a construct the fixture doesn't yet cover.

Validating RO-Crates from the Command Line

You can validate a target RO-Crate against a profile crate or schema using the command-line tool validate-crate.js.

Usage

node validate-crate.js <target-crate.json> <profile-crate.json>

For example, to validate the minimal workflow crate against the workflow profile:

node validate-crate.js profiles/workflow/examples/minimal-example/ro-crate-metadata.json profiles/workflow/profile-crate/ro-crate-metadata.json

The tool will print validation results to the console and exit with a nonzero code if errors are found.

Help wanted!

We would love to see alternative implementations of this proof of concept code. Particularly other approaches to validation -- can ROC-MASP schemas and classes be transformed into SCHACL?