Ballerina XSD Tool

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.

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

1. 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.

2. 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.

1. To build the library:

    ./gradlew clean build
   

2. To run the integration tests:

    ./gradlew clean test
   

3. To build the module without the tests:

    ./gradlew clean build -x test
   

4. To publish to maven local:

    ./gradlew clean build publishToMavenLocal
   

5. Publish the generated artifacts to the local Ballerina central repository:

    ./gradlew clean build -PpublishToLocalCentral=true
   

6. 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.