mirror of
https://github.com/EDCD/EDDN.git
synced 2025-04-18 01:32:21 +03:00
docs: More DRY and getting things in the correct places
This commit is contained in:
Athanasius
parent
93713ffa9b
commit
8de80a868a
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user