From 651add8a4cff43fb943ff4ae3b25a7c505fc9aec Mon Sep 17 00:00:00 2001 From: Jeremy Rimpo Date: Sat, 19 Apr 2025 21:16:40 -0500 Subject: [PATCH 1/6] Add ScanOrganic schema 1.0 --- schemas/scanorganic-README.md | 84 ++++++++++++++++++++++++++++ schemas/scanorganic-v1.0.json | 102 ++++++++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 schemas/scanorganic-README.md create mode 100644 schemas/scanorganic-v1.0.json diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md new file mode 100644 index 0000000..27af4d8 --- /dev/null +++ b/schemas/scanorganic-README.md @@ -0,0 +1,84 @@ +# EDDN ScanOrganic Schema + +## Introduction +Here we document how to take data from an ED `ScanOrganic` Journal Event and +properly structure it for sending to EDDN. + +Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general +documentation for a schema such as this. + +If you find any discrepancies between what this document says and what is +defined in the relevant Schema file, then you should, in the first instance, +assume that it is the Schema file that is correct. +**PLEASE open +[an issue on GitHub](https://github.com/EDCD/EDDN/issues/new/choose) +to report any such anomalies you find so that we can check and resolve the +discrepancy.** + +## Senders +The primary data source for this schema is the ED Journal event `ScanOrganic`. + +### ScanType +The 'Analyse' scan type only triggers when you have the scan tool out for a +long enough duration following your third scan. It's possible to put away the +tool before this completes and the event will then trigger the next time the +tool is used, which could be in another system entirely. For this reason, +it may report incorrect data and is thus excluded from submission. + +### Variant +Variant should be reported if present. It was not included in older journal +versions and therefore is not required to facilitate older journal submissions. + +### Augmentations +#### horizons and odyssey flags +Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) +in the Developers' documentation. + +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. + +#### StarSystem +You MUST add a StarSystem key/value pair representing the name of the system +this event occurred in. Source this from either Location, FSDJump or +CarrierJump as appropriate. + +**You MUST apply a location cross-check, as per +[Other data augmentations](../docs/Developers.md#other-data-augmentations).** + +#### StarPos +You MUST add a `StarPos` array containing the system co-ordinates from the +last `FSDJump`, `CarrierJump`, or `Location` event. + +**You MUST apply a location cross-check, as per +[Other data augmentations](../docs/Developers.md#other-data-augmentations).** + +#### BodyID and BodyName +BodyID is already present in the form of the 'Body' key. This should be +renamed to BodyID to mirror many other events. + +You MUST track `BodyName` both from Status.json *and* also from some +Journal events in order to cross-check it before using the `Body` from +Journal events. + +The following is correct as of game version 4.0.0.801 (Odyssey initial +release, Update 7, plus one patch). + +1. Record `journal_body_name` and `journal_body_id` from the + `BodyName` and `BodyID` values in `ApproachBody` events. + + This will occur when the player flies below Orbital Cruise altitude + around a body. +2. Also record these from `Location` events to cover logging in already there. +3. Unset both `journal_body_name` and `journal_body_id` on `LeaveBody` and + `FSDJump` events. + Do NOT do so for `SupercruiseEntry`, because a player can enter supercruise + below max Orbital Cruise altitude and then come back down without a new + `ApproachBody` event occurring. +4. If Status.json has `BodyName` present, record that as `status_body_name`. + + This key and its value will be present whenever the player comes close + enough to a body for the Orbital Cruise/Glide HUD elements to appear. + It will disappear again when they fly back above that altitude, or jump + away. +5. If Status.json does **not** have `BodyName` then clear `status_body_name`. diff --git a/schemas/scanorganic-v1.0.json b/schemas/scanorganic-v1.0.json new file mode 100644 index 0000000..e788b03 --- /dev/null +++ b/schemas/scanorganic-v1.0.json @@ -0,0 +1,102 @@ +{ + "$schema" : "http://json-schema.org/draft-04/scanorganic#", + "id" : "https://eddn.edcd.io/schemas/scanorganic/1", + "type" : "object", + "additionalProperties" : false, + "required": [ "$schemaRef", "header", "message" ], + "properties": { + "$schemaRef": { + "type" : "string" + }, + "header": { + "type" : "object", + "additionalProperties" : true, + "required" : [ "uploaderID", "softwareName", "softwareVersion" ], + "properties" : { + "uploaderID": { + "type" : "string" + }, + "softwareName": { + "type" : "string" + }, + "softwareVersion": { + "type" : "string" + }, + "gatewayTimestamp": { + "type" : "string", + "format" : "date-time", + "description" : "Timestamp upon receipt at the gateway. If present, this property will be overwritten by the gateway; submitters are not intended to populate this property." + } + } + }, + "message": { + "type" : "object", + "description" : "Contains all properties from the listed events in the client's journal minus the Localised strings and the properties marked below as 'disallowed'", + "additionalProperties" : false, + "required" : [ "timestamp", "event", "ScanType", "Genus", "Species", "SystemAddress", "BodyID", "BodyName"], + "properties" : { + "timestamp": { + "type" : "string", + "format" : "date-time" + }, + "event" : { + "enum" : [ "ScanOrganic" ] + }, + "horizons": { + "type" : "boolean", + "description" : "Boolean value copied from the Journal LoadGame event, when it is present there." + }, + "odyssey": { + "type" : "boolean", + "description" : "Boolean value copied from the Journal LoadGame event, when it is present there." + }, + "StarPos": { + "type" : "array", + "items" : { "type": "number" }, + "minItems" : 3, + "maxItems" : 3, + "description" : "Must be added by the sender" + }, + "ScanType": { + "enum" : ["Log", "Sample"], + "description" : "Scan level of the scan; can be 'Log', 'Sample', or 'Analyse'. 'Analyse' can give bad location data and is excluded." + }, + "Genus": { + "type" : "string", + "minLength" : 1, + "description" : "Internal ID of bio genus string." + }, + "Species": { + "type" : "string", + "minLength" : 1, + "description" : "Internal ID of bio species string." + }, + "Variant": { + "type" : "string", + "minLength" : 1, + "description" : "Internal ID of bio variant string. This mirrors the CodexEntry name." + }, + "SystemAddress": { + "type" : "integer" + }, + "Body": { + "type" : "integer", + "renamed" : "BodyID", + "description" : "Body ID is reported as 'Body' in this event. Rename to BodyID for general cross-compatibility." + }, + "BodyID": { + "type" : "integer" + }, + "BodyName": { + "type" : "string" + } + }, + "patternProperties": { + "_Localised$" : { "$ref" : "#/definitions/disallowed" } + } + } + }, + "definitions": { + "disallowed" : { "not" : { "type": [ "array", "boolean", "integer", "number", "null", "object", "string" ] } } + } +} From a3724363c8e54c8000da0af6dfe613559df940d2 Mon Sep 17 00:00:00 2001 From: Jeremy Rimpo Date: Sat, 19 Apr 2025 21:50:23 -0500 Subject: [PATCH 2/6] Add lat/long and other corrections --- schemas/scanorganic-README.md | 6 ++++++ schemas/scanorganic-v1.0.json | 13 +++++++++++-- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md index 27af4d8..8909d3a 100644 --- a/schemas/scanorganic-README.md +++ b/schemas/scanorganic-README.md @@ -82,3 +82,9 @@ release, Update 7, plus one patch). It will disappear again when they fly back above that altitude, or jump away. 5. If Status.json does **not** have `BodyName` then clear `status_body_name`. + +#### Latitude / Longitude +While latitude and longitude are not reported with the event data, this event +necessitates being on a planet surface. Pulling the current coordinates from +the `Status.json` should be sufficient to populate the data. The `Status.json` +granularity is quite accurate when on-foot. diff --git a/schemas/scanorganic-v1.0.json b/schemas/scanorganic-v1.0.json index e788b03..e0f6fbc 100644 --- a/schemas/scanorganic-v1.0.json +++ b/schemas/scanorganic-v1.0.json @@ -33,7 +33,7 @@ "type" : "object", "description" : "Contains all properties from the listed events in the client's journal minus the Localised strings and the properties marked below as 'disallowed'", "additionalProperties" : false, - "required" : [ "timestamp", "event", "ScanType", "Genus", "Species", "SystemAddress", "BodyID", "BodyName"], + "required" : [ "timestamp", "event", "ScanType", "Genus", "Species", "Latitude", "Longitude", "SystemAddress", "BodyID", "BodyName"], "properties" : { "timestamp": { "type" : "string", @@ -88,7 +88,16 @@ "type" : "integer" }, "BodyName": { - "type" : "string" + "type" : "string", + "description" : "Must be added by the sender to corroborate BodyID" + }, + "Latitude": { + "type" : "number", + "description" : "Must be added by the sender, generally from Status.json" + }, + "Longitude": { + "type" : "number", + "description" : "Must be added by the sender, generally from Status.json" } }, "patternProperties": { From a24fa98067764311c95dc548000411888936ff5c Mon Sep 17 00:00:00 2001 From: Jeremy Rimpo Date: Sat, 26 Apr 2025 00:28:49 -0500 Subject: [PATCH 3/6] Applying changes as per discussion --- schemas/scanorganic-README.md | 23 ++++++++++++++++------- schemas/scanorganic-v1.0.json | 10 +++++----- 2 files changed, 21 insertions(+), 12 deletions(-) diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md index 8909d3a..52aed50 100644 --- a/schemas/scanorganic-README.md +++ b/schemas/scanorganic-README.md @@ -57,9 +57,9 @@ last `FSDJump`, `CarrierJump`, or `Location` event. BodyID is already present in the form of the 'Body' key. This should be renamed to BodyID to mirror many other events. -You MUST track `BodyName` both from Status.json *and* also from some -Journal events in order to cross-check it before using the `Body` from -Journal events. +If proper synchronicity can be achieved, `BodyName` should be reported, +be it from Status.json or from some Journal events. Please cross-check it +as possible before using the `Body` from Journal events. The following is correct as of game version 4.0.0.801 (Odyssey initial release, Update 7, plus one patch). @@ -84,7 +84,16 @@ release, Update 7, plus one patch). 5. If Status.json does **not** have `BodyName` then clear `status_body_name`. #### Latitude / Longitude -While latitude and longitude are not reported with the event data, this event -necessitates being on a planet surface. Pulling the current coordinates from -the `Status.json` should be sufficient to populate the data. The `Status.json` -granularity is quite accurate when on-foot. +As live `Status.json` data is not always available, this augmentation is +optional. While latitude and longitude are not reported with the event data, +this event necessitates being on a planet surface. Pulling the current coordinates +from the `Status.json` should be sufficient to populate the data. Please ensure +the data is properly synced with the journal event. + +### Use of status.json +You are encouraged to augment your submission with values from status.json. When status.json is used: + +* You must verify that the timestamp from status.json is no more than one minute older than the timestamp from the `ScanOrganic` journal event +* You must verify that the status.json `Flags2` value `0x00000010` is true (indicating that the commander is on-foot on a planet) +* You must verify that the `BodyName` from status.json and journal events are in agreement +* Please augment your submission with `BodyName`, `Latitude`, and `Longitude` values diff --git a/schemas/scanorganic-v1.0.json b/schemas/scanorganic-v1.0.json index e0f6fbc..5183aae 100644 --- a/schemas/scanorganic-v1.0.json +++ b/schemas/scanorganic-v1.0.json @@ -33,7 +33,7 @@ "type" : "object", "description" : "Contains all properties from the listed events in the client's journal minus the Localised strings and the properties marked below as 'disallowed'", "additionalProperties" : false, - "required" : [ "timestamp", "event", "ScanType", "Genus", "Species", "Latitude", "Longitude", "SystemAddress", "BodyID", "BodyName"], + "required" : [ "timestamp", "event", "ScanType", "Genus", "Species", "SystemAddress", "BodyID"], "properties" : { "timestamp": { "type" : "string", @@ -74,7 +74,7 @@ "Variant": { "type" : "string", "minLength" : 1, - "description" : "Internal ID of bio variant string. This mirrors the CodexEntry name." + "description" : "Internal ID of bio variant string. This mirrors the CodexEntry name. Not present in older journal files." }, "SystemAddress": { "type" : "integer" @@ -89,15 +89,15 @@ }, "BodyName": { "type" : "string", - "description" : "Must be added by the sender to corroborate BodyID" + "description" : "Optional. Must be added by the sender, perhaps from Status.json." }, "Latitude": { "type" : "number", - "description" : "Must be added by the sender, generally from Status.json" + "description" : "Optional. Must be added by the sender, typically from Status.json." }, "Longitude": { "type" : "number", - "description" : "Must be added by the sender, generally from Status.json" + "description" : "Optional. Must be added by the sender, typically from Status.json." } }, "patternProperties": { From 0e0d5db263ed9e73158fc230c2c5c6d26a784502 Mon Sep 17 00:00:00 2001 From: Jeremy Rimpo Date: Sat, 26 Apr 2025 00:30:26 -0500 Subject: [PATCH 4/6] Move status.json readme text --- schemas/scanorganic-README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md index 52aed50..f9c2877 100644 --- a/schemas/scanorganic-README.md +++ b/schemas/scanorganic-README.md @@ -29,6 +29,14 @@ it may report incorrect data and is thus excluded from submission. Variant should be reported if present. It was not included in older journal versions and therefore is not required to facilitate older journal submissions. +### Use of status.json +You are encouraged to augment your submission with values from status.json. When status.json is used: + +* You must verify that the timestamp from status.json is no more than one minute older than the timestamp from the `ScanOrganic` journal event +* You must verify that the status.json `Flags2` value `0x00000010` is true (indicating that the commander is on-foot on a planet) +* You must verify that the `BodyName` from status.json and journal events are in agreement +* Please augment your submission with `BodyName`, `Latitude`, and `Longitude` values + ### Augmentations #### horizons and odyssey flags Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) @@ -89,11 +97,3 @@ optional. While latitude and longitude are not reported with the event data, this event necessitates being on a planet surface. Pulling the current coordinates from the `Status.json` should be sufficient to populate the data. Please ensure the data is properly synced with the journal event. - -### Use of status.json -You are encouraged to augment your submission with values from status.json. When status.json is used: - -* You must verify that the timestamp from status.json is no more than one minute older than the timestamp from the `ScanOrganic` journal event -* You must verify that the status.json `Flags2` value `0x00000010` is true (indicating that the commander is on-foot on a planet) -* You must verify that the `BodyName` from status.json and journal events are in agreement -* Please augment your submission with `BodyName`, `Latitude`, and `Longitude` values From 8be89a51d9ea2b4ef7b34a6c9c689fa13a201288 Mon Sep 17 00:00:00 2001 From: Jeremy Rimpo Date: Sun, 9 Nov 2025 15:38:30 -0600 Subject: [PATCH 5/6] Make StarSystem required, remove StarPos as per discussion --- schemas/scanorganic-README.md | 7 ------- schemas/scanorganic-v1.0.json | 10 ++++------ 2 files changed, 4 insertions(+), 13 deletions(-) diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md index f9c2877..64093ff 100644 --- a/schemas/scanorganic-README.md +++ b/schemas/scanorganic-README.md @@ -54,13 +54,6 @@ CarrierJump as appropriate. **You MUST apply a location cross-check, as per [Other data augmentations](../docs/Developers.md#other-data-augmentations).** -#### StarPos -You MUST add a `StarPos` array containing the system co-ordinates from the -last `FSDJump`, `CarrierJump`, or `Location` event. - -**You MUST apply a location cross-check, as per -[Other data augmentations](../docs/Developers.md#other-data-augmentations).** - #### BodyID and BodyName BodyID is already present in the form of the 'Body' key. This should be renamed to BodyID to mirror many other events. diff --git a/schemas/scanorganic-v1.0.json b/schemas/scanorganic-v1.0.json index 5183aae..2b34bbb 100644 --- a/schemas/scanorganic-v1.0.json +++ b/schemas/scanorganic-v1.0.json @@ -33,7 +33,7 @@ "type" : "object", "description" : "Contains all properties from the listed events in the client's journal minus the Localised strings and the properties marked below as 'disallowed'", "additionalProperties" : false, - "required" : [ "timestamp", "event", "ScanType", "Genus", "Species", "SystemAddress", "BodyID"], + "required" : [ "timestamp", "event", "StarSystem", "ScanType", "Genus", "Species", "SystemAddress", "BodyID"], "properties" : { "timestamp": { "type" : "string", @@ -50,11 +50,9 @@ "type" : "boolean", "description" : "Boolean value copied from the Journal LoadGame event, when it is present there." }, - "StarPos": { - "type" : "array", - "items" : { "type": "number" }, - "minItems" : 3, - "maxItems" : 3, + "StarSystem": { + "type" : "string", + "minLength" : 1, "description" : "Must be added by the sender" }, "ScanType": { From bf7d75b978bfbde3753e4192417b95247da2f539 Mon Sep 17 00:00:00 2001 From: Jeremy Rimpo Date: Sun, 9 Nov 2025 15:42:18 -0600 Subject: [PATCH 6/6] Restore StarPos as per discussion --- schemas/scanorganic-README.md | 7 +++++++ schemas/scanorganic-v1.0.json | 9 ++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md index 64093ff..f9c2877 100644 --- a/schemas/scanorganic-README.md +++ b/schemas/scanorganic-README.md @@ -54,6 +54,13 @@ CarrierJump as appropriate. **You MUST apply a location cross-check, as per [Other data augmentations](../docs/Developers.md#other-data-augmentations).** +#### StarPos +You MUST add a `StarPos` array containing the system co-ordinates from the +last `FSDJump`, `CarrierJump`, or `Location` event. + +**You MUST apply a location cross-check, as per +[Other data augmentations](../docs/Developers.md#other-data-augmentations).** + #### BodyID and BodyName BodyID is already present in the form of the 'Body' key. This should be renamed to BodyID to mirror many other events. diff --git a/schemas/scanorganic-v1.0.json b/schemas/scanorganic-v1.0.json index 2b34bbb..9e21214 100644 --- a/schemas/scanorganic-v1.0.json +++ b/schemas/scanorganic-v1.0.json @@ -33,7 +33,7 @@ "type" : "object", "description" : "Contains all properties from the listed events in the client's journal minus the Localised strings and the properties marked below as 'disallowed'", "additionalProperties" : false, - "required" : [ "timestamp", "event", "StarSystem", "ScanType", "Genus", "Species", "SystemAddress", "BodyID"], + "required" : [ "timestamp", "event", "StarSystem", "StarPos", "ScanType", "Genus", "Species", "SystemAddress", "BodyID"], "properties" : { "timestamp": { "type" : "string", @@ -55,6 +55,13 @@ "minLength" : 1, "description" : "Must be added by the sender" }, + "StarPos": { + "type" : "array", + "items" : { "type": "number" }, + "minItems" : 3, + "maxItems" : 3, + "description" : "Must be added by the sender" + }, "ScanType": { "enum" : ["Log", "Sample"], "description" : "Scan level of the scan; can be 'Log', 'Sample', or 'Analyse'. 'Analyse' can give bad location data and is excluded."