@skmtc/core 0.0.808 → 0.0.810

package/esm/oas/mediaType/toMediaTypeItemV3.js

@@ -2,6 +2,108 @@ import { toOptionalSchemaV3 } from '../schema/toSchemasV3.js';
 import { toExamplesV3 } from '../example/toExamplesV3.js';
 import { OasMediaType } from './MediaType.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+/**
+ * Transforms an OpenAPI v3 media type object into an internal OAS media type representation.
+ *
+ * This function processes OpenAPI v3 MediaType objects, extracting schema definitions,
+ * examples, encoding information, and specification extensions. It creates a structured
+ * internal representation that can be used by the SKMTC pipeline for code generation
+ * and validation.
+ *
+ * The transformation handles all standard OpenAPI v3 MediaType properties including
+ * schema references, inline schemas, examples, encoding specifications, and custom
+ * extension fields that begin with 'x-'.
+ *
+ * @param args - Transformation arguments
+ * @param args.mediaTypeItem - The OpenAPI v3 media type object to process
+ * @param args.mediaType - The media type identifier (MIME type)
+ * @param args.context - Parsing context for tracing and error handling
+ * @returns Structured OAS media type object for internal processing
+ *
+ * @example Transforming JSON media type
+ * ```typescript
+ * import { toMediaTypeItemV3 } from '@skmtc/core/oas/mediaType';
+ *
+ * const jsonMediaType = {
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       email: { type: 'string', format: 'email' }
+ *     }
+ *   },
+ *   example: {
+ *     name: 'John Doe',
+ *     email: 'john@example.com'
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemV3({
+ *   mediaTypeItem: jsonMediaType,
+ *   mediaType: 'application/json',
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.mediaType); // 'application/json'
+ * console.log(result.schema); // Processed schema object
+ * ```
+ *
+ * @example Processing form data with encoding
+ * ```typescript
+ * const formMediaType = {
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       file: { type: 'string', format: 'binary' },
+ *       metadata: { type: 'string' }
+ *     }
+ *   },
+ *   encoding: {
+ *     file: {
+ *       contentType: 'image/png',
+ *       headers: {
+ *         'X-Rate-Limit': {
+ *           schema: { type: 'integer' }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemV3({
+ *   mediaTypeItem: formMediaType,
+ *   mediaType: 'multipart/form-data',
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.encoding); // Processed encoding configuration
+ * ```
+ *
+ * @example Handling multiple examples
+ * ```typescript
+ * const mediaTypeWithExamples = {
+ *   schema: { type: 'string' },
+ *   examples: {
+ *     success: {
+ *       summary: 'Successful response',
+ *       value: 'Operation completed'
+ *     },
+ *     error: {
+ *       summary: 'Error response',
+ *       value: 'Operation failed'
+ *     }
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemV3({
+ *   mediaTypeItem: mediaTypeWithExamples,
+ *   mediaType: 'text/plain',
+ *   context: parseContext
+ * });
+ *
+ * console.log(Object.keys(result.examples)); // ['success', 'error']
+ * ```
+ */
 export const toMediaTypeItemV3 = ({ mediaTypeItem, mediaType, context }) => {
     const { schema, example, examples, encoding, ...skipped } = mediaTypeItem;
     const extensionFields = toSpecificationExtensionsV3({
@@ -24,6 +126,89 @@ export const toMediaTypeItemV3 = ({ mediaTypeItem, mediaType, context }) => {
     };
     return new OasMediaType(fields);
 };
+/**
+ * Transforms multiple OpenAPI v3 media type objects into internal OAS representations.
+ *
+ * This function processes a complete content map from OpenAPI v3, transforming each
+ * media type entry into its internal OAS representation. It's commonly used to process
+ * the `content` property of request bodies, responses, and parameters that support
+ * multiple media types.
+ *
+ * The function maintains the original media type keys while transforming the values
+ * into structured OAS media type objects. Each transformation is traced for debugging
+ * and error tracking purposes.
+ *
+ * @param args - Transformation arguments
+ * @param args.content - Map of media types to OpenAPI MediaType objects
+ * @param args.context - Parsing context for tracing and error handling
+ * @returns Map of media type strings to processed OAS media type objects
+ *
+ * @example Processing multiple content types
+ * ```typescript
+ * import { toMediaTypeItemsV3 } from '@skmtc/core/oas/mediaType';
+ *
+ * const content = {
+ *   'application/json': {
+ *     schema: {
+ *       type: 'object',
+ *       properties: { message: { type: 'string' } }
+ *     }
+ *   },
+ *   'application/xml': {
+ *     schema: {
+ *       type: 'string'
+ *     }
+ *   },
+ *   'text/plain': {
+ *     schema: {
+ *       type: 'string'
+ *     },
+ *     example: 'Plain text response'
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemsV3({
+ *   content,
+ *   context: parseContext
+ * });
+ *
+ * console.log(Object.keys(result)); // ['application/json', 'application/xml', 'text/plain']
+ * console.log(result['application/json'].mediaType); // 'application/json'
+ * ```
+ *
+ * @example Processing request body content types
+ * ```typescript
+ * const requestBodyContent = {
+ *   'application/json': {
+ *     schema: { $ref: '#/components/schemas/CreateUserRequest' }
+ *   },
+ *   'application/x-www-form-urlencoded': {
+ *     schema: {
+ *       type: 'object',
+ *       properties: {
+ *         name: { type: 'string' },
+ *         email: { type: 'string' }
+ *       }
+ *     },
+ *     encoding: {
+ *       email: {
+ *         style: 'form',
+ *         explode: false
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const processed = toMediaTypeItemsV3({
+ *   content: requestBodyContent,
+ *   context: parseContext
+ * });
+ *
+ * // Each media type is processed with its specific configuration
+ * console.log(processed['application/json'].schema); // Reference object
+ * console.log(processed['application/x-www-form-urlencoded'].encoding); // Form encoding config
+ * ```
+ */
 export const toMediaTypeItemsV3 = ({ content, context }) => {
     return Object.fromEntries(Object.entries(content).map(([mediaType, value]) => [
         mediaType,
@@ -34,6 +219,93 @@ export const toMediaTypeItemsV3 = ({ content, context }) => {
         }))
     ]));
 };
+/**
+ * Optionally transforms OpenAPI v3 media type objects when content is provided.
+ *
+ * This function provides a safe way to process media type content that may or may not
+ * be present in the OpenAPI specification. It handles the common pattern where content
+ * properties are optional in OpenAPI objects (like responses without bodies or
+ * operations without request bodies).
+ *
+ * When content is undefined, the function returns undefined without processing.
+ * When content is provided, it delegates to `toMediaTypeItemsV3` for full processing.
+ *
+ * @param args - Transformation arguments
+ * @param args.content - Optional map of media types to OpenAPI MediaType objects
+ * @param args.context - Parsing context for tracing and error handling
+ * @returns Map of processed media types if content exists, undefined otherwise
+ *
+ * @example Handling optional response content
+ * ```typescript
+ * import { toOptionalMediaTypeItemsV3 } from '@skmtc/core/oas/mediaType';
+ *
+ * // Response with content
+ * const responseWithContent = {
+ *   description: 'Successful response',
+ *   content: {
+ *     'application/json': {
+ *       schema: { type: 'object' }
+ *     }
+ *   }
+ * };
+ *
+ * const withContent = toOptionalMediaTypeItemsV3({
+ *   content: responseWithContent.content,
+ *   context: parseContext
+ * });
+ * console.log(withContent); // { 'application/json': OasMediaType }
+ *
+ * // Response without content (like 204 No Content)
+ * const responseNoContent = {
+ *   description: 'No content response'
+ * };
+ *
+ * const noContent = toOptionalMediaTypeItemsV3({
+ *   content: responseNoContent.content, // undefined
+ *   context: parseContext
+ * });
+ * console.log(noContent); // undefined
+ * ```
+ *
+ * @example Processing operations with optional request bodies
+ * ```typescript
+ * function processOperation(operation: OpenAPIV3.OperationObject) {
+ *   const requestBodyContent = toOptionalMediaTypeItemsV3({
+ *     content: operation.requestBody?.content,
+ *     context: parseContext
+ *   });
+ *
+ *   if (requestBodyContent) {
+ *     console.log('Operation has request body with media types:');
+ *     console.log(Object.keys(requestBodyContent));
+ *   } else {
+ *     console.log('Operation has no request body');
+ *   }
+ * }
+ * ```
+ *
+ * @example Safe processing in response handlers
+ * ```typescript
+ * class ResponseProcessor {
+ *   processResponse(response: OpenAPIV3.ResponseObject) {
+ *     const mediaTypes = toOptionalMediaTypeItemsV3({
+ *       content: response.content,
+ *       context: this.context
+ *     });
+ *
+ *     // Safe to check without worrying about undefined content
+ *     const hasJsonResponse = mediaTypes && 'application/json' in mediaTypes;
+ *
+ *     if (hasJsonResponse) {
+ *       const jsonMediaType = mediaTypes['application/json'];
+ *       return this.generateJsonResponseHandler(jsonMediaType);
+ *     }
+ *
+ *     return this.generateEmptyResponseHandler();
+ *   }
+ * }
+ * ```
+ */
 export const toOptionalMediaTypeItemsV3 = ({ content, context }) => {
     if (!content) {
         return;

package/esm/oas/operation/operation-types.d.ts

@@ -4,19 +4,270 @@ import { type OasParameterRefData, type OasRequestBodyRefData, type OasResponseR
 import { type OasRequestBodyData } from '../requestBody/requestBody-types.js';
 import { type OasResponseData } from '../response/response-types.js';
 import * as v from 'valibot';
+/**
+ * Data type for OpenAPI operation objects processed by the SKMTC pipeline.
+ *
+ * This type represents a complete OpenAPI operation (API endpoint) including all
+ * associated metadata, parameters, request body, responses, and path information.
+ * It serves as the internal representation of OpenAPI operations during the
+ * code generation process, combining operation data with its parent path item context.
+ *
+ * ## Usage in SKMTC Pipeline
+ *
+ * This type is used by:
+ * - Operation parsers to validate and structure incoming OpenAPI operations
+ * - Code generators to access operation metadata and generate client code
+ * - Response processors to understand expected API responses
+ * - Parameter handlers to generate request validation and typing
+ *
+ * @example Basic GET operation
+ * ```typescript
+ * import type { OasOperationData } from '@skmtc/core/oas/operation';
+ *
+ * const getUserOperation: OasOperationData = {
+ *   oasType: 'operation',
+ *   path: '/users/{id}',
+ *   method: 'get',
+ *   operationId: 'getUserById',
+ *   summary: 'Get user by ID',
+ *   description: 'Retrieves a specific user by their unique identifier',
+ *   tags: ['users'],
+ *   parameters: [
+ *     {
+ *       name: 'id',
+ *       in: 'path',
+ *       required: true,
+ *       schema: { type: 'string' }
+ *     }
+ *   ],
+ *   responses: {
+ *     '200': {
+ *       description: 'User found',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     },
+ *     '404': {
+ *       description: 'User not found'
+ *     }
+ *   },
+ *   pathItem: pathItemData
+ * };
+ * ```
+ *
+ * @example POST operation with request body
+ * ```typescript
+ * const createUserOperation: OasOperationData = {
+ *   oasType: 'operation',
+ *   path: '/users',
+ *   method: 'post',
+ *   operationId: 'createUser',
+ *   summary: 'Create new user',
+ *   description: 'Creates a new user account',
+ *   tags: ['users'],
+ *   requestBody: {
+ *     description: 'User data',
+ *     required: true,
+ *     content: {
+ *       'application/json': {
+ *         schema: { $ref: '#/components/schemas/CreateUserRequest' }
+ *       }
+ *     }
+ *   },
+ *   responses: {
+ *     '201': {
+ *       description: 'User created successfully',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     },
+ *     '400': {
+ *       description: 'Invalid request data'
+ *     }
+ *   },
+ *   pathItem: pathItemData
+ * };
+ * ```
+ *
+ * @example Operation with query parameters
+ * ```typescript
+ * const listUsersOperation: OasOperationData = {
+ *   oasType: 'operation',
+ *   path: '/users',
+ *   method: 'get',
+ *   operationId: 'listUsers',
+ *   summary: 'List users',
+ *   description: 'Get paginated list of users',
+ *   tags: ['users'],
+ *   parameters: [
+ *     {
+ *       name: 'page',
+ *       in: 'query',
+ *       schema: { type: 'integer', minimum: 1, default: 1 }
+ *     },
+ *     {
+ *       name: 'limit',
+ *       in: 'query',
+ *       schema: { type: 'integer', minimum: 1, maximum: 100, default: 20 }
+ *     },
+ *     {
+ *       name: 'status',
+ *       in: 'query',
+ *       schema: { type: 'string', enum: ['active', 'inactive'] }
+ *     }
+ *   ],
+ *   responses: {
+ *     '200': {
+ *       description: 'List of users',
+ *       content: {
+ *         'application/json': {
+ *           schema: {
+ *             type: 'object',
+ *             properties: {
+ *               users: {
+ *                 type: 'array',
+ *                 items: { $ref: '#/components/schemas/User' }
+ *               },
+ *               totalCount: { type: 'integer' },
+ *               page: { type: 'integer' },
+ *               limit: { type: 'integer' }
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   pathItem: pathItemData
+ * };
+ * ```
+ */
 export type OasOperationData = {
+    /** Type identifier for SKMTC internal processing */
     oasType: 'operation';
+    /** Parent path item containing this operation */
     pathItem: OasPathItemData;
+    /** The API path template (e.g., '/users/{id}') */
     path: string;
+    /** HTTP method for this operation */
     method: 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+    /** Unique identifier for this operation (used for client method names) */
     operationId?: string;
+    /** Tags for grouping operations (used for code organization) */
     tags?: string[];
+    /** Brief summary of what the operation does */
     summary?: string;
+    /** Detailed description of the operation behavior */
     description?: string;
+    /** List of parameters (path, query, header, cookie) */
     parameters?: (OasParameterData | OasParameterRefData)[];
+    /** Request body specification for operations that accept data */
     requestBody?: OasRequestBodyData | OasRequestBodyRefData;
+    /** Map of status codes to response specifications */
     responses: Record<string, OasResponseData | OasResponseRefData>;
+    /** Whether this operation is deprecated */
     deprecated?: boolean;
 };
+/**
+ * Valibot schema for validating OpenAPI operation data objects.
+ *
+ * This comprehensive schema validates OpenAPI operations according to the OpenAPI v3
+ * specification, including all standard properties like HTTP methods, parameters,
+ * request bodies, responses, and metadata. It uses lazy evaluation and unions to
+ * handle complex nested structures and reference objects.
+ *
+ * The schema ensures that operation data conforms to OpenAPI standards while also
+ * including SKMTC-specific metadata (like `oasType` and `pathItem`) needed for
+ * the code generation pipeline.
+ *
+ * @example Validating a GET operation
+ * ```typescript
+ * import { oasOperationData } from '@skmtc/core/oas/operation';
+ * import * as v from 'valibot';
+ *
+ * const operation = {
+ *   oasType: 'operation',
+ *   path: '/api/users/{id}',
+ *   method: 'get',
+ *   operationId: 'getUserById',
+ *   summary: 'Get user by ID',
+ *   parameters: [
+ *     {
+ *       name: 'id',
+ *       in: 'path',
+ *       required: true,
+ *       schema: { type: 'string' }
+ *     }
+ *   ],
+ *   responses: {
+ *     '200': {
+ *       description: 'Success',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   pathItem: validPathItem
+ * };
+ *
+ * const validated = v.parse(oasOperationData, operation);
+ * console.log(validated.operationId); // 'getUserById'
+ * ```
+ *
+ * @example Validating a POST operation with request body
+ * ```typescript
+ * const postOperation = {
+ *   oasType: 'operation',
+ *   path: '/api/users',
+ *   method: 'post',
+ *   operationId: 'createUser',
+ *   requestBody: {
+ *     description: 'User data',
+ *     required: true,
+ *     content: {
+ *       'application/json': {
+ *         schema: { $ref: '#/components/schemas/CreateUserRequest' }
+ *       }
+ *     }
+ *   },
+ *   responses: {
+ *     '201': {
+ *       description: 'User created',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   pathItem: validPathItem
+ * };
+ *
+ * const validated = v.parse(oasOperationData, postOperation);
+ * console.log(validated.method); // 'post'
+ * ```
+ *
+ * @example Validation error handling
+ * ```typescript
+ * const invalidOperation = {
+ *   oasType: 'operation',
+ *   path: '/api/users',
+ *   method: 'invalid', // Invalid HTTP method
+ *   responses: {} // Missing required responses
+ * };
+ *
+ * try {
+ *   v.parse(oasOperationData, invalidOperation);
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message);
+ *   // Handle validation errors
+ * }
+ * ```
+ */
 export declare const oasOperationData: v.GenericSchema<OasOperationData>;
 //# sourceMappingURL=operation-types.d.ts.map

package/esm/oas/operation/operation-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation-types.d.ts","sourceRoot":"","sources":["../../../src/oas/operation/operation-types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,iCAAiC,CAAA;AACzF,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,+BAA+B,CAAA;AACrF,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EAIxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,KAAK,kBAAkB,EAAsB,MAAM,qCAAqC,CAAA;AACjG,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,+BAA+B,CAAA;AACrF,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,WAAW,CAAA;IACpB,QAAQ,EAAE,eAAe,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;IAClF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IAGpB,UAAU,CAAC,EAAE,CAAC,gBAAgB,GAAG,mBAAmB,CAAC,EAAE,CAAA;IACvD,WAAW,CAAC,EAAE,kBAAkB,GAAG,qBAAqB,CAAA;IACxD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,kBAAkB,CAAC,CAAA;IAE/D,UAAU,CAAC,EAAE,OAAO,CAAA;CAGrB,CAAA;AAED,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,aAAa,CAAC,gBAAgB,CA2B7D,CAAA"}
+{"version":3,"file":"operation-types.d.ts","sourceRoot":"","sources":["../../../src/oas/operation/operation-types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,iCAAiC,CAAA;AACzF,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,+BAA+B,CAAA;AACrF,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EAIxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,KAAK,kBAAkB,EAAsB,MAAM,qCAAqC,CAAA;AACjG,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,+BAA+B,CAAA;AACrF,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4IG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oDAAoD;IACpD,OAAO,EAAE,WAAW,CAAA;IACpB,iDAAiD;IACjD,QAAQ,EAAE,eAAe,CAAA;IACzB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,qCAAqC;IACrC,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;IAClF,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;IAGpB,uDAAuD;IACvD,UAAU,CAAC,EAAE,CAAC,gBAAgB,GAAG,mBAAmB,CAAC,EAAE,CAAA;IACvD,iEAAiE;IACjE,WAAW,CAAC,EAAE,kBAAkB,GAAG,qBAAqB,CAAA;IACxD,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,kBAAkB,CAAC,CAAA;IAE/D,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAA;CAGrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,aAAa,CAAC,gBAAgB,CA2B7D,CAAA"}

package/esm/oas/operation/operation-types.js

@@ -5,6 +5,104 @@ import { oasParameterRefData, oasRequestBodyRefData, oasResponseRefData } from '
 import { oasRequestBodyData } from '../requestBody/requestBody-types.js';
 import { oasResponseData } from '../response/response-types.js';
 import * as v from 'valibot';
+/**
+ * Valibot schema for validating OpenAPI operation data objects.
+ *
+ * This comprehensive schema validates OpenAPI operations according to the OpenAPI v3
+ * specification, including all standard properties like HTTP methods, parameters,
+ * request bodies, responses, and metadata. It uses lazy evaluation and unions to
+ * handle complex nested structures and reference objects.
+ *
+ * The schema ensures that operation data conforms to OpenAPI standards while also
+ * including SKMTC-specific metadata (like `oasType` and `pathItem`) needed for
+ * the code generation pipeline.
+ *
+ * @example Validating a GET operation
+ * ```typescript
+ * import { oasOperationData } from '@skmtc/core/oas/operation';
+ * import * as v from 'valibot';
+ *
+ * const operation = {
+ *   oasType: 'operation',
+ *   path: '/api/users/{id}',
+ *   method: 'get',
+ *   operationId: 'getUserById',
+ *   summary: 'Get user by ID',
+ *   parameters: [
+ *     {
+ *       name: 'id',
+ *       in: 'path',
+ *       required: true,
+ *       schema: { type: 'string' }
+ *     }
+ *   ],
+ *   responses: {
+ *     '200': {
+ *       description: 'Success',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   pathItem: validPathItem
+ * };
+ *
+ * const validated = v.parse(oasOperationData, operation);
+ * console.log(validated.operationId); // 'getUserById'
+ * ```
+ *
+ * @example Validating a POST operation with request body
+ * ```typescript
+ * const postOperation = {
+ *   oasType: 'operation',
+ *   path: '/api/users',
+ *   method: 'post',
+ *   operationId: 'createUser',
+ *   requestBody: {
+ *     description: 'User data',
+ *     required: true,
+ *     content: {
+ *       'application/json': {
+ *         schema: { $ref: '#/components/schemas/CreateUserRequest' }
+ *       }
+ *     }
+ *   },
+ *   responses: {
+ *     '201': {
+ *       description: 'User created',
+ *       content: {
+ *         'application/json': {
+ *           schema: { $ref: '#/components/schemas/User' }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   pathItem: validPathItem
+ * };
+ *
+ * const validated = v.parse(oasOperationData, postOperation);
+ * console.log(validated.method); // 'post'
+ * ```
+ *
+ * @example Validation error handling
+ * ```typescript
+ * const invalidOperation = {
+ *   oasType: 'operation',
+ *   path: '/api/users',
+ *   method: 'invalid', // Invalid HTTP method
+ *   responses: {} // Missing required responses
+ * };
+ *
+ * try {
+ *   v.parse(oasOperationData, invalidOperation);
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message);
+ *   // Handle validation errors
+ * }
+ * ```
+ */
 export const oasOperationData = v.object({
     oasType: v.literal('operation'),
     pathItem: oasPathItemData,