File: README — Documentation by YARD 0.9.38

Purpose

This Ruby gem implements a parser and generator for the NIST Metaschema Information Modeling Framework.

Metaschema is a specification for defining information models in a structured format (currently via XML). It provides a way to define and manage information model schemas that can be converted into XML and JSON Schemas.

This library can be used to parse and generate information schemas defined in the Metaschema XML format.

This library can also be used to generate XML schemas and JSON Schemas from Metaschema XML files.

Note	The Metaschema gem is a work in progress and may not yet support all features of the Metaschema specification.

Note	The Metaschema gem will support the generation of data accessors for Metaschema-defined information models in the future.

Features

Parse, build and round-trip Metaschema XML files
Validate Metaschema XML files against the Metaschema XML Schema
Generate XML (XSD) and JSON Schemas from Metaschema XML files
Generate Lutaml::Model::Serializable Ruby classes from Metaschema XML definitions, with full XML and JSON round-trip fidelity
Validate Metaschema-defined information models against the Metaschema XML Schema
Support for SINGLETON_OR_ARRAY field patterns via service object pipeline (FieldSerializer / FieldDeserializer)
UNWRAPPED XML field handling with delegate mappings

Installation

To install the metaschema gem, use one of the following methods.

Add this line to your application’s Gemfile:

gem 'metaschema'

Then execute:

$ bundle install

Or install it directly using:

$ gem install metaschema

After installation, you can start using the metaschema gem in your Ruby projects or via the command-line interface.

Ruby API

require 'metaschema'

# Load a Metaschema file
# Sample at spec/fixtures/metaschema/examples/computer-example.xml
ms = Metaschema::Root.from_file("computer-example.xml")

ms.to_xml
# <METASCHEMA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
#  xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/metaschema/1.0 ../schema/xml/metaschema.xsd"
#  xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0">
#     <schema-name>Computer Model</schema-name>
#     <schema-version>0.0.5</schema-version>

ms.schema_name
# "Computer Model"

ms.schema_version
# "0.0.5"

ms.assemblies
# [Vendor, Computer, ...]

Model Generation

The Metaschema::ModelGenerator generates Ruby classes from Metaschema XML definitions. It uses a factory-based architecture:

`ModelGenerator`	Orchestrator — handles imports, augments, and delegates to factories
`FieldFactory`	Creates field classes from Metaschema field definitions
`AssemblyFactory`	Creates assembly classes with XML and JSON mappings
`FieldSerializer`	Service object for normalizing field values to JSON
`FieldDeserializer`	Service object for denormalizing JSON values to field instances
`CollapsiblesCollapser`	Groups collapsible fields by shared flag values
`Utils`	Shared naming and utility helpers

Generating Ruby source

# Generate a single Ruby file with all classes
source = Metaschema::ModelGenerator.to_ruby_source(
  "oscal_complete_metaschema.xml",
  module_name: "Oscal"
)

# Generate split files (one per class)
files = Metaschema::ModelGenerator.to_ruby_source(
  "oscal_complete_metaschema.xml",
  module_name: "Oscal",
  split: true
)

Type System

The TypeMapper maps Metaschema data types to Ruby/Lutaml::Model types:

`string`, `token`, `uri`, etc.	`:string`
`integer`	`:integer`
`boolean`	`:boolean`
`date`, `date-time`	`:date`, `:date_time`
`markup-line`	`Metaschema::MarkupLineDatatype`
`markup-multiline`	`Metaschema::MarkupMultilineDatatype`

Dependencies

lutaml-model ~> 0.8.0 — serialization framework
moxml >= 0.1.15 — XML adapter (uses namespace_validation_mode= API)

Tests

The spec/fixtures folder contains tests that the Metaschema gem needs to comply with.

Including:

spec/fixtures/metaschema: the submoduled repository from the Metaschema project
spec/fixtures/metaschema/examples: examples of Metaschema XML files (for us to test round-tripping)
spec/fixtures/metaschema/test-suite: the test suite for the Metaschema project. TODO: This library is to be tested against these files.
spec/fixtures/metaschema/test-suite/schema-generation: these files test against individual features of Metaschema. TODO: This library needs to run RSpecs against every directory here each representing a separate feature.
spec/fixtures/metaschema/test-suite/worked-examples: these files are complete Metaschema XML examples that exercises all features of Metaschema. TODO: This library needs to run RSpecs against each of these files.

License

BSD-3 license.