Improve array schema references to properly link to referenced schemas

Co-authored-by: hawkeyexl <[email protected]>

Author: Copilot

.scripts/buildSchemaReferencesV3.js

@@ -481,18 +481,35 @@ function generatePropertyRow(name, property, options = {}) {
       if (property.items && property.items.type) {
         typeDetails.type = `${typeDetails.type} of ${property.items.type}`;
       }
+      // Check if items have a title (schema reference)
+      else if (property.items && property.items.title) {
+        typeDetails.type = `${typeDetails.type} of object([${property.items.title}](/docs/references/schemas/${property.items.title}))`;
+      }
       // Check if items have multiple possible types
       else if (property.items && (property.items.anyOf || property.items.oneOf)) {
         const itemVariants = property.items.anyOf || property.items.oneOf;
-        if (itemVariants.length === 1 && itemVariants[0].type) {
-          typeDetails.type = `${typeDetails.type} of ${itemVariants[0].type}`;
-        } else {
-          const types = itemVariants
-            .filter(v => v.type)
-            .map(v => v.type)
-            .join(', ');
-          if (types) {
-            typeDetails.type = `${typeDetails.type} of ${types}`;
+        // Handle single variant with title or type
+        if (itemVariants.length === 1) {
+          if (itemVariants[0].title) {
+            typeDetails.type = `${typeDetails.type} of object([${itemVariants[0].title}](/docs/references/schemas/${itemVariants[0].title}))`;
+          } else if (itemVariants[0].type) {
+            typeDetails.type = `${typeDetails.type} of ${itemVariants[0].type}`;
+          }
+        } 
+        // Handle multiple variants
+        else {
+          const typesList = itemVariants.map(v => {
+            if (v.title) {
+              return `object([${v.title}](/docs/references/schemas/${v.title}))`;
+            } else if (v.type) {
+              return v.type;
+            } else {
+              return "unknown";
+            }
+          });
+          
+          if (typesList.length > 0) {
+            typeDetails.type = `${typeDetails.type} of one of: ${typesList.join(', ')}`;
           }
         }
       }
@@ -608,7 +625,15 @@ function getItems(property, typeFilter) {
 
   // Apply type filter if specified
   if (typeFilter && items.length > 0) {
-    items = items.filter((item) => item.type === typeFilter);
+    items = items.filter((item) => {
+      // If item has explicit type that matches
+      if (item.type === typeFilter) return true;
+      
+      // For object filter, also include items with title (schema references)
+      if (typeFilter === 'object' && item.title) return true;
+      
+      return false;
+    });
   }
 
   return items;
@@ -718,6 +743,9 @@ function getArraySubTypes(property, depth) {
           .map(variant => {
             if (variant.type === "object" && variant.title) {
               return `${variant.type}([${variant.title}](/docs/references/schemas/${variant.title}))`;
+            } else if (variant.title) {
+              // Handle case where title exists but type might be undefined
+              return `object([${variant.title}](/docs/references/schemas/${variant.title}))`;
             } else if (variant.type) {
               return variant.type;
             } else {
@@ -731,6 +759,10 @@ function getArraySubTypes(property, depth) {
       else if (item.type) {
         subTypes = `${subTypes}<br/>${spaces}- ${item.type}`;
       }
+      // Check for title on the item directly (handles schema references in array items)
+      else if (item.title) {
+        subTypes = `${subTypes}<br/>${spaces}-&nbsp;object([${item.title}](/docs/references/schemas/${item.title}))`;
+      }
       // Handle unknown types
       else {
         subTypes = `${subTypes}<br/>${spaces}- unknown`;
@@ -751,6 +783,9 @@ function getArraySubTypes(property, depth) {
       const variantTypes = variants.map(variant => {
         if (variant.type === "object" && variant.title) {
           return `${variant.type}([${variant.title}](/docs/references/schemas/${variant.title}))`;
+        } else if (variant.title) {
+          // Handle case where title exists but type might be undefined
+          return `object([${variant.title}](/docs/references/schemas/${variant.title}))`;
         } else if (variant.type) {
           return variant.type;
         } else {
@@ -759,6 +794,10 @@ function getArraySubTypes(property, depth) {
       }).join(", ");
       subTypes += variantTypes;
     }
+    // Check for title on the item directly (handles schema references in array items)
+    else if (item.title) {
+      subTypes = `${subTypes}object([${item.title}](/docs/references/schemas/${item.title}))`;
+    }
     // Handle regular types
     else if (item.type) {
       subTypes += item.type;

docs/references/schemas/config.md

@@ -22,8 +22,8 @@ afterAll | string | Optional. Path(s) to test specifications to perform after th
 afterAll | array of string | Optional. Path(s) to test specifications to perform after those specified by `input`. Useful for cleaning up testing environments. | 
 detectSteps | boolean | Optional. Whether or not to detect steps in input files based on defined markup. | `true`
 logLevel | string | Optional. Amount of detail to output when performing an operation.<br/><br/>Accepted values: `silent`, `error`, `warning`, `info`, `debug` | `info`
-runOn | array of object | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
-fileTypes | array of string, object, object | Optional. Configuration for file types and their markup detection. | 
+runOn | array of object([context](/docs/references/schemas/context)) | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
+fileTypes | array of one of: object([Predefined](/docs/references/schemas/Predefined)), object([Custom](/docs/references/schemas/Custom)), object([Executable](/docs/references/schemas/Executable)) | Optional. Configuration for file types and their markup detection. | 
 integrations | object | Optional. Options for connecting to external services. | 
 integrations.openApi | array of unknown | Optional. No description provided. | 
 telemetry | object | Optional. Options around sending telemetry for Doc Detective usage. | ``{"send":true}``

docs/references/schemas/context.md

@@ -20,7 +20,7 @@ browsers.window.height | integer | Optional. Height of the browser window in pix
 browsers.viewport | object | Optional. Viewport dimensions. | 
 browsers.viewport.width | integer | Optional. Width of the viewport in pixels. | 
 browsers.viewport.height | integer | Optional. Height of the viewport in pixels. | 
-browsers | array of string, object | Optional. Browsers to run tests on. | 
+browsers | array of one of: string, object | Optional. Browsers to run tests on. | 
 browsers[].name | string | Required. Name of the browser.<br/><br/>Accepted values: `chrome`, `firefox`, `safari`, `webkit` | 
 browsers[].headless | boolean | Optional. If `true`, runs the browser in headless mode. | `true`
 browsers[].window | object | Optional. Browser dimensions. | 

docs/references/schemas/specification.md

@@ -11,9 +11,9 @@ specId | string | Optional. Unique identifier for the test specification. |
 description | string | Optional. Description of the test specification. | 
 specPath | string | Optional. Path to the test specification. | 
 contentPath | string | Optional. Path to the content that the specification is associated with. | 
-runOn | array of object | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
+runOn | array of object([context](/docs/references/schemas/context)) | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
 openApi | array of unknown | Optional. No description provided. | 
-tests | array of object | Required. [Tests](test) to perform. | 
+tests | array of object([test](/docs/references/schemas/test)) | Required. [Tests](test) to perform. | 
 
 ## Examples
 

docs/references/schemas/test.md

@@ -15,7 +15,7 @@ testId | string | Optional. Unique identifier for the test. |
 description | string | Optional. Description of the test. | 
 contentPath | string | Optional. Path to the content that the test is associated with. | 
 detectSteps | boolean | Optional. Whether or not to detect steps in input files based on markup regex. | `true`
-runOn | array of object | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
+runOn | array of object([context](/docs/references/schemas/context)) | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
 openApi | array of unknown | Optional. No description provided. | 
 before | string | Optional. Path to a test specification to perform before this test, while maintaining this test's context. Useful for setting up testing environments. Only the `steps` property is used from the first test in the setup spec. | 
 after | string | Optional. Path to a test specification to perform after this test, while maintaining this test's context. Useful for cleaning up testing environments. Only the `steps` property is used from the first test in the cleanup spec. |