OSCAL Java Library

A Java library for processing OSCAL (Open Security Controls Assessment Language) content. This library enables Java developers to create, read, validate, and transform OSCAL documents.

OSCAL is a set of standardized formats developed by NIST for expressing security controls, control baselines, system security plans, assessment plans and results, and plans of action and milestones. Organizations use OSCAL to:

• Document security controls - Express control catalogs (like NIST SP 800-53) in a machine-readable format
• Define control baselines - Create profiles that select and customize controls for specific use cases
• Create system security plans - Document how systems implement required controls
• Automate security assessments - Define assessment procedures and capture results in structured formats
• Track remediation - Manage plans of action and milestones (POA&Ms) for security findings

OSCAL supports XML, JSON, and YAML representations of all document types, with equivalent semantics across all formats. This means you can choose the format that best fits your toolchain while maintaining full compatibility with other OSCAL-compliant tools.

This library provides a complete Java solution for working with OSCAL content:

• Type-safe access - Work with strongly-typed Java objects rather than parsing XML or JSON directly. The compiler catches errors that would otherwise appear at runtime.

• Format flexibility - Read OSCAL from any supported format (XML, JSON, YAML) and write to any format. Convert between formats without losing data.

• Profile resolution - Resolve OSCAL profiles to produce flattened catalogs that include all selected controls with modifications applied.

• Validation - Validate OSCAL documents against the official schemas and constraint rules to ensure well-formed, valid content.

• Built on Metaschema - Leverages the Metaschema Java framework, ensuring the Java model stays synchronized with the official OSCAL specification.

Add the dependency to your Maven project:

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

Load and work with an OSCAL catalog:

import dev.metaschema.oscal.lib.OscalBindingContext;
import dev.metaschema.oscal.lib.model.Catalog;
import java.nio.file.Path;

// Get the binding context
OscalBindingContext context = OscalBindingContext.instance();

// Load a catalog using the convenience method
Catalog catalog = context.loadCatalog(Path.of("catalog.json"));

// Access content
System.out.println("Catalog: " + catalog.getMetadata().getTitle());

See the Installation guide for complete setup instructions.

Read and write OSCAL documents in XML, JSON, and YAML formats. The library automatically detects input format and handles all serialization details. Convert between formats with a simple API call—no manual transformation required.

OSCAL profiles allow organizations to customize control catalogs by selecting controls, modifying parameter values, and adding organization-specific guidance. Profile resolution produces a “resolved catalog” that flattens all selections and modifications into a single catalog document. This library implements the complete profile resolution algorithm as specified in the OSCAL specification.

Validate OSCAL documents at multiple levels:

• Well-formedness - Ensure documents are valid XML, JSON, or YAML
• Schema compliance - Verify documents conform to the OSCAL schema structure
• Constraint validation - (Experimental) Check documents against Metaschema constraint rules that express business logic beyond schema requirements

Build OSCAL documents programmatically using Java builder patterns. Create catalogs, profiles, system security plans, and other OSCAL documents entirely in code, then serialize to any supported format.

This library supports all OSCAL model types. Each document type has a corresponding Java class in the dev.metaschema.oscal.lib.model package:

This library is built on the Metaschema Java Tools project. OSCAL model classes are generated from the OSCAL Metaschema definitions during the build process.

See the Architecture guide for details on the library structure.

This library is part of a larger ecosystem of OSCAL and Metaschema 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
• Contributing - Contribution guidelines