Crate xsd_parser

Source
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! ๐Ÿ˜Š

Crates.io License Crates.io Version Crates.io Total Downloads docs.rs Github CI Dependency Status

ยง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.

overview

ยงPipeline Stages

  1. Parsing: The parsing stage is handled by the Parser type. It loads XML schemas from files or URLs and uses pluggable Resolvers to fetch and preprocess schema definitions. The result is captured in a Schemas model, which stores namespaces, prefixes, and the raw schema structure needed for further processing.

  2. Interpreting:: Interpreting is carried out by the Interpreter. This stage analyzes the schema definitions stored in the Schemas model and converts them into normalized, abstract type descriptions. The resulting MetaTypes model encapsulates schema semantics such as complex types, enumerations, references, and groups in a language-agnostic form.

  3. Optimizing: Optimization is performed by the Optimizer, which takes the MetaTypes 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.

  4. Generating: The generation step uses the Generator to transform the abstract types into Rust-specific type data. It produces the DataTypes 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.

  5. Rendering: Rendering is handled by the Renderer, which converts DataTypes into structured Rust code organized in a Module. It uses the RenderStep trait to define individual rendering steps. Several built-in steps are available, including support for serde or quick-xml. Users can also add custom RenderStep implementations to extend or modify the output.

ยงData Models

  • Schemas: This model is built by the Parser 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 the Interpreter, 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 the Generator, 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 the Renderer. 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 using serde with serde_xml or quick_xml as serializer/deserializer.
  • quick_xml Support: Direct serialization/deserialization support using quick_xml, avoiding serde 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 accompanying DataType 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 of serde-based implementations, such as serde-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 and xs: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 and BigUint Schemas defining integer types without upper bounds can now be mapped to num::BigInt or num::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 the generate 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 the quick_xml crate.
xml
The xml module contains different types to store unstructured XML data. This is useful to represents xs:any and xs:anyAttribute information from the XML schema.

Structsยง

MetaTypesPrinter
Pretty-printer for MetaTypes content.

Enumsยง

Error
Error emitted by the generate function.

Traitsยง

AsAny
Trait that is used to get the Any trait for a specific type.
VecHelper
Helper trait that implements additional methods for vectors.
WithIdent
Helper trait that adds name information to the implementing object.
WithNamespace
Trait that adds namespace information to a type.

Functionsยง

exec_generator
Executes the Generator with the passed config, schema and types to generate a DataTypes for further processing.
exec_interpreter
Executes the Interpreter with the passed config and schema.
exec_optimizer
Executes the Optimizer with the passed config and types.
exec_parser
Executes the Parser with the passed config.
exec_render
Executes the rendering process using the passed config and the types created by the Generator.
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ยง

GeneratorError
Type alias for pipeline::generator::Error.
InterpreterError
Type alias for pipeline::interpreter::Error.
ParserError
Type alias for pipeline::parser::Error.
RendererError
Type alias for pipeline::renderer::Error.