feat: Move validation pointer and keyword into an errors array

Each failure is now an entry in an errors[] array with a #/...
JSON-Pointer-in-fragment pointer. oneOf/anyOf failures list one entry
per branch, deepest-first and de-duplicated.

Author: thced

src/main/java/com/retailsvc/http/internal/ProblemDetail.java

@@ -2,31 +2,70 @@
 
 import com.retailsvc.http.BadRequestException;
 import com.retailsvc.http.validate.ValidationError;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.LinkedHashSet;
+import java.util.List;
 import java.util.Map;
 
 /**
- * Carrier for an RFC 7807 problem+json document. Serialized by the registered JSON {@code
- * TypeMapper}; the wire shape and field-order are whatever the configured mapper produces — title
- * is advisory per RFC 7807 since {@code type} is always {@code about:blank}.
+ * Carrier for an RFC 9457 problem+json document. Serialized by {@link ProblemDetailRenderer}; the
+ * wire shape is the RFC core members (type, title, status, detail) plus an {@code errors} extension
+ * array. Each {@link Entry} locates one validation failure with a JSON-Pointer-in-fragment {@code
+ * pointer} and the failed {@code keyword}. {@code type} is always {@code about:blank}, so {@code
+ * title} is advisory per the RFC.
  */
 public record ProblemDetail(
-    String type, String title, int status, String detail, String pointer, String keyword) {
+    String type, String title, int status, String detail, List<Entry> errors) {
+
+  /** One validation failure: its body location, the failed keyword, and a human-readable detail. */
+  public record Entry(String pointer, String keyword, String detail) {}
 
   private static final String DEFAULT_TYPE = "about:blank";
 
   public static ProblemDetail forValidation(ValidationError e) {
-    return new ProblemDetail(
-        DEFAULT_TYPE, "Bad Request", 400, e.message(), e.pointer(), e.keyword());
+    return new ProblemDetail(DEFAULT_TYPE, "Bad Request", 400, e.message(), entriesOf(e));
   }
 
   public static ProblemDetail forBadRequest(BadRequestException e) {
+    List<Entry> errors =
+        e.pointer()
+            .map(p -> List.of(new Entry(fragment(p), e.keyword().orElse(null), e.getMessage())))
+            .orElseGet(List::of);
     return new ProblemDetail(
-        DEFAULT_TYPE,
-        titleFor(e.status()),
-        e.status(),
-        e.getMessage(),
-        e.pointer().orElse(null),
-        e.keyword().orElse(null));
+        DEFAULT_TYPE, titleFor(e.status()), e.status(), e.getMessage(), errors);
+  }
+
+  /**
+   * Flattens a validation error into ordered {@code errors} entries: the failed branches of a
+   * combinator (one each), or the single leaf otherwise. Multi-entry results are sorted deepest
+   * pointer first (most-likely-intended branch) and de-duplicated on exact equality.
+   */
+  private static List<Entry> entriesOf(ValidationError e) {
+    List<ValidationError> sources = e.branches().isEmpty() ? List.of(e) : e.branches();
+    List<Entry> entries = new ArrayList<>(sources.size());
+    for (ValidationError s : sources) {
+      entries.add(new Entry(fragment(s.pointer()), s.keyword(), s.message()));
+    }
+    if (entries.size() <= 1) {
+      return entries;
+    }
+    entries.sort(Comparator.comparingInt((Entry en) -> depth(en.pointer())).reversed());
+    return new ArrayList<>(new LinkedHashSet<>(entries));
+  }
+
+  private static String fragment(String pointer) {
+    return "#" + pointer;
+  }
+
+  private static int depth(String pointer) {
+    int n = 0;
+    for (int i = 0; i < pointer.length(); i++) {
+      if (pointer.charAt(i) == '/') {
+        n++;
+      }
+    }
+    return n;
   }
 
   private static final Map<Integer, String> TITLES =

src/main/java/com/retailsvc/http/internal/ProblemDetailRenderer.java

@@ -1,15 +1,15 @@
 package com.retailsvc.http.internal;
 
 import java.nio.charset.StandardCharsets;
+import java.util.List;
 
 /**
- * Built-in JSON writer for the {@code application/problem+json} (RFC 7807) wire shape. Keeps the
+ * Built-in JSON writer for the {@code application/problem+json} (RFC 9457) wire shape. Keeps the
  * exception and security paths free of any {@code TypeMapper}, so the library can emit problem
  * responses without a JSON library on the classpath (and without record-accessor reflection that
  * GraalVM Native Image would otherwise need configured).
  *
- * <p>Null-valued fields are omitted, matching the default Gson encoding the library historically
- * produced.
+ * <p>Null-valued fields and an empty {@code errors} array are omitted.
  */
 public final class ProblemDetailRenderer {
 
@@ -26,12 +26,35 @@ public static byte[] renderJson(ProblemDetail pd) {
     first = appendString(out, first, "title", pd.title());
     first = appendInt(out, first, "status", pd.status());
     first = appendString(out, first, "detail", pd.detail());
-    first = appendString(out, first, "pointer", pd.pointer());
-    appendString(out, first, "keyword", pd.keyword());
+    appendErrors(out, first, pd.errors());
     out.append('}');
     return out.toString().getBytes(StandardCharsets.UTF_8);
   }
 
+  private static void appendErrors(
+      StringBuilder out, boolean first, List<ProblemDetail.Entry> errors) {
+    if (errors == null || errors.isEmpty()) {
+      return;
+    }
+    if (!first) {
+      out.append(',');
+    }
+    out.append("\"errors\":[");
+    for (int i = 0; i < errors.size(); i++) {
+      if (i > 0) {
+        out.append(',');
+      }
+      ProblemDetail.Entry e = errors.get(i);
+      out.append('{');
+      boolean entryFirst = true;
+      entryFirst = appendString(out, entryFirst, "pointer", e.pointer());
+      entryFirst = appendString(out, entryFirst, "keyword", e.keyword());
+      appendString(out, entryFirst, "detail", e.detail());
+      out.append('}');
+    }
+    out.append(']');
+  }
+
   private static boolean appendString(StringBuilder out, boolean first, String name, String value) {
     if (value == null) {
       return first;

src/main/java/com/retailsvc/http/internal/SecurityFilter.java

@@ -119,7 +119,7 @@ private void renderRejection(HttpExchange exchange, List<GroupOutcome.Failed> fa
     String detail = describe(pick);
 
     ProblemDetail problemDetail =
-        new ProblemDetail("about:blank", title, status, detail, null, null);
+        new ProblemDetail("about:blank", title, status, detail, List.of());
     byte[] body = ProblemDetailRenderer.renderJson(problemDetail);
     exchange.getResponseHeaders().add("Content-Type", "application/problem+json");
     if (!anyDenied) {

src/test/java/com/retailsvc/http/HandlersDefaultExceptionTest.java

@@ -9,6 +9,7 @@
 import com.retailsvc.http.spec.HttpMethod;
 import com.retailsvc.http.validate.ValidationError;
 import java.nio.charset.StandardCharsets;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import org.junit.jupiter.api.AfterEach;
@@ -54,8 +55,14 @@ void validationExceptionRendersProblemJson() {
     String json = new String(bytes, StandardCharsets.UTF_8);
     @SuppressWarnings("unchecked")
     Map<String, Object> parsed = (Map<String, Object>) JSON.readFrom(bytes, "application/json");
-    assertThat(parsed).containsEntry("keyword", "type");
     assertThat(((Number) parsed.get("status")).intValue()).isEqualTo(400);
+    @SuppressWarnings("unchecked")
+    List<Map<String, Object>> errors = (List<Map<String, Object>>) parsed.get("errors");
+    assertThat(errors)
+        .singleElement()
+        .satisfies(
+            entry ->
+                assertThat(entry).containsEntry("pointer", "#/x").containsEntry("keyword", "type"));
     assertThat(json).contains("expected string");
   }
 
@@ -73,9 +80,16 @@ void badRequestExceptionRendersProblemJsonWithCustomStatus() {
     assertThat(((Number) parsed.get("status")).intValue()).isEqualTo(422);
     assertThat(parsed)
         .containsEntry("title", "Unprocessable Content")
-        .containsEntry("detail", "email taken")
-        .containsEntry("pointer", "/email")
-        .containsEntry("keyword", "unique");
+        .containsEntry("detail", "email taken");
+    @SuppressWarnings("unchecked")
+    List<Map<String, Object>> errors = (List<Map<String, Object>>) parsed.get("errors");
+    assertThat(errors)
+        .singleElement()
+        .satisfies(
+            entry ->
+                assertThat(entry)
+                    .containsEntry("pointer", "#/email")
+                    .containsEntry("keyword", "unique"));
   }
 
   @Test

src/test/java/com/retailsvc/http/internal/ProblemDetailRendererTest.java

@@ -2,41 +2,85 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import com.retailsvc.http.internal.ProblemDetail.Entry;
 import java.nio.charset.StandardCharsets;
+import java.util.List;
 import org.junit.jupiter.api.Test;
 
 class ProblemDetailRendererTest {
 
   @Test
-  void rendersAllFieldsWhenPresent() {
+  void rendersSingleEntryErrorsArray() {
     ProblemDetail pd =
-        new ProblemDetail("about:blank", "Bad Request", 400, "expected string", "/x", "type");
+        new ProblemDetail(
+            "about:blank",
+            "Bad Request",
+            400,
+            "expected string",
+            List.of(new Entry("#/x", "type", "expected string")));
     assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
         .isEqualTo(
             "{\"type\":\"about:blank\",\"title\":\"Bad Request\",\"status\":400,"
-                + "\"detail\":\"expected string\",\"pointer\":\"/x\",\"keyword\":\"type\"}");
+                + "\"detail\":\"expected string\",\"errors\":[{\"pointer\":\"#/x\","
+                + "\"keyword\":\"type\",\"detail\":\"expected string\"}]}");
   }
 
   @Test
-  void omitsNullPointerAndKeyword() {
+  void rendersMultipleErrorEntries() {
     ProblemDetail pd =
-        new ProblemDetail("about:blank", "Unauthorized", 401, "missing token", null, null);
+        new ProblemDetail(
+            "about:blank",
+            "Bad Request",
+            400,
+            "matched 0 of 2 oneOf branches",
+            List.of(
+                new Entry("#/collar/size", "type", "expected integer"),
+                new Entry("#/bark", "type", "expected boolean")));
+    assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
+        .isEqualTo(
+            "{\"type\":\"about:blank\",\"title\":\"Bad"
+                + " Request\",\"status\":400,\"detail\":\"matched 0 of 2 oneOf"
+                + " branches\",\"errors\":[{\"pointer\":\"#/collar/size\",\"keyword\":\"type\",\"detail\":\"expected"
+                + " integer\"},{\"pointer\":\"#/bark\",\"keyword\":\"type\",\"detail\":\"expected"
+                + " boolean\"}]}");
+  }
+
+  @Test
+  void omitsKeywordWithinEntryWhenNull() {
+    ProblemDetail pd =
+        new ProblemDetail(
+            "about:blank",
+            "Unprocessable Content",
+            422,
+            "email taken",
+            List.of(new Entry("#/email", null, "email taken")));
+    assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
+        .isEqualTo(
+            "{\"type\":\"about:blank\",\"title\":\"Unprocessable Content\",\"status\":422,"
+                + "\"detail\":\"email taken\",\"errors\":[{\"pointer\":\"#/email\","
+                + "\"detail\":\"email taken\"}]}");
+  }
+
+  @Test
+  void omitsEmptyErrorsArray() {
+    ProblemDetail pd =
+        new ProblemDetail("about:blank", "Unauthorized", 401, "missing token", List.of());
     assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
         .isEqualTo(
             "{\"type\":\"about:blank\",\"title\":\"Unauthorized\",\"status\":401,"
                 + "\"detail\":\"missing token\"}");
   }
 
   @Test
-  void omitsNullDetail() {
-    ProblemDetail pd = new ProblemDetail("about:blank", "Not Found", 404, null, null, null);
+  void omitsNullDetailAndEmptyErrors() {
+    ProblemDetail pd = new ProblemDetail("about:blank", "Not Found", 404, null, List.of());
     assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
         .isEqualTo("{\"type\":\"about:blank\",\"title\":\"Not Found\",\"status\":404}");
   }
 
   @Test
   void escapesQuoteAndBackslashInDetail() {
-    ProblemDetail pd = new ProblemDetail("about:blank", "Bad Request", 400, "a\"b\\c", null, null);
+    ProblemDetail pd = new ProblemDetail("about:blank", "Bad Request", 400, "a\"b\\c", List.of());
     assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
         .isEqualTo(
             "{\"type\":\"about:blank\",\"title\":\"Bad Request\",\"status\":400,"
@@ -46,25 +90,16 @@ void escapesQuoteAndBackslashInDetail() {
   @Test
   void escapesNamedControlCharsInDetail() {
     ProblemDetail pd =
-        new ProblemDetail("about:blank", "Bad Request", 400, "\b\f\n\r\t", null, null);
+        new ProblemDetail("about:blank", "Bad Request", 400, "\b\f\n\r\t", List.of());
     assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
         .isEqualTo(
             "{\"type\":\"about:blank\",\"title\":\"Bad Request\",\"status\":400,"
                 + "\"detail\":\"\\b\\f\\n\\r\\t\"}");
   }
 
-  @Test
-  void escapesUnnamedControlCharsAsHexUnicode() {
-    ProblemDetail pd = new ProblemDetail("about:blank", "Bad Request", 400, "
", null, null);
-    assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
-        .isEqualTo(
-            "{\"type\":\"about:blank\",\"title\":\"Bad Request\",\"status\":400,"
-                + "\"detail\":\"\\u0001\\u001f\"}");
-  }
-
   @Test
   void passesThroughNonAsciiCharactersVerbatim() {
-    ProblemDetail pd = new ProblemDetail("about:blank", "Bad Request", 400, "café-é", null, null);
+    ProblemDetail pd = new ProblemDetail("about:blank", "Bad Request", 400, "café-é", List.of());
     assertThat(asString(ProblemDetailRenderer.renderJson(pd)))
         .isEqualTo(
             "{\"type\":\"about:blank\",\"title\":\"Bad"