SPEC.md (4523B)
1 # Agoran logs format 2 3 This specificaiton defines a sublanguage of JSON for documents specifying events that have happened in the game of Agora Nomic. It also specifies how particular *types* of events are to be further specified. 4 5 ## Definitions 6 7 TBD 8 9 ## Specification 10 11 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119) [RFC8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here. 12 13 An agoran log MUST be a valid JSON document representing a JSON object. It MUST contain a field `events` whose value is a list that SHALL comply with the section below. 14 15 Additionally, this object MAY contain a key `defs` whose value MUST be an object. Each field's key in this object is an identifier for a type of event, which will be referenced by the events, as per the next section. Each of these fields' values MUST be an object containing the following keys: 16 17 - `href`: a string containing a URL dereferenceable to a document specifying this type. 18 - `type`: a string containing the mimetype of the document references by `href`. Valid values are: 19 - `"application/schema+json"`. In this case, the document is a JSON schema against which an event with this type MUST validate. 20 - `"text/*"`. In this case, the document MUST be a human-readable description of this type of event, which fields are allowed, which are mandatory, and what of what format their values must be instances. 21 22 As an example, an event type with identifier `registration` could have the following value: 23 24 ```json 25 { 26 "href": "https://example.com/specs/registration.json", 27 "type": "application/schema+json" 28 } 29 ``` 30 31 and the document referred to by that URL have the following content: 32 33 ``` 34 { 35 "$id": "https://example.com/specs/registration.json", 36 "required": ["who", "whence"] 37 "properties": { 38 "whence": { 39 "type": "string", 40 "format": "url" 41 "description": "The appropriate method of contact to that player. Most likely, a URL of the `mailto` type." 42 } 43 } 44 } 45 ``` 46 47 ### Events 48 49 Each item of this list MUST be a JSON object, and SHALL contain the following fields, whose values SHALL be restricted to those described here: 50 51 - `when`: an integer, which represents the timestamp of the message on which that action occured, as defined by the rules of Agora. 52 - `what`: a string, which is an identifier for the type of event (see below). This string SHOULD be a dereferenceable URI pointing to a document that specifies that type of event. 53 54 Additionally, it MAY contain the following fields: 55 56 - `where`: a string containing a globally unique identifier for the message where the event took place. If the message is an email message, the value SHOULD be the `Message-Id` of that email. 57 - `who`: a string containing the name of the player responsible for that event, if applicable. 58 - `seq`: a number, which, if present, MUST represent a natural number (non-negative, without a fractional part). This represents the positional order of that event among events in the same message, as defined in the rules of Agora. 59 60 When an event contains a value in the `seq` field, then there MUST be messages in the same list with the same value in the `where` field, and whose values of the `seq` field contain all natural numbers less than the value in the original event in question. That is, the set of values of the `seq` field for all events with the same value in the `where` field must be an initial segment of the natural numbers. 61 62 ## Identifiers for the `what` field 63 64 Each value of the `what` field specifies the type of event that took place. Depending on the specificities of that type, fields that this specification defines as optional may be required, and additional fields may be defined by further specification documents. 65 66 Agents encountering events with an unknown value for the `what` field SHOULD ignore that event, but MAY implement non-interruptory behaviors in that circumstance (e.g., displaying a warning for a user). 67 68 Further specification documents may define the processing model for logs, which would aim at computing the current state of the game given an initial state and the events in a given log. These documents should also specify the type of those states, and formats for representing such states in serialized form.