007 - Re-entry Alert JSON File
Purpose
This design document proposes a design for Re-entry Alert JSON Files.
Context and scope
One of the key responsibilities for Monitor Space Hazards is to present alerts on re-entry events to users across the UK government and internationally. Each alert will include data provided in JSON files by the UK Space Agency’s (UKSA) Orbital Analysis team about the event in question.
A JSON file stores data in key-value pairs and arrays; the software it was made for then accesses the data. JSON allows developers to store various data types as human-readable code, with the keys serving as names and the values containing related data.
Goals and non-goals
The goal of this Design Doc is to articulate a design for the structure of the Re-entry Alert JSON Files.
Goals
- Develop a JSON file which includes all the data fields required for re-entry alerts
- Ensure the JSON file is simple to produce for the UKSA Orbital Analysis team
- Ensure the JSON file is well structured and easily digestible for those reviewing it
The actual design
The Re-entry Alert JSON Files underpinning re-entry alerts largely follow a simple structure of a list of key-value pairs, with values taking the form of a string, number or null. The key-value pairs appear in the same order that they appear in the re-entry alerts. For example:
"eventCode":"RE-20241003-001",
"reportNumber":1,
"reportTime":"2024-10-02T02:22:35",
This is the case for most of the event information found throughout the alert. However, there are two instances of more complex data structures in the form of nested objects and editable value fields.
Nested objects
There are also two examples of nested objects within the Re-entry Alert JSON File.
Firstly, nested objects are used to produce a re-entry overflight map, which renders 30,000 data points on a world map to represent potential re-entry locations of the re-entering object. In this instance, the latitude and longitude of each point on the map in nested within an array called “mapPoints”, as in the example below:
"mapPoints":[
{"latitude":33.856, "longitude":-77.0384},
{"latitude":33.856, "longitude":-77.0384},
{"latitude":33.856, "longitude":-77.0384}
],
Secondly, nested objects are used to record the (a) probability of re-entry and (b) overflight time of the re-entering object in different geographical regions, as in the example below:
"englandNation":[{
"probability":0.01,
"overflightTime":"2024-10-03T02:20:35"}],
"northernIrelandNation":[{
"probability":0.03,
"overflightTime":"2024-10-03T02:20:35"}],
"scotlandNation":[{
"probability":0.00,
"overflightTime":null}],
"walesNation":[{
"probability":0.00,
"overflightTime":null}],
Editable value fields
The re-entry alerts have been designed to enable UKSA staff members to edit alerts after they have been published (see Design Doc 016). Therefore, the JSON file includes a number of key-value pairs where the value field can be edited via a user editing interface. These fields are identified by the use of the word ‘Addition’ within the key, as in the example below:
"pressAttentionAddition":"We have not seen any press attention on this event.",
Alternatives considered
We also considered provision of data to the service via a CSV file; however, this data would have to be converted into a JSON in order to be parsed and presented on the front end. A JSON therefore offered a more streamlined approach.