docusaurus-plugin-generate-schema-docs 1.8.3 → 1.8.4

package/helpers/schema-doc-template.js

@@ -12,6 +12,7 @@ export default function MdxTemplate(data) {
     sourcePath,
     schemaSources,
   } = data;
+  const sourceSchema = schemaSources?.[sourcePath] || schema;
 
   return `---
 title: ${schema.title}
@@ -33,6 +34,9 @@ ${topPartialComponent}
 
 <SchemaViewer
   schema={${JSON.stringify(mergedSchema)}}
+  sourceSchema={${JSON.stringify(sourceSchema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
   ${dataLayerName ? ` dataLayerName={'${dataLayerName}'}` : ''}
 />
 <SchemaJsonViewer

package/helpers/schemaToExamples.js

@@ -1,44 +1,31 @@
 import buildExampleFromSchema from './buildExampleFromSchema';
 import { mergeSchema } from './mergeSchema.js';
+import traversalHelpers from './schemaTraversal.cjs';
 
-const findChoicePoints = (subSchema, path = []) => {
-  if (!subSchema) {
-    return [];
-  }
+const { visitSchemaNodes } = traversalHelpers;
 
-  const choiceType = subSchema.oneOf
-    ? 'oneOf'
-    : subSchema.anyOf
-      ? 'anyOf'
-      : null;
-  const currentChoice = choiceType ? [{ path, schema: subSchema }] : [];
+const findChoicePoints = (schema) => {
+  const choicePoints = [];
 
-  const nestedChoices = subSchema.properties
-    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
-        findChoicePoints(propSchema, [...path, 'properties', key]),
-      )
-    : [];
+  visitSchemaNodes(schema, (subSchema, context) => {
+    if (subSchema.oneOf || subSchema.anyOf) {
+      choicePoints.push({ path: context.path, schema: subSchema });
+    }
+  });
 
-  return [...currentChoice, ...nestedChoices];
+  return choicePoints;
 };
 
-const findConditionalPoints = (subSchema, path = []) => {
-  if (!subSchema) {
-    return [];
-  }
-
-  const currentConditional =
-    subSchema.if && (subSchema.then || subSchema.else)
-      ? [{ path, schema: subSchema }]
-      : [];
+const findConditionalPoints = (schema) => {
+  const conditionalPoints = [];
 
-  const nestedConditionals = subSchema.properties
-    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
-        findConditionalPoints(propSchema, [...path, 'properties', key]),
-      )
-    : [];
+  visitSchemaNodes(schema, (subSchema, context) => {
+    if (subSchema.if && (subSchema.then || subSchema.else)) {
+      conditionalPoints.push({ path: context.path, schema: subSchema });
+    }
+  });
 
-  return [...currentConditional, ...nestedConditionals];
+  return conditionalPoints;
 };
 
 const generateExampleForChoice = (rootSchema, path, option) => {
@@ -151,10 +138,17 @@ export function schemaToExamples(rootSchema) {
 
   if (choicePoints.length === 0 && conditionalPoints.length === 0) {
     const example = buildExampleFromSchema(rootSchema);
-    if (example && Object.keys(example).length > 0) {
-      return [
-        { property: 'default', options: [{ title: 'Example', example }] },
-      ];
+    if (typeof example !== 'undefined') {
+      const shouldIncludeObjectExample =
+        typeof example !== 'object' ||
+        example === null ||
+        Object.keys(example).length > 0;
+
+      if (shouldIncludeObjectExample) {
+        return [
+          { property: 'default', options: [{ title: 'Example', example }] },
+        ];
+      }
     }
     return [];
   }

package/helpers/schemaTraversal.cjs

@@ -0,0 +1,148 @@
+function visitSchemaNodes(schema, visitor, path = []) {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  visitor(schema, { path });
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.entries(schema.properties).forEach(([key, propertySchema]) => {
+      visitSchemaNodes(propertySchema, visitor, [...path, 'properties', key]);
+    });
+  }
+
+  if (schema.items && typeof schema.items === 'object') {
+    visitSchemaNodes(schema.items, visitor, [...path, 'items']);
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    schema.oneOf.forEach((optionSchema, index) => {
+      visitSchemaNodes(optionSchema, visitor, [...path, 'oneOf', index]);
+    });
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    schema.anyOf.forEach((optionSchema, index) => {
+      visitSchemaNodes(optionSchema, visitor, [...path, 'anyOf', index]);
+    });
+  }
+
+  if (schema.if && typeof schema.if === 'object') {
+    visitSchemaNodes(schema.if, visitor, [...path, 'if']);
+  }
+
+  if (schema.then && typeof schema.then === 'object') {
+    visitSchemaNodes(schema.then, visitor, [...path, 'then']);
+  }
+
+  if (schema.else && typeof schema.else === 'object') {
+    visitSchemaNodes(schema.else, visitor, [...path, 'else']);
+  }
+}
+
+function visitPropertyEntryBranches(
+  schema,
+  visitor,
+  { prefix = '', path = [], skipArraySubProperties = false } = {},
+) {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    schema.oneOf.forEach((optionSchema, index) => {
+      visitSchemaPropertyEntries(optionSchema, visitor, {
+        prefix,
+        path: [...path, 'oneOf', index],
+        skipArraySubProperties,
+      });
+    });
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    schema.anyOf.forEach((optionSchema, index) => {
+      visitSchemaPropertyEntries(optionSchema, visitor, {
+        prefix,
+        path: [...path, 'anyOf', index],
+        skipArraySubProperties,
+      });
+    });
+  }
+
+  if (schema.then && typeof schema.then === 'object') {
+    visitSchemaPropertyEntries(schema.then, visitor, {
+      prefix,
+      path: [...path, 'then'],
+      skipArraySubProperties,
+    });
+  }
+
+  if (schema.else && typeof schema.else === 'object') {
+    visitSchemaPropertyEntries(schema.else, visitor, {
+      prefix,
+      path: [...path, 'else'],
+      skipArraySubProperties,
+    });
+  }
+}
+
+function visitSchemaPropertyEntries(
+  schema,
+  visitor,
+  { prefix = '', path = [], skipArraySubProperties = false } = {},
+) {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.entries(schema.properties).forEach(([key, propertySchema]) => {
+      const currentName = prefix ? `${prefix}.${key}` : key;
+      const currentPath = [...path, 'properties', key];
+
+      visitor(propertySchema, {
+        key,
+        name: currentName,
+        path: currentPath,
+        parentSchema: schema,
+      });
+
+      if (propertySchema?.type === 'object' && propertySchema.properties) {
+        visitSchemaPropertyEntries(propertySchema, visitor, {
+          prefix: currentName,
+          path: currentPath,
+          skipArraySubProperties,
+        });
+      }
+
+      if (
+        propertySchema?.type === 'array' &&
+        propertySchema.items?.properties &&
+        !skipArraySubProperties
+      ) {
+        visitSchemaPropertyEntries(propertySchema.items, visitor, {
+          prefix: `${currentName}.0`,
+          path: [...currentPath, 'items'],
+          skipArraySubProperties,
+        });
+      }
+
+      visitPropertyEntryBranches(propertySchema, visitor, {
+        prefix: currentName,
+        path: currentPath,
+        skipArraySubProperties,
+      });
+    });
+  }
+
+  visitPropertyEntryBranches(schema, visitor, {
+    prefix,
+    path,
+    skipArraySubProperties,
+  });
+}
+
+module.exports = {
+  visitSchemaNodes,
+  visitSchemaPropertyEntries,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",

package/scripts/sync-gtm.js

@@ -3,6 +3,9 @@ const path = require('path');
 const { execSync } = require('child_process');
 const RefParser = require('@apidevtools/json-schema-ref-parser');
 const mergeAllOf = require('json-schema-merge-allof');
+const {
+  visitSchemaPropertyEntries,
+} = require('../helpers/schemaTraversal.cjs');
 
 const logger = {
   _isQuiet: false,
@@ -86,49 +89,58 @@ function findJsonFiles(dir) {
   return results;
 }
 
+function isRootTrackingSchema(schema) {
+  return Boolean(schema?.properties?.event || schema?.['x-tracking-targets']);
+}
+
 function parseSchema(schema, options, prefix = '') {
-  if (!schema || !schema.properties) {
-    return [];
-  }
+  const variables = [];
+
+  visitSchemaPropertyEntries(
+    schema,
+    (property, context) => {
+      variables.push({
+        name: context.name,
+        description: property.description,
+        type: property.type,
+      });
+    },
+    {
+      prefix,
+      skipArraySubProperties: options.skipArraySubProperties,
+    },
+  );
 
-  let variables = [];
-  for (const key in schema.properties) {
-    const property = schema.properties[key];
-    const currentPath = prefix ? `${prefix}.${key}` : key;
-    variables.push({
-      name: currentPath,
-      description: property.description,
-      type: property.type,
-    });
-    if (
-      property.type === 'array' &&
-      property.items &&
-      !options.skipArraySubProperties
-    ) {
-      if (property.items.properties) {
-        variables.push(
-          ...parseSchema(property.items, options, `${currentPath}.0`),
-        );
-      }
-    } else if (property.type === 'object' && property.properties) {
-      variables.push(...parseSchema(property, options, currentPath));
-    }
-  }
   return variables;
 }
 
+function shouldIncludeSchemaForGtm(schema) {
+  if (!isRootTrackingSchema(schema)) {
+    return false;
+  }
+
+  const trackingTargets = schema?.['x-tracking-targets'];
+
+  return (
+    Array.isArray(trackingTargets) &&
+    trackingTargets.includes('web-datalayer-js')
+  );
+}
+
 async function getVariablesFromSchemas(
   schemaPath,
   { skipArraySubProperties = false },
 ) {
   const allVariables = new Map();
   const jsonFiles = findJsonFiles(schemaPath);
-  const eventFiles = jsonFiles.filter((f) => !f.includes('components'));
 
-  for (const file of eventFiles) {
+  for (const file of jsonFiles) {
     try {
       let schema = await RefParser.bundle(file);
       schema = mergeAllOf(schema);
+      if (!shouldIncludeSchemaForGtm(schema)) {
+        continue;
+      }
       const fileVariables = parseSchema(schema, { skipArraySubProperties });
       for (const variable of fileVariables) {
         if (!allVariables.has(variable.name)) {
@@ -388,6 +400,7 @@ module.exports = {
   createGtmVariables,
   deleteGtmVariables,
   parseSchema,
+  shouldIncludeSchemaForGtm,
   findJsonFiles,
   safeJsonParse,
   logger,

package/test-data/payloadContracts.js

@@ -118,6 +118,41 @@ const PAYLOAD_CONTRACTS = [
       },
     },
   },
+  {
+    id: 'login-with-user-properties',
+    class: 'user_properties',
+    example: {
+      event: 'login',
+      method: 'email',
+      user_properties: {
+        sign_up_method: 'email',
+        allow_ad_personalization_signals: 'false',
+      },
+    },
+    expected: {
+      web: {
+        eventName: 'login',
+        payload: {
+          event: 'login',
+          method: 'email',
+          user_properties: {
+            sign_up_method: 'email',
+            allow_ad_personalization_signals: 'false',
+          },
+        },
+      },
+      firebase: {
+        eventName: 'login',
+        parameters: {
+          method: 'email',
+        },
+        userProperties: {
+          sign_up_method: 'email',
+          allow_personalized_ads: 'false',
+        },
+      },
+    },
+  },
   {
     id: 'web-fallback-json-serialization',
     class: 'fallback_json_serialization',

package/validateSchemas.js

@@ -43,7 +43,7 @@ const validateSingleSchema = async (filePath, schemaPath) => {
         fileHasAnyExample = true;
         const { example, title } = option;
 
-        if (!example) {
+        if (typeof example === 'undefined') {
           errors.push(
             `x Schema ${file} (option: ${title}) does not produce a valid example.`,
           );