Skip to content

Commit

Permalink
Integrate with the JSON Schema CLI for formatting and linting
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
jviotti committed Jun 11, 2024
1 parent ed28ed2 commit 392e368
Show file tree
Hide file tree
Showing 28 changed files with 738 additions and 488 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
46 changes: 34 additions & 12 deletions gcn/notices/burstcube/alert.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
Expand Down
46 changes: 34 additions & 12 deletions gcn/notices/burstcube/test.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions gcn/notices/core/AdditionalInfo.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
18 changes: 11 additions & 7 deletions gcn/notices/core/Alert.schema.json
Original file line number Diff line number Diff line change
@@ -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"
]
}
}
}
22 changes: 11 additions & 11 deletions gcn/notices/core/DateTime.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
10 changes: 7 additions & 3 deletions gcn/notices/core/DetectorStatus.schema.json
Original file line number Diff line number Diff line change
@@ -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"
]
}
14 changes: 8 additions & 6 deletions gcn/notices/core/Distance.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
32 changes: 18 additions & 14 deletions gcn/notices/core/Duration.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
33 changes: 22 additions & 11 deletions gcn/notices/core/Event.schema.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
Loading

0 comments on commit 392e368

Please sign in to comment.