Merge branch 'develop' into 48-implement-workflow-retrieval-phase-ruleset

Author: douglowe

docs/0_toc.rst

@@ -26,6 +26,7 @@
     :maxdepth: 5
     :caption: Resources
 
+    12_validation_profiles
     11_writing_a_profile
     10_api
     genindex

docs/11_writing_a_profile.rst

@@ -63,11 +63,25 @@ These instructions assume you are familiar with code development using Python an
    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/``, 
+   .. 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.
 
+#. Optionally, associate an ontology graph with the profile by providing 
+   an ``ontology.ttl`` file alongside the SHACL files. 
+   This graph is merged into the crate's data graph at validation time, 
+   allowing you to define formal relationships and additional definitions 
+   between profile entities (e.g., using ``rdfs:subClassOf``, 
+   ``owl:equivalentClass``, etc.).
+   
+   .. warning::
+
+      Including an ontology can significantly impact validation times and 
+      overall performance, especially for large graphs. Use with caution.
+
 #. 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.
@@ -90,4 +104,6 @@ When running the validator manually, use ``--profile-identifier`` to select the
 
 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/
+    rocrate-validator validate \
+      --profile-identifier your-profile-name \
+      tests/data/crates/invalid/1_wroc_crate/no_mainentity/

docs/12_validation_profiles.rst

@@ -0,0 +1,54 @@
+Validation Profiles
+===================
+
+The system comes with a set of **predefined validation profiles** that are loaded 
+automatically when the application starts (see `supported profiles <../#features>`_). 
+These profiles define the standard rules and checks that are applied during RO-Crate validation.
+
+Additional Profiles
+-------------------
+
+You can **extend or override** the predefined validation profiles by specifying 
+the path to additional profiles using the ``--extra-profiles-path`` option on the command line.
+
+CLI Usage
+^^^^^^^^^
+
+.. code-block:: bash
+
+    rocrate-validator validate --extra-profiles-path /path/to/additional/profiles <other_options> <path_to_rocrate>
+
+API Usage
+^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    # Import the `services` and `models` module from the rocrate_validator package
+    from rocrate_validator import services, models
+
+    # Create an instance of `ValidationSettings` class to configure the validation
+    settings = services.ValidationSettings(
+        # ... value for other settings ...
+
+        # Define the path to additional validation profiles
+        extra_profiles_path="/path/to/additional/profiles"  # Path to additional validation profiles
+    )
+
+    # Call the validation service with the settings
+    result = services.validate(settings)
+
+    # process the validation result
+    ...
+
+
+Behavior
+^^^^^^^^
+
+* Profiles provided via ``--extra-profiles-path`` are **loaded in addition to** the system’s predefined profiles.  
+* If an additional profile has the **same name** as a predefined profile, the additional profile **overrides** the predefined one.  
+
+This mechanism allows you to:
+
+* **Add new custom validation profiles** to implement project-specific checks.  
+* **Modify existing profiles** without altering the system’s predefined configuration files.  
+* **Maintain a clear separation** between standard validation logic and project-specific customizations.  

docs/3_usage_api.rst

@@ -29,3 +29,105 @@ Programmatic Validation
     :parser: myst_parser.sphinx_
     :start-line: 121
     :end-line: 162
+
+
+Metadata-only Validation
+------------------------
+
+In addition to full validation, which checks both metadata and data files,
+the library also supports metadata-only validation. This is useful when you
+want to ensure that the metadata conforms to the expected schema without
+checking the actual data files.
+
+To perform metadata-only validation, you can use the `validate_metadata_as_dict` 
+from the `rocrate_validator.services` module. This function takes a dictionary
+representing the metadata and validates it against a given validation profile. 
+
+.. code-block:: python
+
+    import json
+    from rocrate_validator.services import validate_metadata_as_dict
+
+    settings = {
+        "profile_identifier": "workflow-ro-crate-1.0"
+    }
+
+    with open('tests/data/crates/invalid/0_main_workflow/main_workflow_bad_type/ro-crate-metadata.json', 'r') as f:
+        # load the metadata from the JSON file
+        rocrate_metadata = json.load(f)
+        
+        # validate the metadata dictionary
+        result = validate_metadata_as_dict(rocrate_metadata, settings=settings)
+
+        # process the validation result as needed
+        ...
+
+
+Formatting Validation Results
+-----------------------------
+
+Validation results can be rendered using different output formatters provided by
+the library. Two formatter types are available: *text* and *JSON*.  
+Both rely on the ``rich`` Python library and integrate with the
+``rocrate_validator.io.output.console.Console`` class, which extends
+``rich.console.Console`` to support custom formatter registration.
+
+To format results, create a ``Console`` instance, register one formatter,
+and then print any validation output object (e.g., the full report or the
+aggregated statistics).
+
+
+TextOutputFormatter
+~~~~~~~~~~~~~~~~~~~
+
+``TextOutputFormatter`` renders validation reports as human-readable, styled text.  
+It is typically used for console output, report generation, or writing results
+to a file.
+
+.. code-block:: python
+
+    from rocrate_validator.io.output.console import Console
+    from rocrate_validator.io.output.text import TextOutputFormatter
+
+    console = Console()
+    console.register_formatter(TextOutputFormatter())
+
+    # Print the main validation result
+    console.print(result)
+
+    # Print aggregated statistics (violations by severity, executed checks, etc.)
+    console.print(result.statistics)
+
+    # Write the output to a file
+    with open("validation_report.txt", "w") as f:
+        file_console = Console(file=f)
+        file_console.register_formatter(TextOutputFormatter())
+        file_console.print(result.statistics)
+        file_console.print(result)
+
+
+JSONOutputFormatter
+~~~~~~~~~~~~~~~~~~~
+
+``JSONOutputFormatter`` produces JSON-structured output, suitable for logging,
+programmatic processing, or integration with external tools.
+
+.. code-block:: python
+
+    from rocrate_validator.io.output.console import Console
+    from rocrate_validator.io.output.json import JSONOutputFormatter
+
+    console = Console()
+    console.register_formatter(JSONOutputFormatter())
+
+    # Print the main validation result as JSON
+    console.print(result)
+
+    # Print the aggregated statistics
+    console.print(result.statistics)
+
+    # Write the output to a file
+    with open("validation_report.json", "w") as f:
+        file_console = Console(file=f)
+        file_console.register_formatter(JSONOutputFormatter())
+        file_console.print(result)

docs/conf.py

@@ -63,6 +63,9 @@
     'myst_parser',
     'sphinx.ext.mathjax',
     'enum_tools.autoenum',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_copybutton',
 ]
 
 templates_path = ['_templates']

docs/index.rst

@@ -17,9 +17,12 @@
 Welcome to rocrate-validator's documentation!
 =============================================
 
+.. _index:
+
 .. include:: ../README.md
       :parser: myst_parser.sphinx_
       :start-line: 2
       :end-line: 32
 
+
 .. include:: 0_toc.rst