From d10b081be4d284c64112176a08b37a98cf96f9b4 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Sun, 29 May 2022 14:17:30 +0100 Subject: [PATCH] docs: Outline rules and caveats about data Augmentations * Many will need a location cross-check. * Call out this need in the fssbodysignals README. --- docs/Developers.md | 42 ++++++++++++++++++++++++++++++++ schemas/fssbodysignals-README.md | 6 +++++ 2 files changed, 48 insertions(+) diff --git a/docs/Developers.md b/docs/Developers.md index 247e381..ef846ef 100644 --- a/docs/Developers.md +++ b/docs/Developers.md @@ -301,6 +301,48 @@ Horizons-only features disabled. active, but in the non-Odyssey game client case you only get the Horizons boolean. +#### Other data Augmentations +Some schemas mandate that extra data be added, beyond what is in the source +data, to aid Listeners. + +This is usually related to specifying which system an event took place in, and +usually means ensuring there is the full set of: + +1. `StarSystem` - the name of the system. +2. `SystemAddress` - the game's unique numerical identifier for the system. +3. `StarPos` - The system's co-ordinates. + +Whilst it can be argued that any Listener should see preceding event(s) that +give any missing information where at least the system name or `SystemAddress` +is already in the event data, this might not always be true. So Senders MUST +add this data where required. It helps to fill out basic system information +(name, SystemAddress and co-ordinates). + +However, there is a known game bug that can result in it stopping writing to +the game journal, and some observed behaviour implies that it might then later +resume writing to that file, but with events missing. This means any Sender +that blindly assumes it knows the current system/location and uses that for +these Augmentations might send erroneous data. + +1. **Senders MUST cross-check available event data with prior 'location' + event(s) to be sure the correct extra data is being added.** +2. **Listeners SHOULD realise that any data added as an Augmentation might be + in error.** + +For Senders, if the source data only has `SystemAddress` then you MUST check +that it matches that from the prior `Location`, `FSDJump` or `CarrierJump` +event before adding `StarSystem` and `StarPos` data to a message. Drop the +message entirely if it does not match. Apply similar logic if it is only +the system's name that is already present in data. Do not blindly add +`SystemAddress` or `StarPos`. Likewise, do not blindly add `StarPos` if the +other data is already in the source, without cross-checking the system name +and `SystemAddress`. + +Listeners might be able to apply their own cross-check on received messages, +and use any mismatch with respect to what they already know to make a decision +whether to trust the augmented data. Flagging it for manual review is probably +wise. + ### Server responses There are three possible sources of HTTP responses when sending an upload to EDDN. diff --git a/schemas/fssbodysignals-README.md b/schemas/fssbodysignals-README.md index d66c028..10122a3 100644 --- a/schemas/fssbodysignals-README.md +++ b/schemas/fssbodysignals-README.md @@ -28,10 +28,16 @@ in the Developers' documentation. You MUST add a `StarSystem` string containing the name of the system 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).** + #### 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).** + #### Remove _Localised key/values All keys whose name ends with `_Localised`, i.e. the `Type_Localised` key/values in Signals.