NodetteHQ/PureYAML
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

No built-in tag constructors: Date, binary Data, and Set don't auto-decode #11

New Issue
Closed
opened 2026-07-10 13:56:49 +00:00 by Mihaela · 0 comments
Mihaela commented 2026-07-10 13:56:49 +00:00 (Migrated from codeberg.org)
Copy Link

Status (2026-07-10)

Open. Found by a public-API feature-parity audit against Yams
(NodetteHQ/PureYAMLYamsComparison, Reports/macos-2026-07-10-apisguru-sample-504/FEATURE-PARITY.md),
not by a corpus parse-success run: this is a capability gap, not a
correctness bug.

Yams has a Resolver (regex-pattern rules resolving a scalar's implicit
tag) and a Constructor (a tag-to-closure map used to turn a tagged node
into a Swift value), with built-in handlers for Date, binary Data
(base64), Set, and ordered maps. A caller gets these for free; custom
resolvers/constructors extend rather than replace them.

PureYAML has a narrower, opt-in-only version: Tagged.Constructor<Output>
(Sources/Tagged/Tagged.Constructor.swift) lets a caller register exact-tag
handlers with an explicit fallback, on the separate Tagged.Node tree from
parseTagged(_:) (not the primary parse(_:)/Model.Value path). It ships
with zero built-in constructors by design — confirmed explicitly in
docs/MIGRATION.md: "Custom resolvers and environment expansion: Not
implemented." There is no regex-based implicit-tag resolver equivalent to
Yams's Resolver at all.

Impact

A document using YAML's standard timestamp or binary tags (!!timestamp,
!!binary) requires the caller to write and register their own
Tagged.Constructor handlers to get typed Date/Data values out; with
Yams this happens automatically. Anyone porting code that relies on Yams's
default decoding of these needs new code, not just a dependency swap.

Work

  • Decide the built-in tag set to ship: !!timestamp to Date and
    !!binary to Data look like the two most likely to matter in practice,
    matching Yams's defaults; !!set and ordered-map handling may be lower
    priority since PureYAML's Model.Mapping already preserves order and
    duplicate keys without a special tag.
  • Decide where these live: as default-registered handlers on
    Tagged.Constructor, or as a new built-in path integrated with
    parse(_:)/Model.Value directly (the latter would need a way to
    represent a Date/Data value in Model.Value, which does not exist
    today, so likely needs scoping against the Model.Value case set first).
  • Add tests proving standard-tag round-tripping (parse a !!timestamp
    scalar, get a Date, dump it back to the same tagged form).

See NodetteHQ/PureYAMLYamsComparison's FEATURE-PARITY.md for the full
audit.

Part of #8.

## Status (2026-07-10) Open. Found by a public-API feature-parity audit against Yams (NodetteHQ/PureYAMLYamsComparison, `Reports/macos-2026-07-10-apisguru-sample-504/FEATURE-PARITY.md`), not by a corpus parse-success run: this is a capability gap, not a correctness bug. Yams has a `Resolver` (regex-pattern rules resolving a scalar's implicit tag) and a `Constructor` (a tag-to-closure map used to turn a tagged node into a Swift value), with built-in handlers for `Date`, binary `Data` (base64), `Set`, and ordered maps. A caller gets these for free; custom resolvers/constructors extend rather than replace them. PureYAML has a narrower, opt-in-only version: `Tagged.Constructor<Output>` (`Sources/Tagged/Tagged.Constructor.swift`) lets a caller register exact-tag handlers with an explicit fallback, on the separate `Tagged.Node` tree from `parseTagged(_:)` (not the primary `parse(_:)`/`Model.Value` path). It ships with zero built-in constructors by design — confirmed explicitly in `docs/MIGRATION.md`: "Custom resolvers and environment expansion: Not implemented." There is no regex-based implicit-tag resolver equivalent to Yams's `Resolver` at all. ## Impact A document using YAML's standard timestamp or binary tags (`!!timestamp`, `!!binary`) requires the caller to write and register their own `Tagged.Constructor` handlers to get typed `Date`/`Data` values out; with Yams this happens automatically. Anyone porting code that relies on Yams's default decoding of these needs new code, not just a dependency swap. ## Work - Decide the built-in tag set to ship: `!!timestamp` to `Date` and `!!binary` to `Data` look like the two most likely to matter in practice, matching Yams's defaults; `!!set` and ordered-map handling may be lower priority since PureYAML's `Model.Mapping` already preserves order and duplicate keys without a special tag. - Decide where these live: as default-registered handlers on `Tagged.Constructor`, or as a new built-in path integrated with `parse(_:)`/`Model.Value` directly (the latter would need a way to represent a `Date`/`Data` value in `Model.Value`, which does not exist today, so likely needs scoping against the `Model.Value` case set first). - Add tests proving standard-tag round-tripping (parse a `!!timestamp` scalar, get a `Date`, dump it back to the same tagged form). See NodetteHQ/PureYAMLYamsComparison's `FEATURE-PARITY.md` for the full audit. Part of #8.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: NodetteHQ/PureYAML#11
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?