liboscal-java

A Java library to support processing OSCAL content.

This open-source, Metaschema Java library offers a programatic means to work with OSCAL models defined by the Metaschema modeling language. This framework also supports programatically creating, modifying, parsing, and writing XML, JSON, and YAML OSCAL instance data. This work is intended to make it easier for Java software developers to incorporate OSCAL-based capabilities into their applications.

The following features are supported by this library:

• Reading and writing OSCAL documents in XML, JSON, and YAML formats into a common Java object model.
• Resolution of OSCAL profiles to produce resolved catalogs.
• Validation of OSCAL content well-formedness and validation of OSCAL syntax using XML and JSON schemas.
• (Experimental) Validation of OSCAL content using Metaschema constraints to enforce allowed values, cross-references, and some conditionally required data elements.
• Builders for programmatically creating common OSCAL data elements.

This library is based on the Metaschema Java Tools project.

This effort is part of the National Institute of Standards and Technology (NIST) OSCAL Program.

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.

Public domain

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

Using as a Maven dependency

This project's modules are published to Maven Central. We recommend you use the latest stable release on the Maven Central repository. You may also download development snapshots to evaluate new features or bug fixes merged into develop before they are finalized in a published release.

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

We digitally sign these releases with the NIST OSCAL Team's Release Engineering Key.

Building

This project can be built with Apache Maven version 3.8.4 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/usnistgov/liboscal-java.git 

2. Build the project with Maven

mvn install

Using

The following is a simple example of how to load and write OSCAL content using this API.

// Initialize the Metaschema framework
OscalBindingContext bindingContext = OscalBindingContext.instance(); // manages the Metaschema model
IBoundLoader loader = bindingContext.newBoundLoader(); // supports loading OSCAL documents

// load an OSCAL catalog
Catalog catalog = loader.load(Paths.get("src/test/resources/content/test-catalog.xml")); // load the catalog

// Create a serializer which can be used to write multiple catalogs
ISerializer<Catalog> serializer = bindingContext.newSerializer(Format.YAML, Catalog.class);

// create the output directory
Path outDir = Paths.get("target/generated-test-resources");
Files.createDirectories(outDir);

// serialize the catalog as yaml
serializer.serialize(catalog, outDir.resolve("test-catalog.yaml"));

The full code for this example is also available.

Contact us

Maintainer: David Waltermire - @david-waltermire-nist, NIST Information Technology Labratory, Computer Security Division, Security Components and Mechanisms Group

Email us: oscal@nist.gov

Chat with us: Gitter usnistgov-OSCAL/Lobby