Using the CLI

This guide covers the Metaschema command-line interface (CLI) for validating content, generating schemas, converting between formats, and evaluating Metapath expressions.

Build the CLI from source:

mvn install -DskipTests

The CLI is packaged as an executable jar with dependencies in metaschema-cli/target/. You can run it with:

java -jar metaschema-cli/target/metaschema-cli-*-metaschema-cli.jar [command] [options]

For convenience, the examples below use metaschema-cli as a shorthand for this command.

Validate that a Metaschema module is well-formed and valid.

metaschema-cli validate [options] <metaschema-module>

Arguments:

Argument	Description
`metaschema-module`	The Metaschema module file or URL to validate

Options:

Option	Description
`-c, --constraint <URL>`	Additional constraint definitions (repeatable)
`-o, --output <FILE>`	Write SARIF results to the specified file
`--sarif-include-pass`	Include passing results in SARIF output
`--sarif-timing`	Include per-constraint timing data in SARIF output (requires `-o`)
`--disable-schema-validation`	Skip schema validation
`--disable-constraint-validation`	Skip constraint validation
`--path-format <FORMAT>`	Path format in output: `auto`, `metapath`, `xpath`, `jsonpointer` (default: `auto`)
`--threads <N>`	Number of threads for parallel constraint validation (default: 1)

Examples:

# Validate a Metaschema module
metaschema-cli validate schema/metaschema.xml

# Validate with SARIF output
metaschema-cli validate schema/metaschema.xml -o results.sarif

# Validate with timing data in SARIF output
metaschema-cli validate schema/metaschema.xml -o results.sarif --sarif-timing

Validate a content instance against a Metaschema module.

metaschema-cli validate-content [options] <content-file>

Arguments:

Argument	Description
`content-file`	The content instance file or URL to validate

Options:

Option	Description
`-m, --metaschema <FILE_OR_URL>`	(Required) The Metaschema module defining the content
`--as <FORMAT>`	Source format: `XML`, `JSON`, or `YAML` (auto-detected if omitted)
`-c, --constraint <URL>`	Additional constraint definitions (repeatable)
`-o, --output <FILE>`	Write SARIF results to the specified file
`--sarif-include-pass`	Include passing results in SARIF output
`--sarif-timing`	Include per-constraint timing data in SARIF output (requires `-o`)
`--disable-schema-validation`	Skip schema validation
`--disable-constraint-validation`	Skip constraint validation
`--path-format <FORMAT>`	Path format in output: `auto`, `metapath`, `xpath`, `jsonpointer` (default: `auto`)
`--threads <N>`	Number of threads for parallel constraint validation (default: 1)

Examples:

# Validate XML content
metaschema-cli validate-content -m schema/metaschema.xml data/instance.xml

# Validate JSON content with explicit format
metaschema-cli validate-content -m schema/metaschema.xml --as JSON data/instance.json

# Validate with parallel constraint processing and SARIF timing output
metaschema-cli validate-content -m schema/metaschema.xml \
    --threads 4 --sarif-timing -o results.sarif data/instance.xml

# Validate with additional constraints
metaschema-cli validate-content -m schema/metaschema.xml \
    -c extra-constraints.xml data/instance.xml

Convert a content instance from one format to another.

metaschema-cli convert [options] <source-file> [destination-file]

Arguments:

Argument	Description
`source-file`	The content instance file or URL to convert
`destination-file`	Output file (writes to stdout if omitted)

Options:

Option	Description
`-m, --metaschema <FILE_OR_URL>`	(Required) The Metaschema module defining the content
`--to <FORMAT>`	(Required) Target format: `XML`, `JSON`, or `YAML`
`--overwrite`	Overwrite the destination file if it exists

Examples:

# Convert XML to JSON (output to stdout)
metaschema-cli convert -m schema/metaschema.xml --to JSON data/instance.xml

# Convert XML to JSON (output to file)
metaschema-cli convert -m schema/metaschema.xml --to JSON \
    data/instance.xml output.json --overwrite

# Convert YAML to XML
metaschema-cli convert -m schema/metaschema.yaml --to XML data/instance.yaml

Generate an XML Schema (XSD) or JSON Schema from a Metaschema module.

metaschema-cli generate-schema [options] <metaschema-module> [destination-file]

Arguments:

Argument	Description
`metaschema-module`	The Metaschema module file or URL
`destination-file`	Output file (writes to stdout if omitted)

Options:

Option	Description
`--as <FORMAT>`	(Required) Schema format: `XML` (XSD) or `JSON`
`--inline-types`	Generate inline type definitions instead of named types
`--overwrite`	Overwrite the destination file if it exists

Examples:

# Generate JSON Schema (output to stdout)
metaschema-cli generate-schema --as JSON schema/metaschema.xml

# Generate XML Schema to file
metaschema-cli generate-schema --as XML schema/metaschema.xml schema.xsd --overwrite

# Generate JSON Schema with inline types
metaschema-cli generate-schema --as JSON --inline-types schema/metaschema.yaml schema.json

Generate a Mermaid entity-relationship diagram from a Metaschema module.

metaschema-cli generate-diagram [options] <metaschema-module> [destination-file]

Arguments:

Argument	Description
`metaschema-module`	The Metaschema module file or URL
`destination-file`	Output file (writes to stdout if omitted)

Options:

Option	Description
`--overwrite`	Overwrite the destination file if it exists

Examples:

# Generate diagram to stdout
metaschema-cli generate-diagram schema/metaschema.xml

# Generate diagram to file
metaschema-cli generate-diagram schema/metaschema.yaml diagram.mmd --overwrite

Evaluate a Metapath expression.

metaschema-cli metapath eval [options]

Options:

Option	Description
`-e, --expression <EXPR>`	(Required) Metapath expression to evaluate
`-m, --metaschema <FILE_OR_URL>`	Metaschema module for context
`-i <FILE_OR_URL>`	Content instance to evaluate against

The command supports three evaluation modes:

With module and content - Evaluates the expression against parsed content
With module only - Evaluates against the Metaschema module itself
Without module - Limited to expressions that don't require content context

Examples:

# Evaluate a standalone expression
metaschema-cli metapath eval -e 'string-length("hello")'

# Query a content instance
metaschema-cli metapath eval -m schema/metaschema.xml \
    -i data/instance.json -e '//title'

# Query a Metaschema module
metaschema-cli metapath eval -m schema/metaschema.xml -e '//define-assembly/@name'

List all available Metapath functions.

metaschema-cli metapath list-functions

Functions are grouped by namespace (fn:, math:, array:, map:) and displayed with their signatures.

Use --threads to enable parallel constraint evaluation for large documents:

metaschema-cli validate-content -m schema/metaschema.xml \
    --threads 4 data/large-instance.xml

Setting --threads to the number of available CPU cores typically provides the best performance for documents with many constraints.

Use -o to write validation results in SARIF 2.1.0 format:

metaschema-cli validate-content -m schema/metaschema.xml \
    -o results.sarif data/instance.xml

SARIF output includes tool information, validation findings with locations, and rule descriptors. See the SARIF Output guide for details on the output format.

Add --sarif-timing to include performance instrumentation in SARIF output:

metaschema-cli validate-content -m schema/metaschema.xml \
    --sarif-timing -o results.sarif data/instance.xml

This adds per-constraint, per-phase, and overall timing data to the SARIF output. See the SARIF Output guide for the timing data format.

Control how locations are displayed in validation output:

Format	Description	Example
`auto`	Auto-detect based on content format (default)	Varies
`metapath`	Metapath expressions	`/catalog/metadata/title`
`xpath`	XPath for XML content	`/catalog/metadata/title`
`jsonpointer`	JSON Pointer (RFC 6901)	`/catalog/metadata/title`

Load external constraint definitions alongside the module's built-in constraints:

metaschema-cli validate-content -m schema/metaschema.xml \
    -c organization-rules.xml -c project-rules.xml data/instance.xml

The -c option can be specified multiple times to load multiple constraint files.

Validating with Constraints - Java API for constraint validation
SARIF Output - Understanding SARIF validation results
Executing Metapath - Metapath expression syntax
Generating Schemas - Schema generation details