Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions.

2.0/xml.ts

@@ -0,0 +1,142 @@
+import type { Extension } from "./extensions";
+
+/**
+ * -----
+ * XML Object
+ * -----
+ *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms)
+ * and the name property should be used to add that information.
+ *
+ * The XML Object provides additional metadata to describe the XML representation
+ * format of schema properties. It allows for precise control over how JSON
+ * schema definitions are translated to XML, including element naming, namespaces,
+ * attributes, and array wrapping.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#xml-object | Swagger 2.0 XML Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @property `name` - Replaces the name of the element/attribute used for the described schema property.
+ * @property `namespace` - The URL of the namespace definition. Value SHOULD be in the form of a URL.
+ * @property `prefix` - The prefix to be used for the name.
+ * @property `attribute` - Declares whether the property definition translates to an attribute instead of an element. Default value is false.
+ * @property `wrapped` - MAY be used only for an array definition. Signifies whether the array is wrapped. Default value is false.
+ *
+ * @note
+ * All fields are optional. The `wrapped` property only takes effect when defined
+ * alongside `type` being `array` (outside the items). When `wrapped` is true,
+ * arrays are wrapped in a container element.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic XML element):
+ * ```ts
+ * const basicXml: XMLObject = {
+ *   name: "animal"
+ * };
+ * ```
+ *
+ * @example (XML attribute):
+ * ```ts
+ * const attributeXml: XMLObject = {
+ *   name: "id",
+ *   attribute: true
+ * };
+ * ```
+ *
+ * @example (namespaced XML):
+ * ```ts
+ * const namespacedXml: XMLObject = {
+ *   name: "name",
+ *   namespace: "http://swagger.io/schema/sample",
+ *   prefix: "sample"
+ * };
+ * ```
+ *
+ * @example (wrapped array):
+ * ```ts
+ * const wrappedArrayXml: XMLObject = {
+ *   name: "animals",
+ *   wrapped: true
+ * };
+ * ```
+ *
+ * @example (array items with custom name):
+ * ```ts
+ * const arrayItemsXml: XMLObject = {
+ *   name: "animal"
+ * };
+ * ```
+ *
+ * @example (complete XML definition):
+ * ```ts
+ * const completeXml: XMLObject = {
+ *   name: "person",
+ *   namespace: "http://example.com/schema",
+ *   prefix: "ex",
+ *   attribute: false,
+ *   wrapped: false
+ * };
+ * ```
+ */
+export interface XMLObject extends Extension {
+	/**
+	 * Replaces the name of the element/attribute used for the described schema property.
+	 * When defined within the Items Object, it will affect the name of the individual
+	 * XML elements within the list. When defined alongside type being array (outside
+	 * the items), it will affect the wrapping element and only if wrapped is true.
+	 *
+	 * @example "animal"
+	 * @example "item"
+	 * @example "person"
+	 */
+	name?: string;
+
+	/**
+	 * The URL of the namespace definition. Value SHOULD be in the form of a URL.
+	 *
+	 * @example "http://example.com/schema/sample"
+	 * @example "http://www.w3.org/2001/XMLSchema"
+	 * @example "http://swagger.io/schema/sample"
+	 */
+	namespace?: string;
+
+	/**
+	 * The prefix to be used for the name.
+	 *
+	 * @example "sample"
+	 * @example "xs"
+	 * @example "ex"
+	 */
+	prefix?: string;
+
+	/**
+	 * Declares whether the property definition translates to an attribute instead of an element.
+	 * Default value is false.
+	 *
+	 * @default false
+	 * @example true
+	 * @example false
+	 */
+	attribute?: boolean;
+
+	/**
+	 * MAY be used only for an array definition. Signifies whether the array is wrapped
+	 * (for example, <books><book/><book/></books>) or unwrapped (<book/><book/>).
+	 * Default value is false. The definition takes effect only when defined alongside
+	 * type being array (outside the items).
+	 *
+	 * @default false
+	 * @example true
+	 * @example false
+	 */
+	wrapped?: boolean;
+}