# event

For: READ, PUBLISH

The `event` message type is the most common type. It is generated when some kind of event occurs. Whether this is a shot at goal, a referee being assiged or event just the ball moving, these can all generate messages of the 'event' type.

The `event` messages are broken down by a number of different classifier fields. In increasing levels of granularity they are:

#### class

This defines the type of events this message is related to. Some examples include: `sport`; events relating to something that happens as part of the sporting event. EG. A shot at goal or a foul `setup`; events relating to the setup of the match. EG. Assiging a player to a team/position, assigning a referee

#### eventType

The type of the event (inside the class). For a `sport` class message this may be the type of shot being made, or for a `setup` class message the type of thing being assigned.

#### subType

Some eventTypes (but not all) also support a 'subType' to further classify the eventType

#### options

Some eventTypes/subTypes support additional options for more information about the event. These are key/pair values. While some values may be boolean (true/false) others can be integer, strings etc.

While all messages of type 'event' require a class, the other fields may or may not be required depending on the type of event.

```
        {
            "type": "event",
            "fixtureId": "b25692de-ac17-11e8-98d0-529269fb1459",
            "clientType": "AppName:Version",
            "data": {
                "eventId": "c2404cc0-9f75-11e8-98d0-529269fb1459",
                "entityId": "c24048a6-9f75-11e8-98d0-529269fb1459",
                "personId": "c2405b2a-9f75-11e8-98d0-529269fb1459",
                "class": "sport",
                "eventType": "shot",
                "eventTime": "2018-08-14T16:45:33.88",
                "periodId": 2,
                "success": true,
                "x": 56,
                "y": 23,
                "officialId": "c2404ff4-9f75-11e8-98d0-529269fb1459",
                "playId": "d8934b2a-9f75-11e8-98d0-529269fb1459",
                "scores": {
                    "c24048a6-9f75-11e8-98d0-529269fb1459": "56",
                    "b25692de-ac17-11e8-98d0-529269fb1459": "23",
                },
                "status": "updated",
                "timestamp": "2018-08-14T16:45:34.34"
            }
        }
    
```

For each sport/event/eventType/SubType the required fields and available different combinations are varied. Please see the list below for more information.

| class                | eventType                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | subType                                                   | options | Required Fields |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------- | --------------- |
| `setup`              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      | `fixture`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      | `post`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                           |         |                 |
|                      | `attendance`integer Total attendance count `sellOut`boolean Were all tickets sold out?                                                                                                                                                                                                                                                                                                                                                                                                              | <p>class<br>eventType<br></p>                             |         |                 |
|                      | `person`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                           |         |                 |
|                      | `name`string The person's name `unregistered`boolean Is this person unregistered?                                                                                                                                                                                                                                                                                                                                                                                                                   | <p>class<br>eventType<br>personId<br>options.name<br></p> |         |                 |
| `sport`              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      | `cardBlack`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `cardRed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `cardYellow`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `fault`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `fixture`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      | `abandoned`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>subType<br></p>                  |         |                 |
|                      | `cancelled`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>subType<br></p>                  |         |                 |
|                      | `confirmed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>periodId<br></p>                 |         |                 |
|                      | `delayed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      | <p><code>newTime</code>date-time The new start time <code>reason</code>string The reason for the delay Allowed Values:</p><ul><li><code>CROWD</code></li><li><code>EARLY</code></li><li><code>EQUIPMENT</code></li><li><code>LATEFINISH</code></li><li><code>MEDICAL</code></li><li><code>OTHER</code></li><li><code>PREGAME</code></li><li><code>TECHNICAL</code></li><li><code>VENUE</code></li><li><code>WEATHER</code></li></ul><p><code>reasonOther</code>string The reason for the delay </p> | <p>class<br>eventType<br>options.reason<br></p>           |         |                 |
|                      | `end`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>periodId<br></p>                 |         |                 |
|                      | `interrupted`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                           |         |                 |
|                      | <p><code>reason</code>string The reason for the interruption Allowed Values:</p><ul><li><code>CROWD</code></li><li><code>EQUIPMENT</code></li><li><code>MEDICAL</code></li><li><code>OTHER</code></li><li><code>REVIEW</code></li><li><code>VENUE</code></li><li><code>WEATHER</code></li></ul><p><code>reasonOther</code>string The reason for the delay </p>                                                                                                                                      | <p>class<br>eventType<br>options.reason<br></p>           |         |                 |
|                      | `pending`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>periodId<br></p>                 |         |                 |
|                      | `protest`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>subType<br></p>                  |         |                 |
|                      | `start`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>periodId<br></p>                 |         |                 |
|                      | `warm_up`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>subType<br></p>                  |         |                 |
|                      | `let`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `point`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `server`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `shuttleInPlay`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>personId<br>periodId<br></p>     |         |                 |
|                      | `suspendPlay`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                           |         |                 |
|                      | `start`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>periodId<br></p>                 |         |                 |
|                      | `stop`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br>periodId<br></p>                 |         |                 |
| `heartbeat`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      | `client`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br></p>                             |         |                 |
| `disconnect`         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      | `client`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br></p>                             |         |                 |
| `reset`              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      | `client`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                           |         |                 |
|                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <p>class<br>eventType<br></p>                             |         |                 |
| `clientSessionStart` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                           |         |                 |
|                      | `client`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                           |         |                 |
|                      | `sessionId`string Id for the client application user session `authMethod`string The authentication method used by the client application `username`string Username of the user in the client application `userId`string User identifier in the client application                                                                                                                                                                                                                                   | <p>class<br>eventType<br></p>                             |         |                 |

**Bold** fields are required. Other fields may be required depending on the eventClass/type etc.

| Field          | Description                                                                                                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **eventId**    | A unique identifier for an event/action. UUIDv1 format. An edits/deletes of this event will need to use the same identifier.                                                                                                                                   |
| entityId       | A unique identifier for the entity/team that is performing this event/action. UUIDv1 format.                                                                                                                                                                   |
| personId       | A unique identifier for the person /team that is performing this event/action. UUIDv1 format. If the person is part of an entity/team that id field should also be included.                                                                                   |
| **class**      | The class of the event - see above                                                                                                                                                                                                                             |
| eventType      | The eventType of the event - see above                                                                                                                                                                                                                         |
| subType        | The subType of the event - see above                                                                                                                                                                                                                           |
| options        | The options for the event - see above                                                                                                                                                                                                                          |
| **eventTime**  | An ISO-8601 datetime giving the time this event occurred. If this event is added out of sequence, then this timestamp should reflect when the event 'would' have occurred.                                                                                     |
| periodId       | The unique identifier of the period. Overtime periods start at 11. 1 = 1 OT1 = 11                                                                                                                                                                              |
| success        | Boolean. Did the action complete successfully. It most cases this is true, however goal/shot attempts can be false.                                                                                                                                            |
| x              | The x-coordinate on the playing surface where the action occurred.                                                                                                                                                                                             |
| y              | The y-coordinate on the playing surface where the action occurred.                                                                                                                                                                                             |
| officialId     | The unique identifier of the official who made this call.                                                                                                                                                                                                      |
| playId         | The unique identifier of the 'play' (a group of events who share this id).                                                                                                                                                                                     |
| scores         | The structure of entityIds or personIds and scores giving the current score after the completion of the action.                                                                                                                                                |
| status         | The status of this message. Options are `added` (Default); `updated` - meaning the content of this event has been edited; `deleted` - meaning this event has been deleted; `enriched` - meaning further information has been added to the event (not changed). |
| flagged        | Boolean. This event has been flagged for further review and may be changed later                                                                                                                                                                               |
| highlight      | Boolean. This event may be a highlight of the game.                                                                                                                                                                                                            |
| **timestamp**  | An ISO-8601 datetime giving the time this message was sent.                                                                                                                                                                                                    |
| **clientType** | The type of client that is sending this event. Generally this is given as ApplicationName:ApplicationVersion.                                                                                                                                                  |

If a field has no value it should not be sent as part of the message. If a field has no value then it should not be sent as part of the message. "" or 0 are valid values and should only be used when the value is known to be these values.