@api-client/core 0.18.14 → 0.18.16

package/data/models/example-generator-api.json

@@ -42071,10 +42071,10 @@
 "@id": "#197"
 },
 {
-"@id": "#200"
+"@id": "#203"
 },
 {
-"@id": "#203"
+"@id": "#200"
 },
 {
 "@id": "#206"
@@ -42810,10 +42810,10 @@
 "@id": "#219"
 },
 {
-"@id": "#210"
+"@id": "#213"
 },
 {
-"@id": "#213"
+"@id": "#210"
 },
 {
 "@id": "#216"
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43520,7 +43520,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44232,7 +44232,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44253,7 +44253,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44771,12 +44771,12 @@
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.18.14",
+  "version": "0.18.16",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/importers/FilteringJsonSchemaImporter.ts

@@ -0,0 +1,324 @@
+import type { JSONSchema7 } from 'json-schema'
+import type { JsonImportReport, InMemorySchema } from './JsonSchemaImporter.js'
+import { JsonSchemaImporter } from './JsonSchemaImporter.js'
+import {
+  SchemaFilteringStrategy,
+  type SchemaFilteringOptions,
+  FILTERING_STRATEGIES,
+} from './SchemaFilteringStrategy.js'
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainEntity } from '../DomainEntity.js'
+import type { ImportMessage } from './JsonSchemaImporter.js'
+
+/**
+ * Extended JsonSchemaImporter that supports filtering out non-structural schemas.
+ * This version can eliminate schemas that don't contribute meaningful structure
+ * to the data model, such as empty objects or conceptual marker types.
+ */
+export class FilteringJsonSchemaImporter extends JsonSchemaImporter {
+  private filteringStrategy: SchemaFilteringStrategy
+
+  constructor(domain: DataDomain, filteringOptions: SchemaFilteringOptions = {}) {
+    super(domain)
+    this.filteringStrategy = new SchemaFilteringStrategy(filteringOptions)
+  }
+
+  /**
+   * Creates an importer with a predefined filtering strategy.
+   */
+  static withStrategy(
+    domain: DataDomain,
+    strategyName: keyof typeof FILTERING_STRATEGIES
+  ): FilteringJsonSchemaImporter {
+    const strategy = FILTERING_STRATEGIES[strategyName]
+    // Access private options through a public method (would need to be added to SchemaFilteringStrategy)
+    const options = strategy['options'] as SchemaFilteringOptions
+    return new FilteringJsonSchemaImporter(domain, options)
+  }
+
+  /**
+   * Creates an importer optimized for API development.
+   * Excludes schemas that don't contribute to API structure.
+   */
+  static forApiModeling(domain: DataDomain): FilteringJsonSchemaImporter {
+    return new FilteringJsonSchemaImporter(domain, {
+      excludeEmptyObjects: true,
+      excludeConceptualMarkers: true,
+      excludePatterns: [
+        /.*Enumeration$/, // Exclude *Enumeration schemas
+        /.*Type$/, // Exclude conceptual *Type schemas that are just markers
+      ],
+    })
+  }
+
+  /**
+   * Creates an importer optimized for database schema generation.
+   * Very strict filtering - only includes schemas with concrete properties.
+   */
+  static forDatabaseModeling(domain: DataDomain): FilteringJsonSchemaImporter {
+    return new FilteringJsonSchemaImporter(domain, {
+      excludeEmptyObjects: true,
+      excludeConceptualMarkers: true,
+      customExclusionFilter: (schema: JSONSchema7) => {
+        // For database modeling, exclude anything that doesn't have properties or clear structure
+        return (
+          schema.type === 'object' &&
+          !schema.properties &&
+          !schema.additionalProperties &&
+          !schema.allOf?.some(
+            (subSchema) => typeof subSchema === 'object' && 'properties' in subSchema && subSchema.properties
+          )
+        )
+      },
+    })
+  }
+
+  /**
+   * Override the base import method to apply filtering.
+   */
+  override async import(schemas: InMemorySchema[], modelName: string): Promise<JsonImportReport> {
+    // Apply pre-filtering to the schemas before import
+    const filteredSchemas = this.preFilterSchemas(schemas)
+
+    // Get the raw import result with filtered schemas
+    const rawResult = await super.import(filteredSchemas.schemas, modelName)
+
+    // Apply post-filtering to clean up any remaining issues
+    const finalReport = this.postFilterReport(rawResult, filteredSchemas.messages)
+
+    return finalReport
+  }
+
+  /**
+   * Pre-filters schemas before they are processed by the base importer.
+   */
+  private preFilterSchemas(schemas: InMemorySchema[]): {
+    schemas: InMemorySchema[]
+    messages: ImportMessage[]
+  } {
+    const filteredSchemas: InMemorySchema[] = []
+    const messages: ImportMessage[] = []
+
+    for (const schema of schemas) {
+      const schemaId = schema.contents.$id || schema.path
+
+      if (this.filteringStrategy.shouldExcludeSchema(schema.contents, schemaId)) {
+        const reason = this.filteringStrategy.getExclusionReason(schema.contents, schemaId)
+        messages.push({
+          level: 'info',
+          message: `Pre-filtered schema '${schemaId}': ${reason}`,
+          location: schema.path,
+        })
+      } else {
+        filteredSchemas.push(schema)
+      }
+    }
+
+    if (messages.length > 0) {
+      messages.push({
+        level: 'info',
+        message: `Pre-filtering removed ${messages.length} non-structural schema(s)`,
+      })
+    }
+
+    return { schemas: filteredSchemas, messages }
+  }
+
+  /**
+   * Post-processes the import report to clean up any remaining filtered entities.
+   */
+  private postFilterReport(report: JsonImportReport, preFilterMessages: ImportMessage[]): JsonImportReport {
+    const { model, messages } = report
+    const allMessages = [...preFilterMessages, ...messages]
+    let removedCount = 0
+
+    // Get entities as array for easier processing
+    const entities = Array.from(model.listEntities())
+    const entitiesToRemove: string[] = []
+
+    // Check each entity to see if it should be filtered out
+    for (const entity of entities) {
+      const shouldFilter = this.shouldFilterEntity(entity)
+
+      if (shouldFilter) {
+        entitiesToRemove.push(entity.key)
+        const reason = this.getEntityFilterReason(entity)
+        allMessages.push({
+          level: 'info',
+          message: `Post-filtered entity '${entity.info.name}': ${reason}`,
+          location: entity.key,
+        })
+        removedCount++
+      }
+    }
+
+    // Remove the filtered entities
+    for (const entityKey of entitiesToRemove) {
+      try {
+        model.removeEntity(entityKey)
+      } catch (error) {
+        allMessages.push({
+          level: 'warning',
+          message: `Failed to remove entity '${entityKey}': ${error}`,
+          location: entityKey,
+        })
+      }
+    }
+
+    // Clean up orphaned associations
+    this.cleanupOrphanedAssociations(entities, entitiesToRemove, allMessages)
+
+    if (removedCount > 0) {
+      allMessages.push({
+        level: 'info',
+        message: `Post-filtering removed ${removedCount} additional non-structural entity/entities`,
+      })
+    }
+
+    return {
+      model,
+      messages: allMessages,
+    }
+  }
+
+  /**
+   * Determines if an entity should be filtered out based on its characteristics.
+   */
+  private shouldFilterEntity(entity: DomainEntity): boolean {
+    // Check if entity has no properties and no meaningful associations
+    const hasProperties = Array.from(entity.listProperties()).length > 0
+    const hasAssociations = Array.from(entity.listAssociations()).length > 0
+
+    // If it has neither properties nor associations, it's likely a conceptual marker
+    if (!hasProperties && !hasAssociations) {
+      return this.filteringStrategy.shouldExcludeSchema(
+        {
+          type: 'object',
+          title: entity.info.name,
+          description: entity.info.description,
+        } as JSONSchema7,
+        entity.info.name
+      )
+    }
+
+    return false
+  }
+
+  /**
+   * Gets a human-readable reason for filtering an entity.
+   */
+  private getEntityFilterReason(entity: DomainEntity): string {
+    const hasProperties = Array.from(entity.listProperties()).length > 0
+    const hasAssociations = Array.from(entity.listAssociations()).length > 0
+
+    if (!hasProperties && !hasAssociations) {
+      return 'Entity has no properties or associations (likely a conceptual marker)'
+    }
+
+    return 'Entity matches exclusion pattern'
+  }
+
+  /**
+   * Removes associations that reference entities that were filtered out.
+   */
+  private cleanupOrphanedAssociations(
+    entities: DomainEntity[],
+    removedEntityKeys: string[],
+    messages: ImportMessage[]
+  ): void {
+    for (const entity of entities) {
+      const associationsToRemove: string[] = []
+
+      for (const association of entity.listAssociations()) {
+        const hasOrphanedTargets = association.targets?.some((target) => removedEntityKeys.includes(target.key))
+
+        if (hasOrphanedTargets) {
+          associationsToRemove.push(association.key)
+          messages.push({
+            level: 'info',
+            message: `Removed association '${association.info.name}' from '${entity.info.name}' due to filtered target entity`,
+            location: `${entity.key}.${association.key}`,
+          })
+        }
+      }
+
+      for (const associationKey of associationsToRemove) {
+        try {
+          entity.removeAssociation(associationKey)
+        } catch (error) {
+          messages.push({
+            level: 'warning',
+            message: `Failed to remove association '${associationKey}' from '${entity.info.name}': ${error}`,
+            location: `${entity.key}.${associationKey}`,
+          })
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Utility functions for working with filtered imports.
+ */
+export const SchemaFilteringUtils = {
+  /**
+   * Analyzes a JSON schema to determine if it would be filtered by the given strategy.
+   */
+  wouldBeFiltered(schema: JSONSchema7, strategy: SchemaFilteringStrategy): boolean {
+    return strategy.shouldExcludeSchema(schema)
+  },
+
+  /**
+   * Gets statistics about what would be filtered from a set of schemas.
+   */
+  getFilteringStats(
+    schemas: { id: string; schema: JSONSchema7 }[],
+    strategy: SchemaFilteringStrategy
+  ): {
+    total: number
+    filtered: number
+    remaining: number
+    filteredSchemas: { id: string; reason: string }[]
+  } {
+    const filteredSchemas: { id: string; reason: string }[] = []
+
+    for (const { id, schema } of schemas) {
+      if (strategy.shouldExcludeSchema(schema, id)) {
+        filteredSchemas.push({
+          id,
+          reason: strategy.getExclusionReason(schema, id),
+        })
+      }
+    }
+
+    return {
+      total: schemas.length,
+      filtered: filteredSchemas.length,
+      remaining: schemas.length - filteredSchemas.length,
+      filteredSchemas,
+    }
+  },
+
+  /**
+   * Creates a report showing what would be filtered from a schema collection.
+   */
+  createFilteringReport(schemas: { id: string; schema: JSONSchema7 }[], strategy: SchemaFilteringStrategy): string {
+    const stats = this.getFilteringStats(schemas, strategy)
+
+    let report = `Schema Filtering Report\n`
+    report += `======================\n\n`
+    report += `Total schemas: ${stats.total}\n`
+    report += `Would be filtered: ${stats.filtered}\n`
+    report += `Would remain: ${stats.remaining}\n\n`
+
+    if (stats.filteredSchemas.length > 0) {
+      report += `Schemas that would be filtered:\n`
+      report += `-------------------------------\n`
+      for (const { id, reason } of stats.filteredSchemas) {
+        report += `• ${id}: ${reason}\n`
+      }
+    }
+
+    return report
+  },
+}

package/src/modeling/importers/SchemaFilteringStrategy.ts

@@ -0,0 +1,193 @@
+import type { JSONSchema7 } from 'json-schema'
+
+/**
+ * Configuration options for schema filtering during import.
+ */
+export interface SchemaFilteringOptions {
+  /**
+   * Whether to exclude schemas that are empty objects with no properties.
+   * Default: false
+   */
+  excludeEmptyObjects?: boolean
+
+  /**
+   * Whether to exclude schemas that only serve as conceptual markers.
+   * These are typically schemas with only type: "object" and description
+   * but no properties, constraints, or meaningful structure.
+   * Default: false
+   */
+  excludeConceptualMarkers?: boolean
+
+  /**
+   * Custom predicate function to determine if a schema should be excluded.
+   * Return true to exclude the schema from import.
+   */
+  customExclusionFilter?: (schema: JSONSchema7, schemaId?: string) => boolean
+
+  /**
+   * List of schema IDs to explicitly exclude.
+   */
+  excludeSchemaIds?: string[]
+
+  /**
+   * Patterns to match against schema titles or IDs for exclusion.
+   */
+  excludePatterns?: RegExp[]
+}
+
+/**
+ * Strategy class for determining which schemas should be filtered out during import.
+ */
+export class SchemaFilteringStrategy {
+  constructor(private options: SchemaFilteringOptions = {}) {}
+
+  /**
+   * Determines whether a schema should be excluded from import.
+   */
+  shouldExcludeSchema(schema: JSONSchema7, schemaId?: string): boolean {
+    // Check explicit exclusion list
+    if (schemaId && this.options.excludeSchemaIds?.includes(schemaId)) {
+      return true
+    }
+
+    // Check pattern exclusions
+    if (schemaId && this.options.excludePatterns) {
+      for (const pattern of this.options.excludePatterns) {
+        if (pattern.test(schemaId) || (schema.title && pattern.test(schema.title))) {
+          return true
+        }
+      }
+    }
+
+    // Check for empty objects
+    if (this.options.excludeEmptyObjects && this.isEmptyObjectSchema(schema)) {
+      return true
+    }
+
+    // Check for conceptual markers
+    if (this.options.excludeConceptualMarkers && this.isConceptualMarkerSchema(schema)) {
+      return true
+    }
+
+    // Apply custom filter
+    if (this.options.customExclusionFilter?.(schema, schemaId)) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Checks if a schema represents an empty object with no meaningful structure.
+   */
+  private isEmptyObjectSchema(schema: JSONSchema7): boolean {
+    return (
+      schema.type === 'object' &&
+      (!schema.properties || Object.keys(schema.properties).length === 0) &&
+      !schema.additionalProperties &&
+      !schema.patternProperties &&
+      !schema.allOf &&
+      !schema.oneOf &&
+      !schema.anyOf &&
+      !schema.if &&
+      !schema.then &&
+      !schema.else &&
+      !schema.required?.length &&
+      !schema.minProperties &&
+      !schema.maxProperties
+    )
+  }
+
+  /**
+   * Checks if a schema is likely a conceptual marker with no structural value.
+   */
+  private isConceptualMarkerSchema(schema: JSONSchema7): boolean {
+    // Check for schemas that are just empty objects or only have allOf with references
+    if (this.isEmptyObjectSchema(schema)) {
+      return true
+    }
+
+    // Note: We removed the check for single allOf with $ref as this represents
+    // valid schema inheritance/extension patterns (e.g., BlogPosting extending SocialMediaPosting)
+    // Such schemas should be included as they define meaningful type hierarchies
+
+    // Check for schemas that only have description and type but no structure
+    if (
+      schema.type === 'object' &&
+      schema.description &&
+      !schema.properties &&
+      !schema.additionalProperties &&
+      !schema.allOf &&
+      !schema.oneOf &&
+      !schema.anyOf &&
+      Object.keys(schema).filter((key) => !['$schema', '$id', 'title', 'description', 'type'].includes(key)).length ===
+        0
+    ) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Gets a human-readable reason why a schema was excluded.
+   */
+  getExclusionReason(schema: JSONSchema7, schemaId?: string): string {
+    if (schemaId && this.options.excludeSchemaIds?.includes(schemaId)) {
+      return `Schema ID '${schemaId}' is in the exclusion list`
+    }
+
+    if (this.isEmptyObjectSchema(schema)) {
+      return 'Schema is an empty object with no structural definition'
+    }
+
+    if (this.isConceptualMarkerSchema(schema)) {
+      return 'Schema appears to be a conceptual marker with no concrete structure'
+    }
+
+    return 'Schema excluded by custom filter'
+  }
+}
+
+/**
+ * Predefined filtering strategies for common use cases.
+ */
+export const FILTERING_STRATEGIES = {
+  /**
+   * Strategy for API modeling - excludes schemas that don't contribute to API structure.
+   */
+  API_MODELING: new SchemaFilteringStrategy({
+    excludeEmptyObjects: true,
+    excludeConceptualMarkers: true,
+    excludePatterns: [
+      /.*Enumeration$/, // Exclude *Enumeration schemas
+      /.*Type$/, // Exclude conceptual *Type schemas that are just markers
+    ],
+  }),
+
+  /**
+   * Strategy for database modeling - very strict, only includes schemas with concrete properties.
+   */
+  DATABASE_MODELING: new SchemaFilteringStrategy({
+    excludeEmptyObjects: true,
+    excludeConceptualMarkers: true,
+    customExclusionFilter: (schema: JSONSchema7) => {
+      // For database modeling, exclude anything that doesn't have properties or clear structure
+      return (
+        schema.type === 'object' &&
+        !schema.properties &&
+        !schema.additionalProperties &&
+        !schema.allOf?.some(
+          (subSchema) => typeof subSchema === 'object' && 'properties' in subSchema && subSchema.properties
+        )
+      )
+    },
+  }),
+
+  /**
+   * Conservative strategy - only excludes obviously empty schemas.
+   */
+  CONSERVATIVE: new SchemaFilteringStrategy({
+    excludeEmptyObjects: true,
+  }),
+} as const