format

schema/format

String-format validators for the schema package. Each exported function (Email, Color, ObjectID, IPv4, IPv6, Hostname, URI, Date, DateTime, Time, ISO8601, HTML, NoHTML, Markdown, In, NotIn, MatchRegex, Token, Username, WebFinger, UnsafeAny) is a Generator — it takes a configuration arg and returns a StringFormat closure that validates (and may rewrite) a string. See the parent schema README.

What matters here

• A format is registered via schema.UseFormat, which is only safe during init/startup. The registry freezes the first time validation reads from it; registering a format afterward is rejected (reported, then ignored). Register all custom formats before any schema validation runs.
• Empty string is always allowed. Every validator returns early on "" without error — "required" is enforced by the schema element (String.Required), not by the format. A format only constrains the shape of a non-empty value.
• A StringFormat returns (value, error) and may REWRITE the value. Validators are part of a coercion pipeline (see validate_String_Formats in the parent package), so returning a changed string is normal, not a bug — the caller tracks the change.
• Many Generators ignore their arg (e.g. Email, IPv4); the parameter exists to satisfy the uniform Generator signature. In/NotIn/MatchRegex are the ones that actually consume arg (the allowed set / pattern).
• The validators here are the trust boundary for untrusted strings. NoHTML/HTML gate markup (and lean on ../../html + bluemonday); URI/Hostname/IP* constrain network identifiers. Tighten here, not at call sites.
• Markup formats are guarded; unsafe-any is the only escape hatch. html sanitizes and markdown validates. A field whose safety is owned by a different trust boundary has to opt out with unsafe-any, which is deliberately generic and blunt — say why in a comment wherever you reach for it.
• A second sanitize is not automatically safer. This package's HTML policy is deliberately strict (no iframes, no styling, rel="nofollow" added). Re-filtering markup that an application already sanitized under its own wider policy silently deletes content — embeds especially. When an application's renderer has already sanitized a value, do not run it through html again; stacking two policies is safe by accident, not by design.
• Markdown cannot be made safe by rewriting its source. Sanitizing the source is a category error: it corrupts a < b in prose and fenced code blocks that quote markup, and an unregistered format name falls back to NoHTML, which strips tags and collapses the whitespace Markdown depends on. So markdown validates rather than rewrites. It renders the source twice, once honoring raw HTML and once not, and rejects the value when the two disagree — which happens exactly when the source carries raw HTML or a dangerous URL. That test needs no policy and no allow-list, so it can never argue with whatever sanitizer the application applies later: it accepts pure Markdown (links keep no added rel, fenced code keeps its language class) and rejects all embedded HTML, benign tags included. Cost is two renders, linear in length — pair it with a MaxLength, which the schema checks before any format function runs.