feat: add discovery config and library validation

- Add `validate_discovery_config` and `validate_discovery_config_library`.
- Add `validation_error_details` to `DiscoveryConfig` and `usage_count` to
  `DiscoveryConfigLibrary`.
- Reject configs and libraries with no YAML content, with an error that says
  how to fix it.
- Ensure validating leaves nothing behind, even when it fails.
- Let pydantic parse the nested errors payload instead of a custom validator
- Add DataMasqueArgumentError

Author: ClassicMMT

HISTORY.rst

@@ -2,6 +2,16 @@
 History
 =======
 
+1.2.2 (unreleased)
+------------------
+
+* Added ``validation_error_details`` to ``DiscoveryConfig``.
+* Added ``usage_count`` to ``DiscoveryConfigLibrary``.
+* Added ``validate_discovery_config`` and ``validate_discovery_config_library``.
+* ``update_discovery_config``, ``validate_discovery_config``, and ``validate_discovery_config_library``
+* Now raise ``DataMasqueArgumentError`` when the passed entity has no ``yaml`` content,
+  instead of sending a request the server rejects.
+
 1.2.1 (2026-07-30)
 ------------------
 

datamasque/client/base.py

@@ -17,6 +17,7 @@
 
 from datamasque.client.exceptions import (
     DataMasqueApiError,
+    DataMasqueException,
     DataMasqueNotReadyError,
     DataMasqueTransportError,
 )
@@ -309,6 +310,12 @@ def _delete_if_exists(self, path: str, *, params: Optional[dict] = None) -> None
 
         self._raise_for_status(response)
 
+    def _delete_best_effort(self, delete: Callable[[], None], description: str) -> None:
+        try:
+            delete()
+        except DataMasqueException as e:
+            logger.warning("Failed to clean up %s; remove it manually. Error: %s", description, e)
+
     def _iter_paginated(
         self,
         path: str,

datamasque/client/discovery_config_libraries.py

@@ -1,8 +1,9 @@
 import logging
+import uuid
 from typing import Optional
 
 from datamasque.client.base import BaseClient
-from datamasque.client.exceptions import DataMasqueApiError
+from datamasque.client.exceptions import DataMasqueApiError, DataMasqueArgumentError
 from datamasque.client.models.discovery_config_library import DiscoveryConfigLibrary, DiscoveryConfigLibraryId
 
 logger = logging.getLogger(__name__)
@@ -76,15 +77,21 @@ def create_discovery_config_library(self, library: DiscoveryConfigLibrary) -> Di
         Creates a new discovery config library on the server.
 
         Sets the library's server-assigned fields
-        (`id`, `is_valid`, `validation_error`, `created`, `modified`) and returns the library.
+        (`id`, `is_valid`, `validation_error`, `usage_count`, `created`, `modified`) and returns the library.
         """
 
+        if not library.yaml:
+            raise DataMasqueArgumentError(
+                "Cannot create a discovery config library without YAML content (yaml is empty)"
+            )
+
         data = library.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = self.make_request("POST", "/api/discovery/config-libraries/", data=data)
         created = DiscoveryConfigLibrary.model_validate(response.json())
         library.id = created.id
         library.is_valid = created.is_valid
         library.validation_error = created.validation_error
+        library.usage_count = created.usage_count
         library.created = created.created
         library.modified = created.modified
         logger.info('Creation of discovery config library "%s" successful', library.name)
@@ -99,11 +106,13 @@ def update_discovery_config_library(self, library: DiscoveryConfigLibrary) -> Di
         """
 
         if library.id is None:
-            raise ValueError("Cannot update a discovery config library that has not been created yet (id is None)")
+            raise DataMasqueArgumentError(
+                "Cannot update a discovery config library that has not been created yet (id is None)"
+            )
 
-        if library.yaml is None:
-            raise ValueError(
-                "Cannot update a discovery config library without YAML content (yaml is None); "
+        if not library.yaml:
+            raise DataMasqueArgumentError(
+                "Cannot update a discovery config library without YAML content (yaml is empty or unset); "
                 "list results omit YAML, so fetch the full library with `get_discovery_config_library` first"
             )
 
@@ -112,6 +121,7 @@ def update_discovery_config_library(self, library: DiscoveryConfigLibrary) -> Di
         updated = DiscoveryConfigLibrary.model_validate(response.json())
         library.is_valid = updated.is_valid
         library.validation_error = updated.validation_error
+        library.usage_count = updated.usage_count
         library.modified = updated.modified
         logger.debug('Update of discovery config library "%s" successful', library.name)
         return library
@@ -130,6 +140,41 @@ def create_or_update_discovery_config_library(self, library: DiscoveryConfigLibr
 
         return self.create_discovery_config_library(library)
 
+    def validate_discovery_config_library(self, library: DiscoveryConfigLibrary) -> DiscoveryConfigLibrary:
+        """Validates a discovery config library against the server without persisting it."""
+
+        if not library.yaml:
+            raise DataMasqueArgumentError(
+                "Cannot validate a discovery config library without YAML content (yaml is empty or unset); "
+                "list results omit YAML, so fetch the full library with `get_discovery_config_library` first"
+            )
+
+        temporary = DiscoveryConfigLibrary(
+            name=f"dm_python_validate_{uuid.uuid4().hex}",
+            namespace=library.namespace,
+            yaml=library.yaml,
+        )
+        data = temporary.model_dump(exclude_none=True, by_alias=True, mode="json")
+        response = self.make_request("POST", "/api/discovery/config-libraries/", data=data)
+
+        payload = response.json()
+        raw_id = payload.get("id") if isinstance(payload, dict) else None
+        created_id = DiscoveryConfigLibraryId(raw_id) if isinstance(raw_id, str) else None
+
+        try:
+            created = DiscoveryConfigLibrary.model_validate(payload)
+            library.is_valid = created.is_valid
+            library.validation_error = created.validation_error
+        finally:
+            if created_id is not None:
+                self._delete_best_effort(
+                    lambda: self.delete_discovery_config_library_by_id_if_exists(created_id),
+                    f'temporary validation library "{temporary.name}"',
+                )
+
+        logger.debug('Validation of discovery config library "%s" complete', library.name)
+        return library
+
     def delete_discovery_config_library_by_id_if_exists(
         self, library_id: DiscoveryConfigLibraryId, *, force: bool = False
     ) -> None:

datamasque/client/discovery_configs.py

@@ -1,8 +1,9 @@
 import logging
+import uuid
 from typing import Iterator, Optional
 
 from datamasque.client.base import BaseClient
-from datamasque.client.exceptions import DataMasqueApiError, DataMasqueException
+from datamasque.client.exceptions import DataMasqueApiError, DataMasqueArgumentError, DataMasqueException
 from datamasque.client.models.discovery_config import DiscoveryConfig, DiscoveryConfigId, DiscoveryConfigType
 from datamasque.client.models.pagination import Page
 
@@ -75,15 +76,20 @@ def create_discovery_config(self, config: DiscoveryConfig) -> DiscoveryConfig:
         Creates a new discovery config on the server.
 
         Sets the config's server-assigned fields
-        (`id`, `is_valid`, `validation_error`, `created`, `modified`) and returns the config.
+        (`id`, `is_valid`, `validation_error`, `validation_error_details`, `created`, `modified`)
+        and returns the config.
         """
 
+        if not config.yaml:
+            raise DataMasqueArgumentError("Cannot create a discovery config without YAML content (yaml is empty)")
+
         data = config.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = self.make_request("POST", "/api/discovery/configs/", data=data)
         created = DiscoveryConfig.model_validate(response.json())
         config.id = created.id
         config.is_valid = created.is_valid
         config.validation_error = created.validation_error
+        config.validation_error_details = created.validation_error_details
         config.created = created.created
         config.modified = created.modified
         logger.info('Creation of discovery config "%s" successful', config.name)
@@ -94,17 +100,24 @@ def update_discovery_config(self, config: DiscoveryConfig) -> DiscoveryConfig:
         Performs a full update of the discovery config.
 
         The config must have its `id` set
-        (i.e., it must have been previously created or retrieved from the server).
+        and its `yaml` content present.
         """
 
         if config.id is None:
-            raise ValueError("Cannot update a discovery config that has not been created yet (id is None)")
+            raise DataMasqueArgumentError("Cannot update a discovery config that has not been created yet (id is None)")
+
+        if not config.yaml:
+            raise DataMasqueArgumentError(
+                "Cannot update a discovery config without YAML content (yaml is empty or unset); "
+                "list results omit YAML, so fetch the full config with `get_discovery_config` first"
+            )
 
         data = config.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = self.make_request("PUT", f"/api/discovery/configs/{config.id}/", data=data)
         updated = DiscoveryConfig.model_validate(response.json())
         config.is_valid = updated.is_valid
         config.validation_error = updated.validation_error
+        config.validation_error_details = updated.validation_error_details
         config.modified = updated.modified
         logger.debug('Update of discovery config "%s" successful', config.name)
         return config
@@ -123,6 +136,42 @@ def create_or_update_discovery_config(self, config: DiscoveryConfig) -> Discover
 
         return self.create_discovery_config(config)
 
+    def validate_discovery_config(self, config: DiscoveryConfig) -> DiscoveryConfig:
+        """Validates a discovery config against the server."""
+
+        if not config.yaml:
+            raise DataMasqueArgumentError(
+                "Cannot validate a discovery config without YAML content (yaml is empty or unset); "
+                "list results omit YAML, so fetch the full config with `get_discovery_config` first"
+            )
+
+        temporary = DiscoveryConfig(
+            name=f"dm_python_validate_{uuid.uuid4().hex}",
+            yaml=config.yaml,
+            config_type=config.config_type,
+        )
+        data = temporary.model_dump(exclude_none=True, by_alias=True, mode="json")
+        response = self.make_request("POST", "/api/discovery/configs/", data=data)
+
+        payload = response.json()
+        raw_id = payload.get("id") if isinstance(payload, dict) else None
+        created_id = DiscoveryConfigId(raw_id) if isinstance(raw_id, str) else None
+
+        try:
+            created = DiscoveryConfig.model_validate(payload)
+            config.is_valid = created.is_valid
+            config.validation_error = created.validation_error
+            config.validation_error_details = created.validation_error_details
+        finally:
+            if created_id is not None:
+                self._delete_best_effort(
+                    lambda: self.delete_discovery_config_by_id_if_exists(created_id),
+                    f'temporary validation config "{temporary.name}"',
+                )
+
+        logger.debug('Validation of discovery config "%s" complete', config.name)
+        return config
+
     def delete_discovery_config_by_id_if_exists(self, config_id: DiscoveryConfigId) -> None:
         """
         Deletes the discovery config with the given ID.

datamasque/client/exceptions.py

@@ -9,6 +9,16 @@ class DataMasqueUserError(DataMasqueException):
     """Raised when error occurs during user creation or configuration."""
 
 
+class DataMasqueArgumentError(DataMasqueException):
+    """
+    Raised when a client method is given an object it cannot act on.
+
+    Covers arguments the client rejects without contacting the server, such as
+    updating a record that has no `id` yet, or sending a config whose `yaml` is
+    empty.
+    """
+
+
 class DataMasqueApiError(DataMasqueException):
     """
     Raised when the DataMasque server responds to a request with a non-2xx status code.

datamasque/client/models/discovery_config.py

@@ -2,9 +2,9 @@
 from datetime import datetime
 from typing import Any, NewType, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, AliasPath, BaseModel, ConfigDict, Field
 
-from datamasque.client.models.status import ValidationStatus
+from datamasque.client.models.status import ValidationErrorDetails, ValidationStatus
 
 DiscoveryConfigId = NewType("DiscoveryConfigId", str)
 
@@ -49,5 +49,14 @@ class DiscoveryConfig(BaseModel):
     """Validation status; may be `in_progress` briefly after creating a large config."""
     validation_error: Optional[str] = Field(default=None, exclude=True)
     """Human-readable validation error, or `None` when valid."""
+    # Deliberately not `validation_errors`:
+    # this is a different shape to `Ruleset.validation_errors`,
+    # and would sit one character from `validation_error` above.
+    validation_error_details: list[ValidationErrorDetails] = Field(
+        default_factory=list,
+        exclude=True,
+        validation_alias=AliasChoices(AliasPath("errors", "config_yaml"), "validation_error_details"),
+    )
+    """Structured, positional validation errors."""
     created: Optional[datetime] = Field(default=None, exclude=True)
     modified: Optional[datetime] = Field(default=None, exclude=True)

datamasque/client/models/discovery_config_library.py

@@ -27,5 +27,7 @@ class DiscoveryConfigLibrary(BaseModel):
     """Validation status; libraries are validated synchronously on create/update."""
     validation_error: Optional[str] = Field(default=None, exclude=True)
     """Human-readable validation error, or `None` when valid."""
+    usage_count: Optional[int] = Field(default=None, exclude=True)
+    """Number of active discovery configs that import this library."""
     created: Optional[datetime] = Field(default=None, exclude=True)
     modified: Optional[datetime] = Field(default=None, exclude=True)