ModelNormalizerApp

© 2026 Obsvra. This document describes SpiceGrinder and is provided to help you evaluate and use it. It is not a license to reproduce, adapt, or use this material to build a competing product or service. Full terms: the SpiceGrinder EULA.

NAME

ModelNormalizerApp — flatten <Import> references into one self-contained model (Pro)

SYNOPSIS

java -cp spicegrinder.jar com.obsvra.spicegrinder.pro.tools.ModelNormalizerApp [options] model.xml|model.json

On a jpackage Pro install:

normalizer [options] model.xml|model.json

Not present in a Free build — ModelNormalizerApp lives in the pro.tools package and has no Free-tier equivalent.

DESCRIPTION

ModelNormalizerApp reads a single model file and writes out an equivalent model with every <Import> — including nested ones — resolved and inlined. Imported node names are prefixed the same way a normal load would register them (the <Import> node’s own name= or prefix= attribute, falling back to "import" if neither is set), and every reference to an Import’s own alias is rewritten to point at the real, now-inlined node.

The output has no remaining <Import> elements and no dependency on relative file paths — it’s a single, self-contained file that can be moved, shared, or submitted elsewhere without carrying its library dependencies along separately.

The actual flattening logic (ModelNormalizer.flatten) is also directly callable from Java against an in-memory model string; this CLI is a thin wrapper around it. The typical caller is something that needs to flatten a model just before submitting it elsewhere — e.g. a Service API client — not the Service API itself, which never needs to do this on its own behalf.

OPTIONS

Option	Meaning
`--out PATH`	Write the flattened model to a file (default: stdout).
`--quiet`	Suppress the progress banner lines normally written to stderr.
`-h`, `--help`	Print usage and exit.
`--version`	Print the version (e.g. `1.0.0 Alpha 1 (Build 1)`) and exit.
`--json`	Wrap the output (stdout or `--out`) in a JSON object with metadata instead of writing the flattened model text alone. See OUTPUT (JSON) below.

OUTPUT (JSON)

Without --json, the destination (stdout or --out) receives the flattened model text alone — nothing else. With --json, that same destination receives one JSON object instead:

{
  "model": "/abs/path/model.xml",
  "output": "-",
  "flattened": "<the flattened model text>",
  "bytes": 4821
}

output is "-" for stdout, or the resolved --out path. bytes is the flattened text’s own UTF-8 byte length. No third output destination is introduced — whatever would have received the raw flattened text receives this JSON object instead. On failure (model file not found, or normalization failed), the same destination receives a leaner object instead: {"model": "...", "error": "<message>"}.

-h/--help/--version output and bad-argument errors (exit code 2) always stay plain text, unaffected by --json.

EXIT STATUS

Code	Meaning
0	Normalization succeeded.
1	Model file not found, or normalization failed (e.g. an `<Import>` couldn’t be resolved).
2	Bad arguments — missing required value, unrecognized option, or not exactly one model file given.

EXAMPLES

Flatten a model to stdout:

java -cp spicegrinder.jar com.obsvra.spicegrinder.pro.tools.ModelNormalizerApp model.xml

Flatten to a file, no progress banner:

normalizer --quiet --out flattened.xml model.xml

Get a machine-readable result for a script or agent to parse:

normalizer --json --quiet model.xml