jentic-openapi-validator 1.0.0a7__py3-none-any.whl

jentic/apitools/openapi/validator/backends/default/rules/server.py

@@ -0,0 +1,136 @@
+"""
+Server validation rules for OpenAPI specifications.
+
+These rules validate the 'servers' section and individual server objects.
+"""
+
+from typing import Any
+
+from lsprotocol import types as lsp
+
+from . import BaseRule, ValidationIssue
+
+
+__all__ = ["ServersArrayRule", "ServerUrlRule"]
+
+
+class ServersArrayRule(BaseRule):
+    """
+    Validates that the OpenAPI specification contains at least one server.
+
+    The 'servers' array is required and must contain at least one valid server object.
+    """
+
+    @property
+    def rule_id(self) -> str:
+        return "servers-array"
+
+    @property
+    def name(self) -> str:
+        return "Servers Array Validation"
+
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+        servers = spec_data.get("servers")
+
+        if not isinstance(servers, list) or not servers:
+            issues.append(
+                ValidationIssue(
+                    code="MISSING_SERVER_URL",
+                    message="OpenAPI spec must define at least one server in the 'servers' array.",
+                    severity=lsp.DiagnosticSeverity.Error,
+                    path=["servers"],
+                    fixable=False,
+                )
+            )
+
+        return issues
+
+
+class ServerUrlRule(BaseRule):
+    """
+    Validates individual server objects and their URLs.
+
+    Each server must:
+    - Be a valid object (dict)
+    - Have a non-empty 'url' field
+    - Use an absolute URL (http://, https://, or template variable)
+    """
+
+    @property
+    def rule_id(self) -> str:
+        return "server-url"
+
+    @property
+    def name(self) -> str:
+        return "Server URL Validation"
+
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+        servers = spec_data.get("servers")
+
+        # Only validate if servers is a list
+        if not isinstance(servers, list):
+            return issues
+
+        for index, server in enumerate(servers):
+            issues.extend(self._validate_single_server(server, index))
+
+        return issues
+
+    @staticmethod
+    def _validate_single_server(server: Any, index: int) -> list[ValidationIssue]:
+        """
+        Validates a single server object.
+
+        Args:
+            server: The server object to validate
+            index: The index of the server in the servers array
+
+        Returns:
+            List of ValidationIssue objects for any problems found
+        """
+        issues: list[ValidationIssue] = []
+        server_path = f"#/servers/{index}"
+
+        # Check if server is a dict
+        if not isinstance(server, dict):
+            issues.append(
+                ValidationIssue(
+                    code="INVALID_SERVER_OBJECT_FORMAT",
+                    message=f"Server entry at index {index} is not a valid object.",
+                    severity=lsp.DiagnosticSeverity.Error,
+                    path=["servers", index],
+                    fixable=False,
+                )
+            )
+            return issues
+
+        # Check for URL field
+        url = server.get("url")
+
+        if not url or not isinstance(url, str):
+            issues.append(
+                ValidationIssue(
+                    code="SERVER_URL_MISSING_OR_EMPTY",
+                    message=f"Server entry at '{server_path}' must have a non-empty 'url' string.",
+                    severity=lsp.DiagnosticSeverity.Error,
+                    path=["servers", index, "url"],
+                    fixable=False,
+                )
+            )
+            return issues
+
+        # Check if URL is absolute (or uses template variables)
+        if not (url.startswith("http://") or url.startswith("https://") or url.startswith("{")):
+            issues.append(
+                ValidationIssue(
+                    code="RELATIVE_SERVER_URL",
+                    message=f"Server URL '{url}' at index {index} must be an absolute URL (e.g., start with http:// or https://).",
+                    severity=lsp.DiagnosticSeverity.Warning,
+                    path=["servers", index, "url"],
+                    fixable=True,
+                )
+            )
+
+        return issues

jentic/apitools/openapi/validator/backends/default/rules/structural.py

@@ -0,0 +1,109 @@
+"""
+Structural validation rules for OpenAPI specifications.
+
+These rules validate the basic structure and required fields of an OpenAPI document.
+"""
+
+from typing import Any
+
+from lsprotocol import types as lsp
+
+from . import BaseRule, ValidationIssue
+
+
+__all__ = ["InfoObjectRule", "PathsRule"]
+
+
+class InfoObjectRule(BaseRule):
+    """
+    Validates the 'info' object in an OpenAPI specification.
+
+    The 'info' object is required and must contain 'title' and 'version' fields.
+    """
+
+    @property
+    def rule_id(self) -> str:
+        return "info-object"
+
+    @property
+    def name(self) -> str:
+        return "Info Object Validation"
+
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        info_object = spec_data.get("info")
+
+        # Check if info object exists and is a dict
+        if not isinstance(info_object, dict):
+            issues.append(
+                ValidationIssue(
+                    code="OPENAPI_MISSING_INFO",
+                    message="OpenAPI spec is missing the required 'info' section or it is not an object.",
+                    severity=lsp.DiagnosticSeverity.Error,
+                    path=["info"],
+                    fixable=False,
+                )
+            )
+            return issues
+
+        # Check for required fields: title and version
+        missing_fields = []
+        if not info_object.get("title"):
+            missing_fields.append("'title'")
+        if not info_object.get("version"):
+            missing_fields.append("'version'")
+
+        if missing_fields:
+            # Special case: if only x-jentic-source-url is present
+            if len(info_object.keys()) == 1 and "x-jentic-source-url" in info_object:
+                message = "The 'info' object only contains 'x-jentic-source-url' and is missing required fields 'title' and 'version'."
+            else:
+                message = (
+                    f"The 'info' object is missing required field(s): {', '.join(missing_fields)}."
+                )
+
+            issues.append(
+                ValidationIssue(
+                    code="OPENAPI_MISSING_INFO_FIELDS",
+                    message=message,
+                    severity=lsp.DiagnosticSeverity.Error,
+                    path=["info"],
+                    fixable=False,
+                )
+            )
+
+        return issues
+
+
+class PathsRule(BaseRule):
+    """
+    Validates that the OpenAPI specification contains a 'paths' section.
+
+    The 'paths' section is required in OpenAPI 3.x specifications and should
+    contain at least one path definition.
+    """
+
+    @property
+    def rule_id(self) -> str:
+        return "paths-section"
+
+    @property
+    def name(self) -> str:
+        return "Paths Section Validation"
+
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        if "paths" not in spec_data:
+            issues.append(
+                ValidationIssue(
+                    code="OPENAPI_MISSING_PATHS",
+                    message="OpenAPI spec is missing the required 'paths' section.",
+                    severity=lsp.DiagnosticSeverity.Error,
+                    path=["paths"],
+                    fixable=False,
+                )
+            )
+
+        return issues

jentic/apitools/openapi/validator/backends/openapi_spec.py

@@ -0,0 +1,107 @@
+import textwrap
+from collections.abc import Sequence
+from typing import Literal
+
+from lsprotocol import types as lsp
+from openapi_spec_validator import OpenAPIV30SpecValidator, OpenAPIV31SpecValidator
+
+from jentic.apitools.openapi.validator.backends.base import BaseValidatorBackend
+from jentic.apitools.openapi.validator.core.diagnostics import JenticDiagnostic, ValidationResult
+
+
+__all__ = ["OpenAPISpecValidatorBackend"]
+
+
+class OpenAPISpecValidatorBackend(BaseValidatorBackend):
+    def validate(
+        self, document: str | dict, *, base_url: str | None = None, target: str | None = None
+    ) -> ValidationResult:
+        if not isinstance(document, dict):
+            diagnostic = JenticDiagnostic(
+                range=lsp.Range(
+                    start=lsp.Position(line=0, character=0),
+                    end=lsp.Position(line=0, character=12),
+                ),
+                severity=lsp.DiagnosticSeverity.Error,
+                code="OAS1002",
+                source="openapi_spec_validator",
+                message="OpenAPISpecValidatorBackend only accepts dict format",
+            )
+            diagnostic.set_target(target)
+            return ValidationResult(diagnostics=[diagnostic])
+
+        if self._is_openapi_v31(document):
+            validator = OpenAPIV31SpecValidator(document, base_uri=base_url or "")
+        elif self._is_openapi_v30(document):
+            validator = OpenAPIV30SpecValidator(document, base_uri=base_url or "")
+        else:
+            diagnostic = JenticDiagnostic(
+                range=lsp.Range(
+                    start=lsp.Position(line=0, character=0),
+                    end=lsp.Position(line=0, character=12),
+                ),
+                severity=lsp.DiagnosticSeverity.Error,
+                code="OAS1000",
+                # code_description=lsp.CodeDescription(href="https://example.com/rules/OAS1000"),
+                source="openapi_spec_validator",
+                message="Document does not appear to be a valid OpenAPI 3.0.x or 3.1.x specification",
+            )
+            diagnostic.set_target(target)
+            return ValidationResult(diagnostics=[diagnostic])
+
+        diagnostics: list[JenticDiagnostic] = []
+        try:
+            for error in validator.iter_errors():
+                diagnostic = JenticDiagnostic(
+                    range=lsp.Range(
+                        start=lsp.Position(line=0, character=0),
+                        end=lsp.Position(line=0, character=0),
+                    ),
+                    severity=lsp.DiagnosticSeverity.Error,
+                    code=f"{error.validator or str(error.validator_value)}",
+                    source="openapi-spec-validator",
+                    message=error.message,
+                )
+                diagnostic.set_path(list(error.path))
+                diagnostic.set_target(target)
+                diagnostics.append(diagnostic)
+        except Exception as e:
+            error_msg = textwrap.shorten(str(e), width=500, placeholder="...")
+            diagnostic = JenticDiagnostic(
+                range=lsp.Range(
+                    start=lsp.Position(line=0, character=0),
+                    end=lsp.Position(line=0, character=12),
+                ),
+                severity=lsp.DiagnosticSeverity.Error,
+                code="openapi-spec-validator-error",
+                source="openapi-spec-validator",
+                message=f"Error validating spec - {error_msg}",
+            )
+            diagnostic.set_target(target)
+            diagnostics.append(diagnostic)
+
+        return ValidationResult(diagnostics)
+
+    @staticmethod
+    def accepts() -> Sequence[Literal["dict"]]:
+        """Return the document formats this validator can accept.
+
+        Returns:
+            Sequence of supported document format identifiers:
+            - "dict": Python dictionary containing OpenAPI Document data
+        """
+        return ["dict"]
+
+    @staticmethod
+    def _is_openapi_v31(document: dict) -> bool:
+        if not isinstance(document, dict):
+            return False
+        openapi_version = document.get("openapi", "")
+        return isinstance(openapi_version, str) and openapi_version.startswith("3.1")
+
+    @staticmethod
+    def _is_openapi_v30(document: dict) -> bool:
+        if not isinstance(document, dict):
+            return False
+        openapi_version = document.get("openapi", "")
+        return isinstance(openapi_version, str) and openapi_version.startswith("3.0")

jentic/apitools/openapi/validator/core/__init__.py

@@ -0,0 +1,5 @@
+from .diagnostics import JenticDiagnostic, ValidationResult
+from .openapi_validator import OpenAPIValidator
+
+
+__all__ = ["ValidationResult", "JenticDiagnostic", "OpenAPIValidator"]

jentic/apitools/openapi/validator/core/diagnostics.py

@@ -0,0 +1,99 @@
+from dataclasses import dataclass, field
+
+from lsprotocol.types import Diagnostic
+
+
+__all__ = ["JenticDiagnostic", "ValidationResult"]
+
+
+class JenticDiagnostic(Diagnostic):
+    def __init__(self, **data):
+        super().__init__(**data)
+        if not hasattr(self, "data") or self.data is None:
+            self.data = {}
+        if "fixable" not in self.data:
+            self.data["fixable"] = True
+        if "path" not in self.data:
+            self.data["path"] = []
+        if "target" not in self.data:
+            self.data["target"] = ""
+
+    def set_fixable(self, fixable: bool = True):
+        if not hasattr(self, "data") or self.data is None:
+            self.data = {}
+        self.data["fixable"] = fixable
+
+    def set_path(self, path: list[str | int] | None):
+        if path is None:
+            return
+        if not hasattr(self, "data") or self.data is None:
+            self.data = {}
+        self.data["path"] = path
+
+    def set_target(self, target: str | None):
+        if target is None:
+            return
+        if not hasattr(self, "data") or self.data is None:
+            self.data = {}
+        self.data["target"] = target
+
+    def set_data_field(self, key: str, value: str | None):
+        if value is None:
+            return
+        if not hasattr(self, "data") or self.data is None:
+            self.data = {}
+        self.data[key] = value
+
+
+@dataclass
+class ValidationResult:
+    """
+    Represents the result of validating an OpenAPI document.
+
+    This class encapsulates all diagnostics (errors, warnings, etc.) produced
+    by validator backends and provides convenient methods to check validation
+    status and filter diagnostics by severity.
+
+    Attributes:
+        diagnostics: List of all diagnostics from validation
+        valid: True if no diagnostics were found, False otherwise (computed automatically)
+    """
+
+    diagnostics: list[JenticDiagnostic] = field(default_factory=list)
+    valid: bool = field(init=False)
+
+    def __post_init__(self):
+        """Compute the valid attribute after initialization."""
+        self.valid = len(self.diagnostics) == 0
+
+    def __bool__(self) -> bool:
+        """
+        Allow ValidationResult to be used in boolean context.
+
+        Returns:
+            True if validation passed (no diagnostics), False otherwise
+
+        Example:
+            >>> result = validator.validate(document)
+            >>> if result:
+            ...     print("Validation passed!")
+        """
+        return self.valid
+
+    def __len__(self) -> int:
+        """
+        Return the number of diagnostics.
+
+        Returns:
+            Count of all diagnostics
+
+        Example:
+            >>> result = validator.validate(document)
+            >>> print(f"Found {len(result)} issues")
+        """
+        return len(self.diagnostics)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the validation result."""
+        status = "valid" if self.valid else "invalid"
+        return f"ValidationResult(status={status}, diagnostics={len(self.diagnostics)})"

jentic/apitools/openapi/validator/core/openapi_validator.py

@@ -0,0 +1,191 @@
+import importlib.metadata
+import json
+import warnings
+from typing import Type
+
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.validator.backends.base import BaseValidatorBackend
+
+from .diagnostics import JenticDiagnostic, ValidationResult
+
+
+__all__ = ["OpenAPIValidator"]
+
+
+# Cache entry points at module level for performance
+try:
+    _VALIDATOR_BACKENDS = {
+        ep.name: ep
+        for ep in importlib.metadata.entry_points(
+            group="jentic.apitools.openapi.validator.backends"
+        )
+    }
+except Exception as e:
+    warnings.warn(f"Failed to load validator backend entry points: {e}", RuntimeWarning)
+    _VALIDATOR_BACKENDS = {}
+
+
+class OpenAPIValidator:
+    """
+    Validates OpenAPI documents using pluggable validator backends.
+
+    This class provides a flexible validation framework that can use multiple
+    validator backends simultaneously. Backends can be specified by name (via
+    entry points), as class instances, or as class types.
+
+    Attributes:
+        parser: OpenAPIParser instance for parsing and loading documents
+        backends: List of validator backend instances to use for validation
+    """
+
+    def __init__(
+        self,
+        backends: list[str | BaseValidatorBackend | Type[BaseValidatorBackend]] | None = None,
+        parser: OpenAPIParser | None = None,
+    ):
+        """
+        Initialize the OpenAPI validator.
+
+        Args:
+            backends: List of validator backends to use. Each item can be:
+                - str: Name of a backend registered via entry points (e.g., "default", "openapi-spec", "spectral")
+                - BaseValidatorBackend: Instance of a validator backend
+                - Type[BaseValidatorBackend]: Class of a validator backend (will be instantiated)
+                Defaults to ["default"] if None.
+            parser: Custom OpenAPIParser instance. If None, creates a default parser.
+
+        Raises:
+            ValueError: If a backend name is not found in registered entry points
+            TypeError: If a backend is not a valid type (str, instance, or class)
+        """
+        self.parser = parser if parser else OpenAPIParser()
+        self.backends: list[BaseValidatorBackend] = []
+        backends = ["default"] if not backends else backends
+
+        for backend in backends:
+            if isinstance(backend, str):
+                if backend in _VALIDATOR_BACKENDS:
+                    backend_class = _VALIDATOR_BACKENDS[backend].load()  # loads the class
+                    self.backends.append(backend_class())
+                else:
+                    raise ValueError(f"No validator backend named '{backend}' found")
+            elif isinstance(backend, BaseValidatorBackend):
+                self.backends.append(backend)
+            elif isinstance(backend, type) and issubclass(backend, BaseValidatorBackend):
+                # Class (not instance) is passed
+                self.backends.append(backend())
+            else:
+                raise TypeError("Invalid backend type: must be name or backend class/instance")
+
+    def validate(
+        self, document: str | dict, *, base_url: str | None = None, target: str | None = None
+    ) -> ValidationResult:
+        """
+        Validate an OpenAPI document using all configured backends.
+
+        This method accepts OpenAPI documents in multiple formats and automatically
+        converts them to the format(s) required by each backend. All diagnostics
+        from all backends are aggregated into a single ValidationResult.
+
+        Args:
+            document: OpenAPI document in one of the following formats:
+                - File URI (e.g., "file:///path/to/openapi.yaml")
+                - JSON/YAML string representation
+                - Python dictionary
+            base_url: Optional base URL for resolving relative references in the document
+            target: Optional target identifier for validation context
+
+        Returns:
+            ValidationResult containing aggregated diagnostics from all backends.
+            The result's `valid` property indicates if validation passed.
+
+        Raises:
+            TypeError: If document is not a str or dict
+        """
+
+        diagnostics: list[JenticDiagnostic] = []
+        document_is_uri: bool = False
+        document_text: str = ""
+        document_dict: dict | None = None
+
+        # Determine an input type and prepare different representations
+        if isinstance(document, str):
+            document_is_uri = self.parser.is_uri_like(document)
+
+            if document_is_uri:
+                # Load URI content if any backend needs non-URI format
+                document_text = (
+                    self.parser.load_uri(document) if self.has_non_uri_backend() else document
+                )
+                document_dict = (
+                    self.parser.parse(document_text) if self.has_non_uri_backend() else None
+                )
+            else:
+                # Plain text (JSON/YAML)
+                document_text = document
+                document_dict = self.parser.parse(document)
+        elif isinstance(document, dict):
+            document_is_uri = False
+            document_text = json.dumps(document)
+            document_dict = document
+        else:
+            raise TypeError(
+                f"Unsupported document type: {type(document).__name__!r}. "
+                f"Expected str (URI or JSON/YAML) or dict."
+            )
+
+        # Run validation through all backends
+        for backend in self.backends:
+            accepted = backend.accepts()
+            backend_document = None
+
+            # Determine which format to pass to this backend
+            if document_is_uri and "uri" in accepted:
+                backend_document = document
+            elif "dict" in accepted and document_dict is not None:
+                backend_document = document_dict
+            elif "text" in accepted:
+                backend_document = document_text
+
+            if backend_document is not None:
+                result = backend.validate(backend_document, base_url=base_url, target=target)
+                diagnostics.extend(result.diagnostics)
+
+        return ValidationResult(diagnostics=diagnostics)
+
+    def has_non_uri_backend(self) -> bool:
+        """
+        Check if any configured backend requires non-URI document format.
+
+        This helper method determines whether document content needs to be loaded
+        and parsed from a URI. If all backends accept URIs directly, the loading
+        step can be skipped for better performance.
+
+        Returns:
+            True if at least one backend accepts 'text' or 'dict' but not 'uri'.
+            False if all backends can handle URIs directly.
+        """
+        for backend in self.backends:
+            accepted = backend.accepts()
+            if ("text" in accepted or "dict" in accepted) and "uri" not in accepted:
+                return True
+        return False
+
+    @staticmethod
+    def list_backends() -> list[str]:
+        """
+        List all available validator backends registered via entry points.
+
+        This static method discovers and returns the names of all validator backends
+        that have been registered in the 'jentic.apitools.openapi.validator.backends'
+        entry point group.
+
+        Returns:
+            List of backend names that can be used when initializing OpenAPIValidator.
+
+        Example:
+            >>> backends = OpenAPIValidator.list_backends()
+            >>> print(backends)
+            ['default', 'spectral']
+        """
+        return list(_VALIDATOR_BACKENDS.keys())