From 2d2a205c7a5a48837592384729ccc4ff86b65025 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 30 Aug 2022 15:08:04 +0100 Subject: [PATCH 01/13] schemas: New `fcmaterials/1` based on the *Journal* data source only --- schemas/fcmaterials-v1.0.json | 99 +++++++++++++++++++++++++++++++++++ src/eddn/conf/Settings.py | 3 ++ 2 files changed, 102 insertions(+) create mode 100644 schemas/fcmaterials-v1.0.json diff --git a/schemas/fcmaterials-v1.0.json b/schemas/fcmaterials-v1.0.json new file mode 100644 index 0000000..04f821c --- /dev/null +++ b/schemas/fcmaterials-v1.0.json @@ -0,0 +1,99 @@ +{ + "$schema" : "http://json-schema.org/draft-04/schema#", + "id" : "https://eddn.edcd.io/schemas/fcmaterials/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", "MarketID", "CarrierName", "CarrierID", "Items" ], + "properties" : { + "timestamp": { + "type" : "string", + "format" : "date-time" + }, + "event" : { + "enum" : [ "FCMaterials" ] + }, + "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." + }, + + "MarketID": { + "type" : "integer" + }, + + "CarrierName": { + "type" : "string", + "minLength" : 1 + }, + + "CarrierID": { + "type" : "string", + "minLength" : 1 + }, + + "Items": { + "type" : "array", + "required" : [ "id", "Name", "Price", "Stock", "Demand" ], + "properties" : { + "id" : { + "type" : "integer" + }, + "Name": { + "type" : "string", + "minLength" : 1 + }, + "Price": { + "type" : "integer" + }, + "Stock": { + "type" : "integer" + }, + "Demand": { + "type" : "integer" + } + }, + "patternProperties": { + "_Localised$" : { "$ref" : "#/definitions/disallowed" } + } + } + } + } + }, + "definitions": { + "disallowed" : { "not" : { "type": [ "array", "boolean", "integer", "number", "null", "object", "string" ] } } + } +} diff --git a/src/eddn/conf/Settings.py b/src/eddn/conf/Settings.py index 28e9b21..1e313e6 100644 --- a/src/eddn/conf/Settings.py +++ b/src/eddn/conf/Settings.py @@ -84,6 +84,9 @@ class _Settings(object): "https://eddn.edcd.io/schemas/fsssignaldiscovered/1" : "schemas/fsssignaldiscovered-v1.0.json", "https://eddn.edcd.io/schemas/fsssignaldiscovered/1/test" : "schemas/fsssignaldiscovered-v1.0.json", + + "https://eddn.edcd.io/schemas/fcmaterials/1" : "schemas/fcmaterials-v1.0.json", + "https://eddn.edcd.io/schemas/fcmaterials/1/test" : "schemas/fcmaterials-v1.0.json", } GATEWAY_OUTDATED_SCHEMAS = [ From f4ab9eb35aaec0dd53e61362a722d59b2370cc47 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 30 Aug 2022 15:41:55 +0100 Subject: [PATCH 02/13] schemas: fcmaterials/1: Add README --- schemas/fcmaterials-README.md | 38 +++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 schemas/fcmaterials-README.md diff --git a/schemas/fcmaterials-README.md b/schemas/fcmaterials-README.md new file mode 100644 index 0000000..357da91 --- /dev/null +++ b/schemas/fcmaterials-README.md @@ -0,0 +1,38 @@ +# EDDN FCMaterials Schema + +## Introduction +This is the documentation for how to take data from an ED `FCMaterials.json` +file 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 data source for this schema is the file `FCMaterials.json`. That it has +been freshly written is signalled by the ED Journal event `FCMaterials`. +**NB: This schema is not, currently, for sending CAPI `/market`-sourced data +about these materials.** + +So, monitor the Journal as normal, and when you see a `FCMaterials` event open +the `FCMaterials.json` file for reading, read it, and close it again. Use the +data you got from reading this file, not merely the Journal event. + +Your `message` should primarily be the contents of this file, with the addition +of any augmentations, as noted below. + +### Augmentations +#### horizons and odyssey flags +Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) +in 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. From f4b9eab178efd2ea62e780b1c98ad5f8cf151e55 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Wed, 31 Aug 2022 15:17:56 +0000 Subject: [PATCH 03/13] schemas: fcmaterials: Adjust to allow for CAPI-sourced data * Add new mandatory `data-source` field. * `CarrierName` now optional (not in CAPI data). * `Items` is defined a lot more loosely, due to Journal vs CAPI differences. --- schemas/fcmaterials-v1.0.json | 29 +++++++---------------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/schemas/fcmaterials-v1.0.json b/schemas/fcmaterials-v1.0.json index 04f821c..b0cf9cb 100644 --- a/schemas/fcmaterials-v1.0.json +++ b/schemas/fcmaterials-v1.0.json @@ -33,12 +33,15 @@ "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", "MarketID", "CarrierName", "CarrierID", "Items" ], + "required" : [ "timestamp", "data-source", "event", "MarketID", "CarrierID", "Items" ], "properties" : { "timestamp": { "type" : "string", "format" : "date-time" }, + "data-source": { + "enum" : [ "Journal", "CAPI", "CAPI-Journal" ] + }, "event" : { "enum" : [ "FCMaterials" ] }, @@ -66,28 +69,10 @@ }, "Items": { - "type" : "array", - "required" : [ "id", "Name", "Price", "Stock", "Demand" ], - "properties" : { - "id" : { - "type" : "integer" - }, - "Name": { - "type" : "string", - "minLength" : 1 - }, - "Price": { - "type" : "integer" - }, - "Stock": { - "type" : "integer" - }, - "Demand": { - "type" : "integer" - } - }, + "type" : [ "array", "object" ], "patternProperties": { - "_Localised$" : { "$ref" : "#/definitions/disallowed" } + "_Localised$" : { "$ref" : "#/definitions/disallowed" }, + "locName" : { "$ref" : "#/definitions/disallowed" } } } } From 61ef74492d41b71ea55ec82d9d59dd24f2b8743f Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 13:19:46 +0100 Subject: [PATCH 04/13] Revert "schemas: fcmaterials: Adjust to allow for CAPI-sourced data" This reverts commit f4b9eab178efd2ea62e780b1c98ad5f8cf151e55. --- schemas/fcmaterials-v1.0.json | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/schemas/fcmaterials-v1.0.json b/schemas/fcmaterials-v1.0.json index b0cf9cb..04f821c 100644 --- a/schemas/fcmaterials-v1.0.json +++ b/schemas/fcmaterials-v1.0.json @@ -33,15 +33,12 @@ "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", "data-source", "event", "MarketID", "CarrierID", "Items" ], + "required" : [ "timestamp", "event", "MarketID", "CarrierName", "CarrierID", "Items" ], "properties" : { "timestamp": { "type" : "string", "format" : "date-time" }, - "data-source": { - "enum" : [ "Journal", "CAPI", "CAPI-Journal" ] - }, "event" : { "enum" : [ "FCMaterials" ] }, @@ -69,10 +66,28 @@ }, "Items": { - "type" : [ "array", "object" ], + "type" : "array", + "required" : [ "id", "Name", "Price", "Stock", "Demand" ], + "properties" : { + "id" : { + "type" : "integer" + }, + "Name": { + "type" : "string", + "minLength" : 1 + }, + "Price": { + "type" : "integer" + }, + "Stock": { + "type" : "integer" + }, + "Demand": { + "type" : "integer" + } + }, "patternProperties": { - "_Localised$" : { "$ref" : "#/definitions/disallowed" }, - "locName" : { "$ref" : "#/definitions/disallowed" } + "_Localised$" : { "$ref" : "#/definitions/disallowed" } } } } From 5bcdfadb094efb5a4fb695d9689be25d23674d08 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 13:21:03 +0100 Subject: [PATCH 05/13] schemas: Rename Journal-only to `fcmaterials_journal/1` --- schemas/{fcmaterials-README.md => fcmaterials_journal-README.md} | 0 schemas/{fcmaterials-v1.0.json => fcmaterials_journal-v1.0.json} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename schemas/{fcmaterials-README.md => fcmaterials_journal-README.md} (100%) rename schemas/{fcmaterials-v1.0.json => fcmaterials_journal-v1.0.json} (100%) diff --git a/schemas/fcmaterials-README.md b/schemas/fcmaterials_journal-README.md similarity index 100% rename from schemas/fcmaterials-README.md rename to schemas/fcmaterials_journal-README.md diff --git a/schemas/fcmaterials-v1.0.json b/schemas/fcmaterials_journal-v1.0.json similarity index 100% rename from schemas/fcmaterials-v1.0.json rename to schemas/fcmaterials_journal-v1.0.json From 2eb213d76682a2a9c9e88d48c4c0eb4e9c569544 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 13:36:43 +0100 Subject: [PATCH 06/13] schemas/TEMPLATES/journal: Remove the # 'fragment' from end of $id As per > Therefore, "$id" MUST NOT contain a non-empty fragment, and SHOULD NOT contain an empty fragment. --- schemas/TEMPLATES/journalevent-v1.0.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/TEMPLATES/journalevent-v1.0.json b/schemas/TEMPLATES/journalevent-v1.0.json index a87c8fe..0b64ec9 100644 --- a/schemas/TEMPLATES/journalevent-v1.0.json +++ b/schemas/TEMPLATES/journalevent-v1.0.json @@ -39,7 +39,7 @@ # as a result disallow the key. { "$schema" : "http://json-schema.org/draft-04/schema#", - "id" : "https://eddn.edcd.io/schemas/newjournalevent/1#", + "id" : "https://eddn.edcd.io/schemas/newjournalevent/1", "type" : "object", "additionalProperties" : false, "required": [ "$schemaRef", "header", "message" ], From 08127d261f0ca4da4c7be1ed765ba9cec56f70a0 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 13:38:53 +0100 Subject: [PATCH 07/13] schemas/README: Per-schema README is now mandatory I think I only made this 'SHOULD' before because at that stage I'd not yet written the README files for the legacy schemas. --- schemas/README-EDDN-schemas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/README-EDDN-schemas.md b/schemas/README-EDDN-schemas.md index 7905cbb..b903100 100644 --- a/schemas/README-EDDN-schemas.md +++ b/schemas/README-EDDN-schemas.md @@ -15,7 +15,7 @@ those actually running on the Live service. The Schema files themselves are considered to be the canonical definition of the required, and allowed, contents of the relevant EDDN message. There -**SHOULD** be an accompanying README file, e.g. for `commodity-v3.0.json` there +**MUST** be an accompanying README file, e.g. for `commodity-v3.0.json` there is also a `commodity-README.md` file in the project root `schemas/` directory. For more general documentation that all developers wanting to either Upload From b3876824f79c628c755b4b81725d301b3e020ed4 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 13:46:18 +0100 Subject: [PATCH 08/13] schemas/README: Document `$id` conventions 1. Get the designation of the version correct. 2. That empty `#` fragment is a SHOULD NOT, so just don't. 3. Append `_` to the "filename" where necessary. --- schemas/README-EDDN-schemas.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/schemas/README-EDDN-schemas.md b/schemas/README-EDDN-schemas.md index b903100..8423755 100644 --- a/schemas/README-EDDN-schemas.md +++ b/schemas/README-EDDN-schemas.md @@ -29,7 +29,16 @@ It is best to base any new Schema file on contents all Schemas specify a top-level JSON Object with the data: 1. `$schemaRef` - Which Schema (including version) this message is for. -2. `header` - Object containing mandatory information about the upload; +2. `$id` - The canonical URL for this schema once it is in live service. + 1. Remember to have the version as in `journal/1` not `journal-v1.0`. + 2. Do **NOT** end this with a `#` empty fragment. This is + [documented](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.1) + as unnecessary. + 3. Where there are two separate schemas for the same kind of data, but one + is for Journal-sourced, and the other for CAPI-sourced, you should have + the "filename" of the schema end with `_`, e.g. + `fcmaterials_journal/1` and `fcmaterials_capi/1`. +3. `header` - Object containing mandatory information about the upload; 1. `uploaderID` - a unique ID for the player uploading this data. Don't worry about privacy, the EDDN service will hash this with a key that is regularly changed so no-one knows who an uploader is in-game. From 33d6e8fe2e921b5cf4056333aa44b082eedcf747 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 13:48:37 +0100 Subject: [PATCH 09/13] schemas: fcmaterials_journal: Fix `$id` from rename --- schemas/fcmaterials_journal-v1.0.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/fcmaterials_journal-v1.0.json b/schemas/fcmaterials_journal-v1.0.json index 04f821c..35bb080 100644 --- a/schemas/fcmaterials_journal-v1.0.json +++ b/schemas/fcmaterials_journal-v1.0.json @@ -1,6 +1,6 @@ { "$schema" : "http://json-schema.org/draft-04/schema#", - "id" : "https://eddn.edcd.io/schemas/fcmaterials/1#", + "id" : "https://eddn.edcd.io/schemas/fcmaterials_journal/1", "type" : "object", "additionalProperties" : false, "required": [ "$schemaRef", "header", "message" ], From 7111bdbbbb7c95dfa91734c3eeffc5b3e984fcb1 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 15:39:20 +0100 Subject: [PATCH 10/13] scripts/test-schema: A *very* basic script to see if a schema works * It's using `sys.argv`, not `argparse`. * Thus there's no `--help`. * Supply it with: 1) Filename of a schema definition, 2) filename of a full EDDN message text to test for compliance. * No output if both schema and message load *and* the message passes the schema. Else you'll get python exception output from `jsonschema.validate()`. --- scripts/test-schema.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 scripts/test-schema.py diff --git a/scripts/test-schema.py b/scripts/test-schema.py new file mode 100644 index 0000000..8df8617 --- /dev/null +++ b/scripts/test-schema.py @@ -0,0 +1,17 @@ +import sys + +import simplejson +import jsonschema + +schema_filename = sys.argv[1] +message_filename = sys.argv[2] + +schema_file = open(schema_filename, 'r') +schema_data = schema_file.read() +schema = simplejson.loads(schema_data) + +message_file = open(message_filename, 'r') +message_data = message_file.read() +message = simplejson.loads(message_data) + +jsonschema.validate(message, schema, format_checker=jsonschema.FormatChecker()) From af2b29a4a48eb9deb065e82f57c650393d6cdce8 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 15:41:07 +0100 Subject: [PATCH 11/13] schemas: fcmaterials_capi: Initial schema and README * NB: The README is a straight copy of the _journal one right now. Will fix later. --- schemas/fcmaterials_capi-README.md | 38 ++++++++ schemas/fcmaterials_capi-v1.0.json | 144 +++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 schemas/fcmaterials_capi-README.md create mode 100644 schemas/fcmaterials_capi-v1.0.json diff --git a/schemas/fcmaterials_capi-README.md b/schemas/fcmaterials_capi-README.md new file mode 100644 index 0000000..357da91 --- /dev/null +++ b/schemas/fcmaterials_capi-README.md @@ -0,0 +1,38 @@ +# EDDN FCMaterials Schema + +## Introduction +This is the documentation for how to take data from an ED `FCMaterials.json` +file 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 data source for this schema is the file `FCMaterials.json`. That it has +been freshly written is signalled by the ED Journal event `FCMaterials`. +**NB: This schema is not, currently, for sending CAPI `/market`-sourced data +about these materials.** + +So, monitor the Journal as normal, and when you see a `FCMaterials` event open +the `FCMaterials.json` file for reading, read it, and close it again. Use the +data you got from reading this file, not merely the Journal event. + +Your `message` should primarily be the contents of this file, with the addition +of any augmentations, as noted below. + +### Augmentations +#### horizons and odyssey flags +Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) +in 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_capi-v1.0.json b/schemas/fcmaterials_capi-v1.0.json new file mode 100644 index 0000000..49edb06 --- /dev/null +++ b/schemas/fcmaterials_capi-v1.0.json @@ -0,0 +1,144 @@ +{ + "$schema" : "http://json-schema.org/draft-04/schema#", + "id" : "https://eddn.edcd.io/schemas/fcmaterials_capi/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", "MarketID", "CarrierID", "Items" ], + "properties" : { + "timestamp": { + "type" : "string", + "format" : "date-time" + }, + "event" : { + "enum" : [ "FCMaterials" ] + }, + "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." + }, + + "MarketID": { + "type" : "integer" + }, + + "CarrierID": { + "type" : "string", + "minLength" : 1 + }, + + "Items": { + "properties": { + "purchases": { + "type": "array", + "items": { + "type": "object", + "required": [ "name", "price", "outstanding", "total" ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "locName": { + "$ref": "#/definitions/disallowed" + }, + "outstanding": { + "type": "integer" + }, + "price": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + } + }, + "sales": { + "anyOf": [ + { + "type": "array", + "$comment": "If there are no items then sales is an empty array", + "minItems": 0, + "maxItems": 0 + }, + { + "type": "object", + "$comment": "If there ARE items then sales is an object, *NOT* an array", + "patternProperties": { + "^[0-9]+$": { + "type" : "object", + "required" : [ "id", "name", "price", "stock" ], + "additionalProperties": false, + "properties": { + "id" : { + "type" : "integer" + }, + "name" : { + "type" : "string", + "minLength": 1 + }, + "locName" : { + "$ref": "#/definitions/disallowed" + }, + "price" : { + "type": "integer" + }, + "stock": { + "type": "integer" + } + } + } + } + } + ] + } + } + } + } + } + }, + "definitions": { + "disallowed": { + "not" : { + "type": [ + "array", "boolean", "integer", "number", "null", "object", "string" + ] + } + } + } +} From 2a8d09e37871bd4585765245cb18aa9cc406855c Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 16:27:48 +0100 Subject: [PATCH 12/13] schemas: fcmaterials_capi: README: First cut --- schemas/fcmaterials_capi-README.md | 62 ++++++++++++++++++++++++------ 1 file changed, 51 insertions(+), 11 deletions(-) diff --git a/schemas/fcmaterials_capi-README.md b/schemas/fcmaterials_capi-README.md index 357da91..a76f136 100644 --- a/schemas/fcmaterials_capi-README.md +++ b/schemas/fcmaterials_capi-README.md @@ -1,8 +1,8 @@ # EDDN FCMaterials Schema ## Introduction -This is the documentation for how to take data from an ED `FCMaterials.json` -file and properly structure it for sending to EDDN. +This is the documentation for how to take data from an the ED CAPI `/market` +endpoint 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. @@ -16,23 +16,63 @@ to report any such anomalies you find so that we can check and resolve the discrepancy.** ## Senders -The data source for this schema is the file `FCMaterials.json`. That it has -been freshly written is signalled by the ED Journal event `FCMaterials`. -**NB: This schema is not, currently, for sending CAPI `/market`-sourced data -about these materials.** +The data source for this schema is the `/market` ED CAPI endpoint. You only +want selected parts of the full data returned for this schema. -So, monitor the Journal as normal, and when you see a `FCMaterials` event open -the `FCMaterials.json` file for reading, read it, and close it again. Use the -data you got from reading this file, not merely the Journal event. +You **MUST NOT** construct the message by starting with the entirety of the +CAPI data and then removing everything but what you need. That risks Frontier +adding more data to the endpoint and your `fcmaterials_capi` messages being +rejected as invalid. Instead, construct the message content by setting just +the data that is necessary. -Your `message` should primarily be the contents of this file, with the addition -of any augmentations, as noted below. +Your `message` object **MUST**: +1. Have an `"event":"FCMaterials"` member to aid Listeners who pass this + through a "usually from the Journal" code path. +2. Set a `"MarketID"` key with the value from `"id"` in the CAPI data. +3. Set a `"CarrierID"` key with the value from the `"name"` in the CAPI data. +4. Set the `"Items"` key's contents directly from the `/market` -> `orders` + -> `onfootmicroresources` CAPI data. +5. Remove any data where the key is `"locName"` from the `"Items"` data. + +You **MUST NOT**: +1. Attempt to set a `"CarrierName"` from any source, the `CarrierID` is + sufficient. + +### Example algorithm + +1. Make a CAPI `/market` query. +2. Set `event`, `MarketID` and `CarrierID` as outlined above. +3. Set `Items` value to the data in `orders.onfootmicroresources`. +4. Process the contents of `Items`, removing any data with a key of `locName`. ### Augmentations #### horizons and odyssey flags Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +You **SHOULD** set these flags from the Journal `FileHeader` data if you are +reasonably sure you have a live game session against which you are performing +CAPI queries. +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. + ## Listeners The advice above for [Senders](#senders), combined with the actual Schema file *should* provide all the information you need to process these events. + +Do note that the data source for this is the CAPI, and as such the data is not +the same as for the `fcmaterials_journal` schema: + +1. There is no good source of `CarrierName` in CAPI `/market` endpoint data, so + that is not included. +2. The `sales` and `purchases` values do **not** contain the same form of data. +3. The `sales` member of `Items` will be `[]` if there are no sales orders, but + when there are orders: + 1. It will be an object/dictionary. + 2. The keys are the commodity ID. + 3. The value of that key is the rest of the data for that sales order. +4. The `purchases` value: + 1. Is always an array, unlike `sales`. + 2. As a consequence does **not** provide the commodity id at all, only + the name. From 7f7b46279000aa5789c0ca4e30e25c18691cbafd Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 2 Sep 2022 16:30:18 +0100 Subject: [PATCH 13/13] Setttings: Update for `fcmaterials_journal` and `fcmaterials_capi` now --- src/eddn/conf/Settings.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/eddn/conf/Settings.py b/src/eddn/conf/Settings.py index 1e313e6..9e2f6a5 100644 --- a/src/eddn/conf/Settings.py +++ b/src/eddn/conf/Settings.py @@ -85,8 +85,11 @@ class _Settings(object): "https://eddn.edcd.io/schemas/fsssignaldiscovered/1" : "schemas/fsssignaldiscovered-v1.0.json", "https://eddn.edcd.io/schemas/fsssignaldiscovered/1/test" : "schemas/fsssignaldiscovered-v1.0.json", - "https://eddn.edcd.io/schemas/fcmaterials/1" : "schemas/fcmaterials-v1.0.json", - "https://eddn.edcd.io/schemas/fcmaterials/1/test" : "schemas/fcmaterials-v1.0.json", + "https://eddn.edcd.io/schemas/fcmaterials_journal/1" : "schemas/fcmaterials_journal-v1.0.json", + "https://eddn.edcd.io/schemas/fcmaterials_journal/1/test" : "schemas/fcmaterials_journal-v1.0.json", + + "https://eddn.edcd.io/schemas/fcmaterials_capi/1" : "schemas/fcmaterials_capi-v1.0.json", + "https://eddn.edcd.io/schemas/fcmaterials_capi/1/test" : "schemas/fcmaterials_capi-v1.0.json", } GATEWAY_OUTDATED_SCHEMAS = [