release: 🔖 version 0.6.0

Author: kikkomep

docs/0_toc.rst

@@ -20,10 +20,12 @@
     1_installation
     2_usage_cli
     3_usage_api
+    4_how_it_works
 
 .. toctree::
     :maxdepth: 5
     :caption: Resources
 
+    11_writing_a_profile
     10_api
     genindex

docs/11_writing_a_profile.rst

@@ -0,0 +1,93 @@
+Writing a new profile
+=====================
+
+This page is about writing a SHACL validation profile for a new or 
+existing RO-Crate profile. It does *not* offer guidance on creating the 
+RO-Crate profile itself - for that, see the
+`RO-Crate page on Profiles <https://www.researchobject.org/ro-crate/profiles#making-an-ro-crate-profile>`_.
+
+Learning SHACL
+--------------
+
+The validator profiles are written in SHACL (Shapes Constraint Language), a 
+language for validating RDF graphs against a set of conditions. 
+To use SHACL effectively, you also need some familiarity with RDF 
+(Resource Description Framework), the technology which underpins 
+JSON-LD and therefore RO-Crate.
+
+For an RDF introduction, try the `RDF 1.1 Primer <https://www.w3.org/TR/rdf11-primer/>`_ or 
+`Introduction to the Principles of Linked Open Data <https://programminghistorian.org/en/lessons/intro-to-linked-data>`_.
+
+This `chapter on SHACL <https://book.validatingrdf.com/bookHtml011.html>`_ 
+from the book `Validating RDF Data <https://book.validatingrdf.com>`_
+has examples of most of SHACL's features and is a good place 
+to start learning. Other chapters in that book may provide an understanding 
+of *why* SHACL is our language of choice for this purpose.
+
+For complex validation, you may also need some knowledge of SPARQL, an RDF 
+query language. You can learn about SPARQL in the tutorial
+`Using SPARQL to access Linked Open Data <https://programminghistorian.org/en/lessons/retired/graph-databases-and-SPARQL>`_.
+
+All these tools are best learned through practice and examples, so when building a 
+profile, it's encouraged to use the 
+`other profiles <https://github.com/crs4/rocrate-validator/tree/develop/rocrate_validator/profiles>`_
+as a point of reference.
+
+Setting up profile files and tests
+----------------------------------
+
+These instructions assume you are familiar with code development using Python and Git.
+
+#. `Install the repository from source <https://rocrate-validator.readthedocs.io/en/latest/1_installation/#installation>`_.
+#. From the root folder of the repo, create a folder for the profile under 
+   `rocrate_validator/profiles <https://github.com/crs4/rocrate-validator/tree/develop/rocrate_validator/profiles>`_.
+#. To set up the profile metadata, copy across ``profile.ttl`` from another 
+   profile folder to the folder you created 
+   (`example <https://github.com/crs4/rocrate-validator/blob/develop/rocrate_validator/profiles/workflow-ro-crate/profile.ttl>`_) 
+   & update that metadata to reflect your profile. In particular:
+
+    #. change the token for the profile to a new and unique name, e.g.
+       ``prof:hasToken "workflow-ro-crate-linkml"``. This is the name which 
+       can be used to select the profile using ``--profile-identifier``
+       argument (and should also be the name of the folder).
+    #. Ensure the URI of the profile is unique (the first line after the 
+       ``@prefix`` statements), to prevent conflation between this profile 
+       and any other profile in the package.
+    #. If this profile inherits from another profile in the validator 
+       (including the base specification), set ``prof:isProfileOf`` / 
+       ``prof:isTransitiveProfileOf`` to that profile's URI (which can be found
+       in that profile's own ``profile.ttl``).
+
+#. Create a ``profile-name.ttl`` file in the folder you created - this is 
+   where you will write the SHACL for the validation. If you have a lot of 
+   checks to write, you can create multiple files - the validator will 
+   collect them all automatically at runtime. 
+
+    * Note: some profiles split the checks into folders called ``must/``, 
+      ``should/`` and ``may/`` according to the requirement severity. This 
+      is not mandatory - you can also label individual checks/shapes with 
+      ``sh:severity`` in the SHACL code instead.
+
+#. From the root folder of the repo, create a test folder for the profile 
+   under 
+   `tests/integration/profiles <https://github.com/crs4/rocrate-validator/tree/develop/tests/integration/profiles>`_. The name should match the folder you made earlier.
+#. Copy the style of other profiles' tests to build up a test suite for the 
+   profile. Add any required RO-Crate test data under 
+   `tests/data/crates/ <https://github.com/crs4/rocrate-validator/tree/develop/tests/data/crates>`_
+   and create corresponding classes in 
+   `tests/ro_crates.py <https://github.com/crs4/rocrate-validator/blob/develop/tests/ro_crates.py>`_ 
+   which can be used to fetch the data during the tests.
+#. When your profile & tests are written, open a pull request to contribute 
+   it back to the repository!
+
+Running validator & tests during profile development
+----------------------------------------------------
+
+To run the test suite, run ``pytest``. New tests should be picked up automatically for 
+the new profile.
+
+When running the validator manually, use ``--profile-identifier`` to select the desired profile.
+
+The crates in ``tests/data/crates``` can be used as examples for running the validator. For example: ::
+
+    rocrate-validator validate --profile-identifier your-profile-name tests/data/crates/invalid/1_wroc_crate/no_mainentity/

docs/4_how_it_works.rst

@@ -0,0 +1,76 @@
+..
+    Copyright (c) 2024 CRS4
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+How It Works
+============
+
+The `rocrate-validator` is designed to validate RO-Crates against predefined
+*validation profiles*. A validation profile is a set of validation rules, or
+*checks*, which are applied to the RO-Crate.  If the RO-Crate conforms to all
+the rules, then it is deemed *valid*; otherwise, errors will be generated for
+each rule that failed to validate.
+
+Non-conformance to a rule will result in an *issue*.  On the CLI, issues will
+be presented as error messages, with references to the specific rule which
+triggered the error. Note that multiple rules may have the same error message,
+which can result in output with apparently duplicate errors.
+
+`rocrate-validator` is limited to validating conformance to RO-Crate
+profiles for which validation rules have been implemented.  In the absence of
+any matching validation profiles, `rocrate-validator` may return an error or
+request the user to manually select a validation profile to apply.
+
+Validation profiles can be related by inheritance -- i.e., where one validation
+profile extends another one. For instance, Workflow Testing RO-Crate extends Workflow RO-Crate.
+
+
+Validation profile selection
+----------------------------
+
+* **Automatic Profile Matching** (default):
+  By default, `rocrate-validator` will attempt to select the correct validation
+  profiles for the input RO-Crate based on the `conformsTo` property of the Root Data Entity.
+
+    - If a precise match is found for the `conformsTo` property, that profile is selected
+      for validation.
+
+    - If no precise match is found:
+
+      - in **Interactive Mode:** (available only through the CLI) the system
+        will prompt the user to select a profile from the list of
+        profiles to which the RO-Crate conforms;
+
+      - in **Non-Interactive Mode:** the system will validate against all profiles
+        to which the RO-Crate conforms, and for which validation rules are available.
+        In all cases, input RO-Crates are validated against the base `ro-crate` profile.
+
+* **Profile Versions**:
+    - It may happen that the RO-Crate profile version to which the input
+      RO-Crate `conformsTo` does not match the version of the implemented
+      validation profile. In this case, the validator will validate against the
+      *highest available version* of the profile that is lower than the one
+      requested. Thus, the validator will avoid applying a validation profile
+      that is newer than the `conformsTo` profile.  This behaviour can be
+      overridden by manually selecting the desired validation profile (see below).
+
+  .. note::
+      Profile versions are identified by matching the trailing version number
+      in the profile identifier, if present. For instance, the identifier for
+      the `ro-crate` profile version **1.0** is `ro-crate-1.0`, while the
+      profile name without a version is simply `ro-crate`.
+
+* **Manual Profile Selection**:
+    The user can always override the automatic selection of validation profiles
+    by specifying (via CLI or API) which profile to use.