Ballerina XSD Tool

February 2, 2026 · View on GitHub

XSD (XML Schema Definition) is an approach to define the structure, elements, and constraints of XML documents. It is widely used for validating the content and structure of XML files.

The Ballerina XSD Tool simplifies the generation of Ballerina record types from an XSD specification, improving the user experience when integrating with XML-based operations in Ballerina.

Supported XSD Features

The tool supports the following XSD elements and constructs:

Feature	Description	Ballerina Mapping
`xs:element`	Element definitions	Record fields
`xs:complexType`	Complex type definitions	Ballerina records
`xs:simpleType`	Simple type definitions	Type aliases
`xs:sequence`	Ordered element groups	Sequence records with `@xmldata:Sequence`
`xs:choice`	Choice element groups	Choice records with `@xmldata:Choice`
`xs:all`	Unordered element groups	Records with all fields
`xs:attribute`	Attributes	Fields with `@xmldata:Attribute`
`xs:attributeGroup`	Reusable attribute groups	Expanded inline as attributes
`xs:extension`	Type extensions	Record extension
`xs:restriction`	Type restrictions	Constrained types
`xs:enumeration`	Enumeration values	Ballerina enums
`xs:any`	Wildcard elements	`@xmldata:Any`-annotated field of type `anydata` or union of known element/complex-type records
`xs:include`	Schema includes	Multi-file processing

Installation

Execute the command below to pull the XSD tool from Ballerina Central.

$ bal tool pull xsd

Usage

The XSD tool allows you to generate Ballerina record types from an XSD specification.

To generate Ballerina types, use the following command. It is mandatory to run the command inside a Ballerina project.

$ bal xsd <xsd-file-path> 
          [--module <output-module-name>]

Command options

Option	Description	Mandatory/Optional
`<xsd-file-path>`	(Required) The path to the XSD file	Mandatory
`-m`, `--module`	The name of the module in which the Ballerina record types are generated	Optional

Generate types for the given XSD file

Use the following command to generate Ballerina record types for all elements defined in the specified XSD file. By default, the generated types.bal file will be placed in the default module of the current Ballerina project.

$ bal xsd <source-file-path>

For example,

$ bal xsd sample.xsd

If successful, you will see the following output.

The 'types.bal' file is written to the default module

Generate types in a specific module

To generate the Ballerina record types in a specific module, use the --module option.

$ bal xsd <source-file-path> --module <output-module-name>

For example,

$ bal xsd sample.xsd --module custom

This will generate a types.bal file inside the custom submodule within the Ballerina project.

The following output will be displayed.

The 'types.bal' file is written to 'modules/custom'

Upon successful execution, the generated files will include,

modules/
└── custom/
        └── types.bal

Building from the Source

Setting Up the Prerequisites

OpenJDK 21 (Adopt OpenJDK or any other OpenJDK distribution)

Info: You can also use Oracle JDK. Set the JAVA_HOME environment variable to the pathname of the directory into which you installed JDK.
Export GitHub Personal access token with read package permissions as follows,
```
export packageUser=<Username>
export packagePAT=<Personal access token>
```

Building the Source

Execute the commands below to build from the source.

To build the library:
```
 ./gradlew clean build
```
To run the integration tests:
```
 ./gradlew clean test
```
To build the module without the tests:
```
 ./gradlew clean build -x test
```

To publish to maven local:

 ./gradlew clean build publishToMavenLocal

Publish the generated artifacts to the local Ballerina central repository:
```
 ./gradlew clean build -PpublishToLocalCentral=true
```
Publish the generated artifacts to the Ballerina central repository:
```
 ./gradlew clean build -PpublishToCentral=true
```

Contributing to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

You can also check for open issues that interest you. We look forward to receiving your contributions.

For more information, go to the contribution guidelines.

Code of Conduct

All contributors are encouraged to read the Ballerina Code of Conduct.

Useful Links

Chat live with us via our Discord server.
Post all technical questions on Stack Overflow with the #ballerina tag.
View the Ballerina performance test results.