feat: Add extension fields (x-*) support to IR types and parsers

Co-authored-by: mrlubos <[e-mail]>

packages/openapi-ts/src/ir/types.d.ts

···
 }
 
 export interface IROperationObject {
+  /**
+   * OpenAPI extension fields (x-*) from the original operation.
+   * These are custom fields that can be used by plugins.
+   */
+  [extension: `x-${string}`]: unknown;
   body?: IRBodyObject;
   deprecated?: boolean;
   description?: string;
···
   parameters?: IRParametersObject;
   path: keyof IRPathsObject;
   responses?: IRResponsesObject;
-  security?: ReadonlyArray<IRSecurityObject>;
   servers?: ReadonlyArray<IRServerObject>;
   summary?: string;
   tags?: ReadonlyArray<string>;
+  security?: ReadonlyArray<IRSecurityObject>;
 }
 
 interface IRParametersObject {
···
 
 interface IRParameterObject
   extends Pick<JsonSchemaDraft2020_12, 'deprecated' | 'description'> {
+  /**
+   * OpenAPI extension fields (x-*) from the original parameter.
+   * These are custom fields that can be used by plugins.
+   */
+  [extension: `x-${string}`]: unknown;
   /**
    * Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of `contentType` (implicit or explicit) SHALL be ignored.
    */
···
     | 'title'
     | 'example'
   > {
+  /**
+   * OpenAPI extension fields (x-*) from the original schema.
+   * These are custom fields that can be used by plugins.
+   */
+  [extension: `x-${string}`]: unknown;
   /**
    * If the schema is intended to be used as an object property, it can be
    * marked as read-only or write-only. This value controls whether the schema

packages/openapi-ts/src/openApi/2.0.x/parser/operation.ts

···
     operation,
   });
 
+  // Copy extension fields
+  for (const key in operation) {
+    if (key.startsWith('x-')) {
+      (irOperation as unknown as Record<string, unknown>)[key] =
+        operation[key as keyof Operation];
+    }
+  }
+
   return irOperation;
 };
 

packages/openapi-ts/src/openApi/2.0.x/parser/parameter.ts

···
     irParameter.required = parameter.required;
   }
 
+  // Copy extension fields
+  for (const key in parameter) {
+    if (key.startsWith('x-')) {
+      (irParameter as unknown as Record<string, unknown>)[key] =
+        parameter[key as keyof ParameterObject];
+    }
+  }
+
   return irParameter;
 };

packages/openapi-ts/src/openApi/2.0.x/parser/schema.ts

···
   return irSchema;
 };
 
+const parseExtensions = ({
+  irSchema,
+  schema,
+}: {
+  irSchema: IR.SchemaObject;
+  schema: SchemaObject;
+}) => {
+  // Copy all x-* extension fields from the source schema to the IR schema
+  for (const key in schema) {
+    if (key.startsWith('x-')) {
+      (irSchema as unknown as Record<string, unknown>)[key] =
+        schema[key as keyof SchemaObject];
+    }
+  }
+};
+
 const initIrSchema = ({
   schema,
 }: {
···
   const irSchema: IR.SchemaObject = {};
 
   parseSchemaJsDoc({
+    irSchema,
+    schema,
+  });
+
+  parseExtensions({
     irSchema,
     schema,
   });

packages/openapi-ts/src/openApi/3.0.x/parser/operation.ts

···
     operation,
   });
 
+  // Copy extension fields
+  for (const key in operation) {
+    if (key.startsWith('x-')) {
+      (irOperation as unknown as Record<string, unknown>)[key] =
+        operation[key as keyof Operation];
+    }
+  }
+
   return irOperation;
 };
 

packages/openapi-ts/src/openApi/3.0.x/parser/parameter.ts

···
     irParameter.required = parameter.required;
   }
 
+  // Copy extension fields
+  for (const key in parameter) {
+    if (key.startsWith('x-')) {
+      (irParameter as unknown as Record<string, unknown>)[key] =
+        parameter[key as keyof ParameterObject];
+    }
+  }
+
   return irParameter;
 };
 

packages/openapi-ts/src/openApi/3.0.x/parser/schema.ts

···
   return irSchema;
 };
 
+const parseExtensions = ({
+  irSchema,
+  schema,
+}: {
+  irSchema: IR.SchemaObject;
+  schema: SchemaObject;
+}) => {
+  // Copy all x-* extension fields from the source schema to the IR schema
+  for (const key in schema) {
+    if (key.startsWith('x-')) {
+      (irSchema as unknown as Record<string, unknown>)[key] =
+        schema[key as keyof SchemaObject];
+    }
+  }
+};
+
 const initIrSchema = ({
   schema,
 }: {
···
   const irSchema: IR.SchemaObject = {};
 
   parseSchemaJsDoc({
+    irSchema,
+    schema,
+  });
+
+  parseExtensions({
     irSchema,
     schema,
   });

packages/openapi-ts/src/openApi/3.0.x/types/spec.d.ts

···
  */
 export interface OperationObject {
   /**
+   * OpenAPI extension fields (x-*) from the original operation.
+   * Specification Extensions may be used to add additional metadata.
+   */
+  [extension: `x-${string}`]: unknown;
+  /**
    * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#callback-object Callback Object} that describes a request that may be initiated by the API provider and the expected responses.
    */
   callbacks?: Record<string, CallbackObject | ReferenceObject>;
···
    */
   security?: ReadonlyArray<SecurityRequirementObject>;
   /**
-   * An alternative `servers` array to service this operation. If a `servers` array is specified at the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-item-servers Path Item Object} or {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#oas-servers OpenAPI Object} level, it will be overridden by this value.
-   */
-  servers?: ReadonlyArray<ServerObject>;
-  /**
    * A short summary of what the operation does.
    */
   summary?: string;
···
    * A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
    */
   tags?: ReadonlyArray<string>;
+  /**
+   * An alternative `servers` array to service this operation. If a `servers` array is specified at the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-item-servers Path Item Object} or {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#oas-servers OpenAPI Object} level, it will be overridden by this value.
+   */
+  servers?: ReadonlyArray<ServerObject>;
 }
 
 /**
···
  */
 export interface ParameterObject {
   /**
+   * OpenAPI extension fields (x-*) from the original parameter.
+   * Specification Extensions may be used to add additional metadata.
+   */
+  [extension: `x-${string}`]: unknown;
+  /**
    * If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-style `style`} is used, and if {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#style-examples behavior is _n/a_ (cannot be serialized)}, the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#schema-object Schema Object} are implementation-defined. This field is valid only for `query` parameters. Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision.
    */
   allowEmptyValue?: boolean;
···
    * **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.
    */
   in: 'cookie' | 'header' | 'path' | 'query';
-  /**
-   * **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.
-   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in `in`} is `"path"`, the `name` field MUST correspond to a template expression occurring within the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#paths-path path} field in the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#paths-object Paths Object}. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-templating Path Templating} for further information.
-   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in `in`} is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
-   * - For all other cases, the `name` corresponds to the parameter name used by the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in `in`} field.
-   */
-  name: string;
   /**
    * Determines whether this parameter is mandatory. If the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in parameter location} is `"path"`, this field is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is `false`.
    */
···
     | 'pipeDelimited'
     | 'simple'
     | 'spaceDelimited';
+  /**
+   * **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.
+   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in `in`} is `"path"`, the `name` field MUST correspond to a template expression occurring within the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#paths-path path} field in the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#paths-object Paths Object}. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-templating Path Templating} for further information.
+   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in `in`} is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
+   * - For all other cases, the `name` corresponds to the parameter name used by the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-in `in`} field.
+   */
+  name: string;
 }
 
 /**
···
  */
 export interface SchemaObject extends EnumExtensions {
   /**
+   * OpenAPI extension fields (x-*) from the original schema.
+   * Specification Extensions may be used to add additional metadata.
+   */
+  [extension: `x-${string}`]: unknown;
+  /**
    * The value of "additionalProperties" MUST be a boolean or a schema.
    *
    * If "additionalProperties" is absent, it may be considered present with an empty schema as a value.
···
    * A free-form field to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
    */
   example?: unknown;
-  /**
-   * The value of "exclusiveMaximum" MUST be a boolean, representing whether the limit in "maximum" is exclusive or not.  An undefined value is the same as false.
-   *
-   * If "exclusiveMaximum" is true, then a numeric instance SHOULD NOT be equal to the value specified in "maximum".  If "exclusiveMaximum" is false (or not specified), then a numeric instance MAY be equal to the value of "maximum".
-   */
-  exclusiveMaximum?: boolean;
   /**
    * The value of "exclusiveMinimum" MUST be a boolean, representing whether the limit in "minimum" is exclusive or not.  An undefined value is the same as false.
    *
···
    * This MAY be used only on property schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property.
    */
   xml?: XMLObject;
+  /**
+   * The value of "exclusiveMaximum" MUST be a boolean, representing whether the limit in "maximum" is exclusive or not.  An undefined value is the same as false.
+   *
+   * If "exclusiveMaximum" is true, then a numeric instance SHOULD NOT be equal to the value specified in "maximum".  If "exclusiveMaximum" is false (or not specified), then a numeric instance MAY be equal to the value of "maximum".
+   */
+  exclusiveMaximum?: boolean;
 }
 
 /**

packages/openapi-ts/src/openApi/3.1.x/parser/operation.ts

···
     operation,
   });
 
+  // Copy extension fields
+  for (const key in operation) {
+    if (key.startsWith('x-')) {
+      (irOperation as unknown as Record<string, unknown>)[key] =
+        operation[key as keyof Operation];
+    }
+  }
+
   return irOperation;
 };
 

packages/openapi-ts/src/openApi/3.1.x/parser/parameter.ts

···
     irParameter.required = parameter.required;
   }
 
+  // Copy extension fields
+  for (const key in parameter) {
+    if (key.startsWith('x-')) {
+      (irParameter as unknown as Record<string, unknown>)[key] =
+        parameter[key as keyof ParameterObject];
+    }
+  }
+
   return irParameter;
 };
 

packages/openapi-ts/src/openApi/3.1.x/parser/schema.ts

···
   return irSchema;
 };
 
+const parseExtensions = ({
+  irSchema,
+  schema,
+}: {
+  irSchema: IR.SchemaObject;
+  schema: SchemaObject;
+}) => {
+  // Copy all x-* extension fields from the source schema to the IR schema
+  for (const key in schema) {
+    if (key.startsWith('x-')) {
+      (irSchema as unknown as Record<string, unknown>)[key] =
+        schema[key as keyof SchemaObject];
+    }
+  }
+};
+
 const initIrSchema = ({
   schema,
 }: {
···
   const irSchema: IR.SchemaObject = {};
 
   parseSchemaJsDoc({
+    irSchema,
+    schema,
+  });
+
+  parseExtensions({
     irSchema,
     schema,
   });

packages/openapi-ts/src/openApi/3.1.x/types/json-schema-draft-2020-12.d.ts

···
     EnumExtensions,
     OpenApiSchemaExtensions {
   /**
+   * OpenAPI extension fields (x-*) from the original schema.
+   * Specification Extensions may be used to add additional metadata.
+   */
+  [extension: `x-${string}`]: unknown;
+  /**
    * The `$comment` {@link https://json-schema.org/learn/glossary#keyword keyword} is strictly intended for adding comments to a schema. Its value must always be a string. Unlike the annotations `title`, `description`, and `examples`, JSON schema {@link https://json-schema.org/learn/glossary#implementation implementations} aren't allowed to attach any meaning or behavior to it whatsoever, and may even strip them at any time. Therefore, they are useful for leaving notes to future editors of a JSON schema, but should not be used to communicate to users of the schema.
    */
   $comment?: string;
···
    * The `dependentRequired` {@link https://json-schema.org/learn/glossary#keyword keyword} conditionally requires that certain properties must be present if a given property is present in an object. For example, suppose we have a {@link https://json-schema.org/learn/glossary#schema schema} representing a customer. If you have their credit card number, you also want to ensure you have a billing address. If you don't have their credit card number, a billing address would not be required. We represent this dependency of one property on another using the `dependentRequired` keyword. The value of the `dependentRequired` keyword is an object. Each entry in the object maps from the name of a property, _p_, to an array of strings listing properties that are required if _p_ is present.
    */
   dependentRequired?: Record<string, ReadonlyArray<string>>;
-  /**
-   * The `dependentSchemas` keyword conditionally applies a {@link https://json-schema.org/learn/glossary#subschema subschema} when a given property is present. This schema is applied in the same way {@link https://json-schema.org/understanding-json-schema/reference/combining#allof allOf} applies schemas. Nothing is merged or extended. Both schemas apply independently.
-   */
-  dependentSchemas?: Record<string, JsonSchemaDraft2020_12>;
   /**
    * The `deprecated` keyword is a boolean that indicates that the {@link https://json-schema.org/learn/glossary#instance instance} value the keyword applies to should not be used and may be removed in the future.
    */
···
    * The boolean keywords `readOnly` and `writeOnly` are typically used in an API context. `readOnly` indicates that a value should not be modified. It could be used to indicate that a `PUT` request that changes a value would result in a `400 Bad Request` response. `writeOnly` indicates that a value may be set, but will remain hidden. In could be used to indicate you can set a value with a `PUT` request, but it would not be included when retrieving that record with a `GET` request.
    */
   writeOnly?: boolean;
+  /**
+   * The `dependentSchemas` keyword conditionally applies a {@link https://json-schema.org/learn/glossary#subschema subschema} when a given property is present. This schema is applied in the same way {@link https://json-schema.org/understanding-json-schema/reference/combining#allof allOf} applies schemas. Nothing is merged or extended. Both schemas apply independently.
+   */
+  dependentSchemas?: Record<string, JsonSchemaDraft2020_12>;
 }
 
 interface ArrayKeywords {

packages/openapi-ts/src/openApi/3.1.x/types/spec.d.ts

···
  */
 export interface OperationObject {
   /**
+   * OpenAPI extension fields (x-*) from the original operation.
+   * Specification Extensions may be used to add additional metadata.
+   */
+  [extension: `x-${string}`]: unknown;
+  /**
    * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object Callback Object} that describes a request that may be initiated by the API provider and the expected responses.
    */
   callbacks?: Record<string, CallbackObject | ReferenceObject>;
···
    */
   security?: ReadonlyArray<SecurityRequirementObject>;
   /**
-   * An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
-   */
-  servers?: ReadonlyArray<ServerObject>;
-  /**
    * A short summary of what the operation does.
    */
   summary?: string;
···
    * A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
    */
   tags?: ReadonlyArray<string>;
+  /**
+   * An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
+   */
+  servers?: ReadonlyArray<ServerObject>;
 }
 
 /**
···
  */
 export interface ParameterObject {
   /**
+   * OpenAPI extension fields (x-*) from the original parameter.
+   * Specification Extensions may be used to add additional metadata.
+   */
+  [extension: `x-${string}`]: unknown;
+  /**
    * Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle `style`} is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
    */
   allowEmptyValue?: boolean;
···
    */
   in: 'cookie' | 'header' | 'path' | 'query';
   /**
-   * **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.
-   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn `in`} is `"path"`, the `name` field MUST correspond to a template expression occurring within the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath path} field in the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#paths-object Paths Object}. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating Path Templating} for further information.
-   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn `in`} is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
-   * - For all other cases, the `name` corresponds to the parameter name used by the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn `in`} property.
-   */
-  name: string;
-  /**
    * Determines whether this parameter is mandatory. If the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn parameter location} is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
    */
   required?: boolean;
···
     | 'pipeDelimited'
     | 'simple'
     | 'spaceDelimited';
+  /**
+   * **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.
+   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn `in`} is `"path"`, the `name` field MUST correspond to a template expression occurring within the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath path} field in the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#paths-object Paths Object}. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating Path Templating} for further information.
+   * - If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn `in`} is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
+   * - For all other cases, the `name` corresponds to the parameter name used by the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn `in`} property.
+   */
+  name: string;
 }
 
 /**