namespace2xml 3.0.0-preview.2

namespace2xml

A deterministic configuration transformer. It reads ordered namespace profiles and structured inputs, applies scheme directives, and renders many outputs from one overlaid model — XML, JSON, YAML, INI, namespace profiles and quoted-namespace files.

Identical inputs always produce byte-identical outputs, on every supported platform, in every locale, on every run.

Version 3.0 is a rewrite

3.0 replaces the 2.x implementation entirely, against a specification written before the code. The specification is the contract; the implementation is an attempt to satisfy it. Behaviour that 2.4.0 left undefined is now defined, and the intentional differences are listed in docs/migration-2.x-to-3.0.md.

3.0.0-preview.N is a preview line. It is meant to be used, reported against, and revised. See KNOWN-LIMITS.md for what it does not do yet.

Install

dotnet tool install --global namespace2xml --prerelease

Basic usage

namespace2xml -i <input files> -s <scheme files> [-o <output directory>]

Input files carry the data. Scheme files describe what to produce from it: which output formats, which parts become XML elements or attributes, which keys are hidden, and so on.

One model, many formats

test.properties:

a.b.x=1

scheme.properties:

a.output=xml,json,yaml,ini,namespace

namespace2xml -i test.properties -s scheme.properties

produces a.xml, a.json, a.yml, a.ini and a.properties:

<a>
  <b x="1" />
</a>

{
  "b": {
    "x": 1
  }
}

b:
  x: 1

[b]
x = 1

b.x=1

Overlaying

Inputs are applied in command-line order, and later files win:

namespace2xml -i base.properties -i production.properties -i secrets.properties -s scheme.properties

Layer by lifetime — base, then environment, then instance, then secrets — not by topic. See docs/usage-methodology.md for why, and for the anti-patterns that follow from getting it backwards.

For automation and AI agents

This tool is designed to be used by programs, and to be argued with by them.

• --diagnostics-format json writes the entire diagnostic stream to standard error as one canonical JSON array conforming to spec/diagnostic-stream.schema.json. Operational log messages are suppressed in that mode, so standard error is pure data. The array is written once, at exit, so it is always complete and always well-formed.
• Every diagnostic carries a stable code and a specification anchor naming the clause it enforces, so a disagreement can be reported precisely rather than described. See docs/diagnostics.md.
• --version prints one <field>: <value> line per field, including the contract-bundle revision that identifies exactly which specification and diagnostic registry the binary implements.
• Exit codes are contractual. 0 is success, including success with warnings; 1 is failure. Specification Section 6.3 fixes those two and no others. During the 3.0.0-preview line a third code, 70, means this preview has not implemented the requested work — the pipeline was never entered, no destination was written, and nothing about the input has been judged. An agent must treat 70 as "come back later", never as a failure of the configuration it supplied. It disappears at 3.0.0; a released build returns only 0 or 1.
• The specification ships inside the package, so an agent can read the contract offline.
• Symbols and source link are published alongside every release, so a stack trace resolves to the exact source that produced it.

Start at AGENTS.md. The machine-readable index is llms.txt.

Documentation

Found a problem?

Good — that is what the preview is for, and the project is built to absorb it.

Before filing, ask one question: what would have to change so this never surprises anyone again?

Always include the contract-bundle revision from --version. A report against an unknown contract revision cannot be acted on.

Full guidance, including the report form and the rules for agent-authored reports, is in CONTRIBUTING.md.

Building from source

dotnet build namespace2xml.slnx
dotnet test  namespace2xml.slnx

Requires the .NET 10 SDK. The solution uses the .slnx format.

License

MIT.