mirror of
https://github.com/EDCD/EDDN.git
synced 2025-05-22 01:31:22 +03:00
104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
|
!!! STOP !!!
|
|
|
|
!! These are not valid MarkDown comments.
|
|
|
|
!! You MUST read, comply with, and then remove all of these lines to have a
|
|
|
|
!! valid Schema README file.
|
|
|
|
1. Be careful if using any existing Schema, or its README, as reference for a
|
|
new Schema. Some of them will have some departures from best practices for
|
|
historical reasons. It's usually not easy to co-ordinate all Listeners and
|
|
Senders smoothly updating to a new version of a Schema, so less than ideal
|
|
requires/optional/disallowed definitions might be present in older Schemas.
|
|
|
|
[The main Schema documentation](../README-EDDN-schemas.md) is the canonical
|
|
authority.
|
|
2. Replace all instances of `NewJournalEvent` with the name of the actual
|
|
Journal event's Schema you are documenting. This should have the case
|
|
preserved as per how it appears in actual game Journal files.
|
|
3. Replace all instances of `newjournalevent` with the lower-case folded
|
|
version of this Schema's Journal event name.
|
|
4. For new Journal-based schemas no key renames should be necessary.
|
|
|
|
If there are no renames of key names for this Schema, then edit the
|
|
`Key Renames` section to contain only the text `None.`.
|
|
|
|
Where such renames *are* required do **NOT** attempt to list them all here.
|
|
That would just require updating them both here and in the actual Schema.
|
|
|
|
If there are any, call them out in the `description` of the affected
|
|
property in the Schema.
|
|
|
|
5. In the `Elisions` section clearly document any keys (and thus their values)
|
|
that are in the source data, but that should not be in the resulting EDDN
|
|
message.
|
|
|
|
**You do not need to list keys with a `_Localised` suffix.**
|
|
|
|
6. 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:
|
|
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,
|
|
2. and a `StarPos` array is *not already present* in the source data.
|
|
|
|
then you MUST include the `StarPos` section in `Augmentations` and add
|
|
`StarPos` to the `required` message properties in the Schema file.
|
|
|
|
If neither key is in the source data then remove the `StarPos` section from
|
|
this document and the Schema file.
|
|
|
|
The line:
|
|
|
|
# EDDN NewJournalEvent Schema
|
|
|
|
below should ultimately be the first line in this file, after required edits.
|
|
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
|
# EDDN NewJournalEvent Schema
|
|
|
|
## Introduction
|
|
Here we document how to take data from an ED `NewJournalEvent` Journal
|
|
Event 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 ED Journal event `NewJournalEvent`.
|
|
|
|
### Key Renames
|
|
Many of the key names have a different case defined in this schema, make
|
|
sure you are renaming them as appropriate.
|
|
|
|
### Elisions
|
|
None
|
|
|
|
### 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.
|
|
|
|
#### StarPos
|
|
You MUST add a `StarPos` array containing the system co-ordinates from the
|
|
last `FSDJump`, `CarrierJump`, or `Location` event.
|
|
|
|
## Listeners
|
|
The advice above for [Senders](#senders), combined with the actual Schema file *should*
|
|
provide all the information you need to process these events.
|