Expand description
A comprehensive library for parsing XML schemas and generating code based on them.
This project originated as a fork of xsd-parser-rs
but has since evolved into a complete rewrite.
If you enjoy the project and would like to support my work, you can buy me a coffee or send a tip via PayPal. Thanks a lot! ๐
ยงOverview
This library is built around a staged transformation pipeline that converts XML schemas into Rust source code. Each stage handles a specific level of abstraction and produces a well-defined intermediate representation. This makes the library highly flexible, testable, and suitable for advanced customization or tooling.
ยงPipeline Stages
-
Parsing: The parsing stage is handled by the
Parser
type. It loads XML schemas from files or URLs and uses pluggableResolver
s to fetch and preprocess schema definitions. The result is captured in aSchemas
model, which stores namespaces, prefixes, and the raw schema structure needed for further processing. -
Interpreting:: Interpreting is carried out by the
Interpreter
. This stage analyzes the schema definitions stored in theSchemas
model and converts them into normalized, abstract type descriptions. The resultingMetaTypes
model encapsulates schema semantics such as complex types, enumerations, references, and groups in a language-agnostic form. -
Optimizing: Optimization is performed by the
Optimizer
, which takes theMetaTypes
and applies structural transformations. These include deduplication, simplification of unions, merging cardinalities, and resolving typedef aliases. The goal is to prepare the type graph for idiomatic translation into Rust while reducing complexity. -
Generating: The generation step uses the
Generator
to transform the abstract types into Rust-specific type data. It produces theDataTypes
model by attaching names, Rust derivations, trait support, and rendering metadata. These enriched types form the basis for later rendering while still preserving schema semantics. -
Rendering: Rendering is handled by the
Renderer
, which convertsDataTypes
into structured Rust code organized in aModule
. It uses theRenderStep
trait to define individual rendering steps. Several built-in steps are available, including support forserde
orquick-xml
. Users can also add customRenderStep
implementations to extend or modify the output.
ยงData Models
-
Schemas
: This model is built by theParser
and contains the raw XML schema data, including namespaces, prefixes, and schema file content. It serves as the foundation for interpretation and supports multiple sources and resolver types. -
MetaTypes
: Generated by theInterpreter
, this model contains language-neutral type definitions. It includes data like complex types, references, enumerations, and groupings derived from schema structure. It is suitable for introspection, transformation, and optimization. -
DataTypes
: Produced by theGenerator
, this model holds enriched Rust-specific type data. Each type includes metadata for layout, naming, derivations, and other traits required for rendering idiomatic Rust code. This is the core input for the rendering process. -
Module
: The final model is produced by theRenderer
. It wraps the Rust source code output into a structured format, ready for file output or consumption as token streams. Modules support nested submodules, file splitting, and embedded metadata for customization.
ยงFeatures
This library provides the following features:
- Rust Code Generation: Convert any XML schema into Rust code.
- Layered Architecture: Add user-defined code to manipulate type information or generated code.
- User-Defined Types: Inject existing types into the generated code to reuse predefined structures.
serde
Support: Generate code for serialization and deserialization usingserde
withserde_xml
orquick_xml
as serializer/deserializer.quick_xml
Support: Direct serialization/deserialization support usingquick_xml
, avoidingserde
limitations and leveraging asynchronous features.
ยงChangelog
Below you can find a short list of the most important changes for each released version.
ยงVersion 1.2
This release introduces a series of architectural improvements, enhanced flexibility in code generation, and broader schema compatibility.
-
Refactored Pipeline Structure The internal code generation pipeline has been refactored to introduce a new
Renderer
step and an accompanyingDataType
model. This separation gives users more control over the rendering process, allows better extension points for customization, and prepares the architecture for further growth. -
Refactored Serde Support Support for
serde
has been moved into dedicated renderer steps. This makes it possible to support multiple versions ofserde
-based implementations, such asserde-xml-rs
0.7 and 0.8, without mixing code. Each renderer step now cleanly encapsulates the logic for one serialization backend. -
Implement Support for Unstructured Data Added support for
xs:any
andxs:anyAttribute
by introducing an internal representation for unstructured XML data. This enables working with flexible or unknown schema elements and fixes a long-standing gap in schema coverage. -
Implement Support for
BigInt
andBigUint
Schemas defining integer types without upper bounds can now be mapped tonum::BigInt
ornum::BigUint
, depending on context. This is useful when working with large numeric values. -
Improved Documentation Support XSD annotations (
xs:documentation
) are now parsed and included as Rust doc comments in the generated code, improving type-level visibility and usability. -
Different Bug Fixes and Improvements
- Enum restrictions on text types are now correctly interpreted and rendered
- Complex types in the XML Catalog schema are now rendered correctly
- Introduced per-type
derive
settings for advanced customization - Various naming, escaping, and formatting issues were resolved across the pipeline.
- Generated names of nested elements now uses the name of the parent element as prefix to prevent name collisions.
ยงVersion 1.1
- Implemented feature to generated boxed
quick_xml
deserializers to reduce stack usage during deserialization - Improved naming of the generated types
- Implemented feature to split generated code into multiple module files
- Improved and implemented advanced examples
- General bug fixes and improvements
ยงVersion 1.0
- First official release of
xsd-parser
ยงPlanned Features
- Schema-Based Validation: Generate validators directly from schemas to validate XML data during reading or writing.
ยงLicense
This crate is licensed under the MIT License.
Re-exportsยง
pub use self::config::Config;
pub use self::models::code::Module;
pub use self::models::code::SubModules;
pub use self::models::data::DataTypes;
pub use self::models::meta::MetaTypes;
pub use self::models::schema::Schemas;
pub use self::models::Ident;
pub use self::models::IdentType;
pub use self::models::Name;
pub use self::pipeline::generator::Generator;
pub use self::pipeline::interpreter::Interpreter;
pub use self::pipeline::optimizer::Optimizer;
pub use self::pipeline::parser::Parser;
pub use self::pipeline::renderer::DefaultsRenderStep;
pub use self::pipeline::renderer::NamespaceConstantsRenderStep;
pub use self::pipeline::renderer::QuickXmlDeserializeRenderStep;
pub use self::pipeline::renderer::QuickXmlSerializeRenderStep;
pub use self::pipeline::renderer::Renderer;
pub use self::pipeline::renderer::SerdeQuickXmlTypesRenderStep;
pub use self::pipeline::renderer::SerdeXmlRsV7TypesRenderStep;
pub use self::pipeline::renderer::SerdeXmlRsV8TypesRenderStep;
pub use self::pipeline::renderer::TypesRenderStep;
pub use self::pipeline::renderer::WithNamespaceTraitRenderStep;
Modulesยง
- config
- Contains the
Config
structures for thegenerate
method. - models
- Data model definitions used throughout the transformation pipeline.
- pipeline
- Transformation pipeline for processing schema definitions into Rust code.
- quick_
xml - The
quick_xml
module contains helper types for serializing and deserializing generated code using thequick_xml
crate. - xml
- The
xml
module contains different types to store unstructured XML data. This is useful to representsxs:any
andxs:anyAttribute
information from the XML schema.
Structsยง
- Meta
Types Printer - Pretty-printer for
MetaTypes
content.
Enumsยง
Traitsยง
- AsAny
- Trait that is used to get the
Any
trait for a specific type. - VecHelper
- Helper trait that implements additional methods for vectors.
- With
Ident - Helper trait that adds name information to the implementing object.
- With
Namespace - Trait that adds namespace information to a type.
Functionsยง
- exec_
generator - Executes the
Generator
with the passedconfig
,schema
andtypes
to generate aDataTypes
for further processing. - exec_
interpreter - Executes the
Interpreter
with the passedconfig
andschema
. - exec_
optimizer - Executes the
Optimizer
with the passedconfig
andtypes
. - exec_
parser - Executes the
Parser
with the passedconfig
. - exec_
render - Executes the rendering process using the passed
config
and thetypes
created by theGenerator
. - generate
- Generates rust code from a XML schema using the passed
config
. - generate_
modules - Generates rust code split into different modules from a XML schema using the
passed
config
.
Type Aliasesยง
- Generator
Error - Type alias for
pipeline::generator::Error
. - Interpreter
Error - Type alias for
pipeline::interpreter::Error
. - Parser
Error - Type alias for
pipeline::parser::Error
. - Renderer
Error - Type alias for
pipeline::renderer::Error
.