From 46a71994a68551f1485c4e7598ec30e7b57da9d9 Mon Sep 17 00:00:00 2001
From: Athanasius <github@miggy.org>
Date: Sat, 2 Oct 2021 11:49:47 +0000
Subject: [PATCH] schemas/codexentry: Add BodyID/Name, and -README file

* Add BodyID and BodyName as optional keys.
* Add `description` at top-level pointing to README documentation.
* Add schema-specific README to document what should be (in|ex)cluded
  from data, and how to obtain such from Journals etc.
---
 schemas/codexentry-README.md | 49 ++++++++++++++++++++++++++++++++++++
 schemas/codexentry-v1.0.json |  7 ++++++
 2 files changed, 56 insertions(+)
 create mode 100644 schemas/codexentry-README.md

diff --git a/schemas/codexentry-README.md b/schemas/codexentry-README.md
new file mode 100644
index 0000000..4618640
--- /dev/null
+++ b/schemas/codexentry-README.md
@@ -0,0 +1,49 @@
+# EDDN CodexEntry Schema
+
+## Introduction
+Here we document how to take data from an ED `CodexEntry` Journal Event and
+properly structure it for sending to EDDN.
+
+Please see [EDDN Schemas](...) for general documentation for a schema such as
+this.
+
+## Senders
+The primary data source for this schema is the ED Journal event `CodexEntry`.
+
+### Elisions
+You MUST remove any key where the key name ends in 
+`_Localised`.
+
+You MUST remove the two keys `IsNewEntry` and `NewTraitsDiscovered`.
+
+### Augmentations
+#### StarPos
+You MUST **add** a `StarPos` key with value of type `array` containing the 
+galaxy co-ordinates of the system.  You will need to have obtained these 
+from prior event(s) upon the player arriving, or logging into, the system.
+
+e.g. if the system is `Alpha Centauri`:
+```json
+    "StarPos": [3.03125, -0.09375, 3.15625]
+```
+
+#### BodyID and BodyName
+You SHOULD attempt to track the BodyName and BodyID where the player is 
+and add keys/values for these.
+
+For `BodyName` you MUST retrieve this from the latest `Status.json` data, 
+using the `Body` value there-in.
+
+You can obtain the `BodyID` from a `ApproachBody` or `Location` event.  
+You MUST cross-check the `Body` value in this to ensure it has the same 
+name as you got from `Status.json`.  One possible issue is binary bodies where
+you might get an `ApproachBody` for one before descending towards the other, 
+without an additional `ApproachBody` to correct things.
+
+e.g. for `Bestia A 2 a`
+```json
+    "BodyName": "Bestia A 2 a",
+    "BodyID": 15,
+```
+
+## Receivers
diff --git a/schemas/codexentry-v1.0.json b/schemas/codexentry-v1.0.json
index 0a100a4..c57aa93 100644
--- a/schemas/codexentry-v1.0.json
+++ b/schemas/codexentry-v1.0.json
@@ -1,6 +1,7 @@
 {
     "$schema"               : "http://json-schema.org/draft-04/schema#",
     "id"                    : "https://eddn.edcd.io/schemas/codexentry/1#",
+    "description"           : "EDDN schema for CodexEntry Journal events.  Full documentation at https://github.com/EDCD/EDDN/tree/master/schemas/codexentry-README.md",
     "type"                  : "object",
     "additionalProperties"  : false,
     "required": [ "$schemaRef", "header", "message" ],
@@ -104,6 +105,12 @@
                         "minLength"     : 1
                     }
                 },
+                "BodyID": {
+                    "type"          : "integer"
+                },
+                "BodyName": {
+                    "type"          : "string",
+                },
                 "IsNewEntry": {
                     "$ref"          : "#/definitions/disallowed",
                     "description"   : "Contains personal data"