More descriptive message when mistyping flag data field

3 files changed, 13 insertions, 3 deletions

diff --git a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchive.java b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchive.java
index 6604da144b9..05c5acfda06 100644
--- a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchive.java
+++ b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchive.java
@@ -164,7 +164,11 @@ public class SystemFlagsDataArchive {
             String normalizedRawData = removeCommentsFromJson(rawData);
             if (!JSON.equals(serializedData, normalizedRawData)) {
                 throw new IllegalArgumentException(filePath + " contains unknown non-comment fields: " +
-                        "was deserialized to " + serializedData);
+                        "after removing any comment fields the JSON is:\n  " +
+                        normalizedRawData +
+                        "\nbut deserializing this ended up with a JSON that are missing some of the fields:\n  " +
+                        serializedData +
+                        "\nSee https://git.ouroath.com/vespa/hosted-feature-flags for more info on the JSON syntax");
             }
         }
         builder.addFile(filename, flagData);
diff --git a/controller-api/src/test/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchiveTest.java b/controller-api/src/test/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchiveTest.java
index 5ff1cbf7530..509de30fd44 100644
--- a/controller-api/src/test/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchiveTest.java
+++ b/controller-api/src/test/java/com/yahoo/vespa/hosted/controller/api/systemflags/v1/SystemFlagsDataArchiveTest.java
@@ -109,7 +109,12 @@ public class SystemFlagsDataArchiveTest {
     @Test
     public void throws_on_unknown_field() {
         expectedException.expect(IllegalArgumentException.class);
-        expectedException.expectMessage("flags/my-test-flag/main.prod.us-west-1.json contains unknown non-comment fields: was deserialized to {\"id\":\"my-test-flag\",\"rules\":[{\"value\":\"default\"}]}");
+        expectedException.expectMessage(
+                "flags/my-test-flag/main.prod.us-west-1.json contains unknown non-comment fields: after removing any comment fields the JSON is:\n" +
+                "  {\"id\":\"my-test-flag\",\"rules\":[{\"condition\":[{\"type\":\"whitelist\",\"dimension\":\"hostname\",\"values\":[\"foo.com\"]}],\"value\":\"default\"}]}\n" +
+                "but deserializing this ended up with a JSON that are missing some of the fields:\n" +
+                "  {\"id\":\"my-test-flag\",\"rules\":[{\"value\":\"default\"}]}\n" +
+                "See https://git.ouroath.com/vespa/hosted-feature-flags for more info on the JSON syntax");
         SystemFlagsDataArchive.fromDirectory(Paths.get("src/test/resources/system-flags-with-unknown-field-name/"));
     }
 
diff --git a/vespajlib/src/main/java/com/yahoo/text/JSON.java b/vespajlib/src/main/java/com/yahoo/text/JSON.java
index 11e5be9328e..2757bd7945c 100644
--- a/vespajlib/src/main/java/com/yahoo/text/JSON.java
+++ b/vespajlib/src/main/java/com/yahoo/text/JSON.java
@@ -64,7 +64,8 @@ public final class JSON {
      *
      * <p>When comparing two numbers of the two JSON strings, the result is only guaranteed to be
      * correct if (a) both are integers (without fraction and exponent) and each fits in a long, or
-     * (b) both are non-integers, are syntactically identical, and fits in a double.</p>
+     * (b) both are non-integers, fits in a double, and are syntactically identical. Examples
+     * of pairs that may not be equal: 1 and 1.0 (different types), 0.1 and 1e-1, 0.0 and 0.00.</p>
      *
      * @throws RuntimeException on invalid JSON
      */