@nasa-gcn/schema 4.1.0

package/gcn/notices/icecube/lvk_nu_track_search.schema.json

@@ -0,0 +1,85 @@
+{
+  "$id": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/icecube/lvk_nu_track_search.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "title": "IceCube LVK Alert Nu Track Search",
+  "description": "IceCube LVK Coincident Neutrino Track Search",
+  "allOf": [
+    {
+      "$ref": "../core/Alert.schema.json",
+      "description": "Alert information (alert_datetime and alert_type) from LVK alert notices"
+    },
+    {
+      "$ref": "../core/FollowUp.schema.json",
+      "description": "ID (ref_ID) of LVK alert notice"
+    },
+    { "$ref": "../core/AdditionalInfo.schema.json" },
+    {
+      "$ref": "../core/Reporter.schema.json",
+      "description": "Record/Sequence number of LVK alerts"
+    },
+    { "$ref": "../core/DateTime.schema.json" }
+  ],
+  "properties": {
+    "pval_generic": {
+      "description": "P-value from generic transient search; consistency with background expectations [0-1]",
+      "type": ["number", "null"]
+    },
+    "pval_bayesian": {
+      "description": "P-value from LLAMA Bayesian search; consistency with background expectations [0-1]",
+      "type": ["number", "null"]
+    },
+    "n_events_coincident": {
+      "description": "Number of IceCube events in spatial and temporal coincidence with the GW map",
+      "type": "number"
+    },
+    "coincident_events": {
+      "type": "array",
+      "description": "An array of summary of information for each coincident neutrino track event",
+      "items": { "$ref": "#/$defs/coincevent" }
+    },
+    "most_probable_direction": {
+      "description": "Most likely source direction based on all coincident events and GW localizations",
+      "$ref": "../core/Localization.schema.json"
+    },
+    "neutrino_flux_sensitivity_range": {
+      "description": "Time integrated flux sensitivity ranges assuming an E^-2 spectrum (E^2 dN/dE) within the GW map localization",
+      "$ref": "#/$defs/fluxlimits"
+    }
+  },
+  "$defs": {
+    "fluxlimits": {
+      "type": "object",
+      "properties": {
+        "flux_sensitivity": {
+          "description": "Time integrated flux sensitivity range (min, max) [GeV cm^-2] assuming an E^-2 spectrum (E^2 dN/dE) found within the 90% region of GW map localization",
+          "type": "array",
+          "items": { "type": "number" }
+        },
+        "sensitive_energy_range": {
+          "description": "Energy sensitivity range (lower, upper) [GeV] assuming an E^-2 spectrum (E^2 dN/dE)",
+          "type": "array",
+          "items": { "type": "number" }
+        }
+      }
+    },
+    "coincevent": {
+      "type": "object",
+      "allOf": [{ "$ref": "../core/Localization.schema.json" }],
+      "properties": {
+        "event_dt": {
+          "description": "Time difference between LVK alert time and neutrino candidate [sec]",
+          "type": "number"
+        },
+        "event_pval_generic": {
+          "description": "Per-event P-value from generic transient search; consistency with background expectations [0-1]",
+          "type": ["number", "null"]
+        },
+        "event_pval_bayesian": {
+          "description": "Per-event P-value from LLAMA Bayesian search; consistency with background expectations [0-1]",
+          "type": ["number", "null"]
+        }
+      }
+    }
+  }
+}

package/gcn/notices/icecube/test/gold_bronze.update.example.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/icecube/test/gold_bronze_track_alerts.schema.json",
+  "additional_info": "IceCube Bronze Neutrino Track Alert",
+  "event_name": ["IceCube-230416A"],
+  "id": ["137840", "57034692"],
+  "alert_datetime": "2023-04-16T05:42:00.0Z",
+  "alert_type": "update",
+  "ra": 345.82,
+  "dec": 9.01,
+  "ra_dec_error": 0.5,
+  "containment_probability": 0.9,
+  "systematic_included": false,
+  "healpix_url": "https://roc.icecube.wisc.edu/public/",
+  "trigger_time": "2023-04-16T05:22:26.150574Z",
+  "nu_energy": 127.29,
+  "signalness": 0.34064,
+  "far": 8.029e-8
+}

package/gcn/notices/icecube/test/gold_bronze_track_alerts.example.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/icecube/test/gold_bronze_track_alerts.schema.json",
+  "additional_info": "IceCube Bronze Neutrino Track Alert",
+  "id": ["137840", "57034692"],
+  "alert_datetime": "2023-04-16T05:22:29.55Z",
+  "alert_type": "initial",
+  "ra": 345.82,
+  "dec": 9.01,
+  "ra_dec_error": 0.5,
+  "containment_probability": 0.9,
+  "systematic_included": false,
+  "trigger_time": "2023-04-16T05:22:26.150574Z",
+  "nu_energy": 127.29,
+  "signalness": 0.34064,
+  "far": 8.029e-8
+}

package/gcn/notices/icecube/test/gold_bronze_track_alerts.schema.json

@@ -0,0 +1,25 @@
+{
+  "$id": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/icecube/test/gold_bronze_track_alerts.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "title": "IceCubeGoldAndBronzeTracks",
+  "description": "IceCube Astrotrack Gold And Bronze track alert events",
+  "allOf": [
+    { "$ref": "../../core/AdditionalInfo.schema.json" },
+    { "$ref": "../../core/Event.schema.json" },
+    { "$ref": "../../core/Alert.schema.json" },
+    { "$ref": "../../core/Localization.schema.json" },
+    { "$ref": "../../core/DateTime.schema.json" },
+    { "$ref": "../../core/Statistics.schema.json" }
+  ],
+  "properties": {
+    "nu_energy": {
+      "description": "Most probable neutrino energy [TeV] that would have produced an event",
+      "type": "number"
+    },
+    "signalness": {
+      "description": "Probability [dn] that this is an astrophysical signal relative to backgrounds",
+      "type": "number"
+    }
+  }
+}

package/gcn/notices/svom/eclairs/trigger.catalog.example.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/svom/trigger.schema.json",
+  "instrument": "ECLAIRs",
+  "alert_datetime": "2024-02-22T08:51:55",
+  "alert_tense": "test",
+  "alert_type": "initial",
+  "id": ["sb24022203"],
+  "event_name": ["M1"],
+  "trigger_time": "2024-02-22T08:51:31.320000",
+  "ra": 143.2478,
+  "dec": -68.0289,
+  "ra_dec_error": 0.1,
+  "image_snr": 25.67,
+  "image_duration": 0,
+  "image_energy_range": [4, 20],
+  "trigger_type": "rate",
+  "slew_status": "not_requested"
+}

package/gcn/notices/svom/eclairs/trigger.not-slewing.example.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/svom/trigger.schema.json",
+  "instrument": "ECLAIRs",
+  "alert_datetime": "2024-02-22T08:51:55",
+  "alert_tense": "test",
+  "alert_type": "update",
+  "id": ["sb24022203"],
+  "trigger_time": "2024-02-22T08:51:31.320000",
+  "ra": 143.2478,
+  "dec": -68.0289,
+  "ra_dec_error": 0.1,
+  "image_snr": 25.67,
+  "image_duration": 0,
+  "image_energy_range": [4, 20],
+  "trigger_type": "rate",
+  "slew_status": "rejected"
+}

package/gcn/notices/svom/eclairs/trigger.slewing.example.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/svom/trigger.schema.json",
+  "instrument": "ECLAIRs",
+  "alert_datetime": "2024-02-22T08:51:55",
+  "alert_tense": "test",
+  "alert_type": "update",
+  "id": ["sb24022203"],
+  "trigger_time": "2024-02-22T08:51:31.320000",
+  "ra": 143.2478,
+  "dec": -68.0289,
+  "ra_dec_error": 0.1,
+  "image_snr": 25.67,
+  "image_duration": 0,
+  "image_energy_range": [4, 20],
+  "trigger_type": "rate",
+  "slew_status": "accepted"
+}

package/gcn/notices/svom/eclairs/trigger.wakeup.example.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/svom/trigger.schema.json",
+  "instrument": "ECLAIRs",
+  "alert_datetime": "2024-02-22T08:51:55",
+  "alert_tense": "test",
+  "alert_type": "initial",
+  "id": ["sb24022203"],
+  "trigger_time": "2024-02-22T08:51:31.320000",
+  "ra": 143.2478,
+  "dec": -68.0289,
+  "ra_dec_error": 0.1,
+  "image_snr": 25.67,
+  "image_duration": 0,
+  "image_energy_range": [4, 20],
+  "trigger_type": "rate",
+  "slew_status": "not_requested"
+}

package/gcn/notices/svom/grm/trigger.example.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/svom/trigger.schema.json",
+  "instrument": "GRM",
+  "alert_datetime": "2024-02-22T08:51:55",
+  "alert_tense": "test",
+  "alert_type": "initial",
+  "id": ["sb24022203"],
+  "trigger_time": "2024-02-22T08:51:31.320000",
+  "ra": 143.2478,
+  "dec": -68.0289,
+  "ra_dec_error": 0.1,
+  "rate_snr": 25.67,
+  "rate_duration": 0,
+  "rate_energy_range": [15, 550],
+  "triggered_GRDs": [true, true, true]
+}

package/gcn/notices/svom/trigger.schema.json

@@ -0,0 +1,33 @@
+{
+  "$id": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/svom/trigger.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "unevaluatedProperties": false,
+  "title": "SVOM trigger alerts",
+  "description": "ECLAIRs or GRM trigger parameters computed onboard",
+  "allOf": [
+    { "$ref": "../core/AdditionalInfo.schema.json" },
+    { "$ref": "../core/Alert.schema.json" },
+    { "$ref": "../core/DateTime.schema.json" },
+    { "$ref": "../core/Event.schema.json" },
+    { "$ref": "../core/Localization.schema.json" },
+    { "$ref": "../core/Reporter.schema.json" },
+    { "$ref": "../core/Statistics.schema.json" },
+    { "$ref": "../core/Pointing.schema.json" },
+    { "$ref": "../core/GeoLocBase.schema.json" }
+  ],
+  "properties": {
+    "$schema": true,
+    "slew_status": {
+      "enum": ["accepted", "rejected", "not_requested"],
+      "description": "Spacecraft slew status"
+    },
+    "triggered_GRDs": {
+      "type": "array",
+      "items": { "type": "boolean" },
+      "minItems": 3,
+      "maxItems": 3,
+      "description": "In case of a GRM trigger, trigger status the 3 GRDs. Each item correspond to one of the 3 GRDs: true means the GRD triggers, false not"
+    }
+  }
+}

package/gcn/notices/swift/bat/Guano.Retraction.example.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/swift/bat/Guano.schema.json",
+  "mission": "Swift",
+  "instrument": "BAT-GUANO",
+  "messenger": "EM",
+  "record_number": 4,
+  "alert_datetime": "2023-01-01T03:24:36.0Z",
+  "alert_tense": "current",
+  "alert_type": "retraction",
+  "trigger_time": "2022-12-31T21:46:05.13Z",
+  "follow_up_event": "Fermi 694215970",
+  "follow_up_type": "GRB",
+  "data_archive_page": "https://guano.swift.psu.edu/trigger_report?id=694215995",
+  "id": ["694215995"]
+}

package/gcn/notices/swift/bat/Guano.example.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/swift/bat/Guano.schema.json",
+  "mission": "Swift",
+  "instrument": "BAT-GUANO",
+  "messenger": "EM",
+  "record_number": 1,
+  "alert_datetime": "2023-01-01T03:24:36.0Z",
+  "alert_tense": "current",
+  "alert_type": "initial",
+  "trigger_time": "2022-12-31T21:46:05.13Z",
+  "rate_snr": 15.8,
+  "rate_duration": 0.256,
+  "rate_energy_range": [15, 350],
+  "classification": { "GRB": 1 },
+  "far": 0.00001,
+  "follow_up_event": "Fermi 694215970",
+  "follow_up_type": "GRB",
+  "data_archive_page": "https://guano.swift.psu.edu/trigger_report?id=694215995",
+  "id": ["694215995"]
+}

package/gcn/notices/swift/bat/Guano.schema.json

@@ -0,0 +1,28 @@
+{
+  "$id": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/swift/bat/Guano.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Swift/BAT-GUANO Alert",
+  "description": "Candidate gamma-ray transient reported from the BAT-GUANO targeted search",
+  "type": "object",
+  "allOf": [
+    { "$ref": "../../core/Alert.schema.json" },
+    { "$ref": "../../core/Event.schema.json" },
+    { "$ref": "../../core/DateTime.schema.json" },
+    { "$ref": "../../core/Localization.schema.json" },
+    { "$ref": "../../core/Statistics.schema.json" },
+    { "$ref": "../../core/Reporter.schema.json" },
+    { "$ref": "../../core/AdditionalInfo.schema.json" }
+  ],
+  "properties": {
+    "$schema": true,
+    "follow_up_event": {
+      "type": "string",
+      "description": "Name or trigger time of the external trigger that launched the search."
+    },
+    "follow_up_type": {
+      "type": "string",
+      "description": "Type of external trigger that launched the search, eg GW, neutrino, etc."
+    }
+  },
+  "unevaluatedProperties": false
+}

package/gcn/notices/swift/bat/guano.loc_arc_min.example.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/swift/bat/Guano.schema.json",
+  "mission": "Swift",
+  "instrument": "BAT-GUANO",
+  "messenger": "EM",
+  "record_number": 3,
+  "alert_datetime": "2023-01-01T05:33:01Z",
+  "alert_tense": "current",
+  "alert_type": "update",
+  "trigger_time": "2022-12-31T21:46:05.13Z",
+  "ra": 336.26,
+  "dec": 25.139,
+  "ra_dec_error": 0.5,
+  "containment_probability": 0.9,
+  "systematic_included": true,
+  "rate_snr": 15.8,
+  "rate_duration": 0.256,
+  "rate_energy_range": [15, 350],
+  "image_snr": 13.94,
+  "image_duration": 0.256,
+  "image_energy_range": [15, 350],
+  "classification": { "GRB": 1 },
+  "far": 0.00001,
+  "follow_up_event": "Fermi 694215970",
+  "follow_up_type": "GRB",
+  "data_archive_page": "https://guano.swift.psu.edu/trigger_report?id=694215995",
+  "id": ["694215995"]
+}

package/gcn/notices/swift/bat/guano.loc_map.example.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://gcn.nasa.gov/schema/v4.1.0/gcn/notices/swift/bat/Guano.schema.json",
+  "mission": "Swift",
+  "instrument": "BAT-GUANO",
+  "messenger": "EM",
+  "record_number": 2,
+  "alert_datetime": "2023-01-01T03:24:36.0Z",
+  "alert_tense": "current",
+  "alert_type": "update",
+  "trigger_time": "2022-12-31T21:46:05.13Z",
+  "healpix_file": "hhhh...",
+  "systematic_included": true,
+  "rate_snr": 7.5,
+  "rate_duration": 0.256,
+  "rate_energy_range": [15, 350],
+  "classification": { "GRB": 1 },
+  "far": 0.00001,
+  "follow_up_event": "Fermi 694215970",
+  "follow_up_type": "GRB",
+  "data_archive_page": "https://guano.swift.psu.edu/trigger_report?id=694215995",
+  "id": ["694215995"]
+}

package/index.js

@@ -0,0 +1 @@
+// This file is intentionally left blank.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@nasa-gcn/schema",
+  "description": "Unified JSON Schema for multi-messenger and high-energy astronomy alerts",
+  "version": "4.1.0",
+  "repository": {
+    "type": "git",
+    "url": "github:nasa-gcn/gcn-schema"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "test": "node validate.mjs",
+    "version": "node update-tags.mjs && git add -u",
+    "postversion": "node update-tags.mjs --reset && git add -u && git commit --no-verify -m \"Back to development\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@nasa-gcn/eslint-config-gitignore": "^0.0.2",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^8.34.0",
+    "eslint-config-prettier": "^9.1.0",
+    "execa": "^9.3.0",
+    "glob": "^10.1.0",
+    "husky": "^9.1.1",
+    "lint-staged": "^15.2.7",
+    "prettier": "3.3.3"
+  },
+  "prettier": {
+    "semi": false,
+    "singleQuote": true
+  },
+  "eslintConfig": {
+    "env": {
+      "es2022": true,
+      "node": true
+    },
+    "extends": [
+      "eslint:recommended",
+      "@nasa-gcn/eslint-config-gitignore",
+      "prettier"
+    ],
+    "parserOptions": {
+      "sourceType": "module"
+    }
+  },
+  "lint-staged": {
+    "*.{json,js,mjs}": "prettier --write",
+    "*.{js,mjs}": "eslint --max-warnings 0",
+    "*.schema.json": "node validate.mjs"
+  }
+}

package/update-tags.mjs

@@ -0,0 +1,55 @@
+import { readFile, writeFile } from 'fs/promises'
+import { glob as baseGlob } from 'glob'
+import * as prettier from 'prettier'
+
+// FIXME: replace with a JSON import when Import Attributes become part of
+// EcmaScript. See https://github.com/tc39/proposal-import-attributes
+const { version } = JSON.parse(
+  await readFile('package.json', { encoding: 'utf8' }),
+)
+
+const tagPath = `v${version}`
+
+async function glob(path) {
+  return await baseGlob(path, {
+    ignore: ['node_modules/**'],
+    posix: true,
+  })
+}
+
+async function fileUpdates(fileSet, key, oldValue, newValue) {
+  await Promise.all(
+    fileSet.map(async (fileItem) => {
+      let file = JSON.parse(
+        await readFile(fileItem, {
+          encoding: 'utf-8',
+        }),
+      )
+      file[key] = file[key].replace(
+        `https://gcn.nasa.gov/schema/${oldValue}/`,
+        `https://gcn.nasa.gov/schema/${newValue}/`,
+      )
+
+      await writeFile(
+        fileItem,
+        await prettier.format(JSON.stringify(file), {
+          parser: 'json',
+        }),
+      )
+    }),
+  )
+}
+
+async function loadAndUpdateFiles(oldValue, newValue) {
+  const schemaFilenames = await glob('**/*.schema.json')
+  await fileUpdates(schemaFilenames, '$id', oldValue, newValue)
+
+  const exampleFilenames = await glob('**/*.example.json')
+  await fileUpdates(exampleFilenames, '$schema', oldValue, newValue)
+}
+
+if (process.argv.includes('--reset')) {
+  await loadAndUpdateFiles(tagPath, 'main')
+} else {
+  await loadAndUpdateFiles('main', tagPath)
+}

package/validate.mjs

@@ -0,0 +1,100 @@
+import { readFile } from 'fs/promises'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import meta from 'ajv/dist/refs/json-schema-2020-12/index.js'
+import { glob as baseGlob } from 'glob'
+import { execa, ExecaError } from 'execa'
+
+let ref
+try {
+  const { stdout } = await execa`git describe --exact-match --tags`
+  ref = stdout
+} catch (e) {
+  if (e instanceof ExecaError && e.failed) ref = 'main'
+  else throw e
+}
+
+const schemaIdPrefix = `https://gcn.nasa.gov/schema/${ref}`
+
+const ajv = new Ajv({
+  validateSchema: true,
+  verbose: true,
+  allowUnionTypes: true,
+})
+addFormats(ajv)
+ajv.addMetaSchema(meta)
+
+async function glob(path) {
+  return await baseGlob(path, {
+    ignore: ['test/**', 'node_modules/**'],
+    posix: true,
+  })
+}
+
+async function validate() {
+  const schemaFilenames = await glob('**/*.schema.json')
+  const schemas = await Promise.all(
+    schemaFilenames.map(async (match) => {
+      const json = JSON.parse(
+        await readFile(match, {
+          encoding: 'utf-8',
+        }),
+      )
+      const expectedId = `${schemaIdPrefix}/${match}`
+      if (json['$id'] !== expectedId) {
+        console.error(
+          `error: ${match}: expected value of $id to be ${expectedId}, but found ${json['$id']}`,
+        )
+        process.exitCode = 1
+      }
+      return json
+    }),
+  )
+
+  try {
+    ajv.addSchema(schemas).compile(true)
+  } catch (e) {
+    if (e instanceof Error) {
+      process.exitCode = 1
+      console.error(`error: ${e.message}`)
+    } else {
+      throw e
+    }
+  }
+
+  const exampleFilenames = await glob('**/*.example.json')
+  await Promise.all(
+    exampleFilenames.map(async (path) => {
+      const example = JSON.parse(
+        await readFile(path, {
+          encoding: 'utf-8',
+        }),
+      )
+
+      const schemaId = example['$schema']
+      if (!schemaId) {
+        process.exitCode = 1
+        console.error(`error: ${path}: missing required $schema property`)
+        return
+      }
+
+      try {
+        ajv.validate(schemaId, example)
+      } catch (e) {
+        if (e instanceof Error) {
+          process.exitCode = 1
+          console.error(`error: ${path}: ${e.message}`)
+        } else {
+          throw e
+        }
+      }
+
+      if (ajv.errors) {
+        console.log(JSON.stringify(ajv.errors, null, 2))
+        process.exitCode = 1
+      }
+    }),
+  )
+}
+
+await validate()