Unified Schema

The GCN Unified Schema is a framework for defining GCN Notices types using a common format, standardized field names, uniform data types, and consistent physical units across multiple missions. If you are joining GCN as a new notice producer, then you can contribute your own notice types to the Unified Schema present at GitHub.

The over-the-wire format for GCN Notices in the Unified Schema is JavaScript Object Notation (JSON), an Internet standard for encoding arbitrary data as human-readable text. Despite having "JavaScript" in its name, JSON is ubiquitous, and many programming languages have standard library support for JSON.

The definition of the GCN Unified Schema is itself expressed in JSON format using the JSON Schema standard. JSON Schema makes it possible for us to provide automatic, interactive documentation of the schema in our Schema Browser.

Crafting a schema for a new notice type involves selecting one or more of the predefined core schema and adding your own optional mission-specific fields. This approach allows the flexibility of inclusion of mission-specific parameters while ensuring consistency where possible. We encourage producers to utilize the core schema as much as possible.

As you are developing your schema, don't hesitate to contact us with any questions!

Fork the GitHub Repository

To get started, fork the nasa-gcn/gcn-schema repository on GitHub and check it out on your computer. If you are new to GitHub, refer to our GitHub primer.

After you have forked and cloned the repository, make sure that Node.js and NPM are installed on your computer. There are several options to install Node.js and NPM. Pick one of the following:

• Download and run the Node.js installer for your operating system.
• Install and use the Node Version Manager, nvm.
• Install using a package manager.

Finally, run the following command inside the repository working directory to install the pre-commit hooks for code formatting and syntax checking:

npm install

File Naming Conventions

Create a folder in the repository for your mission following the naming convention gcn/notices/mission. Add one or more files for schema definitions named gcn/notices/mission/schema_name.schema.json. The mission name should be lowercase and the schema name should be snake_case. Each file corresponds to a Kafka topic named gcn.notices.mission.schema_name.

We encourage you to add files containing example data. The naming convention for example files is gcn/notices/mission/schema_name.optional_description.example.json. We will automatically validate your example files against your schema.

Define Your Schema

Here is a basic schema file, sample.schema.json, and an example file, sample.example.json, to start from. Place these files in the gcn/notices/mission directory and customize them. Read on for a description of each parameter.

{
  "$id": "https://gcn.nasa.gov/schema/main/gcn/notices/mission/sample.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "unevaluatedProperties": false,
  "title": "Your Schema Name",
  "description": "A description for your schema",
  "allOf": [
    {
      "$ref": "../core/Alert.schema.json"
    },
    {
      "$ref": "../core/Localization.schema.json"
    }
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri"
    },
    "example_field_1": {
      "type": "string",
      "description": "A custom field that can hold text"
    },
    "example_field_2": {
      "type": "number",
      "description": "A custom field that holds a number"
    }
  }
}

JSON Schema Quick Reference

$id

The URL at which this schema can be retrieved.

$schema

Identifies this document as conforming to JSON Schema. (Leave as is.)

type

Declares that this schema describes a compound data type. (Leave as is.)

unevaluatedProperties

Declares that fields other than those listed above or inherited from the listed core schema are not allowed. (Leave as is.)

title

A short, human-friendly name for your schema: a short phrase.

description

A longer description of your schema: a sentence or a short paragraph.

allOf

List of core schema to include fields from. Browse the core schema or view their source on GitHub for options.

properties

Mapping of custom, mission-specific fields. The first property, '$schema: { type: "string", format: "uri" }', must be included when using 'unevaluatedProperties': false, otherwise the inclusion of the $schema property in your example files will cause validation to fail. Field names should use snake_case. Each entry should at least have a description and a type. See the list of available data types.

Extended Example

We recommend exploring our schema browser and GitHub repository for more examples. Here is an extended example from Swift/BAT-GUANO:

{
  "$id": "https://gcn.nasa.gov/schema/main/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": {
      "type": "string",
      "format": "uri"
    },
    "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
}

Validating Schema

The Git repository is configured to automatically format and validate your code at the time that you commit it. This means when you commit your updates, the validator will run to make sure that all of the schemas and their respective examples function correctly. This step also checks general formatting using the Prettier formatter, which adjusts spacing, line-breaks, etc. as needed.

You can also validate your schemas and examples manually by executing the following command:

npm run validate

Submit Your Schema

Once your schema and examples are validated, commit your changes and open a GitHub pull request. See our GitHub primer for help with GitHub.

The GCN team will review and provide feedback. Once you have incorporated the feedback, we will merge your pull request into the main branch. Congratulations on successfully creating your mission schema! You can now use it to send notices to GCN as described in New Notice Producers.