@defra/forms-model 3.0.430 → 3.0.431

package/scripts/schema-modules/schema-simplifiers.js

@@ -0,0 +1,351 @@
+import {
+  CONDITION_TYPES,
+  DESCRIPTIONS,
+  PATH_SEGMENTS,
+  VALUE_TYPES
+} from './constants.js'
+import { fixConditionTitles } from './schema-processors.js'
+
+/**
+ * Handles reference-specific titles
+ * @param {SchemaObject} result - Schema to process
+ */
+export function handleReferenceSpecificTitles(result) {
+  if (result.$ref?.includes('conditionGroupSchema')) {
+    result.title = CONDITION_TYPES.NESTED_GROUP
+    result.description = DESCRIPTIONS.NESTED_CONDITION_GROUP
+  }
+}
+
+/**
+ * Simplifies anyOf validations that just enumerate types
+ * @param {SchemaObject} result - Schema to process
+ */
+export function simplifyTypeEnumerations(result) {
+  if (!result.anyOf || !Array.isArray(result.anyOf)) {
+    return
+  }
+
+  /** @type {Array<string>} */
+  const types = result.anyOf
+    .map(
+      /**
+       * @param {SchemaObject} item
+       * @returns {string|undefined}
+       */
+      (item) => {
+        return item.type
+      }
+    )
+    .filter(/** @returns {val is string} */ (val) => Boolean(val))
+
+  const MIN_TYPES_FOR_ENUMERATION = 3
+
+  const isTypeEnumeration =
+    types.length >= MIN_TYPES_FOR_ENUMERATION &&
+    types.some((t) =>
+      ['string', 'number', 'boolean', 'array', 'object'].includes(t)
+    )
+
+  if (isTypeEnumeration) {
+    delete result.anyOf
+    if (
+      !result.description ||
+      result.description.indexOf('value type') === -1
+    ) {
+      result.description = `${String(result.description || '')}${result.description ? '\n\n' : ''}Value can be of various types (${types.join(', ')}).`
+    }
+  }
+}
+
+/**
+ * Improves titles for condition items
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function improveConditionItemTitles(result, parentPath) {
+  if (!parentPath.includes(`/${PATH_SEGMENTS.CONDITIONS}`) || !result.anyOf) {
+    return
+  }
+
+  result.anyOf.forEach(
+    /** @param {SchemaObject} item */ (item) => {
+      if (item.title?.includes('Item (object)') && item.properties) {
+        if (item.properties.field) {
+          item.title = CONDITION_TYPES.DEFINITION
+        } else if (item.properties.conditionName) {
+          item.title = CONDITION_TYPES.REFERENCE
+        } else if (item.properties.conditions) {
+          item.title = CONDITION_TYPES.NESTED_GROUP
+        } else {
+          item.title = `Unknown Condition Item Type`
+        }
+      }
+    }
+  )
+}
+
+/**
+ * Improves titles for value objects in conditions
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function improveValueObjectTitles(result, parentPath) {
+  if (!parentPath.includes('/value') || !result.anyOf) {
+    return
+  }
+
+  result.anyOf.forEach(
+    /** @param {SchemaObject} item */ (item) => {
+      if (!item.properties) {
+        return
+      }
+
+      if (
+        item.properties.period &&
+        item.properties.unit &&
+        item.properties.direction
+      ) {
+        item.title = VALUE_TYPES.RELATIVE_DATE
+      } else if (
+        item.properties.value &&
+        item.properties.type &&
+        item.properties.display
+      ) {
+        item.title = VALUE_TYPES.STATIC
+      } else {
+        item.title = 'Unknown Value Type'
+      }
+    }
+  )
+}
+
+/**
+ * Improves descriptions for condition operators
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function improveOperatorDescriptions(result, parentPath) {
+  if (
+    parentPath.endsWith('/operator') &&
+    parentPath.includes(`/${PATH_SEGMENTS.CONDITIONS}`)
+  ) {
+    result.description =
+      'Comparison operator: equals, notEquals, contains, notContains, greaterThan, lessThan, isEmpty, isNotEmpty'
+  }
+}
+
+/**
+ * Adds examples to recursive condition groups
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function addExamplesToConditionGroups(result, parentPath) {
+  if (
+    result.title !== 'Condition Group Schema' &&
+    !parentPath.includes('conditionGroupSchema')
+  ) {
+    return
+  }
+
+  if (result.description) {
+    result.description = `${result.description} Note: This structure can be nested multiple levels deep for complex condition logic.`
+  }
+
+  result.examples = [
+    {
+      conditions: [
+        {
+          field: {
+            name: 'farmType',
+            type: 'string',
+            display: 'Type of farm'
+          },
+          operator: 'equals',
+          value: {
+            type: 'string',
+            value: 'livestock',
+            display: 'Livestock farm'
+          },
+          coordinator: 'AND'
+        },
+        {
+          conditionName: 'hasEnvironmentalPermit',
+          conditionDisplayName: 'Has an environmental permit',
+          coordinator: 'OR'
+        }
+      ]
+    }
+  ]
+}
+
+/**
+ * Handles repeat property special case
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ * @returns {SchemaObject|null} Processed schema or null if no special handling needed
+ */
+export function handleRepeatProperty(result, parentPath) {
+  if (
+    !parentPath.endsWith('/repeat') ||
+    !result.oneOf ||
+    result.oneOf.length <= 1
+  ) {
+    return null
+  }
+
+  const mainOption = result.oneOf[0]
+
+  mainOption.description = `${mainOption.description || ''}\n\nNOTE: This configuration is only used when the 'controller' property is set to 'RepeatPageController'. Otherwise, this property should not be specified.`
+
+  delete result.oneOf
+  delete result.anyOf
+
+  Object.assign(result, mainOption)
+  return result
+}
+
+/**
+ * Handles name/title fields
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function handleNameTitleFields(result, parentPath) {
+  if (
+    (parentPath.endsWith('/name') || parentPath.endsWith('/title')) &&
+    result.oneOf &&
+    result.oneOf.length > 1 &&
+    result.anyOf
+  ) {
+    delete result.anyOf
+  }
+}
+
+/**
+ * Improves titles for list items
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function improveListItemTitles(result, parentPath) {
+  if (
+    !parentPath.endsWith(`/${PATH_SEGMENTS.ITEMS}`) ||
+    !result.oneOf ||
+    result.oneOf.length <= 1
+  ) {
+    return
+  }
+
+  result.oneOf.forEach(
+    /** @param {SchemaObject} option */ (option) => {
+      if (option.description?.includes('string values')) {
+        option.title = 'String List Items'
+      } else if (option.description?.includes('numeric values')) {
+        option.title = 'Number List Items'
+      } else {
+        option.title = 'Generic List Items'
+      }
+    }
+  )
+
+  if (result.anyOf) {
+    delete result.anyOf
+  }
+}
+
+/**
+ * Simplifies documentation for condition items in arrays
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function simplifyConditionArrays(result, parentPath) {
+  if (
+    !parentPath.includes(
+      `${PATH_SEGMENTS.CONDITIONS}/${PATH_SEGMENTS.ITEMS}`
+    ) &&
+    !parentPath.endsWith(`/${PATH_SEGMENTS.CONDITIONS}`)
+  ) {
+    return
+  }
+
+  if (result.items?.anyOf) {
+    result.description = `${result.description || ''}\n\nElements can be direct conditions, references to named conditions, or nested condition groups. This structure allows building complex logical expressions with AND/OR operators.`
+  }
+}
+
+/**
+ * Recursively processes properties of a schema
+ * @param {SchemaObject} result - Schema to process
+ * @param {string} parentPath - Path to current schema
+ */
+export function processNestedSchemas(result, parentPath) {
+  if (result.properties) {
+    Object.entries(result.properties).forEach(([propName, propSchema]) => {
+      result.properties[propName] = simplifyForDocs(
+        propSchema,
+        `${parentPath}/${PATH_SEGMENTS.PROPERTIES}/${propName}`
+      )
+    })
+  }
+
+  if (result.items) {
+    if (Array.isArray(result.items)) {
+      result.items = result.items.map((item, idx) =>
+        simplifyForDocs(item, `${parentPath}/${PATH_SEGMENTS.ITEMS}/${idx}`)
+      )
+    } else {
+      result.items = simplifyForDocs(
+        result.items,
+        `${parentPath}/${PATH_SEGMENTS.ITEMS}`
+      )
+    }
+  }
+
+  ;['oneOf', 'anyOf', 'allOf'].forEach((keyword) => {
+    if (result[keyword] && Array.isArray(result[keyword])) {
+      result[keyword] = result[keyword].map((subSchema, idx) =>
+        simplifyForDocs(subSchema, `${parentPath}/${keyword}/${idx}`)
+      )
+    }
+  })
+}
+
+/**
+ * Simplifies a schema for documentation purposes by removing unnecessary internal validation structures
+ * @param {SchemaObject} schema - The schema to simplify
+ * @param {string} parentPath - Path to the current schema location
+ * @returns {SchemaObject} Simplified schema
+ */
+export function simplifyForDocs(schema, parentPath = '') {
+  if (typeof schema !== 'object') {
+    return schema
+  }
+
+  /** @type {SchemaObject} */
+  const result = JSON.parse(JSON.stringify(schema))
+
+  handleReferenceSpecificTitles(result)
+  simplifyTypeEnumerations(result)
+  improveConditionItemTitles(result, parentPath)
+  improveValueObjectTitles(result, parentPath)
+  improveOperatorDescriptions(result, parentPath)
+  addExamplesToConditionGroups(result, parentPath)
+
+  const specialResult = handleRepeatProperty(result, parentPath)
+  if (specialResult) {
+    return specialResult
+  }
+
+  handleNameTitleFields(result, parentPath)
+  improveListItemTitles(result, parentPath)
+  simplifyConditionArrays(result, parentPath)
+
+  fixConditionTitles(result)
+
+  processNestedSchemas(result, parentPath)
+
+  return result
+}
+
+/**
+ * @import { SchemaObject } from './types.js'
+ */

package/scripts/schema-modules/title-processors.js

@@ -0,0 +1,327 @@
+import { formatPropertyName } from './utils.js'
+
+/**
+ * Sets a title on schema object if missing
+ * @param {SchemaObject} schema - Schema object to update
+ * @param {string} parentName - Parent object name for context
+ */
+export function setSchemaTitle(schema, parentName) {
+  if (schema.title) {
+    return
+  } else if (schema.description && typeof schema.description === 'string') {
+    schema.title = schema.description.split('.')[0].trim()
+  } else if (parentName) {
+    schema.title = formatPropertyName(parentName)
+  } else if (schema.type) {
+    schema.title = formatPropertyName(String(schema.type))
+  } else {
+    schema.title = 'Unknown Schema'
+  }
+}
+
+/**
+ * Sets titles for repeat-related schemas
+ * @param {SchemaObject} subSchema - Schema to update
+ * @param {number} index - Index in array
+ */
+export function setRepeatTitles(subSchema, index) {
+  if (index === 0) {
+    subSchema.title = 'Repeat Configuration'
+    subSchema.description =
+      'Configuration for repeatable pages, used with RepeatPageController. ' +
+      'Defines how repeatable sections behave including min/max repetitions and display options.'
+  } else {
+    subSchema.title = 'Alternative Validation'
+    subSchema.description =
+      'Alternative validation schema used internally. Not typically configured directly.'
+  }
+}
+
+/**
+ * Sets titles for component name schemas
+ * @param {SchemaObject} subSchema - Schema to update
+ * @param {number} index - Index in array
+ */
+export function setNameTitles(subSchema, index) {
+  if (index === 0) {
+    subSchema.title = 'Display Component Name'
+    subSchema.description =
+      'Name format for display-only components like HTML, Markdown, etc.'
+  } else {
+    subSchema.title = 'Input Component Name'
+    subSchema.description =
+      'Name format for input components that collect user data.'
+  }
+}
+
+/**
+ * Sets titles for title-related schemas
+ * @param {SchemaObject} subSchema - Schema to update
+ * @param {number} index - Index in array
+ */
+export function setTitleTitles(subSchema, index) {
+  if (index === 0) {
+    subSchema.title = 'Display Component Title'
+    subSchema.description = 'Title format for display-only components.'
+  } else {
+    subSchema.title = 'Input Component Title'
+    subSchema.description = 'Title displayed above input components.'
+  }
+}
+
+/**
+ * Sets titles for pages schemas
+ * @param {SchemaObject} subSchema - Schema to update
+ * @param {number} index - Index in array
+ */
+export function setPagesTitles(subSchema, index) {
+  if (index === 0) {
+    subSchema.title = 'V2 Pages'
+    subSchema.description =
+      'Pages definition for forms using engine version V2.'
+  } else {
+    subSchema.title = 'V1 Pages'
+    subSchema.description =
+      'Pages definition for forms using engine version V1.'
+  }
+}
+
+/**
+ * Sets specific titles based on parent name and keyword
+ * @param {SchemaObject} subSchema - The schema to process
+ * @param {string} parentName - Parent name
+ * @param {string} keyword - oneOf, anyOf, or allOf
+ * @param {number} index - Index in the array
+ * @returns {boolean} Whether a specific title was set
+ */
+export function setSpecificTitle(subSchema, parentName, keyword, index) {
+  if (parentName === 'repeat' && keyword === 'oneOf') {
+    setRepeatTitles(subSchema, index)
+    return true
+  }
+
+  if (parentName === 'name' && keyword === 'oneOf') {
+    setNameTitles(subSchema, index)
+    return true
+  }
+
+  if (parentName === 'title' && keyword === 'oneOf') {
+    setTitleTitles(subSchema, index)
+    return true
+  }
+
+  if (parentName === 'pages' && keyword === 'oneOf') {
+    setPagesTitles(subSchema, index)
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Sets title for alternative validation schemas
+ * @param {SchemaObject} subSchema - The schema to process
+ * @param {string} parentName - Parent name
+ * @param {string} keyword - oneOf, anyOf, or allOf
+ */
+export function setAlternativeValidationTitle(subSchema, parentName, keyword) {
+  if (
+    keyword === 'anyOf' &&
+    parentName.includes('Alternative Validation') &&
+    subSchema.type
+  ) {
+    subSchema.title = `${subSchema.type} Type`
+    subSchema.description = `**INTERNAL VALIDATION ONLY** - This is an internal schema structure used for validation purposes.
+                            When using the ${parentName} property, you should only configure the Repeat Configuration structure
+                            when controller is set to "RepeatPageController".`
+  }
+}
+
+/**
+ * Handles specialized title setting for oneOf/anyOf cases
+ * @param {SchemaObject} subSchema - The schema to process
+ * @param {string} parentName - Parent name
+ * @param {string} keyword - oneOf, anyOf, or allOf
+ * @param {number} index - Index in the array
+ */
+export function handleSpecialTitles(subSchema, parentName, keyword, index) {
+  if (subSchema.title) {
+    return
+  }
+
+  if (!setSpecificTitle(subSchema, parentName, keyword, index)) {
+    if (subSchema.type) {
+      subSchema.title = `${formatPropertyName(parentName)} (${subSchema.type})`
+    } else {
+      subSchema.title = `${formatPropertyName(parentName)} Variant ${index + 1}`
+    }
+  }
+
+  setAlternativeValidationTitle(subSchema, parentName, keyword)
+}
+
+/**
+ * Process schema properties
+ * @param {SchemaObject} schema - Schema to process
+ */
+export function processProperties(schema) {
+  if (!schema.properties || typeof schema.properties !== 'object') {
+    return
+  }
+
+  const entries = Object.entries(schema.properties)
+
+  entries.forEach(([propName, propSchema]) => {
+    if (!propSchema.title) {
+      propSchema.title = formatPropertyName(propName)
+    }
+
+    if (!propSchema.description && propSchema.title) {
+      propSchema.description = `The ${propSchema.title.toLowerCase()} value.`
+    }
+
+    addTitles(propSchema, propName)
+  })
+}
+
+/**
+ * Process array items in schema
+ * @param {SchemaObject} schema - Schema to process
+ * @param {string} parentName - Parent object name
+ */
+export function processArrayItems(schema, parentName) {
+  if (!schema.items) {
+    return
+  }
+
+  if (Array.isArray(schema.items)) {
+    schema.items.forEach((item, index) => {
+      if (!item.title) {
+        item.title = `${formatPropertyName(parentName)} Item ${index + 1}`
+      }
+      addTitles(item, item.title)
+    })
+  } else {
+    if (!schema.items.title) {
+      schema.items.title = `${formatPropertyName(parentName)} Item`
+    }
+    addTitles(schema.items, schema.items.title)
+  }
+}
+
+/**
+ * Process combination keywords (oneOf, anyOf, allOf)
+ * @param {SchemaObject} schema - Schema to process
+ * @param {string} parentName - Parent object name
+ */
+export function processCombinationKeywords(schema, parentName) {
+  ;['oneOf', 'anyOf', 'allOf'].forEach((keyword) => {
+    if (!schema[keyword] || !Array.isArray(schema[keyword])) {
+      return
+    }
+
+    schema[`${keyword}Titles`] = []
+
+    schema[keyword].forEach((subSchema, index) => {
+      handleSpecialTitles(subSchema, parentName, keyword, index)
+
+      schema[`${keyword}Titles`][index] = subSchema.title
+      addTitles(subSchema, subSchema.title || parentName)
+    })
+  })
+}
+
+/**
+ * Process schema references and definitions
+ * @param {SchemaObject} schema - Schema to process
+ */
+export function processReferences(schema) {
+  if (schema.schemas) {
+    Object.entries(schema.schemas).forEach(([schemaName, schemaObj]) => {
+      if (!schemaObj.title) {
+        schemaObj.title = formatPropertyName(schemaName)
+      }
+      addTitles(schemaObj, schemaName)
+    })
+  }
+
+  if (schema.components?.schemas) {
+    Object.entries(schema.components.schemas).forEach(
+      ([schemaName, schemaObj]) => {
+        if (!schemaObj.title) {
+          schemaObj.title = formatPropertyName(schemaName)
+        }
+        addTitles(schemaObj, schemaName)
+      }
+    )
+  }
+
+  if (schema.$defs) {
+    Object.entries(schema.$defs).forEach(([defName, defSchema]) => {
+      if (!defSchema.title) {
+        defSchema.title = formatPropertyName(defName)
+      }
+      addTitles(defSchema, defName)
+    })
+  }
+}
+
+/**
+ * Process additional and pattern properties
+ * @param {SchemaObject} schema - Schema to process
+ * @param {string} parentName - Parent object name
+ */
+export function processAdditionalProperties(schema, parentName) {
+  if (
+    schema.additionalProperties &&
+    typeof schema.additionalProperties === 'object'
+  ) {
+    if (!schema.additionalProperties.title) {
+      schema.additionalProperties.title = `Additional Properties (${parentName})`
+    }
+    addTitles(schema.additionalProperties, `Additional ${parentName}`)
+  }
+
+  if (schema.patternProperties) {
+    Object.entries(schema.patternProperties).forEach(
+      ([pattern, patternSchema]) => {
+        if (!patternSchema.title) {
+          patternSchema.title = `Pattern Property (${pattern})`
+        }
+        addTitles(patternSchema, `Pattern ${parentName}`)
+      }
+    )
+  }
+}
+
+/**
+ * Recursively enhances schemas with descriptive titles and descriptions
+ * for better documentation output
+ * @param {SchemaObject} schema - The schema object to enhance
+ * @param {string} parentName - Name of the parent object for context
+ * @returns {SchemaObject} The enhanced schema
+ */
+export function addTitles(schema, parentName = '') {
+  if (!schema || typeof schema !== 'object') {
+    return schema
+  }
+
+  setSchemaTitle(schema, parentName)
+
+  // process oneOf, anyOf, allOf with improved titles
+  processCombinationKeywords(schema, parentName)
+
+  processProperties(schema)
+
+  processArrayItems(schema, parentName)
+
+  processReferences(schema)
+
+  processAdditionalProperties(schema, parentName)
+
+  return schema
+}
+
+/**
+ * @import { SchemaObject } from './types.js'
+ */

package/scripts/schema-modules/types.js

@@ -0,0 +1,21 @@
+/**
+ * @typedef {{[key: string]: any}} StringIndexedObject
+ * @typedef {object & StringIndexedObject} SchemaObject
+ * @property {string} [title] - Schema title
+ * @property {string} [description] - Schema description
+ * @property {string} [type] - Schema type
+ * @property {{[key: string]: SchemaObject}} [properties] - Schema properties
+ * @property {SchemaObject|SchemaObject[]} [items] - Array items schema
+ * @property {SchemaObject[]} [oneOf] - OneOf array of schemas
+ * @property {SchemaObject[]} [anyOf] - AnyOf array of schemas
+ * @property {SchemaObject[]} [allOf] - AllOf array of schemas
+ * @property {object} [additionalProperties] - Additional properties schema
+ * @property {object} [patternProperties] - Pattern properties schemas
+ * @property {object} [components] - OpenAPI components
+ * @property {object} [schemas] - OpenAPI schemas
+ * @property {object} [$defs] - JSON Schema definitions
+ * @property {string} [$ref] - JSON Schema reference
+ * @property {*} [x] - Any additional properties with string keys
+ */
+
+export {}