diff --git a/schemas/scanorganic-README.md b/schemas/scanorganic-README.md new file mode 100644 index 0000000..f9c2877 --- /dev/null +++ b/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. diff --git a/schemas/scanorganic-v1.0.json b/schemas/scanorganic-v1.0.json new file mode 100644 index 0000000..9e21214 --- /dev/null +++ b/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" ] } } + } +}