Summary
\Test-Toml\ currently validates TOML syntax only. Scripts that load TOML config from external sources often also need to verify the structure — required keys, value types, allowed values — not just that the file parses.
Schema format
There is no official, standardised TOML schema specification. The toml-schema.org effort exists but has no formal spec document and no .NET implementation. JSON Schema is an option but requires a lossy TOML→JSON conversion and pulls in external libraries.
We will define and implement our own schema format — written in TOML, validated by our own pure-PowerShell validator. No external libraries. No NuGet dependencies.
Desired schema format (proposal)
A schema file is a valid TOML document (suggested extension .tosd) that describes the expected shape of a TOML document:
\\ oml
[toml-schema]
version = '1.0'
[fields.title]
type = 'string'
required = true
[fields.port]
type = 'integer'
required = true
min = 1
max = 65535
[fields.tags]
type = 'array'
itemtype = 'string'
[fields.server]
type = 'table'
[fields.server.fields.host]
type = 'string'
required = true
\\
Supported types
\string, \integer, \ loat, \�ool, \datetime, \�rray, \ able\
Supported constraints
equired\ (bool) — key must be present- \min\ / \max\ — numeric range or string/array length bounds
- \pattern\ — regex for strings
- \itemtype\ — element type for arrays
- \ ields\ — nested field definitions for tables
Desired capability
\\powershell
Validate syntax AND structure
Test-Toml -Path config.toml -SchemaPath schema.tosd
Test-Toml -InputObject \ -SchemaPath schema.tosd
\\
Returns \False\ + writes a non-terminating error describing the first schema violation.
Acceptance criteria
- -SchemaPath\ is a new optional parameter — omitting it keeps current syntax-only behaviour
- Schema is itself parsed with \ConvertFrom-Toml\ (no extra parser needed)
- Validation is pure PowerShell — zero new module dependencies
- Returns \True\ only when content is both syntactically valid and conforms to the schema
- Errors are non-terminating (consistent with existing \Test-Toml\ behaviour)
- Schema format is documented in the module's README / help
Implementation scope
New private functions (one per concern):
- \Test-TomlSchemaField\ — validates a single field against its schema entry
- \Test-TomlSchemaTable\ — recurses through a table's fields
- \Test-TomlSchema\ (internal coordinator, or inline in \Test-Toml)
Related
Summary
\Test-Toml\ currently validates TOML syntax only. Scripts that load TOML config from external sources often also need to verify the structure — required keys, value types, allowed values — not just that the file parses.
Schema format
There is no official, standardised TOML schema specification. The toml-schema.org effort exists but has no formal spec document and no .NET implementation. JSON Schema is an option but requires a lossy TOML→JSON conversion and pulls in external libraries.
We will define and implement our own schema format — written in TOML, validated by our own pure-PowerShell validator. No external libraries. No NuGet dependencies.
Desired schema format (proposal)
A schema file is a valid TOML document (suggested extension .tosd) that describes the expected shape of a TOML document:
\\ oml
[toml-schema]
version = '1.0'
[fields.title]
type = 'string'
required = true
[fields.port]
type = 'integer'
required = true
min = 1
max = 65535
[fields.tags]
type = 'array'
itemtype = 'string'
[fields.server]
type = 'table'
[fields.server.fields.host]
type = 'string'
required = true
\\
Supported types
\string, \integer, \ loat, \�ool, \datetime, \�rray, \ able\
Supported constraints
equired\ (bool) — key must be present
Desired capability
\\powershell
Validate syntax AND structure
Test-Toml -Path config.toml -SchemaPath schema.tosd
Test-Toml -InputObject \ -SchemaPath schema.tosd
\\
Returns \False\ + writes a non-terminating error describing the first schema violation.
Acceptance criteria
Implementation scope
New private functions (one per concern):
Related