DamianH.Metaschema.Tool 0.1.0

Metaschema .NET

A .NET implementation of the Metaschema toolchain, providing equivalent functionality to metaschema-java and metaschema-node.

Overview

Metaschema is a framework for defining information models that can be used to generate schemas (XSD, JSON Schema), documentation, and code in multiple programming languages. It is the foundation for OSCAL (Open Security Controls Assessment Language).

Features

• Module Loading - Parse Metaschema XML modules with import resolution and caching
• Data Types - Full implementation of all 23 built-in Metaschema data types
• Metapath - Complete Metapath expression language with 80+ functions
• Serialization - Read and write XML, JSON, and YAML content
• Constraint Validation - Validate content against allowed-values, matches, expect, and cardinality constraints
• Code Generation - Generate C# classes from Metaschema modules
• Schema Generation - Generate XSD and JSON Schema from Metaschema modules
• CLI Tool - Command-line interface for all operations

Packages

Requirements

• .NET 10 SDK (Preview)

Installation

# Install the CLI tool globally
dotnet tool install -g DamianH.Metaschema.Tool

# Add the core library to your project
dotnet add package DamianH.Metaschema.Core

# Add serialization support
dotnet add package DamianH.Metaschema.Databind

Quick Start

Loading a Metaschema Module

using Metaschema.Core.Loading;

// Load a Metaschema module from file
var loader = new ModuleLoader();
var module = loader.Load("path/to/metaschema.xml");

// Access definitions
foreach (var assembly in module.AssemblyDefinitions)
{
    Console.WriteLine($"Assembly: {assembly.Name}");
}

foreach (var field in module.FieldDefinitions)
{
    Console.WriteLine($"Field: {field.Name} ({field.DataTypeName})");
}

Deserializing Content

using Metaschema.Core.Loading;
using Metaschema.Databind;

// Create a binding context with your module
var loader = new ModuleLoader();
var module = loader.Load("path/to/metaschema.xml");
var context = new BindingContext(module);

// Deserialize JSON content
var deserializer = context.GetDeserializer(Format.Json);
var document = deserializer.Deserialize(jsonContent);

// Access the document structure
var rootAssembly = document.RootAssembly;
Console.WriteLine($"Root: {rootAssembly.Name}");

// Access flags (attributes)
foreach (var flag in rootAssembly.Flags)
{
    Console.WriteLine($"  {flag.Key}: {flag.Value.RawValue}");
}

Serializing Content

using Metaschema.Databind;

// Serialize a document to different formats
var serializer = context.GetSerializer(Format.Json);
var json = serializer.Serialize(document);

var xmlSerializer = context.GetSerializer(Format.Xml);
var xml = xmlSerializer.Serialize(document);

var yamlSerializer = context.GetSerializer(Format.Yaml);
var yaml = yamlSerializer.Serialize(document);

Evaluating Metapath Expressions

using Metaschema.Core.Metapath;

// Parse and evaluate a Metapath expression
var expression = MetapathExpression.Parse("//control[@id='ac-1']");
var results = expression.Evaluate(documentNode);

foreach (var item in results)
{
    Console.WriteLine(item);
}

// Use built-in functions
var countExpr = MetapathExpression.Parse("count(//control)");
var count = countExpr.EvaluateSingle(documentNode);

Constraint Validation

using Metaschema.Core.Constraints;

// Validate content against constraints
var validator = new ConstraintValidator(module);
var results = validator.Validate(documentNode);

if (!results.IsValid)
{
    foreach (var finding in results.Findings)
    {
        Console.WriteLine($"[{finding.Severity}] {finding.Message}");
    }
}

Generating Code

using Metaschema.Databind.CodeGeneration;

// Generate C# classes from a module
var generator = new CSharpCodeGenerator();
var options = new CodeGenerationOptions
{
    Namespace = "MyApp.Models",
    OutputPath = "Generated",
    Visibility = Visibility.Public
};

generator.Generate(module, options);

Generating Schemas

using Metaschema.Schemagen;

// Generate JSON Schema
var jsonSchemaGenerator = new JsonSchemaGenerator();
var jsonSchema = jsonSchemaGenerator.Generate(module);

// Generate XSD
var xsdGenerator = new XsdGenerator();
var xsd = xsdGenerator.Generate(module);

CLI Usage

# Validate a Metaschema module
metaschema validate-module path/to/metaschema.xml

# Validate content against a Metaschema
metaschema validate-content document.json --metaschema path/to/metaschema.xml

# Generate JSON Schema
metaschema generate-schema path/to/metaschema.xml --type json-schema --output schema.json

# Generate XSD
metaschema generate-schema path/to/metaschema.xml --type xsd --output schema.xsd

# Generate C# code
metaschema generate-code path/to/metaschema.xml --namespace MyApp.Models --output Generated

# Convert between formats
metaschema convert document.xml --to json --output document.json
metaschema convert document.json --to yaml --output document.yaml

Metapath Functions

The Metapath implementation includes 80+ functions across these categories:

Data Types

All 23 built-in Metaschema data types are supported:

Building from Source

# Clone the repository
git clone https://github.com/damianh/metaschema-dotnet.git
cd metaschema-dotnet

# Build
dotnet build metaschema-dotnet.slnx

# Run tests
dotnet test metaschema-dotnet.slnx

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

• Metaschema Specification
• Metapath Specification
• metaschema-java - Java implementation
• metaschema-node - Node.js/TypeScript implementation
• OSCAL - Open Security Controls Assessment Language