Create universal verbose mode for better error messaging (#257)

* use trace-recursion

* add verbose flag

* add verbose message

* add verbose dict

* improve oneof error messaging

* update tests, add validation errors to verbose mode

* mypy

* types

* update changelog issue num

Author: jonhealy1

CHANGELOG.md

@@ -6,6 +6,13 @@ The format is (loosely) based on [Keep a Changelog](http://keepachangelog.com/)
 
 ## [Unreleased]
 
+### Added
+- Added separate `recommendation` field in error messages when running in non-verbose mode [#257](https://github.com/stac-utils/stac-validator/pull/257)
+- Verbose error messages for JSONSchemaValidationErrors [#257](https://github.com/stac-utils/stac-validator/pull/257)
+
+### Changed
+- Changed --verbose for recursive mode to --trace-recursive to make way for more comprehensive error messaging [#257](https://github.com/stac-utils/stac-validator/pull/257)
+
 ## [v3.8.1] - 2025-06-04
 
 ### Fixed

README.md

@@ -172,13 +172,15 @@ Options:
                                   be used multiple times.
   -p, --pages INTEGER             Maximum number of pages to validate via
                                   --item-collection. Defaults to one page.
-  -v, --verbose                   Enables verbose output for recursive mode.
+  -t, --trace-recursion           Enables verbose output for recursive mode.
   --no_output                     Do not print output to console.
   --log_file TEXT                 Save full recursive output to log file
                                   (local filepath).
   --pydantic                      Validate using stac-pydantic models for enhanced
                                   type checking and validation.
   --schema-config TEXT            Path to a YAML or JSON schema config file.
+  --verbose                       Enable verbose output. This will output
+                                  additional information during validation.
   --help                          Show this message and exit.
 ```
 
@@ -370,7 +372,7 @@ $ stac-validator https://raw.githubusercontent.com/radiantearth/stac-spec/master
 ### --recursive
 
 ```bash
-$ stac-validator https://spot-canada-ortho.s3.amazonaws.com/catalog.json --recursive --max-depth 1 --verbose
+$ stac-validator https://spot-canada-ortho.s3.amazonaws.com/catalog.json --recursive --max-depth 1 --trace-recursion
 ```
 
 ```bash

setup.py

@@ -33,11 +33,7 @@
         "pyYAML>=6.0.1",
     ],
     extras_require={
-        "dev": [
-            "pytest",
-            "requests-mock",
-            "types-setuptools",
-        ],
+        "dev": ["pytest", "requests-mock", "types-setuptools", "stac-pydantic>=3.3.0"],
         "pydantic": [
             "stac-pydantic>=3.3.0",
         ],

stac_validator/stac_validator.py

@@ -140,7 +140,10 @@ def collections_summary(message: List[Dict[str, Any]]) -> None:
     help="Maximum number of pages to validate via --item-collection. Defaults to one page.",
 )
 @click.option(
-    "-v", "--verbose", is_flag=True, help="Enables verbose output for recursive mode."
+    "-t",
+    "--trace-recursion",
+    is_flag=True,
+    help="Enables verbose output for recursive mode.",
 )
 @click.option("--no_output", is_flag=True, help="Do not print output to console.")
 @click.option(
@@ -153,6 +156,11 @@ def collections_summary(message: List[Dict[str, Any]]) -> None:
     is_flag=True,
     help="Validate using stac-pydantic models for enhanced type checking and validation.",
 )
+@click.option(
+    "--verbose",
+    is_flag=True,
+    help="Enable verbose output. This will output additional information during validation.",
+)
 def main(
     stac_file: str,
     collections: bool,
@@ -169,10 +177,11 @@ def main(
     custom: str,
     schema_config: str,
     schema_map: List[Tuple],
-    verbose: bool,
+    trace_recursion: bool,
     no_output: bool,
     log_file: str,
     pydantic: bool,
+    verbose: bool = False,
 ) -> None:
     """Main function for the `stac-validator` command line tool. Validates a STAC file
     against the STAC specification and prints the validation results to the console as JSON.
@@ -193,10 +202,11 @@ def main(
         custom (str): Path to a custom schema file to validate against.
         schema_config (str): Path to a custom schema config file to validate against.
         schema_map (list(tuple)): List of tuples each having two elememts. First element is the schema path to be replaced by the path in the second element.
-        verbose (bool): Whether to enable verbose output for recursive mode.
+        trace_recursion (bool): Whether to enable verbose output for recursive mode.
         no_output (bool): Whether to print output to console.
         log_file (str): Path to a log file to save full recursive output.
         pydantic (bool): Whether to validate using stac-pydantic models for enhanced type checking and validation.
+        verbose (bool): Whether to enable verbose output. This will output additional information during validation.
 
     Returns:
         None
@@ -226,9 +236,10 @@ def main(
         custom=custom,
         schema_config=schema_config,
         schema_map=schema_map_dict,
-        verbose=verbose,
+        trace_recursion=trace_recursion,
         log=log_file,
         pydantic=pydantic,
+        verbose=verbose,
     )
     if not item_collection and not collections:
         valid = stac.run()

stac_validator/utilities.py

@@ -9,9 +9,9 @@
 import requests  # type: ignore
 import yaml  # type: ignore
 from jsonschema import Draft202012Validator
-from referencing import Registry, Resource
-from referencing.jsonschema import DRAFT202012
-from referencing.typing import URI
+from referencing import Registry, Resource  # type: ignore
+from referencing.jsonschema import DRAFT202012  # type: ignore
+from referencing.typing import URI  # type: ignore
 
 NEW_VERSIONS = [
     "1.0.0-beta.2",
@@ -292,3 +292,37 @@ def load_schema_config(config_path: str) -> dict:
     if "schemas" in data:
         return data["schemas"]
     return data
+
+
+def extract_relevant_oneof_error(error, instance=None):
+    """Extract the most relevant error from a 'oneOf' validation error.
+
+    Given a jsonschema.ValidationError for a 'oneOf' failure, this function returns
+    the most relevant sub-error, with preference given to errors matching the instance's 'type'.
+    If no matching type is found, it falls back to returning the first sub-error.
+
+    Args:
+        error (jsonschema.ValidationError): The validation error from a 'oneOf' validation.
+        instance (dict, optional): The instance being validated. If provided and contains a 'type'
+            field, the function will try to find a matching schema for that type. Defaults to None.
+
+    Returns:
+        jsonschema.ValidationError: The most relevant sub-error from the 'oneOf' validation.
+            If the error is not a 'oneOf' validation error or has no context, returns the
+            original error unchanged.
+    """
+    if error.validator == "oneOf" and hasattr(error, "context") and error.context:
+        if instance and "type" in instance:
+            for suberror in error.context:
+                # Try to match the instance 'type' to the schema's 'type'
+                props = suberror.schema.get("properties", {})
+                type_schema = props.get("type", {})
+                if (
+                    isinstance(type_schema, dict)
+                    and "const" in type_schema
+                    and instance["type"] == type_schema["const"]
+                ):
+                    return suberror
+        # Fallback to the first suberror
+        return error.context[0]
+    return error