Installation

This guide explains how to add the Metaschema Java libraries to your project.

The Metaschema Java project consists of several modules that serve different purposes. Most projects will only need one or two:

For most use cases, metaschema-databind provides everything you need. It includes the core Metaschema functionality plus the data binding layer for serialization. If you're specifically working with OSCAL content, liboscal-java bundles this library with pre-built OSCAL model classes.

Before adding the library to your project, ensure your development environment meets these requirements:

The library targets Java 11 for broad compatibility, but building from source requires Java 17. See Building from Source if you need to compile the library yourself.

Stable releases are published to Maven Central and require no additional repository configuration. Add the following dependency to your pom.xml:

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

Replace LATEST_VERSION with the current release from Maven Central.

Snapshot versions contain the latest changes from the develop branch, including new features and bug fixes that haven't yet been released. These are useful for testing upcoming changes or accessing features before they're officially released, but they may be less stable than release versions.

To use snapshots, add the project's snapshot repository:

<repositories>
    <repository>
        <id>metaschema-snapshots</id>
        <url>https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

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

Gradle users can add the library using either Kotlin DSL or Groovy DSL syntax. The examples below show metaschema-databind, but you can substitute any module from the choosing the right module section.

Add to your build.gradle.kts:

dependencies {
    implementation("dev.metaschema.java:metaschema-databind:LATEST_VERSION")
}

For snapshot versions, add the repository:

repositories {
    mavenCentral()
    maven {
        url = uri("https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main")
    }
}

Add to your build.gradle:

dependencies {
    implementation 'dev.metaschema.java:metaschema-databind:LATEST_VERSION'
}

For snapshot versions:

repositories {
    mavenCentral()
    maven {
        url 'https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main'
    }
}

If you need to build the library from source—for example, to contribute changes, debug issues, or access unreleased features—see the Building guide. Building from source requires Java 17 or later.

Modern Java IDEs automatically recognize Maven and Gradle projects, downloading dependencies and configuring the classpath. After adding the dependency to your build file:

1. IntelliJ IDEA: Open the project folder or pom.xml/build.gradle file. IntelliJ will import the project and download dependencies automatically.

2. Eclipse: Import as a Maven or Gradle project using the built-in import wizard. The M2Eclipse plugin handles Maven projects.

3. VS Code: Install the Extension Pack for Java, then open the project folder. VS Code will detect the build system and configure accordingly.

For more detailed IDE setup, refer to your IDE's documentation:

• IntelliJ IDEA - Maven Projects
• Eclipse - Maven Integration
• VS Code - Java Extension Pack

After adding the dependency, verify the installation by creating a simple test class:

import dev.metaschema.core.metapath.MetapathExpression;

public class VerifyInstallation {
    public static void main(String[] args) {
        MetapathExpression expr = MetapathExpression.compile("1 + 1");
        System.out.println("Metaschema installed successfully!");
        System.out.println("Metapath result: " + expr.evaluateAs(null,
            MetapathExpression.ResultType.NUMBER));
    }
}

If this compiles and runs without errors, the library is correctly installed.

Once installed, explore these guides to start using the library:

• Architecture - Understand the module structure and how components interact
• Loading Modules - Load and work with Metaschema definitions
• Generating Java Classes - Use the Maven plugin to generate code
• Reading & Writing Data - Serialize and deserialize data in multiple formats