Add ScanOrganic schema 1.0 #230
+215
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -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: | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| * 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`, `StarSystem`, `StarPos`, and (when available) `Latitude` and `Longitude` values | ||||||
|
Comment on lines
+35
to
+38
|
||||||
|
|
||||||
| ### 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. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 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`. | ||||||
|
|
||||||
|
Comment on lines
+72
to
+93
Member
There was a problem hiding this comment. Remove the data accumulation process in lines 72-93? |
||||||
| #### 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. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" ] } } | ||
| } | ||
| } |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.