feat: dereference local schemas

This allows us to share the CloudEvents configuration between different
events.

Author: paulswartz

__tests__/plugins/deref-json-schemas.test.ts

@@ -0,0 +1,41 @@
+import { expect, test, describe } from "@jest/globals";
+
+import { derefSchemaPath } from "../../src/plugins/deref-json-schemas/deref-json-schema";
+
+describe("deref-json-schemas", () => {
+  test("keeps the description when merging", async () => {
+    const result = await derefSchemaPath(
+      "schemas/com.mbta.ocs.raw_message.json"
+    );
+    expect(result).toMatchObject({
+      properties: {
+        id: {
+          description: expect.stringMatching(/.+/),
+        },
+      },
+    });
+    expect(result["$defs"]).toBeUndefined();
+    expect(result).not.toMatchObject({
+      properties: {
+        id: {
+          $ref: expect.anything(),
+        },
+      },
+    });
+  });
+
+  test("does not duplicate array items", async () => {
+    const result = await derefSchemaPath(
+      "schemas/com.mbta.ocs.raw_message.json"
+    );
+    expect(result["required"]).toEqual([
+      "id",
+      "source",
+      "specversion",
+      "type",
+      "data",
+      "time",
+      "partitionkey",
+    ]);
+  });
+});

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

@@ -1,13 +1,11 @@
 ---
 ---
-
-import Schema from "@site/schemas/com.mbta.ocs.raw_message.json";
-import EventSchema from "@site/src/components/EventSchema.tsx";
+import EventSchemaPath from "@site/src/components/EventSchemaPath.tsx";
 
 Raw message from the OCS System. Trike turns the raw message into an event.
 
 Originally described in [RFC4](https://github.com/mbta/technology-docs/blob/main/rfcs/accepted/0004-socket-proxy-ocs-cloudevents.md).
 
 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).
 
-<EventSchema schema={ Schema } />
+<EventSchemaPath event="com.mbta.ocs.raw_message" />

docusaurus.config.js

@@ -1,76 +1,77 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+const lightCodeTheme = require("prism-react-renderer/themes/github");
+const darkCodeTheme = require("prism-react-renderer/themes/dracula");
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: 'MBTA Event Schemas',
-  tagline: '',
-  favicon: 'img/favicon.ico',
+  title: "MBTA Event Schemas",
+  tagline: "",
+  favicon: "img/favicon.ico",
 
   // Set the production url of your site here
-  url: (process.env.GITHUB_ORIGIN || "http://localhost:3000"),
+  url: process.env.GITHUB_ORIGIN || "http://localhost:3000",
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: (process.env.GITHUB_BASE || "/"),
+  baseUrl: process.env.GITHUB_BASE || "/",
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: "mbta", // Usually your GitHub org/user name.
   projectName: "schemas", // Usually your repo name.
 
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+  onBrokenLinks: "throw",
+  onBrokenMarkdownLinks: "warn",
 
   // Even if you don't use internalization, you can use this field to set useful
   // metadata like html lang. For example, if your site is Chinese, you may want
   // to replace "en" with "zh-Hans".
   i18n: {
-    defaultLocale: 'en',
-    locales: ['en'],
+    defaultLocale: "en",
+    locales: ["en"],
   },
-  staticDirectories: ['static', 'events'],
+  staticDirectories: ["static"],
   presets: [
     [
-      'classic',
+      "classic",
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
           routeBasePath: "/",
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: require.resolve("./sidebars.js"),
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl:
             "https://github.com/mbta/schemas/tree/main/",
         },
         blog: false,
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: require.resolve("./src/css/custom.css"),
         },
       }),
     ],
   ],
 
   themes: [["docusaurus-json-schema-plugin", {}]],
+  plugins: ["./src/plugins/deref-json-schemas"],
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
       // Replace with your project's social card
-      image: 'img/docusaurus-social-card.jpg',
+      image: "img/docusaurus-social-card.jpg",
       navbar: {
-        title: 'Schemas',
+        title: "Schemas",
         logo: {
-          alt: 'MBTA',
-          src: 'img/logo.png',
+          alt: "MBTA",
+          src: "img/logo.png",
         },
         items: [
           {
-            type: 'docSidebar',
-            sidebarId: 'eventsSidebar',
-            position: 'left',
-            label: 'Events',
+            type: "docSidebar",
+            sidebarId: "eventsSidebar",
+            position: "left",
+            label: "Events",
           },
           {
             href: "https://github.com/mbta/schemas",
@@ -80,19 +81,19 @@ const config = {
         ],
       },
       footer: {
-        style: 'dark',
+        style: "dark",
         links: [
           {
-            title: 'Docs',
+            title: "Docs",
             items: [
               {
-                label: 'Events',
-                to: '/category/events',
+                label: "Events",
+                to: "/category/events",
               },
             ],
           },
           {
-            title: 'More',
+            title: "More",
             items: [
               {
                 label: "GitHub",

jest.config.js

@@ -0,0 +1,6 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  reporters: ["default"],
+};

package.json

@@ -13,23 +13,28 @@
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "format": "prettier --write **/*.{js,jsx,ts,tsx,json}",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "test": "jest"
   },
   "dependencies": {
     "@docusaurus/core": "2.4.0",
     "@docusaurus/preset-classic": "2.4.0",
     "@mdx-js/react": "^1.6.22",
+    "@stoplight/json-ref-readers": "^1.2.2",
     "clsx": "^1.2.1",
     "deepmerge": "^4.3.1",
     "docusaurus-json-schema-plugin": "^1.6.0",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react-dom": "^17.0.2",
+    "webpack-merge": "^5.8.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.4.0",
     "@tsconfig/docusaurus": "^1.0.5",
+    "jest": "^29.5.0",
     "prettier": "^2.8.7",
+    "ts-jest": "^29.1.0",
     "typescript": "^4.7.4"
   },
   "browserslist": {

schemas/cloudevents.json

@@ -0,0 +1,93 @@
+{
+  "$id": "https://github.com/mbta/schemas/blob/main/schemas/cloudevents.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Modified from https://github.com/cloudevents/spec/blob/b43a64bf4fa92baee02dad512f23ea5cb77a321c/cloudevents/formats/cloudevents.json",
+  "description": "CloudEvents Specification JSON Schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "description": "Identifies the event.",
+      "type": "string",
+      "minLength": 1,
+      "examples": ["A234-1234-1234"]
+    },
+    "source": {
+      "description": "Identifies the context in which an event happened.",
+      "type": "string",
+      "format": "uri-reference",
+      "minLength": 1,
+      "examples": [
+        "https://github.com/cloudevents",
+        "mailto:[email protected]",
+        "urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66",
+        "cloudevents/spec/pull/123",
+        "/sensors/tn-1234567/alerts",
+        "1-555-123-4567"
+      ]
+    },
+    "specversion": {
+      "description": "The version of the CloudEvents specification which the event uses.",
+      "type": "string",
+      "minLength": 1,
+      "examples": ["1.0"]
+    },
+    "type": {
+      "description": "Describes the type of event related to the originating occurrence.",
+      "type": "string",
+      "minLength": 1,
+      "examples": [
+        "com.github.pull_request.opened",
+        "com.example.object.deleted.v2"
+      ]
+    },
+    "datacontenttype": {
+      "description": "Content type of the data value. Must adhere to RFC 2046 format.",
+      "type": ["string", "null"],
+      "minLength": 1,
+      "examples": [
+        "text/xml",
+        "application/json",
+        "image/png",
+        "multipart/form-data"
+      ]
+    },
+    "dataschema": {
+      "description": "Identifies the schema that data adheres to.",
+      "type": ["string", "null"],
+      "format": "uri",
+      "minLength": 1
+    },
+    "subject": {
+      "description": "Describes the subject of the event in the context of the event producer (identified by source).",
+      "type": ["string", "null"],
+      "minLength": 1,
+      "examples": ["mynewfile.jpg"]
+    },
+    "time": {
+      "description": "Timestamp of when the occurrence happened. Must adhere to RFC 3339.",
+      "type": ["string", "null"],
+      "format": "date-time",
+      "minLength": 1,
+      "examples": ["2018-04-05T17:31:00Z"]
+    },
+    "data": {
+      "description": "The event payload.",
+      "anyOf": [
+        { "type": "object" },
+        { "type": "string" },
+        { "type": "number" },
+        { "type": "array" },
+        { "type": "boolean" },
+        { "type": "null" }
+      ],
+      "examples": ["<much wow=\"xml\"/>"]
+    },
+    "data_base64": {
+      "description": "Base64 encoded event payload. Must adhere to RFC4648.",
+      "type": ["string", "null"],
+      "contentEncoding": "base64",
+      "examples": ["Zm9vYg=="]
+    }
+  },
+  "required": ["id", "source", "specversion", "type"]
+}