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

package/__tests__/components/SchemaJsonViewer.test.js

@@ -14,6 +14,29 @@ jest.mock(
   { virtual: true },
 );
 
+jest.mock('@docusaurus/theme-common', () => ({
+  usePrismTheme: () => ({
+    plain: {
+      color: 'rgb(1, 2, 3)',
+      backgroundColor: 'rgb(4, 5, 6)',
+    },
+    styles: [
+      {
+        types: ['property'],
+        style: { color: 'rgb(0, 0, 255)' },
+      },
+      {
+        types: ['string'],
+        style: { color: 'rgb(255, 0, 0)' },
+      },
+      {
+        types: ['number'],
+        style: { color: 'rgb(0, 128, 0)' },
+      },
+    ],
+  }),
+}));
+
 describe('SchemaJsonViewer', () => {
   it('renders the schema in a syntax-highlighted pre block', () => {
     const schema = {
@@ -38,6 +61,22 @@ describe('SchemaJsonViewer', () => {
     );
   });
 
+  it('uses the prism theme for base json token styling', () => {
+    const schema = {
+      type: 'string',
+      examples: ['x'],
+    };
+
+    render(<SchemaJsonViewer schema={schema} />);
+
+    fireEvent.click(screen.getByText('View Raw JSON Schema'));
+
+    expect(screen.getByText('"type"')).toHaveStyle({ color: 'rgb(0, 0, 255)' });
+    expect(screen.getByText('"string"')).toHaveStyle({
+      color: 'rgb(255, 0, 0)',
+    });
+  });
+
   it('navigates local $ref values inside the viewer and resets to root', () => {
     const rootSchema = {
       type: 'object',
@@ -83,6 +122,84 @@ describe('SchemaJsonViewer', () => {
     ).toBeInTheDocument();
   });
 
+  it('highlights schema meta keywords inside the raw json view', () => {
+    const schema = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $id: 'https://example.com/event.json',
+      $anchor: 'eventRoot',
+      $comment: 'Internal authoring note',
+      $vocabulary: {
+        'https://json-schema.org/draft/2020-12/vocab/validation': true,
+      },
+      type: 'object',
+    };
+
+    render(<SchemaJsonViewer schema={schema} sourcePath="event.json" />);
+
+    fireEvent.click(screen.getByText('View Raw JSON Schema'));
+
+    expect(screen.getByText('"$schema"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--meta',
+    );
+    expect(screen.getByText('"$anchor"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--meta',
+    );
+    expect(screen.getByText('"$vocabulary"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--meta',
+    );
+  });
+
+  it('highlights structural schema keywords inside the raw json view', () => {
+    const schema = {
+      type: 'object',
+      allOf: [{ $ref: './component.json' }],
+      properties: {
+        name: { type: 'string' },
+      },
+    };
+
+    render(<SchemaJsonViewer schema={schema} sourcePath="event.json" />);
+
+    fireEvent.click(screen.getByText('View Raw JSON Schema'));
+
+    expect(screen.getByText('"allOf"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--structural',
+    );
+    expect(screen.getByText('"properties"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--structural',
+    );
+    expect(screen.getByText('"$ref"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--structural',
+    );
+  });
+
+  it('does not highlight payload property names inside properties as meta keywords', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        $schema: {
+          type: 'string',
+        },
+      },
+    };
+
+    render(<SchemaJsonViewer schema={schema} sourcePath="event.json" />);
+
+    fireEvent.click(screen.getByText('View Raw JSON Schema'));
+
+    expect(screen.getByText('"properties"')).toHaveClass(
+      'schema-json-viewer__keyword',
+      'schema-json-viewer__keyword--structural',
+    );
+    expect(screen.getByText('"$schema"')).toHaveClass('token property');
+  });
+
   it('renders external $ref values as new-tab links', () => {
     const schema = {
       $ref: 'https://example.com/schema.json',
@@ -98,5 +215,6 @@ describe('SchemaJsonViewer', () => {
     expect(refLink).toHaveAttribute('href', 'https://example.com/schema.json');
     expect(refLink).toHaveAttribute('target', '_blank');
     expect(refLink).toHaveAttribute('rel', 'noreferrer');
+    expect(refLink).toHaveClass('schema-json-viewer__ref-link');
   });
 });

package/__tests__/helpers/example-helper.test.js

@@ -34,6 +34,12 @@ describe('example-helper', () => {
       };
       expect(getExamples(schema)).toEqual(['example1']);
     });
+
+    it('preserves falsy "example" values', () => {
+      expect(getExamples({ example: false })).toEqual([false]);
+      expect(getExamples({ example: 0 })).toEqual([0]);
+      expect(getExamples({ example: '' })).toEqual(['']);
+    });
   });
 
   describe('getSingleExampleValue', () => {
@@ -67,5 +73,11 @@ describe('example-helper', () => {
       };
       expect(getSingleExampleValue(schema)).toBe('default-value');
     });
+
+    it('returns falsy "example" values when present', () => {
+      expect(getSingleExampleValue({ example: false })).toBe(false);
+      expect(getSingleExampleValue({ example: 0 })).toBe(0);
+      expect(getSingleExampleValue({ example: '' })).toBe('');
+    });
   });
 });

package/__tests__/helpers/getConstraints.test.js

@@ -59,6 +59,7 @@ describe('getConstraints', () => {
       contains: { type: 'string' },
       enum: ['a', 'b', 'c'],
       const: 'hello',
+      not: { const: 'US' },
     };
     const expected = [
       'pattern: /^[a-z]+$/',
@@ -69,6 +70,7 @@ describe('getConstraints', () => {
       'contains: {"type":"string"}',
       'enum: [a, b, c]',
       'const: "hello"',
+      'not: { const: "US" }',
     ];
     expect(getConstraints(prop, false)).toEqual(
       expect.arrayContaining(expected),
@@ -100,4 +102,18 @@ describe('getConstraints', () => {
       expect.arrayContaining(['required', ...expected]),
     );
   });
+
+  it('should render "not" constraint in JSON schema syntax for const', () => {
+    const prop = {
+      not: { const: 'US' },
+    };
+    expect(getConstraints(prop, false)).toEqual(['not: { const: "US" }']);
+  });
+
+  it('should render "not" constraint in JSON schema syntax for type', () => {
+    const prop = {
+      not: { type: 'string' },
+    };
+    expect(getConstraints(prop, false)).toEqual(['not: { type: "string" }']);
+  });
 });

package/__tests__/helpers/processSchema.test.js

@@ -82,4 +82,22 @@ describe('processSchema', () => {
       }),
     );
   });
+
+  it('keeps simple not const constraints readable after allOf merge', async () => {
+    const filePath = path.join(
+      __dirname,
+      '..',
+      '__fixtures__',
+      'validateSchemas',
+      'main-schema-with-not-allof.json',
+    );
+    const mergedSchema = await processSchema(filePath);
+
+    expect(mergedSchema.properties.country).toEqual(
+      expect.objectContaining({
+        type: 'string',
+        not: { const: 'US' },
+      }),
+    );
+  });
 });

package/__tests__/helpers/schemaTraversal.test.js

@@ -0,0 +1,110 @@
+const {
+  visitSchemaNodes,
+  visitSchemaPropertyEntries,
+} = require('../../helpers/schemaTraversal.cjs');
+
+describe('schemaTraversal', () => {
+  it('visits nested choice and conditional schema nodes', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        payment_method: {
+          oneOf: [
+            {
+              properties: {
+                card_number: { type: 'string' },
+              },
+            },
+          ],
+        },
+      },
+      if: {
+        properties: {
+          platform: { const: 'ios' },
+        },
+      },
+      then: {
+        properties: {
+          att_status: { type: 'string' },
+        },
+      },
+    };
+
+    const visitedPaths = [];
+    visitSchemaNodes(schema, (_node, context) => {
+      visitedPaths.push(context.path.join('.'));
+    });
+
+    expect(visitedPaths).toEqual(
+      expect.arrayContaining([
+        '',
+        'properties.payment_method',
+        'properties.payment_method.oneOf.0',
+        'properties.payment_method.oneOf.0.properties.card_number',
+        'if',
+        'then',
+        'then.properties.att_status',
+      ]),
+    );
+  });
+
+  it('collects property entries through object, array, choice, and conditional branches', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string' },
+        items: {
+          type: 'array',
+          items: {
+            properties: {
+              sku: { type: 'string' },
+            },
+          },
+        },
+        contact_method: {
+          type: 'object',
+          oneOf: [
+            {
+              properties: {
+                email: { type: 'string' },
+              },
+            },
+            {
+              properties: {
+                phone_number: { type: 'string' },
+              },
+            },
+          ],
+        },
+      },
+      then: {
+        properties: {
+          att_status: { type: 'string' },
+        },
+      },
+      else: {
+        properties: {
+          ad_personalization_enabled: { type: 'boolean' },
+        },
+      },
+    };
+
+    const variableNames = [];
+    visitSchemaPropertyEntries(schema, (_property, context) => {
+      variableNames.push(context.name);
+    });
+
+    expect(variableNames).toEqual(
+      expect.arrayContaining([
+        'event',
+        'items',
+        'items.0.sku',
+        'contact_method',
+        'contact_method.email',
+        'contact_method.phone_number',
+        'att_status',
+        'ad_personalization_enabled',
+      ]),
+    );
+  });
+});

package/__tests__/syncGtm.test.js

@@ -79,7 +79,7 @@ describe('getVariablesFromSchemas', () => {
 
   const SCHEMA_PATH = '/fake/schemas';
   const mockFiles = {
-    [SCHEMA_PATH]: ['complex-event.json', 'components'],
+    [SCHEMA_PATH]: ['complex-event.json', 'mobile-event.json', 'components'],
     [path.join(SCHEMA_PATH, 'components')]: ['address.json'],
   };
   const addressSchema = {
@@ -92,6 +92,7 @@ describe('getVariablesFromSchemas', () => {
   };
   const complexEventSchema = {
     title: 'Complex Event',
+    'x-tracking-targets': ['web-datalayer-js'],
     type: 'object',
     properties: {
       $schema: { type: 'string', description: 'Should now be included.' },
@@ -107,12 +108,79 @@ describe('getVariablesFromSchemas', () => {
           },
         },
       },
+      contact_method: {
+        type: 'object',
+        oneOf: [
+          {
+            title: 'Email Contact',
+            properties: {
+              email: {
+                type: 'string',
+                description: 'Email address.',
+              },
+            },
+          },
+          {
+            title: 'Phone Contact',
+            properties: {
+              phone_number: {
+                type: 'string',
+                description: 'Phone number.',
+              },
+            },
+          },
+        ],
+      },
+      platform: {
+        type: 'string',
+        description: 'Target platform.',
+      },
       timestamp: { type: 'number', description: 'Event timestamp.' },
     },
+    if: {
+      properties: {
+        platform: { const: 'ios' },
+      },
+    },
+    then: {
+      properties: {
+        att_status: {
+          type: 'string',
+          description: 'App Tracking Transparency status.',
+        },
+      },
+    },
+    else: {
+      properties: {
+        ad_personalization_enabled: {
+          type: 'boolean',
+          description: 'Whether ad personalization is enabled.',
+        },
+      },
+    },
+  };
+  const mobileEventSchema = {
+    title: 'Mobile Event',
+    'x-tracking-targets': ['android-firebase-kotlin-sdk'],
+    type: 'object',
+    properties: {
+      event: { type: 'string', const: 'screen_view' },
+      screen_name: { type: 'string', description: 'Screen name.' },
+    },
+  };
+  const untaggedEventSchema = {
+    title: 'Untagged Event',
+    type: 'object',
+    properties: {
+      event: { type: 'string', const: 'legacy_event' },
+      legacy_field: { type: 'string', description: 'Legacy field.' },
+    },
   };
   const mockFileContents = {
     [path.join(SCHEMA_PATH, 'complex-event.json')]:
       JSON.stringify(complexEventSchema),
+    [path.join(SCHEMA_PATH, 'mobile-event.json')]:
+      JSON.stringify(mobileEventSchema),
     [path.join(SCHEMA_PATH, 'components', 'address.json')]:
       JSON.stringify(addressSchema),
   };
@@ -148,7 +216,7 @@ describe('getVariablesFromSchemas', () => {
       expect.objectContaining({ name: 'timestamp' }),
     ]);
 
-    expect(result.length).toBe(8);
+    expect(result.length).toBe(14);
     expect(result).toEqual(expected);
   });
 
@@ -172,7 +240,163 @@ describe('getVariablesFromSchemas', () => {
     ];
 
     expect(result.map((r) => r.name)).toEqual(expect.arrayContaining(expected));
-    expect(result.length).toBe(expected.length);
+    expect(result.length).toBe(12);
+  });
+
+  it('should include variables from oneOf choices and conditional branches', async () => {
+    const bundledSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+    RefParser.bundle.mockResolvedValue(bundledSchema);
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {});
+    const variableNames = result.map((variable) => variable.name);
+
+    expect(variableNames).toEqual(
+      expect.arrayContaining([
+        'contact_method.email',
+        'contact_method.phone_number',
+        'att_status',
+        'ad_personalization_enabled',
+      ]),
+    );
+  });
+
+  it('should only include schemas explicitly targeted to web-datalayer-js', async () => {
+    const untaggedEventPath = path.join(SCHEMA_PATH, 'legacy-event.json');
+    mockFiles[SCHEMA_PATH].push('legacy-event.json');
+    mockFileContents[untaggedEventPath] = JSON.stringify(untaggedEventSchema);
+
+    const bundledWebSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledWebSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+
+    RefParser.bundle.mockImplementation(async (filePath) => {
+      if (filePath.endsWith('complex-event.json')) {
+        return bundledWebSchema;
+      }
+      if (filePath.endsWith('mobile-event.json')) {
+        return mobileEventSchema;
+      }
+      if (filePath.endsWith('legacy-event.json')) {
+        return untaggedEventSchema;
+      }
+      if (filePath.endsWith('address.json')) {
+        return addressSchema;
+      }
+      throw new Error(`Unexpected schema file: ${filePath}`);
+    });
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {});
+
+    expect(result.map((variable) => variable.name)).toEqual(
+      expect.arrayContaining([
+        '$schema',
+        'event',
+        'user_data',
+        'user_data.user_id',
+        'user_data.addresses',
+        'user_data.addresses.0.street',
+        'user_data.addresses.0.city',
+        'timestamp',
+      ]),
+    );
+    expect(result.map((variable) => variable.name)).not.toContain(
+      'screen_name',
+    );
+    expect(result.map((variable) => variable.name)).not.toContain(
+      'legacy_field',
+    );
+  });
+
+  it('should include root tracking schemas based on content instead of path names', async () => {
+    const nestedSchemaDir = path.join(SCHEMA_PATH, 'event-components-demo');
+    const nestedSchemaPath = path.join(nestedSchemaDir, 'checkout-event.json');
+    const nestedSchema = {
+      title: 'Checkout Event',
+      'x-tracking-targets': ['web-datalayer-js'],
+      type: 'object',
+      properties: {
+        event: { type: 'string', const: 'checkout' },
+        order_id: { type: 'string', description: 'Order identifier.' },
+      },
+    };
+
+    mockFiles[SCHEMA_PATH].push('event-components-demo');
+    mockFiles[nestedSchemaDir] = ['checkout-event.json'];
+    mockFileContents[nestedSchemaPath] = JSON.stringify(nestedSchema);
+
+    const bundledWebSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledWebSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+
+    RefParser.bundle.mockImplementation(async (filePath) => {
+      if (filePath.endsWith('complex-event.json')) {
+        return bundledWebSchema;
+      }
+      if (filePath.endsWith('mobile-event.json')) {
+        return mobileEventSchema;
+      }
+      if (filePath.endsWith('address.json')) {
+        return addressSchema;
+      }
+      if (filePath.endsWith('legacy-event.json')) {
+        return untaggedEventSchema;
+      }
+      if (filePath.endsWith('checkout-event.json')) {
+        return nestedSchema;
+      }
+      throw new Error(`Unexpected schema file: ${filePath}`);
+    });
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {});
+    const variableNames = result.map((variable) => variable.name);
+
+    expect(variableNames).toContain('order_id');
+    expect(RefParser.bundle).toHaveBeenCalledWith(nestedSchemaPath);
+  });
+
+  it('should ignore component schemas even when scanning all json files', async () => {
+    const bundledWebSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledWebSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+    const nestedSchema = {
+      title: 'Checkout Event',
+      'x-tracking-targets': ['web-datalayer-js'],
+      type: 'object',
+      properties: {
+        event: { type: 'string', const: 'checkout' },
+        order_id: { type: 'string', description: 'Order identifier.' },
+      },
+    };
+
+    RefParser.bundle.mockImplementation(async (filePath) => {
+      if (filePath.endsWith('complex-event.json')) {
+        return bundledWebSchema;
+      }
+      if (filePath.endsWith('mobile-event.json')) {
+        return mobileEventSchema;
+      }
+      if (filePath.endsWith('address.json')) {
+        return addressSchema;
+      }
+      if (filePath.endsWith('legacy-event.json')) {
+        return untaggedEventSchema;
+      }
+      if (filePath.endsWith('checkout-event.json')) {
+        return nestedSchema;
+      }
+      throw new Error(`Unexpected schema file: ${filePath}`);
+    });
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {});
+    const variableNames = result.map((variable) => variable.name);
+
+    expect(RefParser.bundle).toHaveBeenCalledWith(
+      path.join(SCHEMA_PATH, 'components', 'address.json'),
+    );
+    expect(variableNames).not.toContain('street');
+    expect(variableNames).not.toContain('city');
   });
 });
 

package/__tests__/validateSchemas.test.js

@@ -102,4 +102,54 @@ describe('validateSchemas', () => {
     expect(consoleErrorSpy).toHaveBeenCalled();
     expect(consoleErrorSpy.mock.calls[0][0]).toContain('x-tracking-targets');
   });
+
+  it('should treat falsy scalar examples as valid examples', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(schemaDir, 'event.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+          event: {
+            type: 'string',
+            const: 'test_event',
+          },
+          is_enabled: {
+            type: 'boolean',
+            example: false,
+          },
+          retry_count: {
+            type: 'integer',
+            example: 0,
+          },
+          note: {
+            type: 'string',
+            example: '',
+          },
+        },
+        required: ['event', 'is_enabled', 'retry_count', 'note'],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(true);
+  });
+
+  it('should allow a top-level falsy example value', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(schemaDir, 'flag.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'boolean',
+        example: false,
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(true);
+  });
 });

package/components/PropertiesTable.js

@@ -5,9 +5,39 @@ import WordWrapButton from './WordWrapButton';
 import { schemaToTableData } from '../helpers/schemaToTableData';
 import styles from './PropertiesTable.module.css';
 
-export default function PropertiesTable({ schema }) {
+function filterInheritedTopLevelProperties(schema, sourceSchema) {
+  if (!schema?.properties || !sourceSchema?.properties) {
+    return schema;
+  }
+
+  const sourceKeys = new Set(Object.keys(sourceSchema.properties));
+  const filteredEntries = Object.entries(schema.properties).filter(
+    ([key, propSchema]) => {
+      if (sourceKeys.has(key)) {
+        return true;
+      }
+
+      const hasDescription =
+        typeof propSchema?.description === 'string' &&
+        propSchema.description.trim().length > 0;
+      const hasExamples =
+        Array.isArray(propSchema?.examples) && propSchema.examples.length > 0;
+      const hasExample = propSchema?.example !== undefined;
+
+      return hasDescription || hasExamples || hasExample;
+    },
+  );
+
+  return {
+    ...schema,
+    properties: Object.fromEntries(filteredEntries),
+  };
+}
+
+export default function PropertiesTable({ schema, sourceSchema }) {
   const [isWordWrapOn, setIsWordWrapOn] = useState(true);
-  const tableData = schemaToTableData(schema);
+  const tableSchema = filterInheritedTopLevelProperties(schema, sourceSchema);
+  const tableData = schemaToTableData(tableSchema);
   const stripeState = { current: 0 };
 
   return (