122 documentation website mkdocs

[douglowe]

Summary

Adds the documentation website for the 2.0 service with MkDocs

Pages

• Home: what the service is and validation modes
• Installation & Setup: quick start and config reference
• Upgrade guide: 1.x to 2.0 mapping, API changes and upgrade list
• API Reference: endpoints, results, webhooks, Crate IDs, health endpoints
• Five Safes RO-Crate: getting the profile and a worked validation example (closes Document how to use the Five Safes RO-Crate profile with the validation service #122)
• Development / Contributions: how to contribute, dev stack, tests, CI, and architecture

The API examples and the Five Safes walkthrough were run/tested against the service whilst writing.

• This will need updating when the https://github.com/eScienceLab/rocrate-validator fork release is updated, but this works fine for now and will still work when the fork is updated.
• PR also adds a GitHub Pages deployment workflow (runs on pushes to main touching the docs, or manually) and sets site_url, so the site publishes to https://esciencelab.org.uk/RO-Crate-Validation-Service/.

To build the docs locally:

uvx --with mkdocs-mermaid2-plugin mkdocs serve

then open http://127.0.0.1:8000. (Or pip install mkdocs mkdocs-mermaid2-plugin and run mkdocs serve.)

[douglowe]

I've created a PR for this as I've questions for some details in the content & don't want to edit it directly without checking on these first.

[alexhambley]

I've created a PR for this as I've questions for some details in the content & don't want to edit it directly without checking on these first.

Yes, please don't edit, I am still actively working on them

[Copilot]

Pull request overview

Adds an MkDocs-based documentation site for the RO-Crate Validation Service and a GitHub Actions workflow to publish it to GitHub Pages, aligning the docs with the service’s v2 storage-backed validation model and Five Safes profile usage.

Changes:

• Introduces an MkDocs site configuration (mkdocs.yml) with navigation and Mermaid support.
• Adds new documentation pages covering installation/setup, upgrading from 1.x, API reference, Five Safes walkthrough, and contribution/development guidance.
• Adds a GitHub Pages deployment workflow that builds the docs on changes to docs/** or mkdocs.yml on main.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
mkdocs.yml	Configures MkDocs site name, URL, navigation, theme, and plugins/extensions.
docs/index.md	Adds overview of the service and its validation modes with an architecture diagram.
docs/installation.md	Documents quick start, storage enablement, configuration reference, profiles, and offline mode.
docs/upgrading.md	Provides a 1.x → current mapping for settings and API/storage behavior changes.
docs/api.md	Documents endpoints, status codes, payloads, result format, webhooks, crate IDs, and health checks.
docs/five-safes.md	Adds Five Safes profile guidance and a worked validation walkthrough.
docs/contribution.md	Adds contribution and development workflow docs (stack, tests, linting, CI, architecture).
.github/workflows/deploy_docs.yml	Builds MkDocs site and deploys it to GitHub Pages on main updates to docs/config.

Comments suppressed due to low confidence (1)

.github/workflows/deploy_docs.yml:55

• This workflow uses actions/deploy-pages@v4 by tag rather than pinning to a commit SHA. For consistency with the repo’s other workflows (which pin actions) and to reduce supply-chain risk, pin this action to a specific commit SHA.

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[douglowe]

I've added a couple of suggested changes below... (sorry)

[douglowe]

Suggested change

The RO-Crate Validation Service evaluates whether [RO-Crates](https://www.researchobject.org/ro-crate/) conform to the RO-Crate specification and to community profiles. The service wraps the [`rocrate-validator`](https://rocrate-validator.readthedocs.io/) library in a REST API, and is deployed as a Docker image. The RO-Crate Validation Service enables pipelines, other services, and Trusted Research Environments (TREs) to validate an RO-Crate over HTTP without running the validator themselves.

The RO-Crate Validation Service provides a REST API for evaluating whether an [RO-Crate](https://www.researchobject.org/ro-crate/) conforms to a given RO-Crate profile. The service wraps the [`rocrate-validator`](https://rocrate-validator.readthedocs.io/) library, enabling pipelines, other services, and Trusted Research Environments (TREs) to validate an RO-Crate over HTTP without having to install the validator themselves.

[douglowe]

Suggested change

An [RO-Crate](https://www.researchobject.org/ro-crate/) packages research data together with structured, machine-readable metadata: a JSON-LD file named `ro-crate-metadata.json`. Validating an RO-Crate evaluates that metadata against a **profile**. A profile is a set of requirements the RO-Crate must satisfy. That can be the base requirements of the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.2/) itself, or a [community profile](https://www.researchobject.org/ro-crate/profiles) that adds domain-specific rules, such as the [Five Safes RO-Crate profile](https://trefx.uk/5s-crate/) for working with sensitive data in TREs.

An [RO-Crate](https://www.researchobject.org/ro-crate/) packages research data together with structured, machine-readable metadata: a JSON-LD file named `ro-crate-metadata.json`. Validating an RO-Crate involves evaluating that metadata against a given **profile**. A profile is a set of requirements the RO-Crate must satisfy, either the base requirements of the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.2/) itself, or a [community profile](https://www.researchobject.org/ro-crate/profiles) that adds domain-specific rules to the base specification. An example of a community profile is the [Five Safes RO-Crate profile](https://trefx.uk/5s-crate/), designed for researchers working with sensitive data in Trusted Research Environments (TREs).

[douglowe]

Suggested change

Whilst the validation checks themselves are performed by [`rocrate-validator`](https://rocrate-validator.readthedocs.io/), this service is a deployable HTTP wrapper around that tool: it adds a web API, asynchronous processing, and object-storage integration. The base validation rules come from the validator itself; we additionally package our own [Five Safes RO-Crate profile](five-safes.md) rules with the service for working in TREs.

Whilst the validation checks themselves are performed by the [`rocrate-validator`](https://rocrate-validator.readthedocs.io/), this service is a deployable HTTP wrapper around that tool: it adds a web API, asynchronous processing, and object-storage integration. The base RO-Crate specification, as well as several [community profiles](https://rocrate-validator.readthedocs.io/en/latest/#features), are provided with the validator itself. We additionally package our own [Five Safes RO-Crate profile](five-safes.md) rules with the service for working in TREs.

[douglowe]

Suggested change

	To validate the contents of an `ro-crate-metadata.json` file, post to the metadata endpoint. The [running example](https://www.researchobject.org/ro-crate/specification/1.2/introduction.html#running-example) from the RO-Crate specification is a good test document.
	To validate the contents of an `ro-crate-metadata.json` file, post to the metadata endpoint. The [running example](https://www.researchobject.org/ro-crate/specification/1.2/introduction.html#running-example) from the RO-Crate specification is a good test document. Create an `ro-crate-metadata.json` file and copy the text from the link above into this, for use in the example below.

[douglowe]

Suggested change

	The file needs to be sent as an escaped JSON string, which `jq` can do:
	The file contents need to be sent to the API as an escaped JSON string, identified using the `crate_json` tag, within a JSON object. The command-line JSON processor, [`jq`](https://jqlang.org/) can be used to do this, as shown below.

[douglowe]

Suggested change

	Install the development dependencies, then run the unit tests, which need no Docker:
	Install the development dependencies, then run the unit tests, which do not use Docker Engine:

[douglowe]

Suggested change

	The integration tests bring up the full Compose stack (including the object store) and seed crates with `boto3`, so they need Docker running:
	The integration tests bring up the full Compose stack (including the object store) and seed crates with `boto3`, for which they need Docker Engine to be running:

[douglowe]

Suggested change

	Direct dependencies are declared in `pyproject.toml`; the `requirements*.txt` files are locks generated with pip-compile:
	Direct dependencies are declared in `pyproject.toml`; while the `requirements*.txt` files are locks generated using `pip-compile`:

[douglowe]

Suggested change

	Pull requests to `develop` run three workflows: unit tests, integration tests (which start the Compose stack), and lint (`ruff check` and `ruff format --check`).
	Pull requests to `develop` will trigger three workflows: unit tests, integration tests (which start the Compose stack), and lint (`ruff check` and `ruff format --check`).

[douglowe]

Suggested change

	The API process handles HTTP and runs metadata-only validation inline. Object storage-backed validation is queued through Redis to a Celery worker, which reads the crate from the S3-compatible store, validates it, and writes the result back:
	The API server handles HTTP and runs metadata-only validation inline. Object storage-backed validation is queued through Redis to a Celery worker, which reads the crate from the S3-compatible store, validates it, and writes the result back: