WIP: inline enums schemas

[wtrocki]

Fix for Enum Removal Leaving Empty Referenced Objects

Problem

The original removeEnums transformation was too aggressive - it removed all enum fields throughout the OpenAPI document, including from schemas that were primarily enum definitions and were referenced elsewhere via $ref.

This caused problems such as:

1. Schemas like AlertAuditTypeView that were purely enum definitions became essentially empty after enum removal
2. These empty schemas were still referenced via $ref in other parts of the document
3. The resulting OpenAPI schema had broken references to empty objects

Example of the Problem

Before transformation:

AlertAuditTypeView:
  description: "Unique identifier of event type."
  enum:
    - ALERT_ACKNOWLEDGED_AUDIT
    - ALERT_UNACKNOWLEDGED_AUDIT
  example: ALERT_ACKNOWLEDGED_AUDIT
  title: "Alert Audit Types"
  type: string

AlertAudit:
  properties:
    eventTypeName:
      $ref: '#/components/schemas/AlertAuditTypeView'

After old transformation:

AlertAuditTypeView:
  description: "Unique identifier of event type."
  # enum field removed - schema becomes essentially useless
  example: ALERT_ACKNOWLEDGED_AUDIT
  title: "Alert Audit Types"
  type: string

AlertAudit:
  properties:
    eventTypeName:
      $ref: '#/components/schemas/AlertAuditTypeView'  # Still references the now-empty schema

Solution

The enhanced removeEnums transformation now handles this case intelligently:

1. Identify enum-only schemas: Detect schemas that are primarily enum definitions (have enum field, type field, but no properties, allOf, oneOf, anyOf, or items)

2. Check if referenced: Only process schemas that are actually referenced via $ref elsewhere in the document

3. Inline and remove: For such schemas:

   • Replace all $ref references with an inline type definition (preserving description, example, title, but removing enum)
   • Remove the original schema entirely

4. Continue normal processing: Remove enum fields from all other schemas as before

After new transformation:

# AlertAuditTypeView schema is completely removed

AlertAudit:
  properties:
    eventTypeName:
      description: "Unique identifier of event type."
      example: ALERT_ACKNOWLEDGED_AUDIT
      title: "Alert Audit Types"
      type: string  # Inlined type definition, no broken reference

Benefits

1. No broken references: Eliminates empty schemas that are still referenced
2. Cleaner output: Removes unnecessary schema definitions
3. Preserves metadata: Important information like descriptions and examples are preserved
4. Backward compatible: Existing behavior for non-referenced enums remains unchanged

[Copilot]

Pull Request Overview

This PR fixes an issue where the removeEnums transformation was too aggressive, leaving empty schema objects that were still referenced elsewhere in the OpenAPI document. The fix intelligently handles enum-only schemas by inlining their type definitions where referenced and removing the original empty schemas.

• Enhanced removeEnums transformation to identify and handle enum-only schemas that are referenced via $ref
• Added logic to inline type definitions (preserving metadata like description, title, example) where enum schemas are referenced
• Implemented comprehensive test coverage for the new functionality

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
tools/transformer/src/transformations/removeEnums.js	Core implementation of enum-only schema detection, inlining, and removal logic
tools/transformer/tests/removeEnums.test.js	Comprehensive test suite covering various scenarios including oneOf references and complex schemas

[Copilot]

The hardcoded array indices for ref parsing (refParts[1], refParts[2], refParts[3]) could fail if the reference format is unexpected. Consider adding validation to ensure refParts has the expected length and structure before accessing these indices.

Suggested change

	if (refParts[1] === "components" && refParts[2] === "schemas") {
	if (refParts.length >= 4 && refParts[1] === "components" && refParts[2] === "schemas" && refParts[3]) {

[Copilot]

[nitpick] Using console.info for logging in a transformation function may not be appropriate for all environments. Consider using a proper logging framework or making logging configurable.

[wtrocki]

Remember: That is approved logging for Transformation

[Copilot]

Using Object.assign to replace the $ref object modifies the original object structure. This could potentially cause issues if other parts of the code expect the original object structure. Consider creating a new object instead of mutating the existing one.

Suggested change

	Object.assign(obj, inlineDefinition);
	const newObj = { ...obj, ...inlineDefinition };
	Object.keys(obj).forEach(k => delete obj[k]); // Clear the original object
	Object.assign(obj, newObj); // Copy new properties into the original object

[github-actions]

This PR has gone 30 days without any activity and meets the project’s definition of "stale". This will be auto-closed if there is no new activity over the next 30 days. If the issue is still relevant and active, you can simply comment with a "bump" to keep it open, or add the label "not_stale". Thanks for keeping our repository healthy!