Metaschema Java Tools

This project provides a Java implementation of the Metaschema framework, a modeling language designed to enable format-agnostic information modeling and processing.

Metaschema addresses a fundamental challenge in data exchange: organizations often need to work with data in multiple formats (XML, JSON, YAML) while maintaining consistent validation and semantics across all formats. Rather than defining separate schemas for each format, Metaschema allows you to define your data model once and automatically generate:

• Format-specific schemas (XML Schema, JSON Schema) for validation
• Type-safe data bindings (Java classes) for programmatic access
• Documentation that stays synchronized with the model

The Metaschema framework originated from NIST as the foundation for the OSCAL (Open Security Controls Assessment Language) project, but its approach to information modeling is applicable to any domain requiring multi-format data exchange.

This library is designed for Java developers who need to:

• Process OSCAL content - If you're working with OSCAL documents, this library (via liboscal-java) provides the foundation for reading, writing, and validating OSCAL in any format.

• Define custom data models - If your organization needs a format-agnostic data model with consistent validation across XML, JSON, and YAML, Metaschema provides a robust framework for defining and implementing that model.

• Generate code from models - The Maven plugin generates type-safe Java classes from Metaschema definitions, eliminating boilerplate serialization code and ensuring your Java objects always match your data model.

• Query and validate data - Metapath, the XPath-like query language included in this library, provides powerful capabilities for querying and validating data regardless of its original format.

Add the dependency to your Maven project:

<dependency>
    <groupId>dev.metaschema.java</groupId>
    <artifactId>metaschema-databind</artifactId>
    <version>3.0.0.M2</version>
</dependency>

Once you have the dependency, you can read and write data:

import dev.metaschema.databind.IBindingContext;
import dev.metaschema.databind.io.Format;
import dev.metaschema.databind.io.IDeserializer;
import dev.metaschema.databind.io.ISerializer;
import java.nio.file.Path;

// Get the binding context for your generated model class
IBindingContext context = IBindingContext.instance();

// Read data from JSON (substitute MyModel with your generated class)
IDeserializer<MyModel> deserializer = context.newDeserializer(Format.JSON, MyModel.class);
MyModel data = deserializer.deserialize(Path.of("input.json"));

// Write data to XML
ISerializer<MyModel> serializer = context.newSerializer(Format.XML, MyModel.class);
serializer.serialize(data, Path.of("output.xml"));

To generate Java classes from your own Metaschema module, configure the Maven plugin:

<plugin>
    <groupId>dev.metaschema.java</groupId>
    <artifactId>metaschema-maven-plugin</artifactId>
    <version>3.0.0.M2</version>
    <executions>
        <execution>
            <goals>
                <goal>generate-sources</goal>
            </goals>
        </execution>
    </executions>
</plugin>

See the Installation and Generating Java Classes guides for complete setup instructions.

Generate type-safe Java classes directly from Metaschema module definitions. The generated classes handle serialization and deserialization for XML, JSON, and YAML formats automatically. This means you write your business logic against Java objects while the library handles all format-specific details.

The metaschema-maven-plugin integrates code generation into your Maven build lifecycle. Define your Metaschema modules, configure the plugin, and generated source code appears in target/generated-sources/ ready for compilation. Changes to your Metaschema automatically regenerate the Java classes on the next build.

Metaschema supports rich constraint definitions that validate data beyond basic schema requirements. Constraints can express business rules, cross-field dependencies, and complex conditions using Metapath expressions. These constraints are defined once in the Metaschema and enforced consistently regardless of whether your data is in XML, JSON, or YAML.

Metapath is an XPath-like expression language designed for querying Metaschema-based data. Unlike XPath which is specific to XML, Metapath works identically across all supported formats. Use Metapath to extract data, define constraints, and navigate complex document structures.

This framework is part of a larger ecosystem of Metaschema and OSCAL tools:

This project includes plugins for Claude Code that provide AI-assisted development. See the Claude Integration guide for details.

Have questions or found an issue? Here's how to get help:

• GitHub Issues - Report bugs or request features
• GitHub Discussions - Ask questions and discuss ideas
• Contributing - Contribution guidelines