From 78e92fb38df6347b0a628e555f1de3342884c419 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Wed, 14 Sep 2022 17:04:34 +0100 Subject: [PATCH 01/22] schemas: journal: Implement header->gameversion --- schemas/journal-README.md | 14 ++++++++++++++ schemas/journal-v1.0.json | 5 +++++ 2 files changed, 19 insertions(+) diff --git a/schemas/journal-README.md b/schemas/journal-README.md index c2aa572..99f56eb 100644 --- a/schemas/journal-README.md +++ b/schemas/journal-README.md @@ -65,6 +65,20 @@ The following keys+values should be removed from `Location` event data: - `SquadronFaction` from within the list of `Factions`. ### Augmentations +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 Odyssey + clients, use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + #### horizons flag You SHOULD add this key/value pair, using the value from the `LoadGame` event. diff --git a/schemas/journal-v1.0.json b/schemas/journal-v1.0.json index 341c6b5..6e7dd33 100644 --- a/schemas/journal-v1.0.json +++ b/schemas/journal-v1.0.json @@ -16,6 +16,11 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From cbbddad13ce694853f0ee5735603cd1e843d603b Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:09:24 +0100 Subject: [PATCH 02/22] schemas/journal: Add `gamebuild` to header as well --- schemas/journal-README.md | 18 ++++++++++++++++-- schemas/journal-v1.0.json | 5 +++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/schemas/journal-README.md b/schemas/journal-README.md index 99f56eb..2924876 100644 --- a/schemas/journal-README.md +++ b/schemas/journal-README.md @@ -73,12 +73,26 @@ You **MUST** always add this field **to the header object**. 2. If you are using the CAPI `/journal` endpoint to retrieve and process Journal events then: 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 Odyssey - clients, use its value. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but with the value `"CAPI"`. +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### horizons flag You SHOULD add this key/value pair, using the value from the `LoadGame` event. diff --git a/schemas/journal-v1.0.json b/schemas/journal-v1.0.json index 6e7dd33..d01fafa 100644 --- a/schemas/journal-v1.0.json +++ b/schemas/journal-v1.0.json @@ -21,6 +21,11 @@ "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From dfdec1182820486e34fbc44edd8690b7af515de0 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:23:50 +0100 Subject: [PATCH 03/22] schemas/journal: `horizons`/`odyssey` now mandatory --- schemas/journal-README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/schemas/journal-README.md b/schemas/journal-README.md index 2924876..a28d17b 100644 --- a/schemas/journal-README.md +++ b/schemas/journal-README.md @@ -94,10 +94,14 @@ You **MUST** always add this field **to the header object**. with the value `"CAPI"`. #### horizons flag -You SHOULD add this key/value pair, using the value from the `LoadGame` event. +You **MUST** add this key/value pair, using the value from the `LoadGame` event. + +Note caveats in [docs/Developers.md](../docs/Developers.md). #### odyssey flag -You SHOULD add this key/value pair, using the value from the `LoadGame` event. +You **MUST** add this key/value pair, using the value from the `LoadGame` event. + +Note caveats in [docs/Developers.md](../docs/Developers.md). #### StarSystem If not already present, you MUST add a `StarSystem` string containing the From 17648a9abdca3fafd7cc8862c4a021f5ea8e925f Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:37:16 +0100 Subject: [PATCH 04/22] schemas/approachsettlement: Add `gameversion`/`gamebuild` --- schemas/approachsettlement-README.md | 28 ++++++++++++++++++++++++++++ schemas/approachsettlement-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/approachsettlement-README.md b/schemas/approachsettlement-README.md index 93c8237..61dad84 100644 --- a/schemas/approachsettlement-README.md +++ b/schemas/approachsettlement-README.md @@ -58,6 +58,34 @@ Examples: Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarSystem You MUST add a StarSystem key/value pair representing the name of the system diff --git a/schemas/approachsettlement-v1.0.json b/schemas/approachsettlement-v1.0.json index b6e5ed8..424d4c3 100644 --- a/schemas/approachsettlement-v1.0.json +++ b/schemas/approachsettlement-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From 9a9e0f099165ca2a0a26c9b0ebb89a88dc21f860 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:38:53 +0100 Subject: [PATCH 05/22] schemas/codexentry: `gameversion` & `gamebuild` in header --- schemas/codexentry-README.md | 28 ++++++++++++++++++++++++++++ schemas/codexentry-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/codexentry-README.md b/schemas/codexentry-README.md index beb6555..dee769d 100644 --- a/schemas/codexentry-README.md +++ b/schemas/codexentry-README.md @@ -23,6 +23,34 @@ The primary data source for this schema is the ED Journal event `CodexEntry`. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the last `FSDJump`, `CarrierJump`, or `Location` event. diff --git a/schemas/codexentry-v1.0.json b/schemas/codexentry-v1.0.json index d191060..a2c4364 100644 --- a/schemas/codexentry-v1.0.json +++ b/schemas/codexentry-v1.0.json @@ -17,6 +17,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From 0bc7c90dfb13240c78dc5f175f61d7dcf0f303bb Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:39:52 +0100 Subject: [PATCH 06/22] schemas/commodity: `gameversion` & `gamebuild` in header --- schemas/commodity-README.md | 28 ++++++++++++++++++++++++++++ schemas/commodity-v3.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/commodity-README.md b/schemas/commodity-README.md index 3e155b6..3ceb378 100644 --- a/schemas/commodity-README.md +++ b/schemas/commodity-README.md @@ -60,6 +60,34 @@ Remove not only the `Category_Localised` key:values, but also the Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + ### Using CAPI data It is *not* recommended to use CAPI data as the source as it's fraught with additional issues. EDMarketConnector does so in order to facilitate diff --git a/schemas/commodity-v3.0.json b/schemas/commodity-v3.0.json index 60c5c78..8c004ff 100644 --- a/schemas/commodity-v3.0.json +++ b/schemas/commodity-v3.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From 15012a2b6e05836fc768e0cd496c5d9acfbf7d06 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:41:45 +0100 Subject: [PATCH 07/22] schemas/fcmaterials_journal: `gameversion` & `gamebuild` in header --- schemas/fcmaterials_journal-README.md | 28 +++++++++++++++++++++++++++ schemas/fcmaterials_journal-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/fcmaterials_journal-README.md b/schemas/fcmaterials_journal-README.md index 357da91..fbcc04c 100644 --- a/schemas/fcmaterials_journal-README.md +++ b/schemas/fcmaterials_journal-README.md @@ -33,6 +33,34 @@ of any augmentations, as noted below. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + ## Listeners The advice above for [Senders](#senders), combined with the actual Schema file *should* provide all the information you need to process these events. diff --git a/schemas/fcmaterials_journal-v1.0.json b/schemas/fcmaterials_journal-v1.0.json index 35bb080..62c5d9b 100644 --- a/schemas/fcmaterials_journal-v1.0.json +++ b/schemas/fcmaterials_journal-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From d5e3cdf8e9d3902f90f85090bf77fa87bf727de4 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:42:24 +0100 Subject: [PATCH 08/22] schemas/fssallbodiesfound: `gameversion` & `gamebuild` in header --- schemas/fssallbodiesfound-README.md | 28 ++++++++++++++++++++++++++++ schemas/fssallbodiesfound-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/fssallbodiesfound-README.md b/schemas/fssallbodiesfound-README.md index e535b32..35a883a 100644 --- a/schemas/fssallbodiesfound-README.md +++ b/schemas/fssallbodiesfound-README.md @@ -24,6 +24,34 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the last `FSDJump`, `CarrierJump`, or `Location` event. diff --git a/schemas/fssallbodiesfound-v1.0.json b/schemas/fssallbodiesfound-v1.0.json index 61ec184..18507d4 100644 --- a/schemas/fssallbodiesfound-v1.0.json +++ b/schemas/fssallbodiesfound-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From 1461eaf720f8a01f94ae47b224cb51b194fa407d Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:43:20 +0100 Subject: [PATCH 09/22] schemas/fssbodysignals: `gameversion` & `gamebuild` in header --- schemas/fssbodysignals-README.md | 28 ++++++++++++++++++++++++++++ schemas/fssbodysignals-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/fssbodysignals-README.md b/schemas/fssbodysignals-README.md index 10122a3..b2110d9 100644 --- a/schemas/fssbodysignals-README.md +++ b/schemas/fssbodysignals-README.md @@ -24,6 +24,34 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarSystem You MUST add a `StarSystem` string containing the name of the system from the last `FSDJump`, `CarrierJump`, or `Location` event. diff --git a/schemas/fssbodysignals-v1.0.json b/schemas/fssbodysignals-v1.0.json index 68ee08e..89bab05 100644 --- a/schemas/fssbodysignals-v1.0.json +++ b/schemas/fssbodysignals-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From 6c9986ec58722bb67c759ba47821527d9558db46 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:44:00 +0100 Subject: [PATCH 10/22] schemas/fssdiscoveryscan: `gameversion` & `gamebuild` in header --- schemas/fssdiscoveryscan-README.md | 28 ++++++++++++++++++++++++++++ schemas/fssdiscoveryscan-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/fssdiscoveryscan-README.md b/schemas/fssdiscoveryscan-README.md index f7c8757..014d44d 100644 --- a/schemas/fssdiscoveryscan-README.md +++ b/schemas/fssdiscoveryscan-README.md @@ -24,6 +24,34 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the last `FSDJump`, `CarrierJump`, or `Location` event. diff --git a/schemas/fssdiscoveryscan-v1.0.json b/schemas/fssdiscoveryscan-v1.0.json index 9751db1..f007fe0 100644 --- a/schemas/fssdiscoveryscan-v1.0.json +++ b/schemas/fssdiscoveryscan-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From fa9e17138172c615ab85f191f5cc0ef12af0ee18 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:44:44 +0100 Subject: [PATCH 11/22] schemas/fsssignaldiscovered: `gameversion` & `gamebuild` in header --- schemas/fsssignaldiscovered-README.md | 28 +++++++++++++++++++++++++++ schemas/fsssignaldiscovered-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md index ddbb9aa..6aab328 100644 --- a/schemas/fsssignaldiscovered-README.md +++ b/schemas/fsssignaldiscovered-README.md @@ -87,6 +87,34 @@ You SHOULD add this key/value pair, using the value from the `LoadGame` event. #### odyssey flag You SHOULD add this key/value pair, using the value from the `LoadGame` event. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarSystem You **MUST** add a `StarSystem` string containing the system name from the last tracked location. You **MUST** cross-check each `FSSSignalDiscovered` diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json index 18f8fef..0e30eaf 100644 --- a/schemas/fsssignaldiscovered-v1.0.json +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -17,6 +17,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From fdb59c2fa819ecc7d16a3a69684eb0bf1c2589fd Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:45:41 +0100 Subject: [PATCH 12/22] schemas/navbeaconscan: `gameversion` & `gamebuild` in header --- schemas/navbeaconscan-README.md | 28 ++++++++++++++++++++++++++++ schemas/navbeaconscan-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/navbeaconscan-README.md b/schemas/navbeaconscan-README.md index 09ecdef..75818eb 100644 --- a/schemas/navbeaconscan-README.md +++ b/schemas/navbeaconscan-README.md @@ -24,6 +24,34 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarSystem You MUST add a `StarSystem` key/value pair representing the name of the system this event occurred in. Source this from either `Location`, diff --git a/schemas/navbeaconscan-v1.0.json b/schemas/navbeaconscan-v1.0.json index b3fdc94..81e089c 100644 --- a/schemas/navbeaconscan-v1.0.json +++ b/schemas/navbeaconscan-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From e3a744a94b51d34a6e883a5291ec4085b54e31b0 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:46:31 +0100 Subject: [PATCH 13/22] schemas/navroute: `gameversion` & `gamebuild` in header --- schemas/navroute-README.md | 27 +++++++++++++++++++++++++++ schemas/navroute-v1.0.json | 10 ++++++++++ 2 files changed, 37 insertions(+) diff --git a/schemas/navroute-README.md b/schemas/navroute-README.md index 703c794..7315e39 100644 --- a/schemas/navroute-README.md +++ b/schemas/navroute-README.md @@ -31,3 +31,30 @@ separate file. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. diff --git a/schemas/navroute-v1.0.json b/schemas/navroute-v1.0.json index 4a5a83c..f160cd6 100644 --- a/schemas/navroute-v1.0.json +++ b/schemas/navroute-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From 33911c32093f4c4cee01f4b1d943c05efdf9fe5b Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:47:26 +0100 Subject: [PATCH 14/22] schemas/outfitting: `gameversion` & `gamebuild` in header --- schemas/outfitting-README.md | 28 ++++++++++++++++++++++++++++ schemas/outfitting-v2.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/outfitting-README.md b/schemas/outfitting-README.md index e3e18bf..6440bff 100644 --- a/schemas/outfitting-README.md +++ b/schemas/outfitting-README.md @@ -53,3 +53,31 @@ station. Namely: #### horizons and odyssey flags Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. + +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. diff --git a/schemas/outfitting-v2.0.json b/schemas/outfitting-v2.0.json index a8959e0..eab688e 100644 --- a/schemas/outfitting-v2.0.json +++ b/schemas/outfitting-v2.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From c8db0792d480ea1c04d600c480982ffdc78fb767 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:48:12 +0100 Subject: [PATCH 15/22] schemas/scanbarycentre: `gameversion` & `gamebuild` in header --- schemas/scanbarycentre-README.md | 28 ++++++++++++++++++++++++++++ schemas/scanbarycentre-v1.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/scanbarycentre-README.md b/schemas/scanbarycentre-README.md index 89c1ce6..9cea06e 100644 --- a/schemas/scanbarycentre-README.md +++ b/schemas/scanbarycentre-README.md @@ -27,6 +27,34 @@ senders SHOULD include any defined in the schema if it's in the source data. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. + #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the last `FSDJump`, `CarrierJump`, or `Location` event. diff --git a/schemas/scanbarycentre-v1.0.json b/schemas/scanbarycentre-v1.0.json index e019326..99df117 100644 --- a/schemas/scanbarycentre-v1.0.json +++ b/schemas/scanbarycentre-v1.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From e000bcc398f9be5f5a43ae64060274dd256f3c51 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:48:51 +0100 Subject: [PATCH 16/22] schemas/shipyard: `gameversion` & `gamebuild` in header --- schemas/shipyard-README.md | 28 ++++++++++++++++++++++++++++ schemas/shipyard-v2.0.json | 10 ++++++++++ 2 files changed, 38 insertions(+) diff --git a/schemas/shipyard-README.md b/schemas/shipyard-README.md index b1f32d9..8492651 100644 --- a/schemas/shipyard-README.md +++ b/schemas/shipyard-README.md @@ -40,3 +40,31 @@ value is what the name would have been in the source Journal data. #### horizons and odyssey flags Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. + +#### gameversion +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `gameversion` element from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but + with the value `"CAPI"`. + +#### gamebuild +You **MUST** always add this field **to the header object**. + +1. If you are using Journal files directly then you **MUST** use the value + of the `build` value from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use + its value. + 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but + with the value `"CAPI"`. diff --git a/schemas/shipyard-v2.0.json b/schemas/shipyard-v2.0.json index bb4fabd..3498e9b 100644 --- a/schemas/shipyard-v2.0.json +++ b/schemas/shipyard-v2.0.json @@ -16,6 +16,16 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "minLength" : 1, + "description" : "From Fileheader event if available, else LoadGame if available there." + }, + "gamebuild": { + "type" : "string", + "minLength" : 1, + "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + }, "softwareName": { "type" : "string" }, From a723fbd83b54ef158ed405aa51657d0a5f8983f8 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 14:50:05 +0100 Subject: [PATCH 17/22] docs/Developers: Fix 'i3' vim-induced typo --- docs/Developers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Developers.md b/docs/Developers.md index b77499e..8758e0c 100644 --- a/docs/Developers.md +++ b/docs/Developers.md @@ -285,7 +285,7 @@ PC-local files for these events): { "timestamp":"2022-09-27T11:28:53Z", "event":"LoadGame", "FID":"", "Commander":"", "Horizons":true, ... ``` -- PC 'base' Client, game version `i3.8.0.407`, no `Odyssey` key was +- PC 'base' Client, game version `3.8.0.407`, no `Odyssey` key was present: ```json { "timestamp":"2022-09-27T11:31:32Z", "event":"LoadGame", "FID":"", "Commander":"", "Horizons":false, ... From d57ab05ee3fbe3e6e9037418f8c83baec4644fbc Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 15:50:17 +0100 Subject: [PATCH 18/22] docs/Developers: Define `header` component field:values * Actually define what we expect from the existing fields. * Document what should go in the new `gameversion` and `gamebuild` fields. * Update the generic example to include all of these "what version of the game, or feature set, did this come from?" fields. --- docs/Developers.md | 56 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/Developers.md b/docs/Developers.md index 8758e0c..9aef715 100644 --- a/docs/Developers.md +++ b/docs/Developers.md @@ -175,6 +175,8 @@ For example, a shipyard message, version 2, might look like: "$schemaRef": "https://eddn.edcd.io/schemas/shipyard/2", "header": { "uploaderID": "Bill", + "gameversion": "4.0.0.1451", + "gamebuild": "r286916/r0 ", "softwareName": "My excellent app", "softwareVersion": "0.0.1" }, @@ -183,7 +185,8 @@ For example, a shipyard message, version 2, might look like: "stationName": "Samson", "marketId": 128023552, "horizons": true, - "timestamp": "2019-01-08T06:39:43Z", + "odyssey": true, + "timestamp": "2022-09-27T06:39:43Z", "ships": [ "anaconda", "dolphin", @@ -200,6 +203,57 @@ For example, a shipyard message, version 2, might look like: } ``` +--- + +### Contents of `header` +You **MUST** send the `header` component of the message. + +#### uploaderID +The EDDN Relay will obfuscate the `uploaderID` value to prevent long-term +tracking of individual players. Please **DO** send a sensible +`uploaderID` value, preferably simply the relevant in-game Commander name. + +#### softwareName +You **MUST** set a unique, and self-consistent, value of `softwareName` so +that you can be easily identified should any issues be found with the messages +you send. + +#### softwareVersion +You **MUST** set a pertinent value for `softwareVersion`. We would recommend +using [Semantic Versionining](https://semver.org/#semantic-versioning-specification-semver) +in your project. + +Listeners MAY make decisions on whether to accept data, or to treat it +differently, based on this. As such you **MUST** increment your version +number if you make any changes to the content of messages your software sends +to EDDN. + +#### `gameversions` and `gamebuild` +To ensure that Listeners can make decisions on how to handle data based on +the client and feature set it came from there are two mandatory fields in +the headers of EDDN messages. + +The `gameversion` value **MUST** come from the field of that name in either +`Fileheader` or `LoadGame` as outlined below. + +The `gamebuild` value **MUST** come from the value of the `build` field in +either `Fileheader` or `LoadGame` as outlined below. + +1. If you are using Journal files directly then you **MUST** use the value + from the`Fileheader` event. +2. If you are using the CAPI `/journal` endpoint to retrieve and process + Journal events then: + 1. You will not have `Fileheader` available. + 2. If the field is present in the `LoadGame` event, as in 4.0 clients, + use its value. + 3. If `LoadGame` does not have the field, as with 3.8 Horizons + clients (up to at least `3.8.0.407`), you **MUST** set the value to + `"CAPI"`. +3. If you are sourcing data from other CAPI endpoints, i.e. for commodity, + shipyard or outfitting messages, then simply set the values to `"CAPI"`. + +--- + ### Contents of `message` Every message MUST comply with the Schema its `$schemaRef` value cites. Each Schema file should have a matching `-README.md` file in the From aa99d3e0573aa3bb9792b932b3ea7656c0ad90d5 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 16:05:49 +0100 Subject: [PATCH 19/22] docs/Developers: Use `CAPI-` for gameversion/build It's the true source of the data, and less fraught with corner cases than trying to be sure that the Journal-derived values would be correct. --- docs/Developers.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/Developers.md b/docs/Developers.md index 9aef715..999c26f 100644 --- a/docs/Developers.md +++ b/docs/Developers.md @@ -248,9 +248,13 @@ either `Fileheader` or `LoadGame` as outlined below. use its value. 3. If `LoadGame` does not have the field, as with 3.8 Horizons clients (up to at least `3.8.0.407`), you **MUST** set the value to - `"CAPI"`. + `"CAPI-journal"`. 3. If you are sourcing data from other CAPI endpoints, i.e. for commodity, - shipyard or outfitting messages, then simply set the values to `"CAPI"`. + shipyard or outfitting messages, then simply set the values appropriately as + per the CAPI endpoint the data came from: + 1. If it's a commodity message then use `"CAPI-market"`. + 2. If it's a shipyard message then use `"CAPI-shipyard"`. + 3. If it's an oufitting message then also use `"CAPI-shipyard"`. --- From 6046c0a6d7b6e25275f68223be463539652ac9e8 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 27 Sep 2022 16:20:59 +0100 Subject: [PATCH 20/22] schemas: Refer to Developers.md about gameversion/build. --- schemas/approachsettlement-README.md | 30 +++------------------------ schemas/codexentry-README.md | 30 +++------------------------ schemas/commodity-README.md | 30 +++------------------------ schemas/fcmaterials_capi-README.md | 4 ++++ schemas/fcmaterials_journal-README.md | 30 +++------------------------ schemas/fssallbodiesfound-README.md | 30 +++------------------------ schemas/fssbodysignals-README.md | 30 +++------------------------ schemas/fssdiscoveryscan-README.md | 30 +++------------------------ schemas/fsssignaldiscovered-README.md | 30 +++------------------------ schemas/journal-README.md | 30 +++------------------------ schemas/navbeaconscan-README.md | 30 +++------------------------ schemas/navroute-README.md | 29 +++----------------------- schemas/outfitting-README.md | 29 +++----------------------- schemas/scanbarycentre-README.md | 30 +++------------------------ schemas/shipyard-README.md | 29 +++----------------------- 15 files changed, 46 insertions(+), 375 deletions(-) diff --git a/schemas/approachsettlement-README.md b/schemas/approachsettlement-README.md index 61dad84..7845e21 100644 --- a/schemas/approachsettlement-README.md +++ b/schemas/approachsettlement-README.md @@ -58,33 +58,9 @@ Examples: Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. #### StarSystem diff --git a/schemas/codexentry-README.md b/schemas/codexentry-README.md index dee769d..3495bed 100644 --- a/schemas/codexentry-README.md +++ b/schemas/codexentry-README.md @@ -23,33 +23,9 @@ The primary data source for this schema is the ED Journal event `CodexEntry`. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the diff --git a/schemas/commodity-README.md b/schemas/commodity-README.md index 3ceb378..220363a 100644 --- a/schemas/commodity-README.md +++ b/schemas/commodity-README.md @@ -60,33 +60,9 @@ Remove not only the `Category_Localised` key:values, but also the Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. ### Using CAPI data It is *not* recommended to use CAPI data as the source as it's fraught with diff --git a/schemas/fcmaterials_capi-README.md b/schemas/fcmaterials_capi-README.md index a76f136..da2b040 100644 --- a/schemas/fcmaterials_capi-README.md +++ b/schemas/fcmaterials_capi-README.md @@ -57,6 +57,10 @@ You **MUST NOT** set them otherwise, as e.g. the player could be active in the game on another computer, using a different game mode and the CAPI data will be for that game mode. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. + ## Listeners The advice above for [Senders](#senders), combined with the actual Schema file *should* provide all the information you need to process these events. diff --git a/schemas/fcmaterials_journal-README.md b/schemas/fcmaterials_journal-README.md index fbcc04c..bf14d02 100644 --- a/schemas/fcmaterials_journal-README.md +++ b/schemas/fcmaterials_journal-README.md @@ -33,33 +33,9 @@ of any augmentations, as noted below. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. ## Listeners The advice above for [Senders](#senders), combined with the actual Schema file diff --git a/schemas/fssallbodiesfound-README.md b/schemas/fssallbodiesfound-README.md index 35a883a..8c186c3 100644 --- a/schemas/fssallbodiesfound-README.md +++ b/schemas/fssallbodiesfound-README.md @@ -24,33 +24,9 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the diff --git a/schemas/fssbodysignals-README.md b/schemas/fssbodysignals-README.md index b2110d9..7582514 100644 --- a/schemas/fssbodysignals-README.md +++ b/schemas/fssbodysignals-README.md @@ -24,33 +24,9 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### 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` string containing the name of the system from the diff --git a/schemas/fssdiscoveryscan-README.md b/schemas/fssdiscoveryscan-README.md index 014d44d..8e3e1f9 100644 --- a/schemas/fssdiscoveryscan-README.md +++ b/schemas/fssdiscoveryscan-README.md @@ -24,33 +24,9 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md index 6aab328..6889dbc 100644 --- a/schemas/fsssignaldiscovered-README.md +++ b/schemas/fsssignaldiscovered-README.md @@ -87,33 +87,9 @@ You SHOULD add this key/value pair, using the value from the `LoadGame` event. #### odyssey flag You SHOULD add this key/value pair, using the value from the `LoadGame` event. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### 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` string containing the system name from the last diff --git a/schemas/journal-README.md b/schemas/journal-README.md index a28d17b..a59865b 100644 --- a/schemas/journal-README.md +++ b/schemas/journal-README.md @@ -65,33 +65,9 @@ The following keys+values should be removed from `Location` event data: - `SquadronFaction` from within the list of `Factions`. ### Augmentations -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. #### horizons flag You **MUST** add this key/value pair, using the value from the `LoadGame` event. diff --git a/schemas/navbeaconscan-README.md b/schemas/navbeaconscan-README.md index 75818eb..de14f12 100644 --- a/schemas/navbeaconscan-README.md +++ b/schemas/navbeaconscan-README.md @@ -24,33 +24,9 @@ The primary data source for this schema is the ED Journal event Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### 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 diff --git a/schemas/navroute-README.md b/schemas/navroute-README.md index 7315e39..5358df8 100644 --- a/schemas/navroute-README.md +++ b/schemas/navroute-README.md @@ -31,30 +31,7 @@ separate file. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. diff --git a/schemas/outfitting-README.md b/schemas/outfitting-README.md index 6440bff..f9a405c 100644 --- a/schemas/outfitting-README.md +++ b/schemas/outfitting-README.md @@ -54,30 +54,7 @@ station. Namely: Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. diff --git a/schemas/scanbarycentre-README.md b/schemas/scanbarycentre-README.md index 9cea06e..11353bb 100644 --- a/schemas/scanbarycentre-README.md +++ b/schemas/scanbarycentre-README.md @@ -27,33 +27,9 @@ senders SHOULD include any defined in the schema if it's in the source data. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the diff --git a/schemas/shipyard-README.md b/schemas/shipyard-README.md index 8492651..0b3ac58 100644 --- a/schemas/shipyard-README.md +++ b/schemas/shipyard-README.md @@ -41,30 +41,7 @@ value is what the name would have been in the source Journal data. Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. -#### gameversion -You **MUST** always add this field **to the header object**. +#### gameversion and gamebuild +You **MUST** always set these as per [the relevant section](../docs/Developers.md#gameversions-and-gamebuild) +of the Developers' documentation. -1. If you are using Journal files directly then you **MUST** use the value - of the `gameversion` element from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `gameversion` is present in the `LoadGame` event, as in 4.0 clients, - use its value. - 3. If `LoadGame` does not have a `gameversion` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gameversion`, but - with the value `"CAPI"`. - -#### gamebuild -You **MUST** always add this field **to the header object**. - -1. If you are using Journal files directly then you **MUST** use the value - of the `build` value from the`Fileheader` event. -2. If you are using the CAPI `/journal` endpoint to retrieve and process - Journal events then: - 1. You will not have `Fileheader` available. - 2. If `build` is present in the `LoadGame` event, as in 4.0 clients, use - its value. - 3. If `LoadGame` does not have a `build` element, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set `gamebuild`, but - with the value `"CAPI"`. From 1df10328860ab1e7acb702ad6ac3a60d21c0583e Mon Sep 17 00:00:00 2001 From: Athanasius Date: Thu, 29 Sep 2022 14:58:35 +0100 Subject: [PATCH 21/22] docs/Developers: Allow for `""` gameversion/build values. The emphasis here is on strongly encouraging Senders to get the actual, full and correct, values to Listeners. But where they can't, be that due to data source limitations (CAPI), or their code architecture (common EDDN sending code that has no concept of the data source), they're allowed to send a less than optimal value. **BUT**, they still should start sending the fields as outlined. --- docs/Developers.md | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/Developers.md b/docs/Developers.md index 999c26f..824b271 100644 --- a/docs/Developers.md +++ b/docs/Developers.md @@ -231,13 +231,16 @@ to EDDN. #### `gameversions` and `gamebuild` To ensure that Listeners can make decisions on how to handle data based on the client and feature set it came from there are two mandatory fields in -the headers of EDDN messages. +the headers of EDDN messages. NB: Initially the *schemas* do not actually +make these mandatory, **but all Senders should make every effort to include +them ASAP**. -The `gameversion` value **MUST** come from the field of that name in either -`Fileheader` or `LoadGame` as outlined below. +Where present in the data source the `gameversion` value **MUST** come from +the field of that name in the data source, i.e. from either `Fileheader` or +`LoadGame` as outlined below. -The `gamebuild` value **MUST** come from the value of the `build` field in -either `Fileheader` or `LoadGame` as outlined below. +For `gamebuild` you **MUST** use the value of the `build` field in the data +source. 1. If you are using Journal files directly then you **MUST** use the value from the`Fileheader` event. @@ -247,14 +250,22 @@ either `Fileheader` or `LoadGame` as outlined below. 2. If the field is present in the `LoadGame` event, as in 4.0 clients, use its value. 3. If `LoadGame` does not have the field, as with 3.8 Horizons - clients (up to at least `3.8.0.407`), you **MUST** set the value to - `"CAPI-journal"`. + clients (up to at least `3.8.0.407`), you **SHOULD** set the value to + `"CAPI-journal"`. If, for reasons of code architecture, you are unable to + determine that data was CAPI-sourced then you MAY set it to `""` instead. 3. If you are sourcing data from other CAPI endpoints, i.e. for commodity, - shipyard or outfitting messages, then simply set the values appropriately as - per the CAPI endpoint the data came from: - 1. If it's a commodity message then use `"CAPI-market"`. - 2. If it's a shipyard message then use `"CAPI-shipyard"`. - 3. If it's an oufitting message then also use `"CAPI-shipyard"`. + shipyard or outfitting messages, then you **SHOULD** set the values + appropriately as per the CAPI endpoint the data came from: + 1. If it's a commodity message, then use `"CAPI-market"`. + 2. If it's a shipyard message, then use `"CAPI-shipyard"`. + 3. If it's an oufitting message, then also use `"CAPI-shipyard"`. + + Again, if your code architecture doesn't allow for signalling that the data + source was CAPI, then you MAY set it to `""` instead. + +For emphasis, **if you cannot set a data-source value, or an appropriate +`"CAPI-..."` value then you **MUST** still send the field with an empty string +value. --- From 1999f52e97c3c857d88d08d1d136890051a3c6ef Mon Sep 17 00:00:00 2001 From: Athanasius Date: Thu, 29 Sep 2022 15:18:52 +0100 Subject: [PATCH 22/22] schemas: Update for allowing `""` gameversion/build * Also has specific description text for the CAPI data source schemas. --- schemas/approachsettlement-v1.0.json | 2 -- schemas/codexentry-v1.0.json | 2 -- schemas/commodity-v3.0.json | 6 ++---- schemas/fcmaterials_capi-v1.0.json | 8 ++++++++ schemas/fcmaterials_journal-v1.0.json | 2 -- schemas/fssallbodiesfound-v1.0.json | 2 -- schemas/fssbodysignals-v1.0.json | 2 -- schemas/fssdiscoveryscan-v1.0.json | 2 -- schemas/fsssignaldiscovered-v1.0.json | 2 -- schemas/journal-v1.0.json | 2 -- schemas/navbeaconscan-v1.0.json | 2 -- schemas/navroute-v1.0.json | 2 -- schemas/outfitting-v2.0.json | 6 ++---- schemas/scanbarycentre-v1.0.json | 2 -- schemas/shipyard-v2.0.json | 6 ++---- 15 files changed, 14 insertions(+), 34 deletions(-) diff --git a/schemas/approachsettlement-v1.0.json b/schemas/approachsettlement-v1.0.json index 424d4c3..1af5052 100644 --- a/schemas/approachsettlement-v1.0.json +++ b/schemas/approachsettlement-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/codexentry-v1.0.json b/schemas/codexentry-v1.0.json index a2c4364..537240f 100644 --- a/schemas/codexentry-v1.0.json +++ b/schemas/codexentry-v1.0.json @@ -19,12 +19,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/commodity-v3.0.json b/schemas/commodity-v3.0.json index 8c004ff..4609ace 100644 --- a/schemas/commodity-v3.0.json +++ b/schemas/commodity-v3.0.json @@ -18,13 +18,11 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, - "description" : "From Fileheader event if available, else LoadGame if available there." + "description" : "Fileheader->gameversion, else LoadGame->gameversion, else 'CAPI-market', else ''." }, "gamebuild": { "type" : "string", - "minLength" : 1, - "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + "description" : "Fileheader->build, else LoadGame->build, else 'CAPI-market', else ''." }, "softwareName": { "type" : "string" diff --git a/schemas/fcmaterials_capi-v1.0.json b/schemas/fcmaterials_capi-v1.0.json index 49edb06..0b3f2be 100644 --- a/schemas/fcmaterials_capi-v1.0.json +++ b/schemas/fcmaterials_capi-v1.0.json @@ -16,6 +16,14 @@ "uploaderID": { "type" : "string" }, + "gameversion": { + "type" : "string", + "description" : "Value of 'CAPI-market' if possible, else empty string." + }, + "gamebuild": { + "type" : "string", + "description" : "Value of 'CAPI-market' if possible, else empty string." + }, "softwareName": { "type" : "string" }, diff --git a/schemas/fcmaterials_journal-v1.0.json b/schemas/fcmaterials_journal-v1.0.json index 62c5d9b..26e4b88 100644 --- a/schemas/fcmaterials_journal-v1.0.json +++ b/schemas/fcmaterials_journal-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/fssallbodiesfound-v1.0.json b/schemas/fssallbodiesfound-v1.0.json index 18507d4..ec148a1 100644 --- a/schemas/fssallbodiesfound-v1.0.json +++ b/schemas/fssallbodiesfound-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/fssbodysignals-v1.0.json b/schemas/fssbodysignals-v1.0.json index 89bab05..26a3551 100644 --- a/schemas/fssbodysignals-v1.0.json +++ b/schemas/fssbodysignals-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/fssdiscoveryscan-v1.0.json b/schemas/fssdiscoveryscan-v1.0.json index f007fe0..618bd48 100644 --- a/schemas/fssdiscoveryscan-v1.0.json +++ b/schemas/fssdiscoveryscan-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json index 0e30eaf..3f7b171 100644 --- a/schemas/fsssignaldiscovered-v1.0.json +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -19,12 +19,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/journal-v1.0.json b/schemas/journal-v1.0.json index d01fafa..eb7737b 100644 --- a/schemas/journal-v1.0.json +++ b/schemas/journal-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/navbeaconscan-v1.0.json b/schemas/navbeaconscan-v1.0.json index 81e089c..5fcab2c 100644 --- a/schemas/navbeaconscan-v1.0.json +++ b/schemas/navbeaconscan-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/navroute-v1.0.json b/schemas/navroute-v1.0.json index f160cd6..b0ef8d2 100644 --- a/schemas/navroute-v1.0.json +++ b/schemas/navroute-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/outfitting-v2.0.json b/schemas/outfitting-v2.0.json index eab688e..b3a0ad2 100644 --- a/schemas/outfitting-v2.0.json +++ b/schemas/outfitting-v2.0.json @@ -18,13 +18,11 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, - "description" : "From Fileheader event if available, else LoadGame if available there." + "description" : "Fileheader->gameversion, else LoadGame->gameversion, else 'CAPI-shipyard', else ''." }, "gamebuild": { "type" : "string", - "minLength" : 1, - "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + "description" : "Fileheader->build, else LoadGame->build, else 'CAPI-shipyard', else ''." }, "softwareName": { "type" : "string" diff --git a/schemas/scanbarycentre-v1.0.json b/schemas/scanbarycentre-v1.0.json index 99df117..ccf263a 100644 --- a/schemas/scanbarycentre-v1.0.json +++ b/schemas/scanbarycentre-v1.0.json @@ -18,12 +18,10 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, "description" : "From Fileheader event if available, else LoadGame if available there." }, "gamebuild": { "type" : "string", - "minLength" : 1, "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." }, "softwareName": { diff --git a/schemas/shipyard-v2.0.json b/schemas/shipyard-v2.0.json index 3498e9b..a300271 100644 --- a/schemas/shipyard-v2.0.json +++ b/schemas/shipyard-v2.0.json @@ -18,13 +18,11 @@ }, "gameversion": { "type" : "string", - "minLength" : 1, - "description" : "From Fileheader event if available, else LoadGame if available there." + "description" : "Fileheader->gameversion, else LoadGame->gameversion, else 'CAPI-shipyard', else ''." }, "gamebuild": { "type" : "string", - "minLength" : 1, - "description" : "The `build` value from a Fileheader event if available, else LoadGame if available there." + "description" : "Fileheader->build, else LoadGame->build, else 'CAPI-shipyard', else ''." }, "softwareName": { "type" : "string"