Fix Schema

About

The Fix Schema plugin allows you to modify OpenAPI schema definitions during the code generation process. This is particularly useful when working with third-party APIs that have incorrect or incomplete schema definitions, allowing you to fix these issues at generation time rather than manually modifying generated code.

Why Use Fix Schema?

OpenAPI specifications are often generated automatically from server code, but this process doesn't always capture the developer's full intent. Common issues include:

• Missing required fields that are actually mandatory in practice
• Incorrect property types due to automatic inference limitations
• Missing properties that exist in the actual API responses
• Deprecated fields still present in the generated spec

The Fix Schema plugin bridges this gap by allowing you to correct these discrepancies without modifying the upstream API specification, ensuring your generated client code accurately reflects the real API behavior.

Additionally, when backend developers are constrained by scheduling issues and unable to modify the OpenAPI specification immediately, frontend developers can use this plugin to make necessary adjustments and proceed with development without delays.

Features

• modify specific schema objects by name during generation
• support for JSON Patch operations for precise schema modifications
• custom JavaScript functions for complex schema transformations
• multiple configuration formats for different use cases

Installation

In your configuration, add fix-schema to your plugins.

import { defaultPlugins, defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: 'src/client',
  plugins: [
    'fix-schema', 
    ...defaultPlugins,
  }]
});

Important: The fix-schema plugin must be registered before defaultPlugins. If registered after defaultPlugins, the schema modifications will not take effect.

Configuration

The plugin accepts a fix configuration option that specifies which schemas to modify and how to modify them. You can use either JSON Patch operations or custom JavaScript functions.

JSON Patch Operations

The target type for JSON Patch operations is IRSchemaObject, which has the following structure:

interface IRSchemaObject {
  // Basic schema properties
  type?:
    | 'array'
    | 'boolean'
    | 'enum'
    | 'integer'
    | 'never'
    | 'null'
    | 'number'
    | 'object'
    | 'string'
    | 'tuple'
    | 'undefined'
    | 'unknown'
    | 'void';
  properties?: Record<string, IRSchemaObject>;
  items?: ReadonlyArray<IRSchemaObject>;
  required?: string[];

  // Validation constraints
  minLength?: number;
  maxLength?: number;
  minItems?: number;
  maxItems?: number;
  minimum?: number;
  maximum?: number;
  pattern?: string;

  // Documentation
  title?: string;
  description?: string;
  deprecated?: boolean;
  default?: any;

  // Additional features
  format?: string;
  additionalProperties?: IRSchemaObject | false;
  accessScope?: 'read' | 'write';
  $ref?: string;
}

Unfortunately, JSON Patch does not provide type safety for the path parameter, so you need to be careful when specifying paths in your patch operations.

Use standard JSON Patch operations to make precise modifications to schemas:

export default {
  input: 'https://api.example.com/openapi.json',
  output: 'src/client',
  plugins: [
    {
      name: 'fix-schema',
      fix: {
        // Remove a required field
        UserDto: {
          op: 'remove',
          path: '/required/2',
        },
        // Add multiple properties
        ArticleDto: [
          {
            op: 'add',
            path: '/properties/publishedAt',
            value: { type: 'string', format: 'date-time' },
          },
          {
            op: 'add',
            path: '/required/-',
            value: 'publishedAt',
          },
        ],
      },
    },
    ...defaultPlugins,
  ],
};

Function-Based Modifications

Use JavaScript functions for more complex schema transformations:

export default {
  input: 'https://api.example.com/openapi.json',
  output: 'src/client',
  plugins: [
    {
      name: 'fix-schema',
      fix: {
        UserDto: (schema) => {
          // Add email property
          schema.properties.email = {
            type: 'string',
            format: 'email',
          };
          // Make it required
          schema.required = schema.required || [];
          schema.required.push('email');
        },
        ProductDto: (schema) => {
          // Remove deprecated fields
          delete schema.properties.oldField;
          // Update required array
          schema.required = schema.required?.filter(
            (field) => field !== 'oldField',
          );
        },
      },
    },
    ...defaultPlugins,
  ],
};

Array Configuration Format

You can also use an array format for configuration:

export default {
  input: 'https://api.example.com/openapi.json',
  output: 'src/client',
  plugins: [
    {
      name: 'fix-schema',
      fix: [
        [
          'UserDto',
          (schema) => {
            schema.properties.id = { type: 'number' };
          },
        ],
        [
          'ArticleDto',
          {
            op: 'add',
            path: '/properties/id',
            value: { type: 'number' },
          },
        ],
      ],
    },
    ...defaultPlugins,
  ],
};

Use Cases

Fix Missing Required Fields

{
  name: 'fix-schema',
  fix: {
    UserDto: {
      op: 'add',
      path: '/required/-',
      value: 'email'
    }
  }
}

Add Missing Properties

{
  name: 'fix-schema',
  fix: {
    ArticleDto: [
      {
        op: 'add',
        path: '/properties/createdAt',
        value: { type: 'string', format: 'date-time' }
      },
      {
        op: 'add',
        path: '/properties/updatedAt',
        value: { type: 'string', format: 'date-time' }
      }
    ]
  }
}

Fix Incorrect Types

{
  name: 'fix-schema',
  fix: {
    UserDto: {
      op: 'replace',
      path: '/properties/age/type',
      value: 'integer'
    }
  }
}

JSON Patch Operations

The plugin supports all standard JSON Patch operations:

• add: Add a new value
• remove: Remove an existing value
• replace: Replace an existing value
• move: Move a value from one location to another
• copy: Copy a value from one location to another
• test: Test that a value at a location equals a specified value

Sponsors

Love Hey API? Become our sponsor.

•