fastapi-errors-plus 0.7.0__tar.gz → 0.9.0__tar.gz

{fastapi_errors_plus-0.7.0 → fastapi_errors_plus-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.7.0
+Version: 0.9.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -22,6 +22,9 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
 # fastapi-errors-plus
@@ -30,7 +33,7 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-101-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-138-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 [![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
@@ -105,13 +108,13 @@ Use boolean flags for common HTTP status codes:
 - `validation_error_422=True` → 422 Unprocessable Entity (defaults to `True`)
 - `internal_server_error_500=True` → 500 Internal Server Error
 
-**Legacy (for backward compatibility):**
+**Legacy (deprecated in 0.9, removal in 1.0):**
 - `unauthorized=True` → 401 Unauthorized
 - `forbidden=True` → 403 Forbidden
-- `validation_error=True` → 422 Unprocessable Entity (defaults to `True`)
+- `validation_error=True` → 422 Unprocessable Entity
 - `internal_server_error=True` → 500 Internal Server Error
 
-**Note:** `validation_error` and `validation_error_422` default to `True` because FastAPI automatically validates all parameters (Path, Query, Body), making 422 relevant in 95%+ of endpoints. Set to `False` only for endpoints without parameters.
+**Note on 422:** If you omit both `validation_error` and `validation_error_422`, the library still adds **422** today but emits a **`DeprecationWarning`** — the default will become **`False` in 1.0**. For ADR-style APIs, set `validation_error_422=False` explicitly (or use **`ErrorProfile`** below).
 
 ```python
 @router.get(
@@ -164,7 +167,7 @@ class MyErrorDTO:
     status_code = 404
     message = "Not found"
     
-    def to_example(self):
+    def to_examples(self):
         return {
             "Not found": {
                 "value": {"detail": "Not found"},
@@ -209,7 +212,7 @@ def delete_item(id: int):
 
 #### OpenAPI extras (`schema`) next to examples
 
-ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_example()`** still defines examples):
+ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** / **`ErrorDoc`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_examples()`** still defines examples):
 
 ```python
 from fastapi import APIRouter, status
@@ -284,6 +287,75 @@ def delete_item(id: int):
 - Reusable across all endpoints
 - Supports inheritance for custom logic
 
+`examples` values may be **strings** (shorthand for `{"detail": text}`) or full OpenAPI Example Objects with **`summary`** and **`value`**.
+
+#### ErrorDoc
+
+For arbitrary response bodies (ADR `code` / `detail` / `context`, not only `detail` strings), use **`ErrorDoc`**:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+permission_denied = ErrorDoc(
+    status_code=403,
+    message="Insufficient permissions",
+    examples={
+        "MissingRole": {
+            "summary": "User lacks required role",
+            "value": {
+                "code": "FORBIDDEN",
+                "detail": "Role admin required",
+            },
+        },
+    },
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+@router.delete("/{id}", responses=Errors(permission_denied))
+def delete_item(id: int):
+    ...
+```
+
+A **plain dict** as an example value is treated as the full response **body** unless it looks like an OpenAPI Example Object (keys only among `value`, `summary`, `description`, `externalValue`).
+
+Optional **`model=`** (Pydantic model on the outer response object for FastAPI `$ref` registration) and **`schema=`** (JSON Schema under `application/json`) avoid a separate status `dict` for typed error bodies:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+conflict = ErrorDoc(
+    status_code=409,
+    message="BusinessRule",
+    model=ApplicationJsonError,  # optional Pydantic model
+    schema=ADR_ERROR_BODY_SCHEMA,  # or raw JSON Schema
+    body={"code": "RULE_VIOLATION", "detail": "Item exists"},
+)
+
+@router.post("/items", responses=Errors(conflict, validation_error_422=False))
+def create_item():
+    ...
+```
+
+#### ErrorProfile
+
+Project-wide defaults (frozen — not mutated by endpoint calls):
+
+```python
+from fastapi_errors_plus import ErrorDoc, ErrorProfile, Errors
+
+ADR = ErrorProfile(
+    validation_error_422=False,
+    unauthorized_401=True,
+    internal_server_error_500=True,
+)
+
+@router.post("/items", responses=Errors(business_conflict, profile=ADR))
+def create_item():
+    ...
+```
+
+Explicit `Errors` keyword flags override profile values. Positional dict/DTO errors are merged after profile-driven standard statuses.
+
 ### 5. Mixed Usage
 
 Combine flags, dict, and ErrorDTO:
@@ -363,7 +435,7 @@ Order matters only for overlaps: whichever **`dict`** is applied **later** in th
 
 ## ErrorDTO Protocol
 
-The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
+The canonical **`ErrorDTO`** protocol defines the interface for error objects compatible with the library:
 
 ```python
 from typing import Protocol, Dict, Any
@@ -372,27 +444,30 @@ class ErrorDTO(Protocol):
     status_code: int
     message: str
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI.
-        
-        Returns:
-            Dict in format: {"key": {"value": {"detail": "message"}}}
-        """
+    def to_examples(self) -> Dict[str, Any]:
+        """OpenAPI ``examples`` map: {"Key": {"value": {...}, "summary": "..."}}."""
         ...
 ```
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**Legacy migration:** classes that only define **`to_example()`** still work at **runtime** (`DeprecationWarning` once per class per `Errors()` call). For static typing use **`LegacyErrorDTO`** or the union alias **`ErrorDTOLike`** (`ErrorDTO | LegacyErrorDTO`).
+
 **Best Practice:** For maximum clarity, consider making your domain exceptions implement the ErrorDTO protocol directly. See [Best Practice: Connecting Exceptions and ErrorDTO](#best-practice-connecting-exceptions-and-errordto) for details.
 
 ### When to Use Protocol vs BaseErrorDTO
 
+Optional on custom DTOs (OpenAPI media-type extras without duplicating a status `dict`):
+
+- attribute **`openapi_json_extras`**: fragment for **`content["application/json"]`** (often `{"schema": ...}` — not for `example` / `examples`);
+- or method **`to_openapi_json_media_type_extras() -> Optional[dict]`** — when non-empty, overrides **`openapi_json_extras`**.
+
 **Use Protocol (structural typing)** when:
 - Your project already has error DTOs that implement the protocol
 - You need maximum flexibility and custom implementations
 - You want to keep your existing error infrastructure
 
-**Use BaseErrorDTO/StandardErrorDTO** when:
+**Use BaseErrorDTO/StandardErrorDTO/ErrorDoc** when:
 - Starting a new project or adding error documentation
 - You want a ready-to-use implementation without boilerplate
 - You need multiple examples for standard HTTP errors (401, 403, etc.)
@@ -403,7 +478,7 @@ Both approaches work together — you can mix them in the same `Errors()` call!
 
 **Note:** Pydantic is **not required** to use this library. This section is for projects that already use Pydantic and want to integrate it with the ErrorDTO protocol.
 
-Since the library uses structural typing (Protocol), any class that implements the required attributes (`status_code`, `message`, `to_example()`) will work, including Pydantic models.
+Since the library uses structural typing (Protocol), any class that implements the required attributes (`status_code`, `message`, `to_examples()`) will work, including Pydantic models. Legacy `to_example()` is still accepted at runtime.
 
 ### Simple Pydantic Model as ErrorDTO
 
@@ -417,8 +492,8 @@ class PydanticErrorDTO(BaseModel):
     status_code: int = Field(..., ge=400, le=599, description="HTTP status code")
     message: str = Field(..., min_length=1, description="Error message")
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate examples for OpenAPI."""
         return {
             self.message: {
                 "value": {"detail": self.message},
@@ -461,8 +536,8 @@ class DetailedErrorDTO(BaseModel):
     error_code: Optional[str] = Field(None, description="Internal error code")
     timestamp: Optional[str] = Field(None, description="Error timestamp")
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate examples for OpenAPI."""
         example = {"detail": self.message}
         if self.error_code:
             example["error_code"] = self.error_code
@@ -519,7 +594,7 @@ class DomainException(Exception):
     status_code: int
     message: str
     
-    def to_example(self) -> Dict[str, Any]:
+    def to_examples(self) -> Dict[str, Any]:
         return {self.message: {"value": {"detail": self.message}}}
     
     @classmethod
@@ -562,7 +637,7 @@ See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete
 
 ## Compatibility with Existing Projects
 
-If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol:
+If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol (or legacy `to_example()` during migration):
 
 ```python
 # Your existing ApiErrorDTO
@@ -571,7 +646,7 @@ class ApiErrorDTO:
     status_code: int
     message: str
     
-    def to_example(self) -> dict:
+    def to_examples(self) -> dict:
         return {
             self.message: {
                 "value": {"detail": self.message},
@@ -608,6 +683,7 @@ Errors(
     forbidden_403: bool = False,
     validation_error_422: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error_500: bool = False,
+    profile: Optional[ErrorProfile] = None,
 )
 ```
 
@@ -626,10 +702,12 @@ Errors(
   - `None` (default): Add 422 (True by default, FastAPI validates all parameters)
   - `False`: Explicitly disable 422
   - `True`: Explicitly enable 422
-- `internal_server_error`: Add 500 Internal Server Error (legacy, for backward compatibility). Defaults to `False`.
+- `internal_server_error`: Add 500 Internal Server Error (legacy, **deprecated** in 0.9). Defaults to `False`.
+- `profile`: Optional **`ErrorProfile`** — project defaults; explicit kwargs override profile.
+
+**Deprecation (0.9+):** legacy kwargs above emit `DeprecationWarning` (removal in **1.0**). Omitting both `validation_error` and `validation_error_422` still adds 422 but warns; default becomes **`False` in 1.0**.
 
-**Why `validation_error=True` by default?**
-FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant in 95%+ of endpoints. For endpoints without parameters, explicitly set `validation_error=False` or `validation_error_422=False`.
+**422 behaviour:** pass `validation_error_422=False` for endpoints without request-body validation or ADR-style error bodies. Use **`ErrorProfile`** to set this once per project.
 
 **Returns:**
 - A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
@@ -640,9 +718,13 @@ FastAPI automatically validates all parameters (Path, Query, Body), so 422 is re
 ```python
 # Instances are Mapping keyed by HTTP status codes
 error_responses = Errors(unauthorized_401=True, forbidden_403=True)
-documented = error_responses[401]  # response block picked up by OpenAPI
+documented = error_responses[401]  # deep copy — safe to read, won't mutate internal state
 ```
 
+**Isolation (0.8+):** incoming response **dicts** are **deep-copied** on ingest; **`errors[status]`** returns a **deep copy** so callers cannot corrupt shared registry templates or internal merge state.
+
+**Descriptions:** response blocks with only **`model`** (no `description`) get a default from **`HTTPStatus.phrase`** so OpenAPI generation does not fail.
+
 ### `ErrorDTO`
 
 Protocol for error objects compatible with the library.
@@ -652,9 +734,47 @@ Protocol for error objects compatible with the library.
 - `message: str` — Error message description
 
 **Required methods:**
-- `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
+- `to_examples() -> Dict[str, Any]` — OpenAPI `examples` map for `application/json`
+
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable **`to_examples()`** / **`to_example()`** raise **`TypeError`** naming what was missing.
+
+### `LegacyErrorDTO` / `ErrorDTOLike`
 
-During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+- **`LegacyErrorDTO`** — typing helper for classes that only implement deprecated **`to_example()`**.
+- **`ErrorDTOLike`** — `Union[ErrorDTO, LegacyErrorDTO]` for transitional annotations.
+
+### `ErrorDoc`
+
+Declarative DTO for arbitrary example bodies and per-example **`summary`**.
+
+**Constructor:**
+```python
+ErrorDoc(
+    status_code: int,
+    message: str,
+    examples: Optional[Dict[str, str | dict]] = None,
+    body: Optional[Dict[str, Any]] = None,
+    example_key: Optional[str] = None,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
+)
+```
+
+When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
+
+### `ErrorProfile`
+
+Frozen project-wide defaults for standard HTTP flags.
+
+```python
+ErrorProfile(
+    unauthorized_401: bool = False,
+    forbidden_403: bool = False,
+    validation_error_422: Optional[bool] = None,
+    internal_server_error_500: bool = False,
+)
+```
 
 ### `BaseErrorDTO`
 
@@ -665,6 +785,8 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
@@ -793,7 +915,7 @@ class DomainException(Exception):
     def __init__(self) -> None:
         super().__init__(self.message)
 
-    def to_example(self) -> Dict[str, Any]:
+    def to_examples(self) -> Dict[str, Any]:
         return {
             self.message: {
                 "value": {"detail": self.message},

{fastapi_errors_plus-0.7.0 → fastapi_errors_plus-0.9.0}/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-101-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-138-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 [![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
@@ -79,13 +79,13 @@ Use boolean flags for common HTTP status codes:
 - `validation_error_422=True` → 422 Unprocessable Entity (defaults to `True`)
 - `internal_server_error_500=True` → 500 Internal Server Error
 
-**Legacy (for backward compatibility):**
+**Legacy (deprecated in 0.9, removal in 1.0):**
 - `unauthorized=True` → 401 Unauthorized
 - `forbidden=True` → 403 Forbidden
-- `validation_error=True` → 422 Unprocessable Entity (defaults to `True`)
+- `validation_error=True` → 422 Unprocessable Entity
 - `internal_server_error=True` → 500 Internal Server Error
 
-**Note:** `validation_error` and `validation_error_422` default to `True` because FastAPI automatically validates all parameters (Path, Query, Body), making 422 relevant in 95%+ of endpoints. Set to `False` only for endpoints without parameters.
+**Note on 422:** If you omit both `validation_error` and `validation_error_422`, the library still adds **422** today but emits a **`DeprecationWarning`** — the default will become **`False` in 1.0**. For ADR-style APIs, set `validation_error_422=False` explicitly (or use **`ErrorProfile`** below).
 
 ```python
 @router.get(
@@ -138,7 +138,7 @@ class MyErrorDTO:
     status_code = 404
     message = "Not found"
     
-    def to_example(self):
+    def to_examples(self):
         return {
             "Not found": {
                 "value": {"detail": "Not found"},
@@ -183,7 +183,7 @@ def delete_item(id: int):
 
 #### OpenAPI extras (`schema`) next to examples
 
-ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_example()`** still defines examples):
+ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** / **`ErrorDoc`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_examples()`** still defines examples):
 
 ```python
 from fastapi import APIRouter, status
@@ -258,6 +258,75 @@ def delete_item(id: int):
 - Reusable across all endpoints
 - Supports inheritance for custom logic
 
+`examples` values may be **strings** (shorthand for `{"detail": text}`) or full OpenAPI Example Objects with **`summary`** and **`value`**.
+
+#### ErrorDoc
+
+For arbitrary response bodies (ADR `code` / `detail` / `context`, not only `detail` strings), use **`ErrorDoc`**:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+permission_denied = ErrorDoc(
+    status_code=403,
+    message="Insufficient permissions",
+    examples={
+        "MissingRole": {
+            "summary": "User lacks required role",
+            "value": {
+                "code": "FORBIDDEN",
+                "detail": "Role admin required",
+            },
+        },
+    },
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+@router.delete("/{id}", responses=Errors(permission_denied))
+def delete_item(id: int):
+    ...
+```
+
+A **plain dict** as an example value is treated as the full response **body** unless it looks like an OpenAPI Example Object (keys only among `value`, `summary`, `description`, `externalValue`).
+
+Optional **`model=`** (Pydantic model on the outer response object for FastAPI `$ref` registration) and **`schema=`** (JSON Schema under `application/json`) avoid a separate status `dict` for typed error bodies:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+conflict = ErrorDoc(
+    status_code=409,
+    message="BusinessRule",
+    model=ApplicationJsonError,  # optional Pydantic model
+    schema=ADR_ERROR_BODY_SCHEMA,  # or raw JSON Schema
+    body={"code": "RULE_VIOLATION", "detail": "Item exists"},
+)
+
+@router.post("/items", responses=Errors(conflict, validation_error_422=False))
+def create_item():
+    ...
+```
+
+#### ErrorProfile
+
+Project-wide defaults (frozen — not mutated by endpoint calls):
+
+```python
+from fastapi_errors_plus import ErrorDoc, ErrorProfile, Errors
+
+ADR = ErrorProfile(
+    validation_error_422=False,
+    unauthorized_401=True,
+    internal_server_error_500=True,
+)
+
+@router.post("/items", responses=Errors(business_conflict, profile=ADR))
+def create_item():
+    ...
+```
+
+Explicit `Errors` keyword flags override profile values. Positional dict/DTO errors are merged after profile-driven standard statuses.
+
 ### 5. Mixed Usage
 
 Combine flags, dict, and ErrorDTO:
@@ -337,7 +406,7 @@ Order matters only for overlaps: whichever **`dict`** is applied **later** in th
 
 ## ErrorDTO Protocol
 
-The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
+The canonical **`ErrorDTO`** protocol defines the interface for error objects compatible with the library:
 
 ```python
 from typing import Protocol, Dict, Any
@@ -346,27 +415,30 @@ class ErrorDTO(Protocol):
     status_code: int
     message: str
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI.
-        
-        Returns:
-            Dict in format: {"key": {"value": {"detail": "message"}}}
-        """
+    def to_examples(self) -> Dict[str, Any]:
+        """OpenAPI ``examples`` map: {"Key": {"value": {...}, "summary": "..."}}."""
         ...
 ```
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**Legacy migration:** classes that only define **`to_example()`** still work at **runtime** (`DeprecationWarning` once per class per `Errors()` call). For static typing use **`LegacyErrorDTO`** or the union alias **`ErrorDTOLike`** (`ErrorDTO | LegacyErrorDTO`).
+
 **Best Practice:** For maximum clarity, consider making your domain exceptions implement the ErrorDTO protocol directly. See [Best Practice: Connecting Exceptions and ErrorDTO](#best-practice-connecting-exceptions-and-errordto) for details.
 
 ### When to Use Protocol vs BaseErrorDTO
 
+Optional on custom DTOs (OpenAPI media-type extras without duplicating a status `dict`):
+
+- attribute **`openapi_json_extras`**: fragment for **`content["application/json"]`** (often `{"schema": ...}` — not for `example` / `examples`);
+- or method **`to_openapi_json_media_type_extras() -> Optional[dict]`** — when non-empty, overrides **`openapi_json_extras`**.
+
 **Use Protocol (structural typing)** when:
 - Your project already has error DTOs that implement the protocol
 - You need maximum flexibility and custom implementations
 - You want to keep your existing error infrastructure
 
-**Use BaseErrorDTO/StandardErrorDTO** when:
+**Use BaseErrorDTO/StandardErrorDTO/ErrorDoc** when:
 - Starting a new project or adding error documentation
 - You want a ready-to-use implementation without boilerplate
 - You need multiple examples for standard HTTP errors (401, 403, etc.)
@@ -377,7 +449,7 @@ Both approaches work together — you can mix them in the same `Errors()` call!
 
 **Note:** Pydantic is **not required** to use this library. This section is for projects that already use Pydantic and want to integrate it with the ErrorDTO protocol.
 
-Since the library uses structural typing (Protocol), any class that implements the required attributes (`status_code`, `message`, `to_example()`) will work, including Pydantic models.
+Since the library uses structural typing (Protocol), any class that implements the required attributes (`status_code`, `message`, `to_examples()`) will work, including Pydantic models. Legacy `to_example()` is still accepted at runtime.
 
 ### Simple Pydantic Model as ErrorDTO
 
@@ -391,8 +463,8 @@ class PydanticErrorDTO(BaseModel):
     status_code: int = Field(..., ge=400, le=599, description="HTTP status code")
     message: str = Field(..., min_length=1, description="Error message")
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate examples for OpenAPI."""
         return {
             self.message: {
                 "value": {"detail": self.message},
@@ -435,8 +507,8 @@ class DetailedErrorDTO(BaseModel):
     error_code: Optional[str] = Field(None, description="Internal error code")
     timestamp: Optional[str] = Field(None, description="Error timestamp")
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate examples for OpenAPI."""
         example = {"detail": self.message}
         if self.error_code:
             example["error_code"] = self.error_code
@@ -493,7 +565,7 @@ class DomainException(Exception):
     status_code: int
     message: str
     
-    def to_example(self) -> Dict[str, Any]:
+    def to_examples(self) -> Dict[str, Any]:
         return {self.message: {"value": {"detail": self.message}}}
     
     @classmethod
@@ -536,7 +608,7 @@ See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete
 
 ## Compatibility with Existing Projects
 
-If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol:
+If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol (or legacy `to_example()` during migration):
 
 ```python
 # Your existing ApiErrorDTO
@@ -545,7 +617,7 @@ class ApiErrorDTO:
     status_code: int
     message: str
     
-    def to_example(self) -> dict:
+    def to_examples(self) -> dict:
         return {
             self.message: {
                 "value": {"detail": self.message},
@@ -582,6 +654,7 @@ Errors(
     forbidden_403: bool = False,
     validation_error_422: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error_500: bool = False,
+    profile: Optional[ErrorProfile] = None,
 )
 ```
 
@@ -600,10 +673,12 @@ Errors(
   - `None` (default): Add 422 (True by default, FastAPI validates all parameters)
   - `False`: Explicitly disable 422
   - `True`: Explicitly enable 422
-- `internal_server_error`: Add 500 Internal Server Error (legacy, for backward compatibility). Defaults to `False`.
+- `internal_server_error`: Add 500 Internal Server Error (legacy, **deprecated** in 0.9). Defaults to `False`.
+- `profile`: Optional **`ErrorProfile`** — project defaults; explicit kwargs override profile.
+
+**Deprecation (0.9+):** legacy kwargs above emit `DeprecationWarning` (removal in **1.0**). Omitting both `validation_error` and `validation_error_422` still adds 422 but warns; default becomes **`False` in 1.0**.
 
-**Why `validation_error=True` by default?**
-FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant in 95%+ of endpoints. For endpoints without parameters, explicitly set `validation_error=False` or `validation_error_422=False`.
+**422 behaviour:** pass `validation_error_422=False` for endpoints without request-body validation or ADR-style error bodies. Use **`ErrorProfile`** to set this once per project.
 
 **Returns:**
 - A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
@@ -614,9 +689,13 @@ FastAPI automatically validates all parameters (Path, Query, Body), so 422 is re
 ```python
 # Instances are Mapping keyed by HTTP status codes
 error_responses = Errors(unauthorized_401=True, forbidden_403=True)
-documented = error_responses[401]  # response block picked up by OpenAPI
+documented = error_responses[401]  # deep copy — safe to read, won't mutate internal state
 ```
 
+**Isolation (0.8+):** incoming response **dicts** are **deep-copied** on ingest; **`errors[status]`** returns a **deep copy** so callers cannot corrupt shared registry templates or internal merge state.
+
+**Descriptions:** response blocks with only **`model`** (no `description`) get a default from **`HTTPStatus.phrase`** so OpenAPI generation does not fail.
+
 ### `ErrorDTO`
 
 Protocol for error objects compatible with the library.
@@ -626,9 +705,47 @@ Protocol for error objects compatible with the library.
 - `message: str` — Error message description
 
 **Required methods:**
-- `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
+- `to_examples() -> Dict[str, Any]` — OpenAPI `examples` map for `application/json`
+
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable **`to_examples()`** / **`to_example()`** raise **`TypeError`** naming what was missing.
+
+### `LegacyErrorDTO` / `ErrorDTOLike`
 
-During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+- **`LegacyErrorDTO`** — typing helper for classes that only implement deprecated **`to_example()`**.
+- **`ErrorDTOLike`** — `Union[ErrorDTO, LegacyErrorDTO]` for transitional annotations.
+
+### `ErrorDoc`
+
+Declarative DTO for arbitrary example bodies and per-example **`summary`**.
+
+**Constructor:**
+```python
+ErrorDoc(
+    status_code: int,
+    message: str,
+    examples: Optional[Dict[str, str | dict]] = None,
+    body: Optional[Dict[str, Any]] = None,
+    example_key: Optional[str] = None,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
+)
+```
+
+When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
+
+### `ErrorProfile`
+
+Frozen project-wide defaults for standard HTTP flags.
+
+```python
+ErrorProfile(
+    unauthorized_401: bool = False,
+    forbidden_403: bool = False,
+    validation_error_422: Optional[bool] = None,
+    internal_server_error_500: bool = False,
+)
+```
 
 ### `BaseErrorDTO`
 
@@ -639,6 +756,8 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
@@ -767,7 +886,7 @@ class DomainException(Exception):
     def __init__(self) -> None:
         super().__init__(self.message)
 
-    def to_example(self) -> Dict[str, Any]:
+    def to_examples(self) -> Dict[str, Any]:
         return {
             self.message: {
                 "value": {"detail": self.message},