Merge pull request #113 from crs4/develop

Merge updates from upstream

Author: elichad

.github/workflows/release.yaml

@@ -92,7 +92,7 @@ jobs:
             - name: 🏗️ Build a binary wheel and a source tarball
               run: poetry build
             - name: 📦 Store the distribution packages
-              uses: actions/upload-artifact@v4
+              uses: actions/upload-artifact@v7
               with:
                   name: python-package-distributions
                   path: |
@@ -111,7 +111,7 @@ jobs:
             id-token: write # IMPORTANT: mandatory for trusted publishing
         steps:
             - name: ⬇️ Download all the distribution packages
-              uses: actions/download-artifact@v4
+              uses: actions/download-artifact@v8
               with:
                   name: python-package-distributions
                   path: dist/
@@ -132,7 +132,7 @@ jobs:
           id-token: write  # IMPORTANT: mandatory for trusted publishing
         steps:
         - name: ⬇️ Download all the dists
-          uses: actions/download-artifact@v4
+          uses: actions/download-artifact@v8
           with:
             name: python-package-distributions
             path: dist/
@@ -151,18 +151,18 @@ jobs:
 
         steps:
             - name: ⬇️ Download all the distribution packages
-              uses: actions/download-artifact@v4
+              uses: actions/download-artifact@v8
               with:
                   name: python-package-distributions
                   path: dist/
             - name: 🖊️ Sign the dists with Sigstore
-              uses: sigstore/gh-action-sigstore-python@v3.0.0
+              uses: sigstore/gh-action-sigstore-python@v3.3.0
               with:
                   inputs: >-
                       ./dist/*.tar.gz
                       ./dist/*.whl
             - name: 📦 Store the signed distribution packages
-              uses: actions/upload-artifact@v4
+              uses: actions/upload-artifact@v7
               with:
                   name: python-package-signatures
                   path: dist/*.json
@@ -177,12 +177,12 @@ jobs:
             id-token: write # IMPORTANT: mandatory for sigstore
         steps:
             - name: ⬇️ Download all the distribution packages
-              uses: actions/download-artifact@v4
+              uses: actions/download-artifact@v8
               with:
                   name: python-package-distributions
                   path: dist/
             - name: ⬇️ Download all the distribution signatures
-              uses: actions/download-artifact@v4
+              uses: actions/download-artifact@v8
               with:
                   name: python-package-signatures
                   path: dist/

.github/workflows/testing.yaml

@@ -56,7 +56,7 @@ jobs:
             - name: ⌛ Lint Python code
               run: flake8 -v rocrate_validator tests
             - name: ⌛ Spell check code and profiles (covers Python and SHACL)
-              uses: crate-ci/typos@v1.41.0
+              uses: crate-ci/typos@v1.47.0
 
     # Runs the tests
     test:

CHANGELOG.md

@@ -5,6 +5,85 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-06-01
+
+Full changelog: https://github.com/crs4/rocrate-validator/compare/0.9.0...0.10.0
+
+### ✨ Added
+
+- feat(cli): add offline mode with an `--offline` flag and an HTTP `cache` subcommand to validate RO-Crates without network access ([e296f10](https://github.com/crs4/rocrate-validator/commit/e296f10), [f8b99bc](https://github.com/crs4/rocrate-validator/commit/f8b99bc))
+- feat(utils): add a cache-aware JSON-LD document loader and HTTP cache warm-up from profile artifacts ([eedabf1](https://github.com/crs4/rocrate-validator/commit/eedabf1), [949ec6f](https://github.com/crs4/rocrate-validator/commit/949ec6f))
+- feat(utils): add offline mode and cache management to `HttpRequester`, with configurable cache path ([c92d88c](https://github.com/crs4/rocrate-validator/commit/c92d88c), [7c9e825](https://github.com/crs4/rocrate-validator/commit/7c9e825))
+- feat(core): support offline mode when downloading remote RO-Crates ([57eceb5](https://github.com/crs4/rocrate-validator/commit/57eceb5))
+- feat(cli/cache): add `cache list` (alias `ls`) and allow caching of explicit URLs via `cache warm` ([f9b43ae](https://github.com/crs4/rocrate-validator/commit/f9b43ae), [6925d55](https://github.com/crs4/rocrate-validator/commit/6925d55))
+- feat(cli): extend the `describe` command to describe individual requirement checks ([f3fb7f3](https://github.com/crs4/rocrate-validator/commit/f3fb7f3))
+- feat(model): add a `SourceSnippet` class and `RequirementCheck.get_source_snippet`, implemented for both SHACL and Python checks ([9f48674](https://github.com/crs4/rocrate-validator/commit/9f48674), [25bc7b4](https://github.com/crs4/rocrate-validator/commit/25bc7b4), [fe740e4](https://github.com/crs4/rocrate-validator/commit/fe740e4))
+- feat(checks): support a `deactivated` flag on `RequirementCheck` to override/deactivate checks by name for Python and SHACL ([dd84c32](https://github.com/crs4/rocrate-validator/commit/dd84c32), [4196f0e](https://github.com/crs4/rocrate-validator/commit/4196f0e))
+- feat(rocrate): add `check_availability()` with `AvailabilityStatus` on entities and granular remote-scheme classification ([76e92a4](https://github.com/crs4/rocrate-validator/commit/76e92a4), [469bbe5](https://github.com/crs4/rocrate-validator/commit/469bbe5))
+- feat(checks): handle `UNAUTHORIZED`/`UNCHECKABLE` web data entities as warnings ([0196dc9](https://github.com/crs4/rocrate-validator/commit/0196dc9))
+- feat(uri): add an `is_external_reference()` scheme detector ([62f89c0](https://github.com/crs4/rocrate-validator/commit/62f89c0))
+- feat(model): extend the `Profile` model to compute descendants ([a9783ce](https://github.com/crs4/rocrate-validator/commit/a9783ce))
+- ISA profile: add RDF classes for ISA types and a dedicated `Process` class for process checks ([3ff4245](https://github.com/crs4/rocrate-validator/commit/3ff4245), [e3fda59](https://github.com/crs4/rocrate-validator/commit/e3fda59), [c3e2d5f](https://github.com/crs4/rocrate-validator/commit/c3e2d5f))
+
+### 🔧 Changed
+
+- refactor(models): introduce pre/post internal validation hooks on `Validator` ([e43364b](https://github.com/crs4/rocrate-validator/commit/e43364b))
+- refactor(SHACL): rewrite `build_node_subgraph` as an iterative BNode traversal ([23164b7](https://github.com/crs4/rocrate-validator/commit/23164b7))
+- refactor(errors): accept `str`, `Path` or `URI` in `ROCrateInvalidURIError` ([0b8289b](https://github.com/crs4/rocrate-validator/commit/0b8289b))
+- refactor(cli/cache): drop the `Status` column from the `cache list` table ([392df1a](https://github.com/crs4/rocrate-validator/commit/392df1a))
+- feat(constants): default the HTTP cache to never expire ([419fece](https://github.com/crs4/rocrate-validator/commit/419fece))
+
+### 🐛 Fixed
+
+- fix(shacl): build property shape subgraphs by reachability and derive `NodeShape` level from nested `PropertyShape`s ([f1c0cfd](https://github.com/crs4/rocrate-validator/commit/f1c0cfd), [50448145](https://github.com/crs4/rocrate-validator/commit/5044814))
+- fix(shacl): evaluate inherited shapes for zero-shape target profiles ([bcb5cac](https://github.com/crs4/rocrate-validator/commit/bcb5cac))
+- fix(shacl): drop sub-threshold PySHACL violations at the source ([254fb88](https://github.com/crs4/rocrate-validator/commit/254fb88))
+- fix(core): filter failed requirements/checks by the configured severity ([a306f7f](https://github.com/crs4/rocrate-validator/commit/a306f7f))
+- fix(models): forward `extra_profiles_path` when computing validation statistics ([7b3e8bc](https://github.com/crs4/rocrate-validator/commit/7b3e8bc))
+- fix(uri): treat `file://` URIs with a non-local authority as remote ([63acb6a](https://github.com/crs4/rocrate-validator/commit/63acb6a))
+- fix(cli/cache): resolve profile tokens in `cache warm` and avoid `stream=True` when fetching remote crates ([7926832](https://github.com/crs4/rocrate-validator/commit/7926832), [33012b6](https://github.com/crs4/rocrate-validator/commit/33012b6))
+- fix(validation): report offline cache misses once per URL ([757b86a](https://github.com/crs4/rocrate-validator/commit/757b86a))
+- fix(ISA): correct the error message for a bad position in `HowToStep` ([03a32fc](https://github.com/crs4/rocrate-validator/commit/03a32fc))
+
+### 📚 Documentation
+
+- docs: add a dedicated documentation page for the cache and offline mode features ([e10c3b5](https://github.com/crs4/rocrate-validator/commit/e10c3b5))
+- docs(profiles): document check override-by-name and deactivation ([0b6bff7](https://github.com/crs4/rocrate-validator/commit/0b6bff7))
+
+## [0.9.0] - 2026-04-20
+
+Full changelog: https://github.com/crs4/rocrate-validator/compare/0.8.1...0.9.0
+
+### ✨ Added
+
+- feat(profiles/isa): add the ISA RO-Crate profile, with checks and tests for Investigation, Study, Assay, Process, Protocol, Sample, Data, Person and PropertyValue entities ([852fb23](https://github.com/crs4/rocrate-validator/commit/852fb23), [d62e214](https://github.com/crs4/rocrate-validator/commit/d62e214), [727b6f0](https://github.com/crs4/rocrate-validator/commit/727b6f0))
+- feat(cli): add CLI options to configure the HTTP cache (`--cache-path`, `--cache-max-age`) ([564230f](https://github.com/crs4/rocrate-validator/commit/564230f))
+- feat(model): enable cache configuration in `ValidationSettings` ([b2b47ba](https://github.com/crs4/rocrate-validator/commit/b2b47ba))
+- feat(utils): extend the `HttpRequester` constructor to support cache configuration parameters ([2f2a873](https://github.com/crs4/rocrate-validator/commit/2f2a873))
+- feat(ro-crate): refine the constraint enforcing metadata descriptor existence ([2c6ea76](https://github.com/crs4/rocrate-validator/commit/2c6ea76))
+- feat(file-descriptor): add an internal remote-context retrieval method supporting the alternate `Link` header ([f8b0e55](https://github.com/crs4/rocrate-validator/commit/f8b0e55))
+
+### 🔧 Changed
+
+- refactor(ro-crate): relax the `ROCrateMetadataFileDescriptor` class definition ([61ddbb5](https://github.com/crs4/rocrate-validator/commit/61ddbb5))
+- refactor(file-descriptor): route checks through the new remote-context retrieval method ([0ce2619](https://github.com/crs4/rocrate-validator/commit/0ce2619))
+- chore(utils): increase the session cache max age to 300 seconds ([36ca0ac](https://github.com/crs4/rocrate-validator/commit/36ca0ac))
+- ci(gh-actions): update outdated GitHub Actions ([d565c5d](https://github.com/crs4/rocrate-validator/commit/d565c5d))
+
+### 🐛 Fixed
+
+- fix(ro-crate): target metadata descriptor shapes by class and select the candidate descriptor via SPARQL ([8219f27](https://github.com/crs4/rocrate-validator/commit/8219f27), [39bd761](https://github.com/crs4/rocrate-validator/commit/39bd761), [1a91aa4](https://github.com/crs4/rocrate-validator/commit/1a91aa4))
+- fix(shacl): extract `@base` from the JSON-LD document for ontology parsing ([57f5c54](https://github.com/crs4/rocrate-validator/commit/57f5c54))
+- fix(SHACL-core): improve SHACL violation parsing with better error handling ([90a9f06](https://github.com/crs4/rocrate-validator/commit/90a9f06))
+- fix(file-descriptor): accept `application/json` and treat the `Link` header case-insensitively for remote context retrieval ([fe5ba1c](https://github.com/crs4/rocrate-validator/commit/fe5ba1c))
+- fix(file-descriptor): refine the compacted JSON-LD key validation logic ([45a7017](https://github.com/crs4/rocrate-validator/commit/45a7017))
+- fix(core): allow terms defined by context prefixes ([5fe8171](https://github.com/crs4/rocrate-validator/commit/5fe8171))
+- fix(core): fix output formatting ([523fbf4](https://github.com/crs4/rocrate-validator/commit/523fbf4))
+
+### 📚 Documentation
+
+- docs(cli): document the `-1` value for no cache expiration in the `--cache-max-age` help ([c5848bc](https://github.com/crs4/rocrate-validator/commit/c5848bc))
+
 ## [0.8.1] - 2026-02-18
 
 Full changelog: https://github.com/crs4/rocrate-validator/compare/0.8.0...0.8.1

docs/0_toc.rst

@@ -1,5 +1,5 @@
 ..
-    Copyright (c) 2024 CRS4
+    Copyright (c) 2024-2026 CRS4
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@
     2_usage_cli
     3_usage_api
     4_how_it_works
+    5_offline_mode
 
 .. toctree::
     :maxdepth: 5
@@ -30,3 +31,9 @@
     11_writing_a_profile
     10_api
     genindex
+
+.. toctree::
+    :maxdepth: 1
+    :caption: About
+
+    ack

docs/10_api.rst

@@ -1,5 +1,5 @@
 ..
-    Copyright (c) 2024 CRS4
+    Copyright (c) 2024-2026 CRS4
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -135,7 +135,7 @@ Python Check API
 ======================
 
 Requirement Class
-----------
+-----------------
 .. autoclass:: rocrate_validator.requirements.python.PyRequirement
     :members:
 

docs/11_writing_a_profile.rst

@@ -94,6 +94,154 @@ These instructions assume you are familiar with code development using Python an
 #. When your profile & tests are written, open a pull request to contribute 
    it back to the repository!
 
+Overriding inherited checks
+---------------------------
+
+When a profile inherits from another profile (via ``prof:isProfileOf`` /
+``prof:isTransitiveProfileOf``), it automatically receives every check
+declared by its ancestors. The validator additionally supports
+**override-by-name**: a child profile can replace an inherited check by
+declaring a new check with the **same name**.
+
+This allows an extension profile to *redefine* the content of an inherited
+check — for example, to make a constraint stricter or looser, change its
+severity, or, as described in the next section, fully deactivate it.
+
+Override-by-name is enabled by default. It can be disabled via the
+``allow_requirement_check_override`` validation setting (CLI / API), which
+will raise an error on duplicate check names instead.
+
+SHACL checks
+^^^^^^^^^^^^
+
+Each SHACL ``NodeShape`` / ``PropertyShape`` becomes a check whose name is
+its ``sh:name``. To override an inherited check, declare a shape in the
+extension profile with the **same** ``sh:name`` as the inherited one:
+
+.. code-block:: turtle
+
+   # Parent profile
+   ro:ShapeC
+       a sh:NodeShape ;
+       sh:name "The Shape C" ;
+       sh:targetNode ro:ro-crate-metadata.json ;
+       sh:property [
+           a sh:PropertyShape ;
+           sh:name "Check Metadata File Descriptor entity existence" ;
+           sh:path rdf:type ;
+           sh:minCount 1 ;
+           sh:message "Missing entity" ;
+       ] .
+
+.. code-block:: turtle
+
+   # Extension profile — overrides the inherited PropertyShape by sh:name
+   ro:ShapeC
+       a sh:NodeShape ;
+       sh:name "The Shape C" ;
+       sh:targetNode ro:ro-crate-metadata.json ;
+       sh:property [
+           a sh:PropertyShape ;
+           sh:name "Check Metadata File Descriptor entity existence" ;
+           sh:path rdf:type ;
+           sh:minCount 1 ;
+           sh:maxCount 1 ;
+           sh:message "Stricter override from extension profile" ;
+       ] .
+
+Both top-level shapes and ``PropertyShape`` entries nested inside a parent
+``NodeShape`` (i.e., declared inline, without an absolute IRI) can be
+overridden this way.
+
+Python checks
+^^^^^^^^^^^^^
+
+Python checks declared via the ``@check`` decorator are matched by their
+``name`` argument. To override an inherited Python check, declare a new
+function with the same ``name`` in the extension profile:
+
+.. code-block:: python
+
+   # In the extension profile's checks module
+   from rocrate_validator.requirements.python import check
+
+   @check(name="Check Metadata File Descriptor entity existence")
+   def overridden_check(self, ctx):
+       # New implementation that replaces the inherited one
+       ...
+
+Deactivating inherited checks
+-----------------------------
+
+A child profile can also **fully deactivate** a check inherited from one of
+its ancestors. A deactivated check is skipped during validation and
+reported as such in the validation result. This is useful when an extension
+profile relaxes the parent's expectations, or replaces a coarse-grained
+check with a more specific one declared elsewhere in the same profile.
+
+SHACL checks
+^^^^^^^^^^^^
+
+Two complementary mechanisms are supported, depending on whether the shape
+to disable has an absolute IRI of its own.
+
+**Shape with an absolute IRI** (e.g. a top-level ``NodeShape`` or a named
+``PropertyShape``): reference the shape by IRI from the extension profile
+and mark it as deactivated, without redeclaring it.
+
+.. code-block:: turtle
+
+   # Extension profile
+   <https://parent-profile/ShapeC> sh:deactivated true .
+
+**Nested ``PropertyShape`` without an absolute IRI** (a property declared
+inline inside a parent ``NodeShape``): use the override-by-name mechanism
+described in the previous section. Declare a new ``PropertyShape`` in the
+extension profile with the same ``sh:name`` as the one to disable, and set
+``sh:deactivated true`` on it. This overrides the parent's
+``PropertyShape``, and the validator reports the resulting check as
+deactivated.
+
+.. code-block:: turtle
+
+   # Extension profile — disables the inherited PropertyShape by sh:name
+   ro:ShapeC
+       a sh:NodeShape ;
+       sh:name "The Shape C" ;
+       sh:targetNode ro:ro-crate-metadata.json ;
+       sh:property [
+           a sh:PropertyShape ;
+           sh:name "Check Metadata File Descriptor entity existence" ;
+           sh:path rdf:type ;
+           sh:deactivated true ;
+       ] .
+
+.. note::
+
+   Cross-profile deactivation is scoped to the shape's transitive
+   descendants: a ``sh:deactivated true`` triple declared by a profile
+   that does not inherit (directly or transitively) from the shape's
+   owning profile is ignored. This prevents unrelated profiles loaded in
+   the same process from interfering with one another.
+
+Python checks
+^^^^^^^^^^^^^
+
+The ``@check`` decorator accepts a ``deactivated`` flag, mirroring SHACL's
+``sh:deactivated``. Combined with override-by-name, an extension profile
+can disable an inherited Python check by redeclaring it with
+``deactivated=True``:
+
+.. code-block:: python
+
+   from rocrate_validator.requirements.python import check
+
+   @check(name="Check Metadata File Descriptor entity existence",
+          deactivated=True)
+   def disabled(self, ctx):
+       # Body is irrelevant — the check is skipped during validation.
+       return True
+
 Running validator & tests during profile development
 ----------------------------------------------------
 

docs/1_installation.rst

@@ -1,5 +1,5 @@
 ..
-    Copyright (c) 2024 CRS4
+    Copyright (c) 2024-2026 CRS4
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.

docs/2_usage_cli.rst

@@ -1,5 +1,5 @@
 ..
-    Copyright (c) 2024 CRS4
+    Copyright (c) 2024-2026 CRS4
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -31,3 +31,9 @@ CLI Validation
     :parser: myst_parser.sphinx_
     :start-line: 93
     :end-line: 120
+
+.. seealso::
+
+    To validate without network access and manage the HTTP cache from the
+    command line (the ``--offline`` and ``--no-cache`` flags and the ``cache``
+    subcommand), see :ref:`offline_mode`.

docs/3_usage_api.rst

@@ -1,5 +1,5 @@
 ..
-    Copyright (c) 2024 CRS4
+    Copyright (c) 2024-2026 CRS4
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -30,6 +30,12 @@ Programmatic Validation
     :start-line: 121
     :end-line: 162
 
+.. seealso::
+
+    To resolve resources from a local cache or run validation without network
+    access (the ``offline`` / ``no_cache`` settings of ``ValidationSettings``),
+    see :ref:`offline_mode`.
+
 
 Metadata-only Validation
 ------------------------