refactor(api)!: migrate API errors to RFC 7807 ProblemDetail

.github/workflows/basic_code_checks.yml

@@ -213,7 +213,7 @@ jobs:
           SPRING_JPA_DATABASE_PLATFORM: 'org.hibernate.dialect.H2Dialect'
           SPRING_FLYWAY_ENABLED: 'false'
           SPRING_JPA_HIBERNATE_DDL_AUTO: 'none'
-          SPRING_DATASOURCE_URL: 'jdbc:h2:mem'
+          SPRING_DATASOURCE_URL: 'jdbc:h2:mem:idp_core;DB_CLOSE_DELAY=-1'
           SPRING_DATASOURCE_DRIVER_CLASS_NAME: 'org.h2.Driver'
         run: |
           mkdir -p specs

.mvn/wrapper/maven-wrapper.properties

@@ -1,2 +1,5 @@
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
-wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.3.2/maven-wrapper-3.3.2.jar
+wrapperVersion=3.3.4
+distributionType=bin
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.10.0/apache-maven-3.10.0-bin.zip
+distributionSha256Sum=1f6d9909266510f039f59aa0e13dcd2c66da85f043e56276e41f2918f8bddaff
+wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.3.4/maven-wrapper-3.3.4.jar

docs/src/contributing/code/exception-handling.md

@@ -6,28 +6,52 @@ description: Global exception handling strategy and error response formats for I
 ## Strategy
 
 1. **Domain**: Throw specific business exceptions, for example `EntityTemplateNotFoundException`.
-2. **Infrastructure**: Catch exceptions in `ApiExceptionHandler` with `@ControllerAdvice` annotation.
-3. **API**: Return consistent JSON error responses.
+2. **Infrastructure**: Catch exceptions in `ApiExceptionHandler` with `@RestControllerAdvice`.
+3. **API**: Return RFC 7807 `ProblemDetail` responses with legacy extension fields.
 
 ## Exception Mapping
 
-| Exception Type                         | HTTP Status        | Description          |
-| -------------------------------------- | ------------------ | -------------------- |
-| `EntityTemplateNotFoundException`      | 404 Not Found      | Entity not found     |
-| `EntityTemplateAlreadyExistsException` | 409 Conflict       | Duplicate identifier |
-| `ConstraintViolationException`         | 400 Bad Request    | Validation failed    |
-| `MethodArgumentNotValidException`      | 400 Bad Request    | Invalid request body |
-| `HttpMessageNotReadableException`      | 400 Bad Request    | JSON parsing error   |
-| `Exception`                            | 500 Internal Error | Unexpected error     |
+| Exception Type                         | HTTP Status        | Description                  |
+| -------------------------------------- | ------------------ | ---------------------------- |
+| `EntityTemplateNotFoundException`      | 404 Not Found      | Entity not found             |
+| `EntityTemplateAlreadyExistsException` | 409 Conflict       | Duplicate identifier         |
+| `ConstraintViolationException`         | 400 Bad Request    | Validation failed            |
+| `MethodArgumentNotValidException`      | 400 Bad Request    | Invalid request body         |
+| `HttpMessageNotReadableException`      | 400 Bad Request    | Framework JSON parsing error |
+| `Exception`                            | 500 Internal Error | Unexpected error             |
 
 ## Error Response Format
 
-At API level, always follow the same error response structure:
+The API now returns `application/problem+json` responses. Standard RFC 7807 fields are
+present alongside legacy compatibility fields:
 
 ```json
 {
+  "type": "about:blank",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Template with ID 'invalid-id' not found",
+  "instance": "/api/v1/entity-templates/invalid-id",
   "error": "NOT_FOUND",
   "error_description": "Template with ID 'invalid-id' not found",
   "timestamp": "2025-11-28T10:30:00Z"
 }
 ```
+
+The `error` and `error_description` fields preserve the legacy contract for existing
+clients. `timestamp` is included as an `Instant` for traceability.
+
+> [!WARNING]
+> Strict clients may reject the new media type or the extra extension fields. They should
+> be updated to parse `application/problem+json` and tolerate RFC 7807 extensions.
+
+### Intentional differences
+
+- Spring MVC validation and JSON parsing errors now use the framework's native problem detail handling.
+- The manual JSON parsing logic was removed, so some malformed payload messages may differ from the previous custom wording.
+
+### Migration note
+
+Communicate the response shape change to API consumers before they depend on the new contract.
+Keep compatibility tests in place while clients migrate, and verify both the standard
+ProblemDetail fields and the legacy extension properties.