OpenAPI Schema XML Transformer

Build a utility that transforms OpenAPI schema objects by adding XML serialization metadata to prepare them for APIs that support both JSON and XML representations.

Requirements

Create a TypeScript module that provides functionality to enhance OpenAPI 3.0 schema objects with XML serialization configuration.

Schema Enhancement

Your utility should accept an OpenAPI 3.0 schema object and XML configuration options, then return an enhanced schema with appropriate XML metadata.

The XML configuration should support:

• Custom XML element names (different from the schema property name)
• XML namespace URIs for proper namespace handling
• XML namespace prefixes for qualified names
• Attribute vs element distinction (whether to serialize as XML attribute)
• Wrapping configuration for array items

Validation

The utility should validate that:

• Input is a valid OpenAPI 3.0 schema object structure
• XML configuration options are properly formatted
• The resulting schema maintains OpenAPI 3.0 compliance

Implementation

@generates

API

import { OpenAPIV3 } from 'openapi-types';

/**
 * Configuration for XML serialization metadata
 */
export interface XMLConfig {
  name?: string;
  namespace?: string;
  prefix?: string;
  attribute?: boolean;
  wrapped?: boolean;
}

/**
 * Enhances an OpenAPI schema with XML serialization metadata
 *
 * @param schema - The OpenAPI 3.0 schema object to enhance
 * @param xmlConfig - XML serialization configuration
 * @returns Enhanced schema with XML metadata
 * @throws Error if schema or xmlConfig is invalid
 */
export function addXMLMetadata(
  schema: OpenAPIV3.SchemaObject,
  xmlConfig: XMLConfig
): OpenAPIV3.SchemaObject;

/**
 * Validates that a schema object has proper XML metadata
 *
 * @param schema - The schema to validate
 * @returns true if schema has valid XML metadata, false otherwise
 */
export function hasValidXMLMetadata(schema: OpenAPIV3.SchemaObject): boolean;

Test Cases

Basic XML name assignment

• Given a simple schema object and XML config with a custom name, the function returns a schema with the xml.name property set @test

XML namespace configuration

• Given a schema and XML config with namespace and prefix, the function returns a schema with xml.namespace and xml.prefix properties set @test

XML attribute serialization

• Given a schema and XML config with attribute=true, the function returns a schema with xml.attribute set to true @test

Array wrapping configuration

• Given an array schema and XML config with wrapped=true, the function returns a schema with xml.wrapped set to true @test

Invalid input handling

• When given an invalid schema (null or non-object), the function throws an appropriate error @test

Dependencies { .dependencies }

openapi-types { .dependency }

Provides TypeScript type definitions for OpenAPI 3.0 specifications, including XMLObject type for schema XML serialization metadata.