Fork me on GitHub
Built by Maven

Installation

This guide explains how to add OSCAL Java Library to your Java project.

This library provides everything you need to work with OSCAL documents in Java. Adding this single dependency gives you:

  • Pre-generated Java model classes for all OSCAL document types
  • Serialization support for XML, JSON, and YAML formats
  • Profile resolution capabilities
  • Validation tools
  • The underlying Metaschema Java framework

Before installing, ensure your development environment meets these requirements:

Requirement Minimum Version Recommended
Java JDK 11 17 or later
Maven 3.9.0 Latest
Gradle 7.0 Latest

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.oscal</groupId>
    <artifactId>liboscal-java</artifactId>
    <version>7.0.0</version>
</dependency>

Release versions are available from Maven Central.

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

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

<repositories>
    <repository>
        <id>sonatype-snapshots</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>dev.metaschema.oscal</groupId>
        <artifactId>liboscal-java</artifactId>
        <version>7.0.0</version>
    </dependency>
</dependencies>

Gradle users can add the library using either Kotlin DSL or Groovy DSL syntax.

Add to your build.gradle.kts:

dependencies {
    implementation("dev.metaschema.oscal:liboscal-java:7.0.0")
}

For snapshot versions, add the repository:

repositories {
    mavenCentral()
    maven {
        url = uri("https://oss.sonatype.org/content/repositories/snapshots/")
    }
}

Add to your build.gradle:

dependencies {
    implementation 'dev.metaschema.oscal:liboscal-java:7.0.0'
}

For snapshot versions, add the repository:

repositories {
    mavenCentral()
    maven {
        url 'https://oss.sonatype.org/content/repositories/snapshots/'
    }
}

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:

After adding the dependency, verify the installation by loading a sample OSCAL document:

import dev.metaschema.oscal.lib.OscalBindingContext;
import dev.metaschema.oscal.lib.model.Catalog;
import dev.metaschema.databind.io.Format;
import dev.metaschema.databind.io.IDeserializer;
import java.net.URI;

public class VerifyInstallation {
    public static void main(String[] args) throws Exception {
        OscalBindingContext context = OscalBindingContext.instance();

        // Load the NIST SP 800-53 catalog from the official OSCAL content repository
        URI catalogUri = URI.create(
            "https://raw.githubusercontent.com/usnistgov/oscal-content/main/" +
            "nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json");

        IDeserializer<Catalog> deserializer = context.newDeserializer(
            Format.JSON, Catalog.class);
        Catalog catalog = deserializer.deserialize(catalogUri);

        System.out.println("Successfully loaded: " + catalog.getMetadata().getTitle());
        System.out.println("Number of groups: " + catalog.getGroups().size());
    }
}

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

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