From 8de80a868af498eda0a8eff694ac5a46fab3fbc5 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Sun, 30 Jan 2022 15:29:41 +0000 Subject: [PATCH] docs: More DRY and getting things in the correct places --- docs/Contributing.md | 2 +- docs/Developers.md | 29 +++++++-------------- schemas/README-EDDN-schemas.md | 33 +++++++++++++++++++----- schemas/TEMPLATES/journalevent-README.md | 12 ++++++--- 4 files changed, 44 insertions(+), 32 deletions(-) diff --git a/docs/Contributing.md b/docs/Contributing.md index 986c0b6..9a5cb2b 100644 --- a/docs/Contributing.md +++ b/docs/Contributing.md @@ -282,7 +282,7 @@ include: is what the Gateway code uses. The script `contrib/test-schema.py` will check both this and that the validation code doesn't choke on it. 4. All new Schemas **MUST** comply with all requirements outlined in the - [general Schemas documentation](https://github.com/EDCD/EDDN/blob/live/schemas/README-EDDN-schemas.md). + [general Schemas documentation](../schemas/README-EDDN-schemas.md). If you have a good reason why your new Schema can't and shouldn't comply with these requirements, then consensus will need to be achieved on changing those requirements and/or allowing the exception. diff --git a/docs/Developers.md b/docs/Developers.md index 772ca88..4dddb87 100644 --- a/docs/Developers.md +++ b/docs/Developers.md @@ -165,26 +165,9 @@ In general: - *Delayed* good data is better than degrading the EDDN service for others. ### Format of uploaded messages -Each message is a JSON object in UTF-8 encoding containing the following -key+value pairs: - -1. `$schemaRef` - Which Schema (including version) this message is for. -2. `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. - 2. `softwareName` - an identifier for the software performing the upload. - 3. `softwareVersion` - The version of that software being used. - - Listeners MAY make decisions about whether to utilise the data in any - message based on the combination of `softwareName` and `softwareVersion`. - - **DO not** add `gatewaytimestamp` yourself. The EDDN Gateway will add - this and will overwrite any that you provide, so don't bother. -4. `message` - Object containing the data for this message. Consult the - relevant README file within this documentation, e.g. - [codexentry-README.md](./codexentry-README.md). There are some general - guidelines [below](#contents-of-message). +Each message is a JSON object in UTF-8 encoding with contents that comply with +the relevant Schema. There is an outline in the general +[EDDN Message README](../schemas/README-EDDN-schemas.md#mandatory-schema-file-contents). For example, a shipyard message, version 2, might look like: @@ -252,6 +235,12 @@ services or the local map. To that end: The individual Schemas will instruct you on various elisions (removals) to be made to comply with this. +Because the first versions of some Schemas were defined when only the CAPI +data was available, before Journal files existed, many of the key names chosen +in the Schemas are based on the equivalent in CAPI data, not Journal events. +This means you MUST rename many of the keys from Journal events to match the +Schemas. Consult the relevant Schema for details. + Some of these requirements are also enforced by the Schemas, and some things the Schemas enforce might not be explicitly called out in documentation. So, **do** check what you're sending against the relevant Schema(s) when making any diff --git a/schemas/README-EDDN-schemas.md b/schemas/README-EDDN-schemas.md index ae49751..4620dd1 100644 --- a/schemas/README-EDDN-schemas.md +++ b/schemas/README-EDDN-schemas.md @@ -22,7 +22,30 @@ For more general documentation that all developers wanting to either Upload messages or Listen to the stream of messages from the Relay, please consult [the Developer documentation](../docs/Developers.md). -## General EDDN message outline +### Mandatory Schema file contents + +It is best to base any new Schema file on +[the provided template](./TEMPLATES/journalevent-v1.0.json). As per its +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; + 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. + 2. `softwareName` - an identifier for the software performing the upload. + 3. `softwareVersion` - The version of that software being used. + + Listeners MAY make decisions about whether to utilise the data in any + message based on the combination of `softwareName` and `softwareVersion`. + + **DO not** add `gatewaytimestamp` yourself. The EDDN Gateway will add + this and will overwrite any that you provide, so don't bother. +4. `message` - Object containing the data for this message. Consult the + relevant README file within this documentation, e.g. + [codexentry-README.md](./codexentry-README.md). + +### General EDDN message outline Each `message` object must have, at bare minimum: @@ -56,9 +79,5 @@ Each `message` object must have, at bare minimum: [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) and include them whenever possible. -Because the first versions of some Schemas were defined when only the CAPI -data was available, before Journal files existed, many of the key names chosen -in the Schemas are based on the equivalent in CAPI data, not Journal events. -This means you MUST rename many of the keys from Journal events to match the -Schemas. Consult the relevant Schema, and its README, for details. - +Where a key has to be renamed this will be specified in the Schema through a +`renamed` property on the object in question. diff --git a/schemas/TEMPLATES/journalevent-README.md b/schemas/TEMPLATES/journalevent-README.md index ff007ba..2ba8d3e 100644 --- a/schemas/TEMPLATES/journalevent-README.md +++ b/schemas/TEMPLATES/journalevent-README.md @@ -48,11 +48,11 @@ ``` -6. Do **NOT** remove the `horizons and odyssey flags` section. It is +5. Do **NOT** remove the `horizons and odyssey flags` section. It is mandatory that they are allowed (but are optional) in any Journal-based EDDN Schema. -7. If both: +6. If both: 1. either the source Journal event contains information that includes the System name (possibly as `StarSystem` or `SystemName`), **OR** the source data contains a `SystemAddress` value, @@ -64,6 +64,10 @@ If neither key is in the source data then remove the `StarPos` section from this document and the Schema file. +7. Do **NOT** add an 'Elisions'/'Removals' section. Leave the Schema as the + sole reference for any data that is in the source but should not be in the + final EDDN message. + The line: # EDDN NewJournalEvent Schema @@ -99,8 +103,8 @@ value is what the name would have been in the source Journal data. ### Augmentations #### horizons and odyssey flags -Please read [horizons and odyssey flags](../README-EDDN-schemas.md#horizons-and-odyssey-flags) -over in the main Schema documentation. +Please read [horizons and odyssey flags](../../docs/Developers.md#horizons-and-odyssey-flags) +over in the Developers' documentation. #### StarPos You MUST add a `StarPos` array containing the system co-ordinates from the