Merge pull request #132 from stac-utils/universal-verbose

- Added support for --verbose flag to show verbose error messages
- Updated stac-validator to v3.9.0
- Improved cli output, message formatting

Author: jonhealy1

CHANGELOG.md

@@ -6,6 +6,18 @@ The format is (loosely) based on [Keep a Changelog](http://keepachangelog.com/)
 
 ## Unreleased
 
+
+## [v1.9.0] - 2025-06-13
+
+### Added
+
+- Added support for --verbose flag to show verbose error messages ([#132](https://github.com/stac-utils/stac-check/pull/132))
+
+### Changed
+
+- Updated stac-validator to v3.9.0 ([#132](https://github.com/stac-utils/stac-check/pull/132))
+- Improved cli output, message formatting ([#132](https://github.com/stac-utils/stac-check/pull/132))
+
 ## [v1.8.0] - 2025-06-11
 
 ### Changed
@@ -240,7 +252,8 @@ The format is (loosely) based on [Keep a Changelog](http://keepachangelog.com/)
 - Validation from stac-validator 2.3.0
 - Links and assets validation checks
 
-[Unreleased]: https://github.com/stac-utils/stac-check/compare/v1.8.0...main
+[Unreleased]: https://github.com/stac-utils/stac-check/compare/v1.9.0...main
+[v1.9.0]: https://github.com/stac-utils/stac-check/compare/v1.8.0...v1.9.0
 [v1.8.0]: https://github.com/stac-utils/stac-check/compare/v1.7.0...v1.8.0
 [v1.7.0]: https://github.com/stac-utils/stac-check/compare/v1.6.0...v1.7.0
 [v1.6.0]: https://github.com/stac-utils/stac-check/compare/v1.5.0...v1.6.0

README.md

@@ -109,6 +109,7 @@ Options:
   --header KEY VALUE       HTTP header to include in the requests. Can be used
                            multiple times.
   --pydantic               Use stac-pydantic for enhanced validation with Pydantic models.
+  --verbose                Show verbose error messages.
   --help                   Show this message and exit.
 ```
 

setup.py

@@ -3,7 +3,7 @@
 
 from setuptools import find_packages, setup
 
-__version__ = "1.8.0"
+__version__ = "1.9.0"
 
 with open("README.md", "r") as fh:
     long_description = fh.read()
@@ -20,7 +20,7 @@
         "requests>=2.32.3",
         "jsonschema>=4.23.0",
         "click>=8.1.8",
-        "stac-validator>=3.8.1",
+        "stac-validator~=3.9.0",
         "PyYAML",
         "python-dotenv",
     ],
@@ -29,15 +29,15 @@
             "pytest",
             "requests-mock",
             "types-setuptools",
-            "stac-validator[pydantic]",
+            "stac-validator[pydantic]~=3.9.0",
         ],
         "docs": [
             "sphinx>=4.0.0",
             "sphinx_rtd_theme>=1.0.0",
             "myst-parser>=0.18.0",
             "sphinx-autodoc-typehints>=1.18.0",
         ],
-        "pydantic": ["stac-validator[pydantic]"],
+        "pydantic": ["stac-validator[pydantic]~=3.9.0"],
     },
     entry_points={"console_scripts": ["stac-check=stac_check.cli:main"]},
     author="Jonathan Healy",

stac_check/cli.py

@@ -4,6 +4,7 @@
 
 from .lint import Linter
 from .logo import logo
+from .utilities import format_verbose_error
 
 
 def link_asset_message(
@@ -88,15 +89,18 @@ def intro_message(linter: Linter) -> None:
     click.secho()
 
     click.secho(
-        f"Validator: stac-validator {linter.validator_version}", bg="blue", fg="white"
+        f"\n Validator: stac-validator {linter.validator_version}",
+        bold=True,
+        bg="black",
+        fg="white",
     )
 
     # Always show validation method
     validation_method = (
         "Pydantic" if hasattr(linter, "pydantic") and linter.pydantic else "JSONSchema"
     )
     click.secho()
-    click.secho(f"Validation method: {validation_method}", bg="yellow", fg="black")
+    click.secho(f"\n Validation method: {validation_method}", bg="black", fg="white")
 
     click.secho()
 
@@ -137,7 +141,7 @@ def cli_message(linter: Linter) -> None:
     click.secho()
     for message in linter.best_practices_msg:
         if message == linter.best_practices_msg[0]:
-            click.secho(message, bg="blue")
+            click.secho("\n " + message, bg="blue")
         else:
             click.secho(message, fg="red")
 
@@ -146,7 +150,7 @@ def cli_message(linter: Linter) -> None:
         click.secho()
         for message in linter.geometry_errors_msg:
             if message == linter.geometry_errors_msg[0]:
-                click.secho(message, bg="yellow", fg="black")
+                click.secho("\n " + message, bg="yellow", fg="black")
             else:
                 click.secho(message, fg="red")
 
@@ -176,14 +180,36 @@ def cli_message(linter: Linter) -> None:
         link_asset_message(linter.invalid_link_request, "link", "request", True)
 
     if linter.error_type != "":
+        click.secho()
+        click.secho("\n Validation Errors: ", fg="white", bold=True, bg="black")
         click.secho("Validation error type: ", fg="red")
         click.secho(f"    {linter.error_type}")
+        click.secho()
 
     if linter.error_msg != "":
         click.secho("Validation error message: ", fg="red")
         click.secho(f"    {linter.error_msg}")
+        click.secho()
+
+    if linter.error_msg != "" and linter.verbose_error_msg == "":
+        click.secho("Refer to --verbose for more details.", fg="blue")
+        click.secho()
+
+    if linter.verbose_error_msg:
+        click.secho()
+        click.secho("\n Verbose Validation Output: ", fg="white", bg="red")
 
-    click.secho(f"This object has {len(linter.data['links'])} links")
+        if isinstance(linter.verbose_error_msg, dict):
+            formatted_error = format_verbose_error(linter.verbose_error_msg)
+        else:
+            formatted_error = str(linter.verbose_error_msg)
+
+        click.secho(formatted_error)
+
+    click.secho()
+    click.secho()
+    click.secho("\n Additional Information: ", bg="green", fg="white")
+    click.secho(f"This object has {len(linter.data['links'])} links", bold=True)
 
     click.secho()
 
@@ -225,10 +251,18 @@ def cli_message(linter: Linter) -> None:
     is_flag=True,
     help="Use pydantic validation (requires stac-pydantic to be installed).",
 )
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Enable verbose output.",
+)
 @click.command()
 @click.argument("file")
 @click.version_option(version=importlib.metadata.distribution("stac-check").version)
-def main(file, recursive, max_depth, assets, links, no_assets_urls, header, pydantic):
+def main(
+    file, recursive, max_depth, assets, links, no_assets_urls, header, pydantic, verbose
+):
     # Check if pydantic validation is requested but not installed
     if pydantic:
         try:
@@ -250,6 +284,7 @@ def main(file, recursive, max_depth, assets, links, no_assets_urls, header, pyda
         assets_open_urls=not no_assets_urls,
         headers=dict(header),
         pydantic=pydantic,
+        verbose=verbose,
     )
     intro_message(linter)
     if recursive > 0:

stac_check/lint.py

@@ -28,6 +28,7 @@ class Linter:
         assets_open_urls (bool): Whether to open assets URLs when validating assets. Defaults to True.
         headers (dict): HTTP headers to include in the requests.
         pydantic (bool, optional): A boolean value indicating whether to use pydantic validation. Defaults to False.
+        verbose (bool, optional): A boolean value indicating whether to enable verbose output. Defaults to False.
 
     Attributes:
         data (dict): A dictionary representing the STAC JSON file.
@@ -139,6 +140,7 @@ def check_summaries(self) -> bool:
     assets_open_urls: bool = True
     headers: Dict = field(default_factory=dict)
     pydantic: bool = False
+    verbose: bool = False
 
     def __post_init__(self):
         # Check if pydantic validation is requested but not installed
@@ -170,6 +172,7 @@ def __post_init__(self):
         self.valid_stac = self.message["valid_stac"]
         self.error_type = self.check_error_type()
         self.error_msg = self.check_error_message()
+        self.verbose_error_msg = self.check_verbose_error_message()
         self.invalid_asset_format = (
             self.check_links_assets(10, "assets", "format") if self.assets else None
         )
@@ -291,7 +294,18 @@ def validate_file(self, file: Union[str, dict]) -> Dict[str, Any]:
         Raises:
             ValueError: If `file` is not a valid file path or STAC dictionary.
         """
-        if isinstance(file, str):
+        if isinstance(file, str) and self.verbose:
+            stac = StacValidate(
+                file,
+                links=self.links,
+                assets=self.assets,
+                assets_open_urls=self.assets_open_urls,
+                headers=self.headers,
+                pydantic=self.pydantic,
+                verbose=self.verbose,
+            )
+            stac.run()
+        elif isinstance(file, str):
             stac = StacValidate(
                 file,
                 links=self.links,
@@ -411,6 +425,17 @@ def check_error_message(self) -> str:
         else:
             return ""
 
+    def check_verbose_error_message(self) -> str:
+        """Checks whether the `message` attribute contains an `verbose_error_message` field.
+
+        Returns:
+            A string containing the value of the `verbose_error_message` field, or an empty string if the field is not present.
+        """
+        if "error_verbose" in self.message:
+            return self.message["error_verbose"]
+        else:
+            return ""
+
     def check_summaries(self) -> bool:
         """Check if a Collection asset has a "summaries" property.
 
@@ -1047,6 +1072,7 @@ def create_best_practices_msg(self) -> List[str]:
             "geometry_coordinates_definite_errors",
             "check_bbox_antimeridian",
             "check_bbox_geometry_match",
+            "bbox_geometry_mismatch",
         ]
         filtered_dict = {
             k: v for k, v in best_practices_dict.items() if k not in geometry_keys
@@ -1087,6 +1113,7 @@ def create_geometry_errors_msg(self) -> List[str]:
             "geometry_coordinates_definite_errors",
             "check_bbox_antimeridian",
             "check_bbox_geometry_match",
+            "bbox_geometry_mismatch",
         ]
         geometry_dict = {
             k: v for k, v in best_practices_dict.items() if k in geometry_keys

stac_check/utilities.py

@@ -0,0 +1,55 @@
+def format_verbose_error(error_data):
+    """Format verbose error data into a human-readable string."""
+    if not error_data or not isinstance(error_data, dict):
+        return str(error_data)
+
+    output = []
+
+    # Handle validator type
+    if "validator" in error_data:
+        output.append(f"Validator: {error_data['validator']}")
+
+    # Handle schema information if available
+    if "schema" in error_data and error_data["schema"]:
+        output.append("\nSchema Information:")
+        if isinstance(error_data["schema"], list):
+            for schema in error_data["schema"]:
+                if isinstance(schema, dict):
+                    if "$comment" in schema:
+                        output.append(f"- {schema['$comment']}")
+                    if "required" in schema:
+                        output.append(
+                            f"  Required fields: {', '.join(schema['required'])}"
+                        )
+                    # Handle nested schema requirements
+                    if "properties" in schema and "properties" in schema.get(
+                        "properties", {}
+                    ):
+                        props = schema["properties"]["properties"]
+                        if "allOf" in props:
+                            for item in props["allOf"]:
+                                if "anyOf" in item:
+                                    for req in item["anyOf"]:
+                                        if "required" in req:
+                                            output.append(
+                                                f"  One of these fields is required: {', '.join(req['required'])}"
+                                            )
+
+    # Handle path information if available
+    if "path_in_schema" in error_data and error_data["path_in_schema"]:
+        output.append(
+            f"\nError Path: {' -> '.join(str(p) for p in error_data['path_in_schema'])}"
+        )
+
+    # Handle any other fields we haven't specifically formatted
+    other_fields = set(error_data.keys()) - {
+        "validator",
+        "schema",
+        "path_in_schema",
+        "path_in_document",
+    }
+    for field in other_fields:
+        if isinstance(error_data[field], (str, int, float, bool)):
+            output.append(f"\n{field.replace('_', ' ').title()}: {error_data[field]}")
+
+    return "\n".join(output)

tests/test_lint.py

@@ -980,3 +980,34 @@ def test_pydantic_fallback_without_import(monkeypatch):
     assert linter.valid_stac is True
     assert linter.asset_type == "ITEM"
     assert linter.message["validation_method"] == "default"
+
+
+def test_verbose_error_message():
+    """Test that verbose error messages are properly formatted and included."""
+    # Test with a known bad item that will generate validation errors
+    file = "sample_files/1.0.0/bad-item.json"
+    linter = Linter(file, verbose=True)
+
+    # Verify the item is invalid
+    assert linter.valid_stac is False
+
+    # Check that we have the expected error message
+    assert "id" in linter.error_msg.lower()
+    assert "required" in linter.error_msg.lower()
+
+    # Check that verbose error message contains expected structure
+    assert isinstance(linter.verbose_error_msg, dict)
+    assert "validator" in linter.verbose_error_msg
+    assert "path_in_schema" in linter.verbose_error_msg
+
+    # Check specific parts of the verbose error message
+    assert linter.verbose_error_msg.get("validator") == "required"
+
+    # Check path_in_schema - it might contain both strings and integers
+    path_in_schema = linter.verbose_error_msg.get("path_in_schema", [])
+    assert any(isinstance(p, (str, int)) for p in path_in_schema)
+
+    # Check that the error message is included in the string representation
+    verbose_str = str(linter.verbose_error_msg)
+    assert "required" in verbose_str
+    assert "id" in verbose_str