Mechanism, not policy¶

yamldoc moves text. It has no opinion about what the text means.

This boundary is what keeps the library useful to callers whose needs differ, and it is enforced by a simple test:

If a decision can only be justified by reference to a particular kind of YAML — configuration, manifests, CI pipelines — it does not belong here.

What that rules out¶

Merging and precedence. Combining two documents, or two files, into an effective value is a policy decision. A configuration loader wants later-wins; a manifest tool wants them kept separate. yamldoc gives you the documents; you decide.

Overlay semantics. Related, and worth stating separately because it is the easiest assumption to make by accident. A multi-document file is a sequence of independent documents in YAML. Treating later ones as overriding earlier ones is a reasonable convention — and it is your convention, not this library's.

Schema and validation. Whether a value is acceptable depends entirely on the application.

File I/O. This is where policy hides in plain sight: atomic writes, permissions, locking, temp-and-rename, watching, filesystem abstraction. Callers have strong and differing opinions about all of it. yamldoc takes []byte and returns []byte, so it works over a real filesystem, an in-memory one, a git worktree, or an object store, and it drags no filesystem dependency into your build.

What that leaves in¶

Parsing to a syntax revision and composing its meaning under YAML's own schemas. Addressing nodes by step or path. Setting, inserting, replacing and removing values, and deciding which comments belong to which node while doing it. Validating that a document means something under its version. Writing the bytes back with nothing else changed.

Those are all questions about YAML documents, answerable without knowing what the document is for. Interpreting YAML is mechanism: yes is a boolean under a %YAML 1.1 directive because the standard says so, not because a configuration file wants it to be.

Where the line is deliberately awkward¶

Tags sit right on the boundary. !secret vault/db is YAML, and the engine parses it, preserves it, validates around it and edits beside it as mechanism. What the tag means is policy, and the engine does not guess: it never invokes anything while parsing, validating or emitting, and a caller that wants the value registers a handler for the tag and asks for a specific node. The registry is the seam, and everything on the far side of it, a vault client, an environment lookup, a file include, is the caller's.

The same line runs through partial validation. A file with a tag the engine does not know is not wrong; it is unresolved. PartialValidation reports everything it can establish and lists the checks it could not run, and whether that is acceptable is, again, the caller's decision.