Skip to content

Add yaml struct tags to Schema for bidirectional YAML (un)marshaling#192

Open
alecrubin wants to merge 1 commit into
invopop:mainfrom
alecrubin:yaml-struct-tags
Open

Add yaml struct tags to Schema for bidirectional YAML (un)marshaling#192
alecrubin wants to merge 1 commit into
invopop:mainfrom
alecrubin:yaml-struct-tags

Conversation

@alecrubin

@alecrubin alecrubin commented Jun 9, 2026

Copy link
Copy Markdown

This revives #171 with the context that was missing the first time. My follow-up there only went up after the PR had already been closed, so the use case never really got a hearing. Putting it here up front.

What this does

Mirrors the existing json struct tags on every Schema field with matching yaml tags. Purely additive: no behavioral change for JSON users, the tags are inert unless a YAML (un)marshaler is actually used.

Why a JSON→YAML converter doesn't cover it

The suggestion on #171 was to use a JSON→YAML converter instead. That only solves the write path. The use case here is bidirectional:

  • Read path. We persist schemas as hand-edited YAML files and yaml.Unmarshal them back into *jsonschema.Schema. With no yaml tags, the decoder falls back to the lowercased field name, which matches none of the $-prefixed or camelCase keys — $schema, $defs, prefixItems, additionalProperties, patternProperties, etc. A converter can't help on decode; it needs tags on the library's own struct (the only alternative is a parallel mirror struct, which is far more friction than the tags it would replace).
  • Order preservation. Properties is a *orderedmap.OrderedMap, and property order is structurally meaningful in JSON Schema. Round-tripping through a generic map[string]any converter flattens it through an unordered map and reorders fields; marshaling straight from the struct keeps order intact.

On the "duplicating tags adds friction" concern

It's ~50 tags that mechanically match the existing json names, added once, with zero ongoing cost — they're ignored entirely by anyone who never imports a YAML package. The friction is a one-time mirror; the capability it unlocks (round-tripping schemas through YAML without losing field order or $-prefixed keys) isn't otherwise reachable without forking the struct.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant