Metaschema Java Tools and Libraries

This open-source, Metaschema Java framework offers a set of Java libraries providing a programmatic means to work with models defined by the Metaschema modeling language. This framework also supports programmatically creating, modifying, parsing, and writing XML, JSON, and YAML instance data that conforms to a given Metaschema model. This work is intended to make it easier for Java software developers to incorporate Metaschema-based capabilities into their applications.

The Metaschema Java framework provides:

• Java objects for loading and working with XML-based Metaschema constructs. This functionality is provided by the Metaschema XML model.
• Java bean code generation based on one or more Metaschema using Maven. This functionality is provided by the Metaschema Maven plugin.
• A Java parser for reading and writing XML, JSON, or YAML into Java beans generated by this framework. This functionality is provided by the Metaschema Java Binding Parser.
• XML and JSON schema generation based on a Metaschema provided by Netaschema Schema Generator.

Public domain

See the project license in this repository.

This project is in the worldwide public domain and as stated in CONTRIBUTING.md.

Contributing to this code base

Thank you for interest in contributing to the Metaschema Java framework. For complete instructions on how to contribute code, please read through our CONTRIBUTING.md documentation.

Using as a Maven dependency

This project's modules are published to Maven Central.

You can include these artifacts in your Maven POM as a dependency.

Building

This project can be built with Apache Maven version 3.9.0 or greater.

The following instructions can be used to clone and build this project.

1. Clone the GitHub repository.

git clone --recurse-submodules https://github.com/metaschema-framework/metaschema-java.git 

2. Build the project with Maven

mvn install

Installing the CLI tool

The maintainers provide developers of Metaschema-enabled tools a CLI tool from this repository to dynamically validate Metaschema models themselves, content based on developer-provided models, and format conversion for models and content between supported data formats (e.g. JSON, XML, and YAML). There are multiple ways to install this CLI tool.

1. Build the project locally with Maven.
2. Download a developer snapshot from the Metaschema Framework repository for pre-release builds.
3. Download the official releases from the official Maven Central.
4. Download an OCI-conformant container image from the GitHub Container Registry (ghcr.io) for use with docker, podman, Kubernetes, or other container orchestration platforms.

Build the project locally with Maven

To build the project locally, follow the instructions above that explain how to build and install project packages, including the CLI, with Maven (mvn).

Download pre-built snapshot release

To download, unzip, and install a pre-built snapshot release (a developer build that is not an official release), please visit the GitHub metaschema-framework/maven2 repository to download a .bz2, .gz, or .zip archive.

# Visit https://github.com/metaschema-framework/maven2/commits/main/dev/metaschema/java/metaschema-cli
# Adjust the value for CURRENT_SNAPSHOT_PATH for most recently committed artifact by folder and file name.
export CURRENT_SNAPSHOT_PATH="3.0.0.M1-SNAPSHOT/metaschema-cli-3.0.0.M1-20251213.151427-29-metaschema-cli.zip"
# Download the zip archive to /tmp
cd /tmp
curl -L -O "https://github.com/metaschema-framework/maven2/raw/refs/heads/main/dev/metaschema/java/metaschema-cli/${CURRENT_SNAPSHOT_PATH}"
# Extract zip archive to /opt/metaschema-cli
# You might need sudo for permission to write files to this path
sudo unzip /tmp/metaschema-cli-*-metaschema-cli.zip -d /opt/metaschema-cli
# Now add this installation directory to the path
export PATH="${PATH}:/opt/metaschema-cli"
# Run the CLI to test it is properly installed
metaschema-cli --version

Download a pre-built official release from Maven Central

You can also use Maven to download a pre-built official release from Maven Central using the Maven (mvn) CLI tool, unzipping the archive, and then adding that directory to your path.

# Download the zip archive of the latest release to /tmp
mvn \
    org.apache.maven.plugins:maven-dependency-plugin:LATEST:copy  \
    -DoutputDirectory=/tmp \
    -DremoteRepositories=https://repo1.maven.org/maven2 \
    -Dartifact=dev.metaschema.java:metaschema-cli:LATEST:zip:metaschema-cli
# Extract zip archive to /opt/metaschema-cli
# You might need sudo for permission to write files to this path
sudo unzip "/tmp/*metaschema-cli.zip" -d /opt/metaschema-cli
# Now add this installation directory to the path
export PATH="${PATH}:/opt/metaschema-cli"
# Run the CLI to test it is properly installed
metaschema-cli --version

Download container image

You can also download pre-release and official release versions of the CLI as an OCI-conformant image with docker, podman, or other tools.

docker pull ghcr.io/metaschema-framework/metaschema-cli:latest
docker run -it ghcr.io/metaschema-framework/metaschema-cli:latest --version

CLI Usage Notes

Disabling Color Output

The CLI uses ANSI escape codes for colored output, which is supported by most modern terminals including Windows 10+, Linux, and macOS. If you are using a legacy console that does not support ANSI escape codes (e.g., older Windows cmd.exe, certain CI/CD environments, or when redirecting output to a file), you may see raw escape sequences in the output.

To disable colored output, use the --no-color flag:

metaschema-cli --no-color <command>

Shell Completion

The CLI supports tab completion for Bash and Zsh shells, providing intelligent suggestions for commands, subcommands, and options.

Bash:

# Generate and source completion (temporary, current session only)
source <(metaschema-cli shell-completion bash)

# Or save to a file and source it in your ~/.bashrc for persistence
metaschema-cli shell-completion bash > ~/.metaschema-completion.bash
echo 'source ~/.metaschema-completion.bash' >> ~/.bashrc

Zsh:

# Ensure your completions directory exists
mkdir -p ~/.zsh/completions

# Generate completion script
metaschema-cli shell-completion zsh > ~/.zsh/completions/_metaschema-cli

# Add to your ~/.zshrc if not already configured
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

After setting up completion, restart your shell or source the configuration file.

Relationship to prior work

The contents of this repository is based on work from the Metaschema Java repository maintained by the National Institute of Standards and Technology (NIST), the contents of which have been dedicated in the worldwide public domain using the CC0 1.0 Universal public domain dedication. This repository builds on this prior work, maintaining the CCO license on any new works in this repository.

This library is maintained to be feature compatible with the features in the NIST v1.0.0-M1 release. As a result, Metaschema-based content produced for either will work with this library. Bugs have been fixed in cases where bugs have been identified in the NIST version and when confirmed to have been present in this library. This has been noted in related issues in the NIST repository.