ysd - Convert YAMLSchema and JSON Schema¶

ysd converts between .ysd, canonical .ysdc, and JSON Schema. It reads standard input when no input path is given and writes to standard output unless -o names a file.

See the installation instructions.

Usage¶

ysd --help
ysd [INPUT]
ysd (-t FORMAT | -o FILE) [INPUT]
ysd -N, --norm [INPUT]
ysd -R, --roundtrip [-q, --quiet] [INPUT]

Options¶

Option	Meaning
`-t`, `--to FORMAT`	Select `ysd`, `ysdc`, or `jsc`
`-f`, `--from FORMAT`	Select `ysd`, `ysdc`, or `jsc` input
`-Y`, `--yaml`	Emit YAML output
`-J`, `--json`	Emit JSON output
`-o`, `--output FILE`	Write to a file, or use `-` for standard output
`-N`, `--norm`	Normalize to draft 2020-12 JSON Schema
`-R`, `--roundtrip`	Test a JSON Schema or .ysd roundtrip
`-q`, `--quiet`	Suppress successful roundtrip output
`-C`, `--compact`	Emit compact JSON
`--upgrade`	Upgrade from the repository's default branch
`--help`	Show command help
`--version`	Show the installed version

Shell completion¶

The installers enable completion automatically in Bash, Zsh, Fish, and PowerShell by loading the matching script from the installation. The scripts can also be sourced directly from a checkout or installation:

source /path/to/yamlschema/share/complete.bash
source /path/to/yamlschema/share/complete.zsh

source /path/to/yamlschema/share/complete.fish

. $HOME\.local\share\yamlschema\complete.ps1

The installed .rc also adds the bundled manuals to MANPATH. Use man ysd, man yamlschema, man yamlschema-design, or man yamlschema-json-schema.

Upgrade¶

ysd --upgrade fetches the configured default branch of the repository under $PREFIX/share/yamlschema, checks out its current HEAD, and runs make install with the same prefix. The command refuses to replace an installed checkout with local changes.

Default direction¶

The first non-whitespace character and the filename extension determine the input form. JSON input converts to .ysd, while .ysd and .ysdc input convert to JSON Schema.

The recognized filename extensions are .ysd.yaml, .ysd.json, .ysdc.yaml, .ysdc.json, .schema.json, .schema.json.yaml, .schema.yaml, and .schema.yml. JSON Schema input may use JSON or YAML syntax regardless of its recognized filename extension, so a .schema.json file containing YAML is accepted.

ysd contact.schema.json
ysd contact.ysd.yaml
ysd contact.ysdc.yaml
ysd contact.ysdc.json

Use -f when reading standard input or when a filename is ambiguous:

cat contact.yaml | ysd -f ysd -t jsc
cat contact-schema.yaml | ysd -f jsc -t ysd

Explicit targets¶

The .ysd and .ysdc targets emit YAML by default, while jsc emits JSON. Use -Y / --yaml or -J / --json to override that default. The output options and a recognized output filename extension must agree.

ysd -t ysd contact.schema.json
ysd -t ysdc contact.ysd.yaml
ysd -t ysdc -J contact.ysd.yaml
ysd -t jsc contact.ysd.yaml
ysd -t jsc -Y contact.ysd.yaml

Normalize JSON Schema¶

Normalization adds the draft 2020-12 dialect, chooses canonical keyword positions, and preserves property order. Draft 4 root id normalizes to $id. JSON Schema input keeps its JSON or YAML serialization unless -J, -Y, -C, or an output filename selects one explicitly.

The preferred keyword order is:

$id $schema $comment $anchor title description
type format $ref const default
minimum maximum minLength maxLength
minItems maxItems uniqueItems minProperties maxProperties
items additionalProperties required patternProperties
enum dependentRequired $defs properties

Unlisted keywords are sorted alphabetically immediately before properties. Definition and property names retain their source order. When root schema content precedes $defs in the source, normalization keeps that layout by moving $defs after properties.

ysd -N contact.schema.json
ysd -N -Y contact.schema.json

-C / --compact applies only to JSON output.

Roundtrip reports¶

Roundtrip checks begin from the input representation:

ysd -R contact.schema.json
ysd -R contact.ysd.yaml

Use quiet mode in automation:

ysd -Rq contact.ysd.yaml

A successful quiet check produces no output and exits successfully.