Integrate with the JSON Schema CLI for formatting and linting

Hey there! This is a PR to mainly start a conversation. I'm a member of JSON Schema organization involved in maintaining various JSON Schema related tooling (like https://alterschema.sourcemeta.com) and documentation (like https://www.learnjsonschema.com), plus co-author of the recently published O'Reilly book touching on JSON Schema (https://www.oreilly.com/library/view/unifying-business-data/9781098144999/). Based on our experience working with organizations maintaining repositories of schemas (like you!), we've been working on an open-source CLI tool that aims to simplify development and CI/CD when dealing with schemas. This CLI supports a growing amount of commands, but I'm proposing two for this repository to start with: - Formatting: making sure your schemas following a consistent style (i.e. indentation) plus a consistent ordering of keywords that was designed to make schemas easier to read - Linting: we are collecting common rules to highlight anti-patterns, common pitfalls, etc when using JSON Schema. There are not that many implement out there, but the linter already caught a little anti-pattern in `Reporter`: setting `enum` alongside `type` I would love to hear your feedback, feature requests, etc to help you make better use of JSON Schema with this CLI! We also have other things on the way, like a proper JSON Schema test runner that could eventually simplify your AJV scripts. Signed-off-by: Juan Cruz Viotti <[email protected]>
nasa-gcn · Jun 4, 2024 · 5cefb79 · 5cefb79
1 parent ed28ed2
commit 5cefb79
Show file tree

Hide file tree

Showing 28 changed files with 738 additions and 488 deletions.
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -7,6 +7,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: intelligence-ai/[email protected]
+      - run: jsonschema lint gcn --extension .schema.json --verbose
+      - run: jsonschema fmt gcn --extension .schema.json --check --verbose
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:

diff --git a/gcn/notices/burstcube/alert.schema.json b/gcn/notices/burstcube/alert.schema.json
@@ -1,26 +1,48 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/burstcube/alert.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/burstcube/alert.schema.json",
   "title": "Alert",
   "description": "BurstCube Trigger Alert",
   "type": "object",
   "allOf": [
-    { "$ref": "../core/Alert.schema.json" },
-    { "$ref": "../core/Reporter.schema.json" },
-    { "$ref": "../core/DateTime.schema.json" },
-    { "$ref": "../core/Event.schema.json" },
-    { "$ref": "../core/Localization.schema.json" },
-    { "$ref": "../core/Statistics.schema.json" },
-    { "$ref": "../core/Duration.schema.json" }
+    {
+      "$ref": "../core/Alert.schema.json"
+    },
+    {
+      "$ref": "../core/Reporter.schema.json"
+    },
+    {
+      "$ref": "../core/DateTime.schema.json"
+    },
+    {
+      "$ref": "../core/Event.schema.json"
+    },
+    {
+      "$ref": "../core/Localization.schema.json"
+    },
+    {
+      "$ref": "../core/Statistics.schema.json"
+    },
+    {
+      "$ref": "../core/Duration.schema.json"
+    }
   ],
   "properties": {
     "detector_status": {
       "type": "object",
       "properties": {
-        "CsI0": { "$ref": "../core/DetectorStatus.schema.json" },
-        "CsI1": { "$ref": "../core/DetectorStatus.schema.json" },
-        "CsI2": { "$ref": "../core/DetectorStatus.schema.json" },
-        "CsI3": { "$ref": "../core/DetectorStatus.schema.json" }
+        "CsI0": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        },
+        "CsI1": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        },
+        "CsI2": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        },
+        "CsI3": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        }
       }
     }
   }

diff --git a/gcn/notices/burstcube/test.schema.json b/gcn/notices/burstcube/test.schema.json
@@ -1,26 +1,48 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/burstcube/test.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/burstcube/test.schema.json",
   "title": "Alert",
   "description": "BurstCube Trigger Alert",
   "type": "object",
   "allOf": [
-    { "$ref": "../core/Alert.schema.json" },
-    { "$ref": "../core/Reporter.schema.json" },
-    { "$ref": "../core/DateTime.schema.json" },
-    { "$ref": "../core/Event.schema.json" },
-    { "$ref": "../core/Localization.schema.json" },
-    { "$ref": "../core/Statistics.schema.json" },
-    { "$ref": "../core/Duration.schema.json" }
+    {
+      "$ref": "../core/Alert.schema.json"
+    },
+    {
+      "$ref": "../core/Reporter.schema.json"
+    },
+    {
+      "$ref": "../core/DateTime.schema.json"
+    },
+    {
+      "$ref": "../core/Event.schema.json"
+    },
+    {
+      "$ref": "../core/Localization.schema.json"
+    },
+    {
+      "$ref": "../core/Statistics.schema.json"
+    },
+    {
+      "$ref": "../core/Duration.schema.json"
+    }
   ],
   "properties": {
     "detector_status": {
       "type": "object",
       "properties": {
-        "CsI0": { "$ref": "../core/DetectorStatus.schema.json" },
-        "CsI1": { "$ref": "../core/DetectorStatus.schema.json" },
-        "CsI2": { "$ref": "../core/DetectorStatus.schema.json" },
-        "CsI3": { "$ref": "../core/DetectorStatus.schema.json" }
+        "CsI0": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        },
+        "CsI1": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        },
+        "CsI2": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        },
+        "CsI3": {
+          "$ref": "../core/DetectorStatus.schema.json"
+        }
       }
     }
   }

diff --git a/gcn/notices/core/AdditionalInfo.schema.json b/gcn/notices/core/AdditionalInfo.schema.json
@@ -1,13 +1,13 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/AdditionalInfo.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/AdditionalInfo.schema.json",
   "title": "Comments",
   "description": "Comments that are not summarized elsewhere in schema",
+  "type": "object",
   "properties": {
     "additional_info": {
-      "type": "string",
-      "description": "Additional information about the event"
+      "description": "Additional information about the event",
+      "type": "string"
     }
   }
 }
diff --git a/gcn/notices/core/Alert.schema.json b/gcn/notices/core/Alert.schema.json
@@ -1,28 +1,32 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Alert.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Alert.schema.json",
   "title": "Alert",
   "description": "Alert Information description properties of this notice",
   "type": "object",
   "properties": {
     "alert_datetime": {
-      "type": "string",
-      "description": "Date and time of notice creation [UTC, ISO 8601], ex YYYY-MM-DDTHH:MM:SS.ssssssZ"
+      "description": "Date and time of notice creation [UTC, ISO 8601], ex YYYY-MM-DDTHH:MM:SS.ssssssZ",
+      "type": "string"
     },
     "alert_tense": {
+      "description": "Indication of whether this alert refers to a recent observation (current), re-analysis of archival data (archival), a planned observation in the future (planned), a signal injection (injection), commanded trigger (commanded) or a test trigger (test).",
       "enum": [
         "current",
         "archival",
         "planned",
         "injection",
         "commanded",
         "test"
-      ],
-      "description": "Indication of whether this alert refers to a recent observation (current), re-analysis of archival data (archival), a planned observation in the future (planned), a signal injection (injection), commanded trigger (commanded) or a test trigger (test)."
+      ]
     },
     "alert_type": {
-      "enum": ["initial", "update", "retraction"],
-      "description": "Indication of alert sequence if multiple of same type sent"
+      "description": "Indication of alert sequence if multiple of same type sent",
+      "enum": [
+        "initial",
+        "update",
+        "retraction"
+      ]
     }
   }
 }
diff --git a/gcn/notices/core/DateTime.schema.json b/gcn/notices/core/DateTime.schema.json
@@ -1,25 +1,25 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/DateTime.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/DateTime.schema.json",
   "title": "DateTime",
   "description": "Time descriptions of transient event and observation",
   "type": "object",
   "properties": {
-    "trigger_time": {
-      "type": "string",
-      "description": "Time of the trigger [ISO 8601], ex YYYY-MM-DDTHH:MM:SS.ssssssZ"
+    "observation_livetime": {
+      "description": "Livetime of the observation [s]",
+      "type": "number"
     },
     "observation_start": {
-      "type": "string",
-      "description": "Start time of the observation [ISO 8601]"
+      "description": "Start time of the observation [ISO 8601]",
+      "type": "string"
     },
     "observation_stop": {
-      "type": "string",
-      "description": "Stop time of the observation [ISO 8601]"
+      "description": "Stop time of the observation [ISO 8601]",
+      "type": "string"
     },
-    "observation_livetime": {
-      "type": "number",
-      "description": "Livetime of the observation [s]"
+    "trigger_time": {
+      "description": "Time of the trigger [ISO 8601], ex YYYY-MM-DDTHH:MM:SS.ssssssZ",
+      "type": "string"
     }
   }
 }
diff --git a/gcn/notices/core/DetectorStatus.schema.json b/gcn/notices/core/DetectorStatus.schema.json
@@ -1,7 +1,11 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/DetectorStatus.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/DetectorStatus.schema.json",
   "title": "DetectorStatus",
-  "enum": ["on", "off", "triggered"],
-  "description": "Status of a specified detector at the time of the alert"
+  "description": "Status of a specified detector at the time of the alert",
+  "enum": [
+    "on",
+    "off",
+    "triggered"
+  ]
 }
diff --git a/gcn/notices/core/Distance.schema.json b/gcn/notices/core/Distance.schema.json
@@ -1,19 +1,21 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Distance.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Distance.schema.json",
   "title": "Distance",
   "description": "Luminosity Distance",
+  "type": "object",
   "properties": {
     "luminosity_distance": {
-      "type": "number",
-      "description": "Luminosity distance [Mpc]"
+      "description": "Luminosity distance [Mpc]",
+      "type": "number"
     },
     "luminosity_distance_error": {
+      "description": "Luminosity distance uncertainty [Mpc, 1-sigma], with optional asymmetric uncertainty",
       "type": "array",
-      "items": { "type": "number" },
       "maxItems": 2,
-      "description": "Luminosity distance uncertainty [Mpc, 1-sigma], with optional asymmetric uncertainty"
+      "items": {
+        "type": "number"
+      }
     }
   }
 }
diff --git a/gcn/notices/core/Duration.schema.json b/gcn/notices/core/Duration.schema.json
@@ -1,28 +1,32 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Duration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Duration.schema.json",
   "title": "Duration",
+  "type": "object",
   "properties": {
-    "t90": {
-      "type": "number",
-      "description": "Time duration of central 90% of integrated fluence [s]"
+    "t50": {
+      "description": "Time duration of central 50% of integrated fluence [s]",
+      "type": "number"
     },
-    "t90_error": {
+    "t50_error": {
+      "description": "1-sigma uncertainty of the T50 duration [s], with asymmetric statistical errors taken into account",
       "type": "array",
-      "items": { "type": "number" },
       "maxItems": 2,
-      "description": "1-sigma uncertainty of the T90 duration [s], with asymmetric statistical errors taken into account"
+      "items": {
+        "type": "number"
+      }
     },
-    "t50": {
-      "type": "number",
-      "description": "Time duration of central 50% of integrated fluence [s]"
+    "t90": {
+      "description": "Time duration of central 90% of integrated fluence [s]",
+      "type": "number"
     },
-    "t50_error": {
+    "t90_error": {
+      "description": "1-sigma uncertainty of the T90 duration [s], with asymmetric statistical errors taken into account",
       "type": "array",
-      "items": { "type": "number" },
       "maxItems": 2,
-      "description": "1-sigma uncertainty of the T50 duration [s], with asymmetric statistical errors taken into account"
+      "items": {
+        "type": "number"
+      }
     }
   }
 }
diff --git a/gcn/notices/core/Event.schema.json b/gcn/notices/core/Event.schema.json
@@ -1,23 +1,34 @@
 {
-  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Event.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
+  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Event.schema.json",
   "title": "Event Information",
   "description": "Name or names of the event",
+  "type": "object",
   "properties": {
-    "event_name": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Name of the event (ex: GRB 170817A, GW170817, AT2017gfo, SSS 17a)"
-    },
     "id": {
+      "description": "Instrument-specific trigger ID (ex: bn230313485 (Fermi), 1159327 (Swift)) or alternate ID",
       "type": "array",
-      "items": { "oneOf": [{ "type": "string" }, { "type": "number" }] },
-      "description": "Instrument-specific trigger ID (ex: bn230313485 (Fermi), 1159327 (Swift)) or alternate ID"
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          }
+        ]
+      }
     },
     "data_archive_page": {
-      "type": "string",
-      "description": "URL of archived data files"
+      "description": "URL of archived data files",
+      "type": "string"
+    },
+    "event_name": {
+      "description": "Name of the event (ex: GRB 170817A, GW170817, AT2017gfo, SSS 17a)",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
     }
   }
 }