Add ScanOrganic schema 1.0

schemas/scanorganic-README.md

@@ -0,0 +1,99 @@
+# 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.
+
+### 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)
+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.
+
+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).
+
+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`.
+
+#### Latitude / Longitude
+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.

schemas/scanorganic-v1.0.json

@@ -0,0 +1,116 @@
+{
+    "$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", "StarSystem", "StarPos", "ScanType", "Genus", "Species", "SystemAddress", "BodyID"],
+            "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."
+                },
+                "StarSystem": {
+                    "type"          : "string",
+                    "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."
+                },
+                "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. Not present in older journal files."
+                },
+                "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",
+                    "description"   : "Optional. Must be added by the sender, perhaps from Status.json."
+                },
+                "Latitude": {
+                    "type"          : "number",
+                    "description"   : "Optional. Must be added by the sender, typically from Status.json."
+                },
+                "Longitude": {
+                    "type"          : "number",
+                    "description"   : "Optional. Must be added by the sender, typically from Status.json."
+                }
+            },
+            "patternProperties": {
+                "_Localised$"       : { "$ref" : "#/definitions/disallowed" }
+            }
+        }
+    },
+    "definitions": {
+        "disallowed" : { "not" : { "type": [ "array", "boolean", "integer", "number", "null", "object", "string" ] } }
+    }
+}