docusaurus-plugin-generate-schema-docs 1.1.1 → 1.3.0

package/README.md

@@ -45,7 +45,7 @@ npm install --save docusaurus-plugin-generate-schema-docs
 To generate the documentation from your schemas, run the following command:
 
 ```bash
-npx docusaurus generate schema-docs
+npm run gen-docs
 ```
 
 This will generate MDX files in the `docs/events` directory.
@@ -55,17 +55,75 @@ This will generate MDX files in the `docs/events` directory.
 To validate your schemas, run the following command:
 
 ```bash
-npx docusaurus validate-schemas
+npm run validate-schemas
 ```
 
 This will validate the schemas in the `schemas` directory.
 
+### Update Schema IDs
+
+When using versioning, you can update the `$id` of your versioned schemas by running:
+
+```bash
+npm run update-schema-ids
+```
+
+This command will update the `$id` of all schemas in the versioned directories.
+
 ## How it Works
 
 The plugin reads your JSON schemas, dereferences any `$ref` properties, and merges `allOf` properties. It then generates an MDX file for each schema, which uses custom React components to render the schema details.
 
 The validation script builds an example from each schema and validates it against the schema itself, ensuring your examples are always in sync with your schemas.
 
+## Versioning
+
+This plugin supports documentation and schema versioning, integrated with Docusaurus's native versioning system.
+
+### Enabling Versioning
+
+To enable versioning, you need to:
+
+1.  **Enable Docusaurus Versioning**: Follow the [Docusaurus documentation](https://docusaurus.io/docs/versioning) to enable versioning for your site. This typically involves creating a `versions.json` file.
+
+2.  **Organize Your Schemas**: Create a versioned directory structure for your schemas. Instead of placing your schemas in `static/schemas`, you should have:
+    - `static/schemas/next`: For the "current" or "next" version of your schemas.
+    - `static/schemas/<version>`: For each version of your schemas (e.g., `static/schemas/1.1.1`).
+
+When versioning is enabled, the plugin will automatically detect the `versions.json` file and generate documentation for each version, as well as for the `current` version.
+
+### Non-Versioned Mode
+
+If you do not have a `versions.json` file in your `siteDir`, the plugin will run in non-versioned mode. It will read your schemas from `static/schemas` and generate documentation in `docs/events`.
+
+### Schema `$id` Versioning
+
+When using the versioning feature, the plugin will automatically update the `$id` of your schemas to include the version number. For example, if your site's `url` is `https://example.com` and you have a schema `my-event.json` in version `1.0.0`, the `$id` will be updated to `https://example.com/schemas/1.0.0/my-event.json`.
+
+This is done automatically by the plugin. However, if you need to update the `$id`s of your schemas manually, you can use the `update-schema-ids.js` script located in the plugin's `helpers` directory.
+
+## Partials
+
+You can provide additional content to the generated documentation pages by creating partial files. Partials are Markdown files that can be automatically included in the generated pages.
+
+### Naming Convention
+
+Partials must be named after the schema file they correspond to. For a schema named `my-event.json`, the partials would be:
+
+- `my-event.mdx`: This partial is rendered directly after the schema's main description.
+- `my-event_bottom.mdx`: This partial is rendered at the very bottom of the page.
+
+### Location
+
+Place your partial files in the `/docs/partials` directory at the root of your docusaurus project. The plugin will automatically find and include them.
+
+### Example
+
+If you have a schema `add-to-cart-event.json`, you can create the following files:
+
+- `docs/partials/add-to-cart-event.mdx`: For content to appear after the description.
+- `docs/partials/add-to-cart-event_bottom.mdx`: For content to appear at the bottom.
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request if you have any ideas or improvements.

package/__tests__/ExampleDataLayer.test.js

@@ -0,0 +1,92 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import ExampleDataLayer, {
+  findClearableProperties,
+} from '../components/ExampleDataLayer';
+import choiceEventSchema from './__fixtures__/static/schemas/choice-event.json';
+
+// Mock the CodeBlock to make assertions on its content easier
+jest.mock('@theme/CodeBlock', () => {
+  return function CodeBlock({ children, language }) {
+    return <pre data-language={language}>{children}</pre>;
+  };
+});
+
+jest.mock('@theme/Tabs', () => {
+  return function Tabs({ children }) {
+    return <div data-testid="tabs">{children}</div>;
+  };
+});
+
+jest.mock('@theme/TabItem', () => {
+  return function TabItem({ children, label }) {
+    return (
+      <div data-testid="tab-item" data-label={label}>
+        {children}
+      </div>
+    );
+  };
+});
+
+describe('ExampleDataLayer', () => {
+  it('should render a single example for a simple schema', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+    const { container } = render(<ExampleDataLayer schema={schema} />);
+    expect(container).toMatchSnapshot();
+  });
+
+  it('should render nothing for an empty schema', () => {
+    const { container } = render(<ExampleDataLayer schema={{}} />);
+    // An empty schema produces no examples, so the component should render null
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('should render grouped tabs for a schema with choices', () => {
+    const { container, getAllByTestId } = render(
+      <ExampleDataLayer schema={choiceEventSchema} />,
+    );
+
+    // Check for the group headings
+    const headings = screen.getAllByRole('heading', { level: 4 });
+    expect(headings[0]).toHaveTextContent(/user_id options:/);
+    expect(headings[1]).toHaveTextContent(/payment_method options:/);
+
+    const tabItems = getAllByTestId('tab-item');
+    // 2 options for user_id + 2 options for payment_method = 4 tabs total
+    expect(tabItems).toHaveLength(4);
+
+    // Check the labels for one of the groups
+    expect(tabItems[0]).toHaveAttribute('data-label', 'User ID as String');
+    expect(tabItems[1]).toHaveAttribute('data-label', 'User ID as Integer');
+
+    // Let snapshot testing verify the complex content of each tab
+    expect(container).toMatchSnapshot();
+  });
+});
+
+describe('findClearableProperties', () => {
+  it('should return an empty array when schema is empty, null, or has no properties', () => {
+    expect(findClearableProperties({})).toEqual([]);
+    expect(findClearableProperties({ type: 'object' })).toEqual([]);
+    expect(findClearableProperties(null)).toEqual([]);
+    expect(findClearableProperties(undefined)).toEqual([]);
+  });
+
+  it('should return properties with "x-gtm-clear": true', () => {
+    const schema = {
+      properties: {
+        prop1: { type: 'string' },
+        prop2: { 'x-gtm-clear': true, type: 'object' },
+        prop3: { 'x-gtm-clear': false, type: 'object' },
+        prop4: { 'x-gtm-clear': true, type: 'array' },
+      },
+    };
+    expect(findClearableProperties(schema)).toEqual(['prop2', 'prop4']);
+  });
+});

package/__tests__/__fixtures__/static/schemas/add-to-cart-event.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/add-to-cart-event.json",
+  "title": "Add to Cart Event",
+  "description": "An add_to_cart event fires when a user adds one or more items to their shopping cart. Based on Google Analytics 4 ecommerce event specifications.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./components/dataLayer.json"
+    }
+  ],
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "add_to_cart",
+      "description": "The name of the event indicating a add_to_cart has occurred."
+    },
+    "ecommerce": {
+      "type": "object",
+      "description": "Ecommerce related data for the purchase event.",
+      "properties": {
+        "value": {
+          "type": "number",
+          "description": "The monetary value of the event. Set value to the sum of (price * quantity) for all items in items.",
+          "examples": [30.03, 99.99, 45.5]
+        },
+        "currency": {
+          "type": "string",
+          "description": "The currency of the items in ISO 4217 three-letter format. Required when value is set.",
+          "examples": ["USD", "EUR", "GBP"]
+        },
+        "items": {
+          "type": "array",
+          "description": "The products added to the cart.",
+          "minItems": 1,
+          "items": {
+            "$ref": "./components/product.json"
+          }
+        }
+      },
+      "required": ["currency", "items"]
+    }
+  }
+}

package/__tests__/__fixtures__/static/schemas/choice-event.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/1.2.0/choice-event.json",
+  "title": "Choice Event",
+  "description": "An example event that uses oneOf and anyOf.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "one_of_event"
+    },
+    "user_id": {
+      "description": "The user's ID.",
+      "oneOf": [
+        {
+          "type": "string",
+          "title": "User ID as String",
+          "description": "The user's ID as a string.",
+          "examples": ["user-123"]
+        },
+        {
+          "type": "integer",
+          "title": "User ID as Integer",
+          "description": "The user's ID as an integer.",
+          "examples": [123]
+        }
+      ]
+    },
+    "payment_method": {
+      "description": "The user's payment method.",
+      "type": "object",
+      "anyOf": [
+        {
+          "title": "Credit Card",
+          "properties": {
+            "payment_type": {
+              "type": "string",
+              "enum": ["credit_card", "debit_card"],
+              "examples": ["credit_card"]
+            },
+            "card_number": {
+              "type": "string",
+              "examples": ["1234-5678-9012-3456"]
+            },
+            "expiry_date": {
+              "type": "string",
+              "examples": ["12/26"]
+            }
+          },
+          "required": ["card_number", "expiry_date"]
+        },
+        {
+          "title": "PayPal",
+          "type": "object",
+          "properties": {
+            "payment_type": {
+              "type": "string",
+              "const": "paypal"
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "examples": ["test@example.com"]
+            }
+          },
+          "required": ["email"]
+        }
+      ]
+    }
+  },
+  "required": ["event", "user_id", "payment_method"]
+}

package/__tests__/__fixtures__/static/schemas/components/dataLayer.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/components/dataLayer.json",
+  "title": "dataLayer",
+  "description": "Schema for the object structure pushed to the dataLayer.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/$defs/strictObject"
+    }
+  ],
+  "properties": {
+    "event": {
+      "type": "string",
+      "description": "The name of the event."
+    },
+    "ecommerce": {
+      "type": "object",
+      "description": "Ecommerce related data.",
+      "x-gtm-clear": true
+    },
+    "user_data": {
+      "type": "object",
+      "description": "User related data.",
+      "x-gtm-clear": true
+    }
+  },
+  "required": ["event"],
+  "$defs": {
+    "strictObject": {
+      "type": "object",
+      "propertyNames": {
+        "maxLength": 40,
+        "pattern": "^[a-z0-9_]+$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/strictObject"
+          },
+          {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/strictObject"
+            }
+          },
+          {
+            "not": {
+              "type": "object"
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/__tests__/__fixtures__/static/schemas/components/product.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/components/product.json",
+  "title": "A Product",
+  "description": "A product object representing an item for use within a purchase event, based on Google Analytics 4 ecommerce event specifications.",
+  "type": "object",
+  "properties": {
+    "item_id": {
+      "type": "string",
+      "description": "The ID of the item. Either item_id or item_name is required.",
+      "examples": ["SKU_12345", "PROD_98765"]
+    },
+    "item_name": {
+      "type": "string",
+      "description": "The name of the item. Either item_id or item_name is required.",
+      "examples": ["Stan and Friends Tee", "Blue Running Shoes"]
+    },
+    "affiliation": {
+      "type": "string",
+      "description": "A product affiliation to indicate a supplier or store. Note: affiliation is only available at the item level.",
+      "examples": ["Google Merchandise Store", "Nike Store"]
+    },
+    "coupon": {
+      "type": "string",
+      "description": "The coupon name/code associated with the item. Coupon parameters at event and item levels are independent.",
+      "examples": ["SUMMER_FUN", "WELCOME20", "SAVE10"]
+    },
+    "discount": {
+      "type": "number",
+      "description": "The monetary value of the discount per unit applied to the item.",
+      "examples": [2.22, 5.0, 10.5]
+    },
+    "index": {
+      "type": "number",
+      "description": "The index or position of the item in a list.",
+      "examples": [0, 1, 2]
+    },
+    "item_brand": {
+      "type": "string",
+      "description": "The brand of the item.",
+      "examples": ["Google", "Nike", "Adidas"]
+    },
+    "item_category": {
+      "type": "string",
+      "description": "The category of the item. If used as part of a category hierarchy or taxonomy, this is the first category.",
+      "examples": ["Apparel", "Footwear", "Electronics"]
+    },
+    "item_category2": {
+      "type": "string",
+      "description": "The second category hierarchy or additional taxonomy of the item.",
+      "examples": ["Adult", "Women", "Men"]
+    },
+    "item_category3": {
+      "type": "string",
+      "description": "The third category hierarchy or additional taxonomy of the item.",
+      "examples": ["Shirts", "Shoes", "Boots"]
+    },
+    "item_category4": {
+      "type": "string",
+      "description": "The fourth category hierarchy or additional taxonomy of the item.",
+      "examples": ["Crew", "Running", "Casual"]
+    },
+    "item_category5": {
+      "type": "string",
+      "description": "The fifth category hierarchy or additional taxonomy of the item.",
+      "examples": ["Short sleeve", "Long distance", "Lightweight"]
+    },
+    "item_list_id": {
+      "type": "string",
+      "description": "The ID of the list in which the item was presented to the user. If set, item_list_id at the event level is ignored. If not set, item_list_id at the event level is used if available.",
+      "examples": ["related_products", "search_results", "recommendations"]
+    },
+    "item_list_name": {
+      "type": "string",
+      "description": "The name of the list in which the item was presented to the user. If set, item_list_name at the event level is ignored. If not set, item_list_name at the event level is used if available.",
+      "examples": ["Related Products", "Search Results", "Recommended Items"]
+    },
+    "item_variant": {
+      "type": "string",
+      "description": "The item variant or unique code or description for additional item details/options.",
+      "examples": ["green", "Blue Size 10", "M-Black"]
+    },
+    "location_id": {
+      "type": "string",
+      "description": "The physical location associated with the item, such as the location of a brick-and-mortar store. It is recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: location_id is only available at the item level.",
+      "examples": ["ChIJIQBpAG2ahYAR_6128GcTUEo", "store_123", "location_sf"]
+    },
+    "price": {
+      "type": "number",
+      "description": "The price of the item in the specified currency unit. If a discount is applied to the item, set price to the reduced per-unit price and provide the per-unit price discount in the discount parameter.",
+      "examples": [10.01, 21.01, 89.99]
+    },
+    "quantity": {
+      "type": "number",
+      "description": "The item quantity. If not set, quantity is set to 1.",
+      "examples": [1, 2, 3]
+    },
+    "promotion_id": {
+      "type": "string",
+      "description": "The ID of the promotion associated with the item.",
+      "examples": ["P_12345", "PROMO_001"]
+    },
+    "promotion_name": {
+      "type": "string",
+      "description": "The name of the promotion associated with the item.",
+      "examples": ["Summer Sale", "Black Friday", "Flash Deal"]
+    },
+    "creative_name": {
+      "type": "string",
+      "description": "The name of the promotion creative.",
+      "examples": ["summer_banner2", "holiday_email_v1"]
+    },
+    "creative_slot": {
+      "type": "string",
+      "description": "The name of the creative slot associated with the item.",
+      "examples": ["featured_app_1", "top_banner", "sidebar"]
+    },
+    "google_business_vertical": {
+      "type": "string",
+      "description": "The business vertical for the item (e.g., 'retail').",
+      "examples": ["retail", "ecommerce"]
+    }
+  },
+  "required": []
+}

package/__tests__/__fixtures__/static/schemas/nested/child-event.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/nested/child-event.json",
+  "title": "Child Event",
+  "type": "object",
+  "oneOf": [
+    { "$ref": "./grandchild-a.json" },
+    { "$ref": "./grandchild-b.json" }
+  ]
+}

package/__tests__/__fixtures__/static/schemas/nested/grandchild-a.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/nested/grandchild-a.json",
+  "title": "Grandchild A",
+  "type": "object",
+  "properties": {
+    "prop_a": { "type": "string" }
+  }
+}

package/__tests__/__fixtures__/static/schemas/nested/grandchild-b.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/nested/grandchild-b.json",
+  "title": "Grandchild B",
+  "type": "object",
+  "properties": {
+    "prop_b": { "type": "string" }
+  }
+}

package/__tests__/__fixtures__/static/schemas/nested/parent-event.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/nested/parent-event.json",
+  "title": "Parent Event",
+  "type": "object",
+  "oneOf": [{ "$ref": "./child-event.json" }]
+}

package/__tests__/__fixtures__/static/schemas/root-any-of-event.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/1.2.0/root-any-of-event.json",
+  "title": "Root AnyOf Event",
+  "description": "An example event that has anyOf at the root level.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "any_of_event"
+    }
+  },
+  "anyOf": [
+    {
+      "title": "Has Param C",
+      "properties": {
+        "param_c": {
+          "type": "string",
+          "examples": ["example_c"],
+          "description": "This is the description for Param C."
+        }
+      }
+    },
+    {
+      "title": "Has Param D",
+      "properties": {
+        "param_d": {
+          "type": "boolean",
+          "examples": [true]
+        }
+      }
+    }
+  ]
+}

package/__tests__/__fixtures__/static/schemas/root-choice-event.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/root-choice-event.schema.json",
+  "title": "Root Choice Event",
+  "description": "An example event that has oneOf at the root level.",
+  "oneOf": [
+    {
+      "title": "Option A",
+      "type": "object",
+      "properties": {
+        "event": {
+          "type": "string",
+          "const": "option_a"
+        },
+        "param_a": {
+          "type": "string",
+          "examples": ["example_a"]
+        }
+      }
+    },
+    {
+      "title": "Option B",
+      "type": "object",
+      "properties": {
+        "event": {
+          "type": "string",
+          "const": "option_b"
+        },
+        "param_b": {
+          "type": "integer",
+          "examples": [123]
+        }
+      }
+    }
+  ]
+}

package/__tests__/__fixtures__/validateSchemas/circular-schema.json

@@ -0,0 +1,8 @@
+{
+  "title": "Circular Schema",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "parent": { "$ref": "#" }
+  }
+}

package/__tests__/__fixtures__/validateSchemas/components/referenced.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "components/referenced.json",
+  "title": "Referenced Component",
+  "type": "object",
+  "properties": {
+    "prop": { "type": "string", "examples": ["component prop"] }
+  },
+  "required": ["prop"]
+}

package/__tests__/__fixtures__/validateSchemas/invalid-example-schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "invalid-example-schema",
+  "title": "Invalid Example Schema",
+  "type": "object",
+  "properties": { "age": { "type": "number", "examples": ["not-a-number"] } },
+  "required": ["age"]
+}

package/__tests__/__fixtures__/validateSchemas/main-schema-with-missing-ref.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "main-schema-with-missing-ref",
+  "title": "Main Schema with Missing Ref",
+  "type": "object",
+  "properties": { "component": { "$ref": "non-existent-component.json" } },
+  "required": ["component"]
+}

package/__tests__/__fixtures__/validateSchemas/main-schema-with-ref.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "main-schema-with-ref",
+  "title": "Main Schema with Ref",
+  "type": "object",
+  "properties": { "component": { "$ref": "components/referenced.json" } },
+  "required": ["component"]
+}

package/__tests__/__fixtures__/validateSchemas/no-example-schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "no-valid-example-schema",
+  "title": "No Valid Example Schema",
+  "type": "object",
+  "properties": {
+    "some_prop": {
+      "description": "This property has no type or example, so it won't be in the generated example."
+    }
+  },
+  "required": ["some_prop"]
+}

package/__tests__/__fixtures__/validateSchemas/schema-A.json

@@ -0,0 +1,7 @@
+{
+  "title": "Schema A",
+  "type": "object",
+  "properties": {
+    "b": { "$ref": "schema-B.json" }
+  }
+}