Documentation

dotReg is a line-oriented configuration notation built around dotted key paths, with explicit triple-quoted and literal pipe forms for multiline values. Start with the short guide, then use the specification when you need the precise rules.

Back to the project

Find your way

Document	Read it to…
Getting started	Learn the required file declaration, value lines, repeated values, headings, grouped retrieval, strings and unset values through small examples
Coding agent skill	Install the portable skill, invoke it for application development and run its offline configuration checker
Configuration file format	Consult the reference specification for syntax, processing stages and application responsibilities
Type profiles and candidate types	Look up defined type-specific representations and distinguish them from candidate type names and examples
Conformance checklist	Check syntax, decoding and any provided consumer layer against the specified rules
Third-party licences	Read the copyright and licence notices for the Astro and Starlight site framework
Undecided matters	Check which parts of the format remain open
Example configuration	Explore repeated values, quoted names, escapes, both multiline forms and the Go sample’s experimental type annotations
Go sample guide	Run the optional parser and CLI, use its API, or inspect its supported scope and provisional choices
Sample parser set	Choose Go, Python, JavaScript, TypeScript, Java, C#, Rust or C++; compare the shared syntax contract and streaming APIs

Format and implementation scope

The format specification defines the notation and processing rules. The type-profile document describes type-specific representations and candidate names; the open-issues document lists matters the specification leaves undecided. The getting started guide introduces the format without replacing the specification.

The current format version is declared by the mandatory @dotReg 0.1 property region and blank separator. Future version policy and standard type names remain undecided. Use .dotreg by default or .conf when that better suits the application; the format does not depend on the filename extension. See file properties and undecided matters.

The sample implementations demonstrate the notation. Their public APIs are provisional. The parsers other than Go cover syntax and common string decoding, retaining type expressions without conversion. The Go sample also provides an illustrative type profile and retrieval API. The string, int and bool annotations in the example configuration do not establish standard type names or conversion rules.

How the documents fit together

The core specification defines the notation and separates syntax processing, common string decoding, type conversion and application-specific validation. Type profiles and candidate types supplements it with type-specific representations and clearly labelled candidates. Undecided matters records the remaining questions; it does not add format rules. The Go guide describes one implementation of those stages and its handling of unspecified details.

For a first read, follow Getting started. For a particular rule, use the specification sections below. Implementers can also check their parser against the conformance checklist:

• File properties and format version.
• Key paths and quoting.
• Headings, relative notation and indentation.
• Type annotations.
• String decoding and unset values.
• Repeated values and read state.
• Retrieving values by key prefix.
• Triple-quoted multiline values and literal pipe blocks.
• Processing and application responsibilities.

Repository layout

.
├── README.md              # Project introduction
├── docs/                  # Guides and reference specification
├── .agents/skills/dotreg/  # Portable coding agent skill and offline checker
├── examples/              # Configuration inputs
├── implementations/
│   ├── README.md          # Parser set and common contract
│   ├── go/                # Go sample and experimental type consumer
│   ├── python/            # Python sample
│   ├── javascript/        # JavaScript engine
│   ├── typescript/        # Typed interface to the JavaScript engine
│   ├── java/              # Java sample
│   ├── csharp/            # C# sample
│   ├── rust/              # Rust sample
│   ├── cpp/               # C++ sample
│   ├── conformance/       # Shared syntax/decoding fixtures and runner
├── .github/               # CI and GitHub configuration
└── LICENSE                # MIT licence

Licence

The specification, examples and sample implementations are available under the MIT License.

You may choose your own licence for configuration files you author with this notation and for independently written implementations. Copies of material from this repository remain subject to the MIT terms.