Schemas for Glides Events (#2)

* Schema, docs, and examples for Glides Events
* Tweaks to docs organization, don't use auto-generated categories
* Tweaks to Examples component
* Refactor test script into a single script that compiles all schemas and checks all examples.

Author: skyqrose

README.md

@@ -5,6 +5,7 @@ This website is built using [Docusaurus 2](https://docusaurus.io/), a modern sta
 ### Installation
 
 ```
+$ asdf install
 $ yarn
 ```
 
@@ -16,23 +17,21 @@ $ yarn start
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-### Schema Validation
+### Testing
+
+To check that the schemas in `schemas/` and the examples in `examples/` are valid:
 
 ``` shell
-# Check that the schemas in `schemas/` are valid
 $ yarn test:schemas
-
-# Check that the examples in `examples/` match the schemas in `schemas/`
-$ yarn test:examples
 ```
 
-### Testing
+Each file `examples/<schema name>/<example name>.json` is validated against the schema `schemas/<schema name>.json`.
+
+To run all tests:
 
 ``` shell
 $ yarn ci
-# or 
-$ yarn format --check
-$ yarn typecheck
+# or
 $ yarn test
 ```
 

docs/events/_category_.json

@@ -11,5 +11,10 @@ Originally described in [RFC4](https://github.com/mbta/technology-docs/blob/main
 
 If you are internal to the MBTA, documentation for the contents of the `raw` field live in [SharePoint](https://mbta.sharepoint.com/:w:/r/sites/CTD/Shared%20Documents/General/Transit%20Tech%20CTD-wide/Transit%20Data/Product%20Documentation/RTR%20+%20Prediction%20Analyzer/Notes/ocs_messages.docx?d=wd7d5fea4e2104a4cac86b296e3083a47&csf=1&web=1&e=0vRTqp).
 
-<Examples examples={{ RGPS }} />
+## Examples
+
+<Examples examples={[{ label: "RGPS", json: RGPS }]} />
+
+## Schema
+
 <EventSchemaPath event="com.mbta.ocs.raw_message" />

docs/events/com.mbta.ocs.raw_message.mdx

@@ -1,35 +1,65 @@
 ---
+sidebar_label: glides.editors_changed
 ---
 
-import GlidesExamples from "@site/examples/glides-events-schema/glides-examples.json";
 import EventSchemaPath from "@site/src/components/EventSchemaPath.tsx";
 import Examples from "@site/src/components/Examples.tsx";
+import example from "@site/examples/glides-events/editors_changed.v1.take_over.json";
 
-Operator sign in and out of editing specific trainsheets. This event publishes
-changes to who is editing. Since one action by an inspector might result in
-multiple changes, for example if they sign out of one location and in to
-another, the changes are published in a list.
+# editors_changed
 
-In practice, we limit each location to have only one editor, and limit each
-editor to only one location, but that rule may or may not change and this data
-in this event doesn't guarantee that.
+event type: `com.mbta.ctd.glides.editors_changed.v1`
 
-Note that the author may or may not match the editors in changes, since
-inspectors can change whether other people are editing. For example, when an
-inspector takes over editing at a location, they may sign out the previous
-editor. Then they would issue a stop change for the previous editor and a start
-change for themself.
+Inspectors sign in and out of editing specific trainsheets. This event publishes changes to who is editing.
 
-Fields in the event:
+Since one action by an inspector might result in
+multiple changes, for example if they sign out of one location and in to another, the changes are published in a list.
 
-- `metadata` (Metadata): how the changes were entered in Glides, including the author.
-- `changes` (array of EditorChange): a list of start and stop editing events
+In practice, we limit each location to have only one editor, and limit each editor to only one location, but that rule may or may not change and this event schema doesn't guarantee that.
+
+Note that the author may or may not match the editors in changes, since inspectors can change whether other people are editing.
+For example, when an inspector takes over editing at a location, they may sign out the previous editor.
+Then they would issue a stop change for the previous editor and a start change for themself.
+
+## Data
+
+Fields in the event's `data`:
+
+- `metadata` ([Metadata](.#metadata)): how the changes were entered in Glides, including the author.
+- `changes` (array of [EditorChange](#editorchange)): a list of start and stop editing events.
+
+### EditorChange
+
+Fields:
+
+- `type` (string `"start"`|`"stop"`): Whether the editor started or stopped editing.
+- `location` ([Location](.#location)): the location the editor started or stopped managing.
+- `editor` ([GlidesUser](.#glidesuser)): the affected editor.
+
+### GlidesUser
+
+See [GlidesUser](.#glidesuser)
+
+### Location
+
+See [Location](.#location)
+
+### Metadata
+
+See [Metadata](.#metadata)
+
+## Examples
 
 <Examples
-  examples={{
-    Example: GlidesExamples.find(
-      (example) => example.type == "com.mbta.ctd.glides.editors_changed.v1"
-    ),
-  }}
+  examples={[
+    {
+      description:
+        'Inspector Alice (badge number: 123) starts her shift at Boston College. The previous inspector (badge number: 456) did not stop editing, so Alice clicks the "Take Over" button in Glides.',
+      json: example,
+    },
+  ]}
 />
+
+## Schema
+
 <EventSchemaPath event="com.mbta.ctd.glides.editors_changed.v1" />

docs/events/glides/_category_.json

@@ -1,29 +1,63 @@
 ---
+sidebar_label: glides.operator_signed_in
 ---
 
-import GlidesExamples from "@site/examples/glides-events-schema/glides-examples.json";
 import EventSchemaPath from "@site/src/components/EventSchemaPath.tsx";
 import Examples from "@site/src/components/Examples.tsx";
+import example from "@site/examples/glides-events/operator_signed_in.v1.json";
 
-At the start of their shift, operators need to confirm that they are
-fit-for-duty and do not have any electronic devices. They currently do this by
-physically signing a paper trainsheet: in the future, they will do this
-digitally.
+# operator_signed_in
 
-Fields in the event:
+event type: `com.mbta.ctd.glides.operator_signed_in.v1`
 
-- `metadata` (Metadata): how the operator was signed in in Glides, including the inspector who signed them in.
-- `operator` (Operator): the operator who signed in
-- `signedInAt` (RFC3999 timestamp): the time at which they signed in (separate from the time of the event)
-- `signature` (Signature): how the operator confirmed that they signed in.
+At the start of their shift, operators need to confirm in Glides (on an inspector's device) that they are fit-for-duty and do not have any electronic devices.
 
-Originally described in [RFC18](https://github.com/mbta/technology-docs/blob/main/rfcs/accepted/0018-glides-trainsheet-events.md).
+## Data
+
+Fields in the event's `data`:
+
+- `metadata` ([Metadata](.#metadata)): how the operator was signed in in Glides, including the inspector who signed them in.
+- `operator` ([Operator](.#operator)): the operator who signed in
+- `signedInAt` (RFC3999 timestamp): the time at which they signed in (this is separate from the event timestamp)
+- `signature` ([Signature](#signature)): how the operator signed in.
+
+### Metadata
+
+See [Metadata](.#metadata)
+
+### Operator
+
+See [Operator](.#operator)
+
+### Signature
+
+How the operator signed that they were fit for duty.
+
+Fields:
+
+- `type` (string): How the the operator made their signature.
+
+Current values for `type` are
+
+- `"tap"` if they signed in by tapping their badge to an RFID scanner.
+- `"type"` if they signed in by typing their badge number into Glides as a signature.
+
+Represented as an object with a string field instead of `const`s, so that we could include other types of signatures or other data about the signature in the future without a breaking change.
+
+The tapped badge's RFID serial number is not included in the stream for security reasons (it could be used to impersonate an employee).
+
+## Examples
 
 <Examples
-  examples={{
-    Example: GlidesExamples.find(
-      (example) => example.type == "com.mbta.ctd.glides.operator_signed_in.v1"
-    ),
-  }}
+  examples={[
+    {
+      description:
+        "Operator Charlie (badge: 789) returns from his break and stops by Inspector Alice's booth. Alice checks him as fit for duty, and he signs in by tapping his badge to the RFID reader attached to Alice's computer.",
+      json: example,
+    },
+  ]}
 />
+
+## Schema
+
 <EventSchemaPath event="com.mbta.ctd.glides.operator_signed_in.v1" />