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

package/README.md

@@ -29,6 +29,7 @@ npm install --save docusaurus-plugin-generate-schema-docs
           'docusaurus-plugin-generate-schema-docs',
           {
             // Options if any
+            dataLayerName: 'customDataLayer',
           },
         ],
       ],
@@ -36,6 +37,8 @@ npm install --save docusaurus-plugin-generate-schema-docs
     };
     ```
 
+    The `dataLayerName` option allows you to customize the name of the data layer variable in the generated examples. If not provided, it defaults to `dataLayer`.
+
 2.  Place your JSON schemas in the `schemas` directory at the root of your project.
 
 ## CLI Commands
@@ -76,6 +79,31 @@ The plugin reads your JSON schemas, dereferences any `$ref` properties, and merg
 
 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.
 
+## Schema Composition (anyOf, oneOf)
+
+The plugin has special handling for `anyOf` and `oneOf` keywords in your JSON schemas.
+
+### `anyOf`
+
+When `anyOf` is used, the plugin will render a dropdown menu in the documentation that allows users to switch between the different sub-schemas. This is useful for representing properties that can have multiple different structures.
+
+### `oneOf`
+
+Similar to `anyOf`, `oneOf` will also render a dropdown menu.
+
+#### `oneOf` at the Root Level
+
+A special behavior is triggered when `oneOf` is used at the root level of a schema file. If a schema's top-level definition is a `oneOf` array, the plugin will generate a directory structure that reflects the choices.
+
+For example, given a schema `my-event.json` with a `oneOf` at the root, where each item in the `oneOf` array is a reference to another schema file (e.g., `option-a.json`, `option-b.json`), the plugin will generate the following structure:
+
+- `docs/events/my-event/`: A directory for the parent schema.
+- `docs/events/my-event/index.mdx`: An index page for `my-event`.
+- `docs/events/my-event/option-a.mdx`: A page for the first option.
+- `docs/events/my-event/option-b.mdx`: A page for the second option.
+
+This creates a nested navigation structure in Docusaurus, which is useful for grouping related events or entities under a single menu item.
+
 ## Versioning
 
 This plugin supports documentation and schema versioning, integrated with Docusaurus's native versioning system.

package/__tests__/ExampleDataLayer.test.js

@@ -68,6 +68,19 @@ describe('ExampleDataLayer', () => {
     // Let snapshot testing verify the complex content of each tab
     expect(container).toMatchSnapshot();
   });
+
+  it('should use the provided dataLayerName', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+    const { getByText } = render(
+      <ExampleDataLayer schema={schema} dataLayerName="customDataLayer" />,
+    );
+    expect(getByText(/window.customDataLayer.push/)).toBeInTheDocument();
+  });
 });
 
 describe('findClearableProperties', () => {

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

@@ -0,0 +1,29 @@
+{
+  "$id": "https://example.com/parent-event-anchor.json",
+  "title": "Parent Event Anchor",
+  "description": "This is a parent event with oneOf.",
+  "type": "object",
+  "oneOf": [
+    {
+      "title": "Child Event Anchor",
+      "description": "This is a child event with an anchor.",
+      "$anchor": "child-event-with-anchor",
+      "type": "object",
+      "properties": {
+        "property_a": {
+          "type": "string"
+        }
+      }
+    },
+    {
+      "title": "Child Event Title",
+      "description": "This is a child event with only a title.",
+      "type": "object",
+      "properties": {
+        "property_b": {
+          "type": "string"
+        }
+      }
+    }
+  ]
+}

package/__tests__/__fixtures__/validateSchemas/complex-validation/events/add-to-cart-event.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "events/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",
+  "properties": {
+    "$schema": {
+      "description": "Defines the structure of the event. This can be used to validate an event against the schema provided.",
+      "const": "events/add-to-cart-event.json",
+      "type": "string"
+    },
+    "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"]
+    }
+  },
+  "required": ["$schema", "event"]
+}

package/__tests__/__fixtures__/validateSchemas/complex-validation/events/choice-event.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "events/choice-event.json",
+  "title": "Choice Event",
+  "description": "An example event that uses oneOf and anyOf.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Defines the structure of the event. This can be used to validate an event against the schema provided.",
+      "const": "events/choice-event.json"
+    },
+    "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",
+          "type": "object",
+          "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__/validateSchemas/complex-validation/events/complex-event.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "events/complex-event.json",
+  "title": "Complex Event with Validation Constraints",
+  "description": "A generic event demonstrating various validation constraints and recursive documentation capabilities.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "event",
+    "number_constraints",
+    "string_constraints",
+    "user_data"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Defines the structure of the event. This can be used to validate an event against the schema provided.",
+      "const": "events/complex-event.json"
+    },
+    "event": {
+      "type": "string",
+      "const": "user_update",
+      "description": "The event name.",
+      "examples": ["user_update"]
+    },
+    "timestamp": {
+      "type": "integer",
+      "description": "Unix timestamp of the event.",
+      "examples": [16788922]
+    },
+    "user_data": {
+      "type": "object",
+      "description": "Container for user information.",
+      "required": ["user_id", "attributes"],
+      "properties": {
+        "user_id": {
+          "type": "string",
+          "description": "Unique User ID.",
+          "examples": ["U_999"]
+        },
+        "is_active": {
+          "type": "boolean",
+          "description": "Status of the user.",
+          "examples": [true]
+        },
+        "attributes": {
+          "type": "object",
+          "description": "Nested generic attributes.",
+          "properties": {
+            "segment": {
+              "type": "string",
+              "description": "Marketing segment.",
+              "examples": ["premium"]
+            },
+            "score": {
+              "type": "number",
+              "description": "Engagement score.",
+              "examples": [95]
+            }
+          }
+        },
+        "addresses": {
+          "type": "array",
+          "description": "List of user addresses.",
+          "items": {
+            "type": "object",
+            "required": ["city", "zip"],
+            "properties": {
+              "street": {
+                "type": "string",
+                "examples": ["123 Main St"]
+              },
+              "city": {
+                "type": "string",
+                "examples": ["New York"]
+              },
+              "zip": {
+                "type": "string",
+                "examples": ["10001"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "string_constraints": {
+      "type": "string",
+      "description": "A string with various constraints.",
+      "minLength": 2,
+      "maxLength": 10,
+      "pattern": "^[a-z]+$",
+      "format": "hostname",
+      "examples": ["example"]
+    },
+    "number_constraints": {
+      "type": "number",
+      "description": "A number with various constraints.",
+      "minimum": 10,
+      "maximum": 100,
+      "multipleOf": 5,
+      "examples": [50]
+    },
+    "exclusive_number_constraints": {
+      "type": "number",
+      "description": "A number with exclusive constraints.",
+      "exclusiveMinimum": 10,
+      "exclusiveMaximum": 100,
+      "examples": [50]
+    },
+    "array_constraints": {
+      "type": "array",
+      "description": "An array with various constraints.",
+      "minItems": 1,
+      "maxItems": 5,
+      "uniqueItems": true,
+      "items": {
+        "type": "string"
+      },
+      "examples": [["a", "b"]]
+    },
+    "contains_array_constraints": {
+      "type": "array",
+      "description": "An array with contains constraints.",
+      "contains": {
+        "type": "integer"
+      },
+      "minContains": 1,
+      "maxContains": 2,
+      "examples": [[1, "text", 2]]
+    },
+    "object_constraints": {
+      "type": "object",
+      "description": "An object with various constraints.",
+      "minProperties": 1,
+      "maxProperties": 3,
+      "additionalProperties": false,
+      "propertyNames": {
+        "pattern": "^[a-z0-9_]+$"
+      },
+      "properties": {
+        "prop_a": {
+          "type": "string",
+          "examples": ["some_value"]
+        },
+        "prop_b": {
+          "type": "string",
+          "examples": ["another_value"]
+        }
+      },
+      "examples": [
+        {
+          "prop_a": "some_value",
+          "prop_b": "another_value"
+        }
+      ]
+    },
+    "dependent_required_constraint": {
+      "type": "object",
+      "description": "An object with dependent required properties.",
+      "dependentRequired": {
+        "credit_card": ["billing_address"]
+      },
+      "properties": {
+        "credit_card": {
+          "type": "number",
+          "examples": [1234567890123456]
+        },
+        "billing_address": {
+          "type": "string",
+          "examples": ["123 Billing Address, Anytown, USA"]
+        }
+      },
+      "examples": [
+        {
+          "credit_card": 1234567890123456,
+          "billing_address": "123 Billing Address, Anytown, USA"
+        }
+      ]
+    },
+    "enum_constraint": {
+      "type": "string",
+      "description": "A property with an enum constraint.",
+      "enum": ["admin", "editor", "viewer"],
+      "examples": ["admin"]
+    },
+    "const_constraint": {
+      "type": "string",
+      "description": "A property that must have a constant value.",
+      "const": "must_be_this",
+      "examples": ["must_be_this"]
+    }
+  }
+}

package/__tests__/__fixtures__/validateSchemas/complex-validation/events/components/dataLayer.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "events/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": "^(\\$schema)|[a-z0-9_]+$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/strictObject"
+          },
+          {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/strictObject"
+            }
+          },
+          {
+            "not": {
+              "type": "object"
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/__tests__/__fixtures__/validateSchemas/complex-validation/events/components/product.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "events/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, 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],
+      "default": 1
+    },
+    "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/complex-validation/events/purchase-event.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "events/purchase-event.json",
+  "title": "Purchase Event",
+  "description": "A purchase event fires when a user completes a purchase. Based on Google Analytics 4 ecommerce event specifications.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Defines the structure of the event. This can be used to validate an event against the schema provided.",
+      "const": "events/purchase-event.json"
+    },
+    "event": {
+      "type": "string",
+      "const": "purchase",
+      "description": "The name of the event indicating a purchase has occurred."
+    },
+    "ecommerce": {
+      "type": "object",
+      "description": "Ecommerce related data for the purchase event.",
+      "properties": {
+        "transaction_id": {
+          "type": "string",
+          "description": "The unique ID of a transaction. The transaction_id parameter helps avoid duplicate transaction recording.",
+          "examples": ["T_12345", "TXN_20231205_001"]
+        },
+        "value": {
+          "type": "number",
+          "description": "The monetary value of the event. Set value to the sum of (price * quantity) for all items in items.",
+          "examples": [72.05, 99.99, 150.5]
+        },
+        "currency": {
+          "type": "string",
+          "description": "The currency of the items in ISO 4217 three-letter format. Required when value is set.",
+          "minLength": 3,
+          "maxLength": 3,
+          "examples": ["USD", "EUR", "GBP"]
+        },
+        "coupon": {
+          "type": "string",
+          "description": "The coupon/code associated with the event. Event-level and item-level coupon parameters are independent.",
+          "examples": ["SUMMER_SALE", "WELCOME15"]
+        },
+        "shipping": {
+          "type": "number",
+          "description": "The shipping cost associated with the transaction.",
+          "examples": [5.99, 10, 0]
+        },
+        "tax": {
+          "type": "number",
+          "description": "The tax associated with the transaction.",
+          "examples": [3.6, 7.5, 0]
+        },
+        "customer_type": {
+          "type": "string",
+          "enum": ["new", "returning"],
+          "description": "Whether this is from a new or returning customer. 'new' = customer with no purchase in the specified time window (default 540 days). 'returning' = customer with purchase in the specified time window.",
+          "examples": ["new", "returning"]
+        },
+        "items": {
+          "type": "array",
+          "description": "The products purchased in the transaction.",
+          "minItems": 1,
+          "items": {
+            "$ref": "./components/product.json"
+          }
+        }
+      },
+      "required": ["transaction_id", "value", "currency", "items"]
+    }
+  },
+  "required": ["$schema", "event"]
+}