feat: add xsd support (#2350)

Author: jonaslagoni

.gitignore

@@ -12,3 +12,6 @@ java_runtime_node
 .netlify
 .metals
 .scala-build
+
+.cursorrules
+.cursor

README.md

@@ -204,6 +204,10 @@ The following table provides a short summary of available features for supported
     <td><a href="./docs/usage.md#generate-models-from-openapi-documents">OpenAPI</a></td>
     <td>We support the following OpenAPI versions: <em><a href="./docs/usage.md#generate-models-from-swagger-20-documents">Swagger 2.0</a>, <a href="./docs/usage.md#generate-models-from-openapi-documents">OpenAPI 3.0 and 3.1</a></em>, which generates models for all the defined request and response payloads.</td>
   </tr>
+  <tr>
+    <td><a href="./examples/xsd-to-typescript">XSD (XML Schema Definition)</a></td>
+    <td>We support XML Schema Definition (XSD) with common elements including simple types, complex types, sequences, choices, attributes, and enumerations.</td>
+  </tr>
   <tr>
     <td><a href="./docs/usage.md#generate-model-from-typescript-type-files">TypeScript</a></td>
     <td>We currently support TypeScript types as file input for model generation</td>

docs/inputs/XSD.md

@@ -0,0 +1,86 @@
+# Interpretation of XSD to MetaModel
+
+The library transforms XSD (XML Schema Definition) from XML data validation schemas to data model representations ([`MetaModel`](../internal-model.md)s). 
+
+The algorithm processes the XSD document structure to create models that represent the data types defined in the schema, including complex types, simple types, elements, attributes, and their relationships.
+
+## Overview
+
+XSD input processing follows this flow:
+1. **XML Parsing**: The XSD string is parsed into a JavaScript object using `fast-xml-parser`
+2. **XSD Schema Model**: The parsed XML is converted to a structured `XsdSchema` model
+3. **MetaModel Conversion**: The XSD types are mapped to Modelina's internal `MetaModel` representation
+4. **Model Generation**: The MetaModels are processed by generators to create output code
+
+## Supported XSD Features
+
+### Simple Types
+- **Enumerations**: `xs:restriction` with `xs:enumeration` values → enum models
+- **Restrictions**: Patterns, length constraints, and numeric ranges (constraint information preserved in original input)
+
+### Complex Types
+- **Sequences**: `xs:sequence` elements → object properties in defined order
+- **Choices**: `xs:choice` elements → optional object properties
+- **Attributes**: Converted to object properties alongside elements
+  - `use="required"` → required properties
+  - `use="optional"` → optional properties
+
+### Advanced Features
+- **Complex Content (Inheritance)**: `xs:complexContent` with `xs:extension`
+  - Currently: Properties from base type are merged into extending type
+  - Note: Full inheritance support may be added in future versions
+- **Simple Content**: Text content plus attributes → object with `value` property
+- **Arrays**: `maxOccurs="unbounded"` or `maxOccurs` > 1 → array properties
+- **Optional Elements**: `minOccurs="0"` → non-required properties
+- **Wildcards**: `xs:any` elements → mapped to `any` type
+  - Supports `minOccurs` and `maxOccurs` for cardinality
+  - Generated as properties with names like `additionalProperty`, `additionalProperty1`, etc.
+
+## Type Mappings
+
+The following table shows how XSD built-in types are mapped to Modelina's internal types:
+
+| XSD Type | Mapped Type | Notes |
+|----------|-------------|-------|
+| `xs:string`, `xs:token`, `xs:normalizedString` | string | General text types |
+| `xs:int`, `xs:integer`, `xs:long`, `xs:short`, `xs:byte` | integer | Integer numeric types |
+| `xs:unsignedLong`, `xs:unsignedInt`, `xs:unsignedShort`, `xs:unsignedByte` | integer | Unsigned integer types |
+| `xs:positiveInteger`, `xs:negativeInteger`, `xs:nonPositiveInteger`, `xs:nonNegativeInteger` | integer | Constrained integer types |
+| `xs:float`, `xs:double`, `xs:decimal` | float | Floating-point numeric types |
+| `xs:boolean` | boolean | Boolean type |
+| `xs:date`, `xs:time`, `xs:dateTime`, `xs:duration` | string | Date/time types (represented as strings) |
+| `xs:gYear`, `xs:gMonth`, `xs:gDay` | string | Partial date types |
+| `xs:anyURI`, `xs:QName` | string | URI and qualified name types |
+| `xs:base64Binary`, `xs:hexBinary` | string | Binary data types (represented as strings) |
+| Complex types | object | Converted to object models with properties |
+| Simple types with enumerations | enum | Converted to enum models |
+
+## Namespace Handling
+
+XSD namespaces are handled in a simplified manner:
+- `targetNamespace` is extracted but not actively used
+- Both `xs:` and `xsd:` prefixes are supported
+- Custom namespace prefixes (e.g., `tns:BookType`) are stripped and resolved by name only
+
+## Limitations
+
+### Partial Support
+- **Element References**: `ref` attribute has basic support
+- **Union/List**: `xs:union` and `xs:list` have basic implementations
+- **Inheritance**: Properties are merged rather than creating true inheritance
+
+### Not Supported
+- `xs:group` and `xs:attributeGroup` (named groups)
+- `xs:unique`, `xs:key`, `xs:keyref` (constraints)
+- `xs:notation` and `xs:redefine`
+- Full `xs:restriction` on complex types
+- `substitutionGroup` (element substitution)
+- Full namespace handling and validation
+- Constraint enforcement in generated models (patterns, lengths, ranges)
+
+## Examples
+
+See the [XSD to TypeScript example](../../examples/xsd-to-typescript/) for a complete working demonstration of XSD input processing.
+
+For general usage information, see the [usage documentation](../usage.md#generate-models-from-xsd-documents).
+

docs/integration.md

@@ -53,9 +53,6 @@ Do NOT enable users to write their own option callbacks. This includes but not l
 
 To be on the safeside, only enable the user to chose between the internal options and presets, as you can see the [playground does](https://www.asyncapi.com/tools/modelina).
 
-## Integrate Modelina in an AsyncAPI generator template
-TODO
-
 ## Integrate Modelina into Maven
 
 There are at least two ways you can integrate Modelina into your build process for Maven projects, either with the AsyncAPI CLI or with a custom build script. Which one to choose all depends on your scenario, look below:

docs/languages/Rust.md

@@ -39,19 +39,3 @@ To generate a `new` method, use the preset `RUST_COMMON_PRESET` and provide the
 ## Implement `Default` for enums
 
 To generate `Default` implementation for enums that provide a default value, use the preset `RUST_COMMON_PRESET` and provide the option `implementDefault: true`.
-
-## Implement `From<String>` (serde_json)
-
-TODO
-
-## Implement `Into<String>` (serde_json)
-
-TODO
-
-## Implement `From<FramedByteStream>` (tokio_serde)
-
-TODO
-
-## Implement `From<FramedByteStream>` (tokio_serde)
-
-TOOD

docs/usage.md

@@ -24,6 +24,7 @@ For more specific integration options, please check out the [integration documen
     + [Limitations and Compatibility](#limitations-and-compatibility-2)
       - [Polymorphism](#polymorphism-2)
 - [Generate models from TypeScript type files](#generate-models-from-typescript-type-files)
+- [Generate models from XSD documents](#generate-models-from-xsd-documents)
 - [Generate models from Meta models](#generate-models-from-meta-models)
 - [Generate Go models](#generate-go-models)
 - [Generate C# models](#generate-c%23-models)
@@ -166,6 +167,16 @@ Currently, we support generating models from a TypeScript type file.
 
 The TypeScript input processor expects that the typescript file and base directory where it's present, is passed as input, in order to process the types accurately. The input processor converts the TypeScript types into JSON Schema, which are then passed on to the [JSON Schema processor](#generate-models-from-json-schema-documents). 
 
+## Generate models from XSD documents
+
+XSD (XML Schema Definition) is fully supported as an input format. This enables Modelina to work with XML-based schemas commonly used in enterprise and legacy systems.
+
+- [Generate TypeScript models from XSD](../examples/xsd-to-typescript/)
+
+The XSD input processor automatically detects XSD schemas by looking for schema indicators (`xs:schema` or `xsd:schema`).
+
+For a detailed explanation of how XSD is interpreted, see the [XSD input processing documentation](./inputs/XSD.md).
+
 ## Generate models from Meta models
 Sometimes, the supported inputs such as AsyncAPI and JSON Schema wont be enough for your use-case and you want to create your own data models while still utilizing the full sweep of features from the generators.
 

examples/README.md

@@ -53,6 +53,7 @@ These examples show a specific input and how they can be used:
 - [openapi-from-object](./openapi-from-object) - A basic example where an OpenAPI v3.0 JS object is used to generate models.
 - [openapi-include-components](./openapi-include-components) - A basic example where an OpenAPI document without paths is used to generate models by iterating the components.
 - [openapi-v3_1-from-object](./openapi-v3_1-from-object) - A basic example where an OpenAPI v3.1 JS object is used to generate models.
+- [xsd-to-typescript](./xsd-to-typescript) - A basic example showing how to generate TypeScript models from XSD (XML Schema Definition).
 - [meta-model](./meta-model) - A basic example how to provide a meta model for the generator
 
 ## General examples

examples/csharp-generate-records/README.md

@@ -1,6 +1,5 @@
-# TODO: Your example title
-
-TODO: Your example description
+# C# generate records
+Simple example showing how to generate C# records
 
 ## How to run this example
 

examples/java-from-typescript-type-with-options/README.md

@@ -1,4 +1,4 @@
-# TODO: Generate Java model from a TypeScript Types file using processor options
+# Generate Java model from a TypeScript Types file using processor options
 
 This is a basic example of generating Java models using a Typescript type file as input and processor options. This can be extended to generating Go, C# and other supported language models.
 

examples/xsd-to-typescript/README.md

@@ -0,0 +1,17 @@
+# Generate TypeScript models from XSD
+
+This example shows you how to generate TypeScript models from an XSD (XML Schema Definition) file.
+
+## How to run this example
+
+Run this example using:
+
+```sh
+npm i && npm run start
+```
+
+If you are on Windows, use the `start:windows` script instead:
+
+```sh
+npm i && npm run start:windows
+```