docusaurus-plugin-generate-schema-docs 1.1.0

package/components/ExampleDataLayer.js

@@ -0,0 +1,38 @@
+import React from 'react';
+import CodeBlock from '@theme/CodeBlock';
+import buildExampleFromSchema from '../helpers/buildExampleFromSchema';
+
+export default function ExampleDataLayer({ schema }) {
+    // 1. Identify properties that need to be reset (cleared) first
+    const propertiesToReset = findComplexPropertiesToReset(schema || {});
+
+    // 2. Build the main example data
+    const example = buildExampleFromSchema(schema || {});
+
+    // 3. Construct the code snippet
+    let codeSnippet = '';
+
+    // If there are properties to reset, push them as null first
+    if (propertiesToReset.length > 0)
+    {
+        const resetObject = {};
+        propertiesToReset.forEach(prop => {
+            resetObject[prop] = null;
+        });
+        codeSnippet += `window.dataLayer.push(${JSON.stringify(resetObject, null, 2)});\n`;
+    }
+
+    // Append the main data payload
+    codeSnippet += `window.dataLayer.push(${JSON.stringify(example, null, 2)});`;
+
+    return <CodeBlock language="javascript">{codeSnippet}</CodeBlock>
+};
+
+const findComplexPropertiesToReset = (schema) => {
+    if (!schema || !schema.properties) return [];
+
+    return Object.entries(schema.properties)
+        .filter(([key, definition]) => definition["x-gtm-clear"] === true)
+        .map(([key]) => key);
+}
+

package/components/PropertiesTable.js

@@ -0,0 +1,19 @@
+import SchemaRows from './SchemaRows';
+
+export default function PropertiesTable({ schema }) {
+
+    return <table>
+        <thead>
+            <tr>
+                <th width="20%">Property</th>
+                <th width="15%">Type</th>
+                <th width="10%">Req</th>
+                <th with="15%">Examples</th>
+                <th>Description</th>
+            </tr>
+        </thead>
+        <tbody>
+            <SchemaRows properties={schema.properties} requiredList={schema.required} />
+        </tbody>
+    </table>
+}

package/components/SchemaJsonViewer.js

@@ -0,0 +1,10 @@
+import CodeBlock from '@theme/CodeBlock';
+
+export default function SchemaJsonViewer({ schema }) {
+
+    return (
+        <details>
+            <summary>View Raw JSON Schema</summary>
+            <CodeBlock language="json">{JSON.stringify(schema, null, 2)}</CodeBlock>
+        </details>);
+}

package/components/SchemaRows.js

@@ -0,0 +1,75 @@
+import React from 'react';
+
+const SchemaRows = ({ properties, requiredList = [], level = 0 }) => {
+    return (
+        <>
+            {Object.entries(properties).map(([key, prop]) => {
+                const isReq = requiredList.includes(key);
+
+                // 1. Calculate if it has children (Same as before)
+                const hasChildren =
+                    (prop.type === 'object' &&
+                        prop.properties &&
+                        Object.keys(prop.properties).length > 0) ||
+                    (prop.type === 'array' &&
+                        prop.items &&
+                        prop.items.properties &&
+                        Object.keys(prop.items.properties).length > 0);
+
+                const isObject = prop.type === 'object';
+                const isArrayOfObjects = prop.type === 'array' && prop.items && prop.items.type === 'object';
+
+                if ((isObject || isArrayOfObjects) && !hasChildren)
+                {
+                    return null;
+                }
+
+                return (
+                    <React.Fragment key={key}>
+                        {/* Main property row */}
+                        <tr style={{ backgroundColor: isReq ? 'rgba(255,0,0,0.05)' : 'transparent' }}>
+                            <td>
+                                <strong>{key}</strong>
+                                {hasChildren && <span style={{ fontSize: '0.8em', marginLeft: '5px' }}>⤵</span>}
+                            </td>
+                            <td><code>{Array.isArray(prop.type) ? prop.type.join('|') : prop.type}</code></td>
+                            <td style={{ textAlign: 'center' }}>{isReq ? '✅' : ''}</td>
+                            <td>{prop.examples ? prop.examples.join(', ') : ''}</td>
+                            <td>{prop.description || ''}</td>
+                        </tr>
+
+                        {/* Nested children rendered immediately after parent */}
+                        {hasChildren && (
+                            <tr>
+                                <td colSpan="5" style={{ paddingLeft: '20px', borderLeft: '4px solid #eee' }}>
+                                    <strong>{prop.type === 'array' ? `${key} [ ]` : `${key} { }`}</strong>
+                                    <table style={{ width: '100%', marginTop: '5px' }}>
+                                        <thead>
+                                            <tr>
+                                                <th width="20%">Property</th>
+                                                <th width="15%">Type</th>
+                                                <th width="10%">Req</th>
+                                                <th width="15%">Examples</th>
+                                                <th>Description</th>
+                                            </tr>
+                                        </thead>
+                                        <tbody>
+                                            <SchemaRows
+                                                properties={prop.type === 'object' ? prop.properties : prop.items.properties}
+                                                requiredList={prop.type === 'object' ? prop.required || [] : prop.items.required || []}
+                                                level={level + 1}
+                                            />
+                                        </tbody>
+                                    </table>
+                                </td>
+                            </tr>
+                        )
+                        }
+                    </React.Fragment >
+                );
+            })}
+        </>
+    );
+};
+
+export default SchemaRows;

package/components/SchemaViewer.js

@@ -0,0 +1,19 @@
+import ExampleDataLayer from './ExampleDataLayer';
+import PropertiesTable from './PropertiesTable';
+
+// --- Main Exported Component ---
+// Helper: Build an example payload from per-property `examples` or other hints
+
+
+export default function SchemaViewer({ schema }) {
+
+    return (
+        <div>
+            <h2>DataLayer Example</h2>
+            <ExampleDataLayer schema={schema} />
+
+            <h2>Event Properties</h2>
+            <PropertiesTable schema={schema} />
+        </div>
+    );
+}

package/generateEventDocs.js

@@ -0,0 +1,68 @@
+import $RefParser from "@apidevtools/json-schema-ref-parser";
+import mergeJsonSchema from "json-schema-merge-allof";
+import fs from 'fs';
+import path from 'path';
+
+export default async function generateEventDocs() {
+    // CONFIGURATION
+    const SCHEMA_DIR = 'schemas'; // Where your JSON files are
+    const OUTPUT_DIR = 'docs/events'; // Where MDX goes
+
+    // Ensure output dir exists
+    if (!fs.existsSync(OUTPUT_DIR))
+    {
+        fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+    }
+
+    // Read all JSON files
+    const files = fs.readdirSync(SCHEMA_DIR).filter(file => file.endsWith('.json'));
+
+    console.log(`🚀 Generating documentation for ${files.length} schemas...`);
+
+    for (const file of files)
+    {
+        const filePath = path.join(SCHEMA_DIR, file);
+        const rawContent = fs.readFileSync(filePath, 'utf-8');
+        const schema = JSON.parse(rawContent);
+
+        // First, dereference all $ref properties
+        const clonedSchema = await $RefParser.dereference(filePath, {
+            mutateInputSchema: false, dereference: {
+                circular: 'ignore'
+            }
+        });
+
+        // Then merge allOf properties
+        const mergedSchema = mergeJsonSchema(clonedSchema, {
+            resolvers: {
+                defaultResolver: mergeJsonSchema.options.resolvers.title
+            }
+        });
+
+        // Define the MDX Content
+        // We embed the JSON directly into the file to avoid Webpack import issues
+        const mdxContent = `---
+title: ${schema.title}
+description: ${schema.description}
+sidebar_label: ${schema.title}
+---
+
+import SchemaViewer from '@theme/SchemaViewer';
+import SchemaJsonViewer from '@theme/SchemaJsonViewer';
+
+# ${schema.title}
+
+${schema.description}
+
+<SchemaViewer schema={${JSON.stringify(mergedSchema)}} />
+<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+`;
+
+        // Write the .mdx file
+        const outputFilename = file.replace('.json', '.mdx');
+        fs.writeFileSync(path.join(OUTPUT_DIR, outputFilename), mdxContent);
+        console.log(`✅ Generated docs/events/${outputFilename}`);
+    }
+
+    console.log('🎉 Documentation generation complete!');
+}

package/helpers/buildExampleFromSchema.js

@@ -0,0 +1,83 @@
+const buildExampleFromSchema = (schema) => {
+    const buildValue = (prop) => {
+        if (!prop) return undefined;
+
+        // 1. Prefer explicit examples or constants if available
+        if (prop.examples && prop.examples.length) return prop.examples[0];
+        if (prop.const !== undefined) return prop.const;
+        if (prop.default !== undefined) return prop.default;
+
+        const type = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+
+        if (type === 'object')
+        {
+            if (prop.properties)
+            {
+                const obj = {};
+                Object.entries(prop.properties).forEach(([k, v]) => {
+                    const val = buildValue(v);
+                    // Only add the property if it has a valid value (not undefined)
+                    if (val !== undefined)
+                    {
+                        obj[k] = val;
+                    }
+                });
+
+                // If the object ends up having no keys, consider it "empty" and return undefined
+                if (Object.keys(obj).length === 0) return undefined;
+                return obj;
+            }
+            // Object with no properties defined
+            return {};
+        }
+
+        if (type === 'array')
+        {
+            if (prop.items)
+            {
+                const itemVal = buildValue(prop.items);
+                // If the inner item is valid, return it as an array
+                if (itemVal !== undefined)
+                {
+                    return [itemVal];
+                }
+            }
+            // Empty array or array of undefined items
+            return [];
+        }
+
+        switch (type)
+        {
+            case 'string': return '';
+            case 'integer':
+            case 'number': return 0;
+            case 'boolean': return false;
+            default: return undefined;
+        }
+    };
+
+    // If the schema provides a top-level examples array with an object, prefer it
+    if (schema && schema.examples && schema.examples.length)
+    {
+        const first = schema.examples[0];
+        if (typeof first === 'object' && first !== null) return first;
+    }
+
+    // Otherwise, build from properties
+    if (schema && schema.properties)
+    {
+        const out = {};
+        Object.entries(schema.properties).forEach(([k, p]) => {
+            const val = buildValue(p);
+            // Only add top-level keys if they are not undefined
+            if (val !== undefined)
+            {
+                out[k] = val;
+            }
+        });
+        return out;
+    }
+
+    return {};
+}
+export default buildExampleFromSchema;

package/index.js

@@ -0,0 +1,50 @@
+import validateSchemas from './validateSchemas.js';
+import generateEventDocs from './generateEventDocs.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default function (context, options) {
+    return {
+        name: 'docusaurus-plugin-generate-schema-docs',
+
+        getThemePath() {
+            return path.resolve(__dirname, './components');
+        },
+
+        extendCli(cli) {
+            cli
+                .command('validate-schemas')
+                .description('Validate JSON Schemas with the examples inside the schemas')
+                .action(async () => {
+                    console.log('Validating GTM Schemas...');
+                    // You might get the path from 'options' or assume a default
+                    const schemaPath = options?.path || path.join(context.siteDir, 'schemas');
+
+                    const success = await validateSchemas(schemaPath);
+
+                    if (!success)
+                    {
+                        console.error('Validation failed.');
+                        process.exit(1); // Important for CI to fail!
+                    }
+                    console.log('✅ All schemas and examples are valid!');
+                });
+
+            cli
+                .command('generate schema-docs')
+                .description('Generate schema documentation from JSON schemas')
+                .action(async () => {
+                    // You can pass options here if generateEventDocs needs the path too
+                    // e.g., await generateEventDocs(options.path || './static/schemas');
+                    await generateEventDocs();
+                });
+        },
+
+        async loadContent() {
+            await generateEventDocs();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "docusaurus-plugin-generate-schema-docs",
+  "version": "1.1.0",
+  "description": "Docusaurus plugin to generate documentation from JSON schemas.",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^15.1.3",
+    "fs-extra": "^11.2.0",
+    "json-schema-merge-allof": "^0.8.1"
+  }
+}

package/validateSchemas.js

@@ -0,0 +1,86 @@
+import fs from 'fs';
+import path from 'path';
+import buildExampleFromSchema from './helpers/buildExampleFromSchema';
+import Ajv2020 from 'ajv/dist/2020.js';
+import $RefParser from "@apidevtools/json-schema-ref-parser";
+import mergeJsonSchema from "json-schema-merge-allof";
+
+const validateSchemas = async (schemaPath) => {
+    const ajv = new Ajv2020();
+    ajv.addKeyword('x-gtm-clear');
+
+    const getAllFiles = (dir, allFiles = []) => {
+        const files = fs.readdirSync(dir);
+
+        files.forEach(file => {
+            const filePath = path.join(dir, file);
+            if (fs.statSync(filePath).isDirectory())
+            {
+                getAllFiles(filePath, allFiles);
+            } else
+            {
+                if (file.endsWith('.json'))
+                {
+                    allFiles.push(filePath);
+                }
+            }
+        });
+        return allFiles;
+    };
+
+    const allSchemaFiles = getAllFiles('schemas');
+    for (const file of allSchemaFiles)
+    {
+        const schemaContent = fs.readFileSync(file, 'utf-8');
+        const schema = JSON.parse(schemaContent);
+        ajv.addSchema(schema);
+    }
+
+    const schemaFiles = fs.readdirSync(schemaPath).filter(file => file.endsWith('.json'));
+    let allValid = true;
+    for (const file of schemaFiles)
+    {
+        const filePath = path.join(schemaPath, file);
+        
+        // Dereference and merge, same as in generateEventDocs.js
+        const clonedSchema = await $RefParser.dereference(filePath, {
+            mutateInputSchema: false, dereference: {
+                circular: 'ignore'
+            }
+        });
+        const mergedSchema = mergeJsonSchema(clonedSchema, {
+            resolvers: {
+                defaultResolver: mergeJsonSchema.options.resolvers.title
+            }
+        });
+
+        const example_data = buildExampleFromSchema(mergedSchema);
+
+        if (!example_data)
+        {
+            console.error(`❌ Schema ${file} does not produce a valid example.`);
+            allValid = false;
+        } else
+        {
+            const originalSchema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            const validate = ajv.getSchema(originalSchema.$id);
+            if (!validate) {
+                console.error(`❌ Could not find compiled schema for ${originalSchema.$id}`);
+                allValid = false;
+                continue;
+            }
+            if (validate(example_data))
+            {
+                console.log(`✅ Schema ${file} produced a valid example.`);
+            } else
+            {
+                console.error(`❌ Schema ${file} example data failed validation:`);
+                console.error(validate.errors);
+                allValid = false;
+            }
+        }
+    }
+    return allValid;
+};
+
+export default validateSchemas;