docusaurus-plugin-generate-schema-docs 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,97 @@
+# Docusaurus Plugin: Generate Schema Docs
+
+This Docusaurus v2 plugin generates documentation from JSON schemas. It provides a set of tools to automatically create and validate documentation for your event schemas.
+
+## Features
+
+- **Automatic Documentation Generation**: Generates MDX documentation from your JSON schemas.
+- **Schema Validation**: Validates your schemas against the examples provided within them.
+- **CLI Commands**: Provides CLI commands to generate and validate schema documentation.
+- **Custom Components**: Includes React components to beautifully render your schema documentation.
+
+## Installation
+
+```bash
+npm install --save docusaurus-plugin-generate-schema-docs
+```
+
+## Usage
+
+1.  Configure the plugin in your `docusaurus.config.js`:
+
+    ```javascript
+    // docusaurus.config.js
+
+    module.exports = {
+      // ...
+      plugins: [
+        [
+          'docusaurus-plugin-generate-schema-docs',
+          {
+            // Options if any
+          },
+        ],
+      ],
+      // ...
+    };
+    ```
+
+2.  Place your JSON schemas in the `schemas` directory at the root of your project.
+
+## CLI Commands
+
+### Generate Documentation
+
+To generate the documentation from your schemas, run the following command:
+
+```bash
+npx docusaurus generate schema-docs
+```
+
+This will generate MDX files in the `docs/events` directory.
+
+### Validate Schemas
+
+To validate your schemas, run the following command:
+
+```bash
+npx docusaurus validate-schemas
+```
+
+This will validate the schemas in the `schemas` directory.
+
+## 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.
+
+## 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.
+
+## License
+
+This project is licensed under the MIT License.

package/__tests__/ExampleDataLayer.test.js

@@ -0,0 +1,169 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import ExampleDataLayer, { findClearableProperties } from '../components/ExampleDataLayer';
+import buildExampleFromSchema from '../helpers/buildExampleFromSchema';
+
+jest.mock('../helpers/buildExampleFromSchema', () => jest.fn());
+
+jest.mock('@theme/CodeBlock', () => {
+    return function CodeBlock({ children }) {
+        return <pre>{children}</pre>;
+    };
+});
+
+describe('ExampleDataLayer', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should render correctly with a simple schema', () => {
+        const schema = {
+            type: 'object',
+            properties: {
+                event: { type: 'string', examples: ['test_event'] },
+            },
+        };
+        const example = { event: 'test_event' };
+        buildExampleFromSchema.mockReturnValue(example);
+
+        const { container } = render(<ExampleDataLayer schema={schema} />);
+
+        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
+        const codeElement = container.querySelector('pre');
+        expect(codeElement.textContent).toMatchInlineSnapshot(`
+"window.dataLayer.push({
+  "event": "test_event"
+});"
+`);
+    });
+
+    it('should render correctly with properties to reset', () => {
+        const schema = {
+            type: 'object',
+            properties: {
+                ecommerce: {
+                    'x-gtm-clear': true,
+                    type: 'object',
+                    properties: { items: { type: 'array' } },
+                },
+                user_id: { type: 'string' }
+            },
+        };
+        const example = {
+            ecommerce: { items: [{ item_name: 'donuts' }] },
+            user_id: '123'
+        };
+        buildExampleFromSchema.mockReturnValue(example);
+
+        const { container } = render(<ExampleDataLayer schema={schema} />);
+
+        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
+
+        const codeElement = container.querySelector('pre');
+        expect(codeElement.textContent).toMatchInlineSnapshot(`
+"window.dataLayer.push({
+  "ecommerce": null
+});
+window.dataLayer.push({
+  "ecommerce": {
+    "items": [
+      {
+        "item_name": "donuts"
+      }
+    ]
+  },
+  "user_id": "123"
+});"
+`);
+    });
+
+    it('should render correctly with an empty schema', () => {
+        const schema = {};
+        const example = {};
+        buildExampleFromSchema.mockReturnValue(example);
+
+        const { container } = render(<ExampleDataLayer schema={schema} />);
+
+        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
+        const codeElement = container.querySelector('pre');
+        expect(codeElement.textContent).toMatchInlineSnapshot(`"window.dataLayer.push({});"`);
+    });
+
+    it('should not reset properties that are not in the final example', () => {
+        const schema = {
+            type: 'object',
+            properties: {
+                ecommerce: {
+                    'x-gtm-clear': true,
+                    type: 'object',
+                    properties: { items: { type: 'array' } },
+                },
+                user_data: {
+                    'x-gtm-clear': true,
+                    type: 'object'
+                },
+                event: { type: 'string' }
+            },
+        };
+        // buildExampleFromSchema will not include user_data because it's an empty object
+        const example = {
+            ecommerce: { items: [{ item_name: 'donuts' }] },
+            event: 'purchase'
+        };
+        buildExampleFromSchema.mockReturnValue(example);
+
+        const { container } = render(<ExampleDataLayer schema={schema} />);
+
+        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
+
+        const codeElement = container.querySelector('pre');
+        expect(codeElement.textContent).toMatchInlineSnapshot(`
+"window.dataLayer.push({
+  "ecommerce": null
+});
+window.dataLayer.push({
+  "ecommerce": {
+    "items": [
+      {
+        "item_name": "donuts"
+      }
+    ]
+  },
+  "event": "purchase"
+});"
+`);
+    });
+});
+
+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']);
+    });
+
+    it('should return an empty array if no properties have "x-gtm-clear": true', () => {
+        const schema = {
+            properties: {
+                prop1: { type: 'string' },
+                prop2: { type: 'object' },
+                prop3: { 'x-gtm-clear': false, type: 'object' },
+            }
+        };
+        expect(findClearableProperties(schema)).toEqual([]);
+    });
+});

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

@@ -0,0 +1,55 @@
+{
+  "$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.50
+          ]
+        },
+        "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/components/dataLayer.json

@@ -0,0 +1,58 @@
+{
+    "$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,211 @@
+{
+    "$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.00,
+                10.50
+            ]
+        },
+        "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__/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,8 @@
+{
+    "$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" }
+    }
+}

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

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

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

@@ -0,0 +1,8 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "valid-schema",
+    "title": "Valid Schema",
+    "type": "object",
+    "properties": { "name": { "type": "string", "examples": ["Test"] } },
+    "required": ["name"]
+}