@api-client/core 0.18.13 → 0.18.15

package/src/modeling/importers/SchemaFilteringStrategy.ts

@@ -0,0 +1,201 @@
+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
+    }
+
+    // Check for schemas that only contain a single allOf with a $ref (like ActionStatusType)
+    if (
+      schema.type === 'object' &&
+      schema.allOf?.length === 1 &&
+      typeof schema.allOf[0] === 'object' &&
+      '$ref' in schema.allOf[0] &&
+      !schema.properties &&
+      !schema.additionalProperties
+    ) {
+      return true
+    }
+
+    // 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

package/src/modeling/validation/entity_validation.ts

@@ -17,7 +17,8 @@ export class EntityValidation {
   /**
    * Performs all the validation rules on the entity.
    * If you are interested in a specific rule, use the specific method.
-   * @param target The target entity to validate. Can be a string with the entity key or a DomainEntity object.
+   * @param target The target entity to validate. Can be a string with
+   *               the entity key or a DomainEntity object.
    */
   validate(target: string | DomainEntity): DomainValidation[] {
     const results: DomainValidation[] = []
@@ -41,21 +42,20 @@ export class EntityValidation {
       })
       return results
     }
-    const primary = this.validatePrimaryKey(entity)
-    results.push(...primary)
-    const minimum = this.minimumRequiredProperties(entity)
-    results.push(...minimum)
+    const primaryKey = this.validatePrimaryKey(entity)
+    results.push(...primaryKey)
+    const minimumProperties = this.minimumRequiredProperties(entity)
+    results.push(...minimumProperties)
     const name = this.validateName(entity)
     results.push(...name)
-    const uniqueName = this.uniqueName(entity)
-    results.push(...uniqueName)
+    const unique = this.uniqueName(entity)
+    results.push(...unique)
     return results
   }
 
   /**
-   * Validates the entity against the primary key validation rules.
+   * Validates the entity primary key.
    * @param entity The entity to validate
-   * @returns The list of validation messages.
    */
   validatePrimaryKey(entity: DomainEntity): DomainValidation[] {
     const results: DomainValidation[] = []
@@ -76,13 +76,62 @@ export class EntityValidation {
     return results
   }
 
+  /**
+   * Checks if an entity has properties through its entire inheritance chain.
+   * This includes direct properties and properties inherited from any level of parent entities.
+   * @param entity The entity to check
+   * @returns True if the entity has properties either directly or through inheritance
+   */
+  private hasPropertiesInherited(entity: DomainEntity): boolean {
+    // Check direct properties first
+    if (entity.hasProperties()) {
+      return true
+    }
+
+    // Check all parents recursively
+    for (const parent of entity.listParents()) {
+      if (this.hasPropertiesInherited(parent)) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Checks if an entity has associations through its entire inheritance chain.
+   * This includes direct associations and associations inherited from any level of parent entities.
+   * @param entity The entity to check
+   * @returns True if the entity has associations either directly or through inheritance
+   */
+  private hasAssociationsInherited(entity: DomainEntity): boolean {
+    // Check direct associations first
+    if (entity.hasAssociations()) {
+      return true
+    }
+
+    // Check all parents recursively
+    for (const parent of entity.listParents()) {
+      if (this.hasAssociationsInherited(parent)) {
+        return true
+      }
+    }
+
+    return false
+  }
+
   /**
    * Checks if the entity has the minimum required properties.
    * @param entity The entity to validate
    */
   minimumRequiredProperties(entity: DomainEntity): DomainValidation[] {
     const results: DomainValidation[] = []
-    if (!entity.hasProperties() && !entity.hasAssociations()) {
+
+    // Check if entity has properties or associations through entire inheritance chain
+    const hasProperties = this.hasPropertiesInherited(entity)
+    const hasAssociations = this.hasAssociationsInherited(entity)
+
+    if (!hasProperties && !hasAssociations) {
       const message = `The "${entity.info.getLabel()}" entity has no properties. It will be ignored.`
       const help = `Entities that have no properties are ignored in the data domain. No schema will be generated for it.`
       results.push({