@api-client/core 0.18.3 → 0.18.5

package/src/modeling/importers/JsonSchemaImporter.ts

@@ -0,0 +1,642 @@
+import type { JSONSchema7, JSONSchema7Definition, JSONSchema7TypeName } from 'json-schema'
+import { DataDomain } from '../DataDomain.js'
+import { DomainModel } from '../DomainModel.js'
+import { DomainEntity } from '../DomainEntity.js'
+import { DomainProperty, type DomainPropertySchema } from '../DomainProperty.js'
+import type { PropertySchema } from '../types.js'
+import type { PropertyWebBindings } from '../Bindings.js'
+import type { DomainPropertyFormat, DomainPropertyType } from '../DataFormat.js'
+import { sanitizeInput, toDatabaseColumnName, toDatabaseTableName } from '../helpers/database.js'
+
+/**
+ * Represents a single message (info, warning, or error) generated during the import process.
+ */
+export interface ImportMessage {
+  level: 'warning' | 'info'
+  message: string
+  location?: string
+}
+
+/**
+ * A report containing the result of the import process, including the created model
+ * and any non-blocking messages.
+ */
+export interface JsonImportReport {
+  /**
+   * An array of messages generated during the import process.
+   * These can include warnings, info messages, or other non-blocking notifications.
+   */
+  messages: ImportMessage[]
+  /**
+   * The model that was created during the import.
+   */
+  model: DomainModel
+}
+
+/**
+ * A structure to hold in-memory JSON schema files for browser-based import.
+ */
+export interface InMemorySchema {
+  /** A virtual path or identifier for the schema, used in `$ref` values. */
+  path: string
+  /** The parsed content of the JSON schema file. */
+  contents: JSONSchema7
+}
+
+/**
+ * Imports JSON Schema definitions into a DataDomain.
+ *
+ * This class parses a root JSON Schema file, bundles all its dependencies,
+ * and translates the object definitions into DomainEntity instances within a specified DomainModel.
+ */
+export class JsonSchemaImporter {
+  private domain: DataDomain
+  private model!: DomainModel
+  private refMap = new Map<string, string>()
+  private messages: ImportMessage[] = []
+  private enums = new Map<string, JSONSchema7>()
+
+  constructor(domain: DataDomain) {
+    this.domain = domain
+  }
+
+  /**
+   * Resets the internal state for a new import operation.
+   */
+  private resetState(modelName: string) {
+    this.model = this.domain.addModel({ info: { name: modelName } })
+    this.refMap.clear()
+    this.enums.clear()
+    this.messages = []
+  }
+
+  /**
+   * Centralized reporting for warnings and info messages.
+   */
+  private report(level: 'warning' | 'info', message: string, location?: string): void {
+    this.messages.push({ level, message, location })
+  }
+
+  /**
+   * Main import method: orchestrates schema bundling, entity creation, and population.
+   */
+  public async import(schemas: InMemorySchema[], modelName: string): Promise<JsonImportReport> {
+    this.resetState(modelName)
+
+    // Build a flat map of all definitions and $id-indexed schemas
+    const definitionMap = new Map<string, JSONSchema7>()
+    const idMap = new Map<string, JSONSchema7>()
+    for (const schema of schemas) {
+      // Add $id mapping if present
+      if (schema.contents.$id) {
+        idMap.set(schema.contents.$id, schema.contents)
+      }
+      // Add the schema itself by its path
+      definitionMap.set(schema.path, schema.contents)
+      // Add all definitions inside this schema
+      const defs = (schema.contents.definitions ||
+        (schema.contents as unknown as { $defs: Record<string, JSONSchema7Definition> }).$defs) as
+        | Record<string, JSONSchema7Definition>
+        | undefined
+      if (defs) {
+        for (const [defName, defSchema] of Object.entries(defs)) {
+          if (typeof defSchema === 'object') {
+            // Use a JSON pointer for the key
+            definitionMap.set(`${schema.path}#/definitions/${defName}`, defSchema as JSONSchema7)
+            // Also allow lookup by just #/definitions/defName for single-file schemas
+            definitionMap.set(`#/definitions/${defName}`, defSchema as JSONSchema7)
+          }
+        }
+      }
+    }
+
+    // == Pass 1: Create all entities ==
+    for (const [key, schema] of definitionMap.entries()) {
+      if (typeof schema === 'object' && schema.type === 'object') {
+        this.createEntity(key, schema, key)
+      } else if (this.isEnum(schema)) {
+        this.enums.set(key, schema)
+      } else {
+        this.report('warning', `Skipping non-object schema at ${key}`, key)
+      }
+    }
+    // Also create entities for all $id-indexed schemas if not already present
+    for (const [id, schema] of idMap.entries()) {
+      if (!this.refMap.has(id) && typeof schema === 'object' && schema.type === 'object') {
+        this.createEntity(id, schema, id)
+      } else if (this.isEnum(schema)) {
+        this.enums.set(id, schema)
+      } else {
+        this.report('warning', `Skipping non-object schema at ${id}`, id)
+      }
+    }
+
+    // == Pass 2: Populate entities ==
+    for (const [refPath, entityKey] of this.refMap.entries()) {
+      const entity = this.domain.findEntity(entityKey)
+      if (!entity) {
+        this.report('warning', `Entity not found: ${entityKey}`, refPath)
+        continue
+      }
+      const schema = this.resolveSchemaRef(refPath, definitionMap, idMap)
+      if (!schema) {
+        this.report('warning', `Schema not found for ref: ${refPath}`, refPath)
+        continue
+      }
+      this.populateEntity(entity, schema)
+    }
+
+    return { model: this.model, messages: this.messages }
+  }
+
+  private isEnum(schema: JSONSchema7): boolean {
+    if (schema.type !== 'string') {
+      // I might be wrong about it, but I think enums are only for strings
+      return false
+    }
+    if (!Array.isArray(schema.oneOf)) {
+      return false
+    }
+    const notConst = schema.oneOf.find((s) => typeof s !== 'object' || !('const' in s))
+    return !notConst // If all schemas in oneOf have 'const', it's an enum
+  }
+
+  /**
+   * Resolves a schema reference from the flat definition/id maps.
+   * Supports #/definitions/..., $id, or direct path keys.
+   */
+  private resolveSchemaRef(
+    refPath: string,
+    definitionMap: Map<string, JSONSchema7>,
+    idMap: Map<string, JSONSchema7>
+  ): JSONSchema7 | undefined {
+    // Try direct match
+    if (definitionMap.has(refPath)) return definitionMap.get(refPath)
+    if (idMap.has(refPath)) return idMap.get(refPath)
+    // Try to resolve #/definitions/Name from any schema
+    if (refPath.startsWith('#/definitions/')) {
+      for (const [key, schema] of definitionMap.entries()) {
+        if (key.endsWith(refPath)) return schema
+      }
+    }
+    // Try to resolve by $id fragment
+    if (refPath.startsWith('#')) {
+      for (const [id, schema] of idMap.entries()) {
+        if (id.endsWith(refPath)) return schema
+      }
+    }
+    return undefined
+  }
+
+  /**
+   * Helper for entity creation, can be extended for custom logic.
+   */
+  private createEntity(name: string, schema: JSONSchema7, refPath: string): DomainEntity {
+    const fixedName = schema.title || name
+    const cleanName = toDatabaseTableName(fixedName, 'untitled_entity')
+    const entity = this.model.addEntity({
+      info: {
+        name: cleanName,
+        displayName: fixedName,
+      },
+    })
+    if (fixedName !== cleanName) {
+      entity.info.displayName = fixedName // Keep original title for display
+    }
+    if (schema.description) {
+      entity.info.description = schema.description
+    }
+    this.refMap.set(refPath, entity.key)
+    return entity
+  }
+
+  /**
+   * Populates a DomainEntity with its properties, associations, and parent relationships.
+   */
+  private populateEntity(entity: DomainEntity, schema: JSONSchema7): void {
+    const properties = schema.properties || {}
+    const required = new Set(schema.required || [])
+
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      if (typeof propSchema === 'object') {
+        this.createPropertyOrAssociation(entity, propName, propSchema, required.has(propName))
+      }
+    }
+
+    // Handle 'allOf' for inheritance and composition.
+    if (schema.allOf) {
+      this.processAllOf(entity, schema.allOf)
+    }
+  }
+
+  /**
+   * Processes the `allOf` keyword, which can contain references (for inheritance)
+   * or inline schemas (for composition/mixins).
+   */
+  private processAllOf(entity: DomainEntity, allOfSchemas: JSONSchema7Definition[]): void {
+    allOfSchemas.forEach((subSchema, index) => {
+      if (typeof subSchema !== 'object') {
+        return
+      }
+      // Case 1: It's a reference to another entity (standard inheritance).
+      if (subSchema.$ref) {
+        // Try to resolve the referenced entity by $ref (could be #/definitions/..., $id, or path)
+        const parentKey = this.refMap.get(subSchema.$ref)
+        if (parentKey) {
+          try {
+            entity.addParent(parentKey)
+          } catch (e) {
+            this.report(
+              'warning',
+              `Could not add parent ${parentKey} to ${entity.key}: ${(e as Error).message}`,
+              entity.key
+            )
+          }
+        } else {
+          this.report('warning', `Could not resolve parent reference: ${subSchema.$ref}`, entity.key)
+        }
+        return
+      }
+      // Case 2: It's an inline schema to be mixed in.
+      // const mixinKey = `${entity.key}_mixin_${index}`
+      const mixinName = subSchema.title || `${entity.info.name} Mixin ${index + 1}`
+      const mixinEntity = this.model.addEntity({
+        // key: mixinKey,
+        info: {
+          name: mixinName,
+          description:
+            subSchema.description ||
+            `Auto-generated mixin entity from an 'allOf' clause in the schema for '${entity.info.name}'. This entity is not intended for direct use.`,
+        },
+      })
+      this.populateEntity(mixinEntity, subSchema)
+      try {
+        entity.addParent(mixinEntity.key)
+      } catch (e) {
+        this.report(
+          'warning',
+          `Could not add mixin parent ${mixinEntity.key} to ${entity.key}: ${(e as Error).message}`,
+          entity.key
+        )
+      }
+    })
+  }
+  /**
+   * Recursively analyzes a schema definition to find all contained primitive types and `$ref`s.
+   * It's used to understand the nature of a property (is it a primitive, an association, or a mix).
+   */
+  private collectTypesAndRefs(schema: JSONSchema7Definition): {
+    refs: Set<string>
+    types: Set<JSONSchema7TypeName>
+    isArray: boolean
+  } {
+    const collected = { refs: new Set<string>(), types: new Set<JSONSchema7TypeName>(), isArray: false }
+
+    if (typeof schema !== 'object') {
+      return collected
+    }
+
+    if (schema.$ref) {
+      collected.refs.add(schema.$ref)
+      return collected
+    }
+
+    if (schema.type) {
+      const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+      for (const t of types) {
+        if (t !== 'null') collected.types.add(t)
+      }
+    }
+
+    if (schema.type === 'array') {
+      collected.isArray = true
+      if (typeof schema.items === 'object') {
+        // Recurse into items
+        const itemInfo = this.collectTypesAndRefs(Array.isArray(schema.items) ? schema.items[0] : schema.items)
+        itemInfo.refs.forEach((r) => collected.refs.add(r))
+        itemInfo.types.forEach((t) => collected.types.add(t))
+      }
+      return collected
+    }
+
+    const choices = schema.anyOf || schema.oneOf
+    if (choices) {
+      for (const choice of choices) {
+        const choiceInfo = this.collectTypesAndRefs(choice)
+        choiceInfo.refs.forEach((r) => collected.refs.add(r))
+        choiceInfo.types.forEach((t) => collected.types.add(t))
+        if (choiceInfo.isArray) {
+          collected.isArray = true
+        }
+      }
+    }
+
+    return collected
+  }
+
+  /**
+   * Determines whether to create a DomainProperty or a DomainAssociation for a given schema property.
+   */
+  private createPropertyOrAssociation(
+    entity: DomainEntity,
+    propName: string,
+    propSchema: JSONSchema7,
+    isRequired: boolean
+  ): void {
+    // Analyze the property schema to understand its composition (primitives, refs, arrays).
+    const analysis = this.collectTypesAndRefs(propSchema)
+
+    // Case 1: If the property has `$ref` to an enum, we treat it as a DomainProperty.
+    if (analysis.refs.size === 1 && this.enums.has([...analysis.refs][0])) {
+      const prop = this.createEnumProperty(
+        propName,
+        propSchema,
+        this.enums.get([...analysis.refs][0]) as JSONSchema7,
+        entity.info.name as string
+      )
+      if (prop) {
+        prop.multiple = analysis.isArray
+        // console.log(`Adding enum property '${propName}' to entity '${entity.info.name}'`, prop.toJSON())
+        entity.addProperty(prop.toJSON())
+      }
+      return
+    }
+
+    // Case 2: If any `$ref` was found, we treat it as an Association.
+    if (analysis.refs.size > 0) {
+      const sanitizedName = toDatabaseColumnName(propName, 'untitled_association')
+      const assoc = entity.addAssociation({}, { info: { name: sanitizedName } })
+      if (sanitizedName !== propName) {
+        assoc.info.displayName = propName // Keep original name for display
+      }
+      if (propSchema.description) {
+        assoc.info.description = propSchema.description
+      }
+      assoc.required = isRequired
+      assoc.multiple = analysis.isArray
+      for (const ref of analysis.refs) {
+        const targetKey = this.refMap.get(ref)
+        if (targetKey) {
+          assoc.addTarget(targetKey)
+        }
+      }
+      if (analysis.types.size > 0) {
+        this.report(
+          'warning',
+          `Property '${propName}' has a mix of reference and primitive types. Only the reference(s) will be used to create an association. The primitive types (${[
+            ...analysis.types,
+          ].join(', ')}) are ignored.`,
+          entity.key
+        )
+      }
+      return
+    }
+    // Case 3: No `$ref`s found, only primitive types. We treat it as a DomainProperty.
+    if (analysis.types.size > 0) {
+      // We need to create a temporary schema object to pass to createDomainProperty,
+      // as it expects a single schema. We'll use the first detected type.
+      const tempSchema: JSONSchema7 = {
+        ...propSchema,
+        // Pass the collected types to be resolved by mapJsonTypeToDomainType
+        type: [...analysis.types],
+      }
+      const prop = this.createDomainProperty(entity.key, propName, tempSchema, isRequired)
+      if (prop) {
+        prop.multiple = analysis.isArray
+        entity.addProperty(prop.toJSON())
+      }
+      return
+    }
+  }
+
+  /**
+   * Creates and configures a DomainProperty based on a JSON schema property definition.
+   */
+  private createDomainProperty(
+    parentEntityKey: string,
+    propName: string,
+    propSchema: JSONSchema7,
+    isRequired: boolean
+  ): DomainProperty | null {
+    const typeInfo = this.mapJsonTypeToDomainType(propSchema.type, propSchema, `${parentEntityKey}.${propName}`)
+    if (!typeInfo) return null
+    const sanitizedName = toDatabaseColumnName(propName, 'untitled_property')
+    const propertyInit: Partial<DomainPropertySchema> = {
+      info: { name: sanitizedName, description: propSchema.description },
+      type: typeInfo.type,
+      required: isRequired,
+    }
+
+    // Use the constructor that doesn't add to the graph immediately.
+    const prop = new DomainProperty(this.domain, parentEntityKey, propertyInit)
+    if (sanitizedName !== propName) {
+      prop.info.displayName = propName // Keep original name for display
+    }
+
+    const schema: PropertySchema = {}
+    const webBindings: PropertyWebBindings = {}
+
+    if (propSchema.pattern) schema.pattern = propSchema.pattern
+    if (propSchema.enum) schema.enum = propSchema.enum.map(String)
+    if (propSchema.default !== undefined) schema.defaultValue = { type: 'literal', value: String(propSchema.default) }
+
+    if (typeInfo.type === 'string') {
+      if (typeof propSchema.minLength === 'number') schema.minimum = propSchema.minLength
+      if (typeof propSchema.maxLength === 'number') schema.maximum = propSchema.maxLength
+    } else if (typeInfo.type === 'number') {
+      if (typeof propSchema.minimum === 'number') schema.minimum = propSchema.minimum
+      if (typeof propSchema.maximum === 'number') schema.maximum = propSchema.maximum
+      if (typeof propSchema.exclusiveMinimum === 'number') {
+        schema.minimum = propSchema.exclusiveMinimum
+        schema.exclusiveMinimum = true
+      }
+      if (typeof propSchema.exclusiveMaximum === 'number') {
+        schema.maximum = propSchema.exclusiveMaximum
+        schema.exclusiveMaximum = true
+      }
+      if (typeof propSchema.multipleOf === 'number') schema.multipleOf = propSchema.multipleOf
+      if (typeInfo.format) {
+        webBindings.format = typeInfo.format
+      }
+    }
+
+    if (Object.keys(schema).length > 0) {
+      prop.schema = schema
+    }
+    if (Object.keys(webBindings).length > 0) {
+      prop.bindings = [{ type: 'web', schema: webBindings }]
+    }
+
+    return prop
+  }
+
+  /**
+   * Maps a JSON Schema type to a DomainPropertyType.
+   */
+  private mapJsonTypeToDomainType(
+    jsonType: JSONSchema7TypeName | JSONSchema7TypeName[] | undefined,
+    schema: JSONSchema7,
+    location?: string
+  ): { type: DomainPropertyType; format?: DomainPropertyFormat } | null {
+    if (!jsonType) {
+      return null
+    }
+
+    if (Array.isArray(jsonType)) {
+      const nonNullTypes = jsonType.filter((t) => t !== 'null')
+      if (nonNullTypes.length === 0) {
+        return null
+      }
+      if (nonNullTypes.length === 2 && nonNullTypes.includes('array')) {
+        const nonArrayType = nonNullTypes.filter((t) => t !== 'array')[0]
+        return this.mapJsonTypeToDomainType(nonArrayType, schema, location)
+      }
+      if (nonNullTypes.length > 1) {
+        this.report(
+          'warning',
+          `Property has a union of primitive types: [${nonNullTypes.join(', ')}]. The importer will use the first type ('${nonNullTypes[0]}').`,
+          location
+        )
+      }
+      // Pick the first non-null type from the union.
+      return this.mapJsonTypeToDomainType(nonNullTypes[0], schema, location)
+    }
+
+    if (jsonType === 'string') {
+      // JSON Schema has the `format` property which can specify more about the string type.
+      // We need to decide how to handle these formats.
+      const choices = schema.anyOf || schema.oneOf
+      if (Array.isArray(choices)) {
+        // If we have a list of choices, we need to pick one.
+        const formats: string[] = []
+        for (const choice of choices) {
+          const typed = choice as JSONSchema7
+          if (typed.format) {
+            formats.push(typed.format)
+          }
+        }
+        // we will list dates from the most specific to the least specific
+        if (formats.includes('date-time')) {
+          return { type: 'datetime' }
+        }
+        if (formats.includes('date')) {
+          return { type: 'date' }
+        }
+        if (formats.includes('time')) {
+          return { type: 'time' }
+        }
+      }
+      // If no specific format is found, we default to string.
+      return { type: 'string' }
+    }
+
+    switch (jsonType) {
+      case 'number':
+        return { type: 'number', format: 'double' }
+      case 'integer':
+        return { type: 'number', format: 'int64' }
+      case 'boolean':
+        return { type: 'boolean' }
+      // JSON Schema's 'object' and 'array' are handled as associations or multi-valued properties.
+      // Other types like 'null' are handled by making the property not required.
+      default:
+        return null
+    }
+  }
+
+  private createEnumProperty(
+    propName: string,
+    propSchema: JSONSchema7,
+    enumSchema: JSONSchema7,
+    parentEntityKey: string
+  ): DomainProperty | null {
+    const description = propSchema.description ?? enumSchema.description
+    const typeInfo = this.mapJsonTypeToDomainType(enumSchema.type, enumSchema, `${parentEntityKey}.${propName}`)
+    if (!typeInfo) return null
+
+    const sanitizedName = toDatabaseColumnName(propName)
+    const propertyInit: Partial<DomainPropertySchema> = {
+      info: { name: sanitizedName },
+      type: typeInfo.type,
+      // required: isRequired,
+      required: false,
+    }
+
+    // Use the constructor that doesn't add to the graph immediately.
+    const prop = new DomainProperty(this.domain, parentEntityKey, propertyInit)
+    if (sanitizedName !== propName) {
+      prop.info.displayName = propName // Keep original name for display
+    }
+    if (description) {
+      prop.info.description = sanitizeInput(description)
+    }
+
+    const schema: PropertySchema = {}
+
+    const pattern = propSchema.pattern ?? enumSchema.pattern
+    if (pattern) {
+      schema.pattern = pattern
+    }
+    const defaultValue = propSchema.default ?? enumSchema.default
+    if (defaultValue !== undefined) {
+      schema.defaultValue = { type: 'literal', value: String(defaultValue) }
+    }
+
+    if (typeInfo.type === 'string') {
+      const minLength = propSchema.minLength ?? enumSchema.minLength
+      const maxLength = propSchema.maxLength ?? enumSchema.maxLength
+      if (minLength !== undefined) schema.minimum = minLength
+      if (maxLength !== undefined) schema.maximum = maxLength
+    } else if (typeInfo.type === 'number') {
+      const minimum = propSchema.minimum ?? enumSchema.minimum
+      const maximum = propSchema.maximum ?? enumSchema.maximum
+      if (minimum !== undefined) {
+        schema.minimum = minimum
+      }
+      if (maximum !== undefined) {
+        schema.maximum = maximum
+      }
+      const exclusiveMinimum = propSchema.exclusiveMinimum ?? enumSchema.exclusiveMinimum
+      const exclusiveMaximum = propSchema.exclusiveMaximum ?? enumSchema.exclusiveMaximum
+      if (typeof exclusiveMinimum === 'number') {
+        schema.minimum = exclusiveMinimum
+        schema.exclusiveMinimum = true
+      }
+      if (typeof exclusiveMaximum === 'number') {
+        schema.maximum = exclusiveMaximum
+        schema.exclusiveMaximum = true
+      }
+      const multipleOf = propSchema.multipleOf ?? enumSchema.multipleOf
+      if (typeof multipleOf === 'number') {
+        schema.multipleOf = multipleOf
+      }
+    }
+    if (enumSchema.oneOf && Array.isArray(enumSchema.oneOf)) {
+      schema.enum = []
+      for (const item of enumSchema.oneOf) {
+        if (typeof item !== 'object' || !('const' in item)) {
+          this.report(
+            'warning',
+            `Invalid enum item in oneOf: ${JSON.stringify(item)}. Expected an object with 'const' property.`,
+            `${parentEntityKey}.${propName}`
+          )
+          continue
+        }
+        if (typeof (item as JSONSchema7).const !== 'string') {
+          this.report(
+            'warning',
+            `Invalid enum const value: ${JSON.stringify((item as JSONSchema7).const)}. Expected a string.`,
+            `${parentEntityKey}.${propName}`
+          )
+          continue
+        }
+        schema.enum.push((item as JSONSchema7).const as string)
+      }
+    }
+
+    if (Object.keys(schema).length > 0) {
+      prop.schema = schema
+    }
+    return prop
+  }
+}