Plan 148: Named field-type shortcuts for inline schemas (#279)

jeduden · claude · web-flow · commit c8c210b755ce · 2026-05-14T00:13:19.000+02:00
* Add named field-type shortcuts for inline schemas (plan 148)

Inline schemas can now reference a small library of named CUE
patterns by short name (`created: date`, `homepage: url`). The
library lives at cue/types/types.cue and ships embedded in the
binary; resolution happens in the shared frontmatterExpr loader,
so both inline `schema:` blocks and proto.md frontmatter pick up
the shortcuts.

CUE built-ins (string, int, bool, …) keep passing through so
existing schemas with bare-name builtins are unaffected. Bare
scalars that match neither a shortcut nor a builtin error at
config-load time, naming the field and the unknown name — typos
like `iso-date` no longer slide through to deep CUE errors.

* Docs: add docs/reference/schema-types.md and cross-link plan 148

Documents every registered shortcut (date, datetime, time, email,
url, filename, nonEmpty) with its canonical CUE expression and an
inline + proto.md walk-through. The MDS020 README, schemas guide,
and file-kinds guide each link the new page so a reader landing on
any of them can find the vocabulary.

Marks plan 148 ✅, settles the on-disk and CUE import paths, and
folds the implementation evidence (test names) into each
acceptance-criterion bullet so a reviewer can audit the claim
against the code.

The package-name nolint in cue/types/types.go keeps the Go-side
identifier aligned with the documented CUE import path
`github.com/jeduden/mdsmith/types` despite revive's
"meaningless package names" check.

---------

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -77,6 +77,7 @@ row: "- [{summary}](../{filename})"
 - [Print the mdsmith build version and exit.](../docs/reference/cli/version.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](../docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](../docs/reference/globs.md)
+- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](../docs/reference/schema-types.md)
 <?/catalog?>
 
 ### Development Workflow
diff --git a/AGENTS.md b/AGENTS.md
@@ -83,6 +83,7 @@ row: "- [{summary}]({filename})"
 - [Print the mdsmith build version and exit.](docs/reference/cli/version.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
+- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
 <?/catalog?>
 
 ## Development Workflow
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -69,6 +69,7 @@ row: "- [{summary}]({filename})"
 - [Print the mdsmith build version and exit.](docs/reference/cli/version.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
+- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
 <?/catalog?>
 
 ## Development Workflow
diff --git a/PLAN.md b/PLAN.md
@@ -76,7 +76,7 @@ footer: |
 | 145 | 🔲     | opus   | [Publish mdsmith via asdf and mise registry submissions](plan/145_asdf-mise-registry-submissions.md)                      |
 | 146 | ✅     | opus   | [Schema engine — sources, scope tree, per-scope rules](plan/146_inline-schema-in-kinds.md)                                |
 | 147 | 🔲     | opus   | [Actionable schema diagnostics for MDS020](plan/147_actionable-schema-diagnostics.md)                                     |
-| 148 | 🔲     | sonnet | [Named field-type shortcuts for inline schemas](plan/148_named-field-type-shortcuts.md)                                   |
+| 148 | ✅     | sonnet | [Named field-type shortcuts for inline schemas](plan/148_named-field-type-shortcuts.md)                                   |
 | 149 | 🔲     | opus   | [Section content schema for non-heading AST nodes](plan/149_section-content-schema.md)                                    |
 | 151 | ✅     | opus   | [LSP rename for headings and link-reference labels](plan/151_lsp-rename.md)                                               |
 | 152 | 🔲     | sonnet | [Claude Code plugin extensions — skills, agents, hooks](plan/152_claude-code-skills-agents-hooks.md)                      |
diff --git a/cue/types/types.cue b/cue/types/types.cue
@@ -0,0 +1,49 @@
+// Package types is the canonical vocabulary of named
+// field-type shortcuts that inline schemas (plan 146)
+// and proto.md frontmatter values reference by short
+// name (e.g. `created: date`).
+//
+// Each definition resolves to a plain CUE expression.
+// mdsmith embeds this file via go:embed and reads the
+// definitions to build the runtime registry used by
+// schema parsing. See plan/148_named-field-type-shortcuts.md.
+//
+// The user-visible contract is the import path
+// `github.com/jeduden/mdsmith/types` and the symbol
+// names. The literal CUE `import` syntax is reserved
+// for a future plan; today's surface is the bare-name
+// YAML scalar (`created: date`).
+package types
+
+// #date matches an ISO-8601 calendar date in YYYY-MM-DD
+// form. The check is shape-only; February 30th still
+// matches.
+#date: =~"^\\d{4}-\\d{2}-\\d{2}$"
+
+// #datetime matches an ISO-8601 timestamp with seconds,
+// either `Z` or a `±HH:MM` offset. Fractional seconds
+// and basic-format strings are rejected.
+#datetime: =~"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})?$"
+
+// #time matches `HH:MM` with optional `:SS` seconds.
+// No timezone suffix.
+#time: =~"^\\d{2}:\\d{2}(:\\d{2})?$"
+
+// #email matches `local@domain.tld` where neither side
+// contains `@` or whitespace and the domain has at
+// least one `.`. Internationalised addresses and
+// quoted local parts are rejected.
+#email: =~"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+
+// #url matches any string starting with `http://` or
+// `https://`. The remainder is not validated.
+#url: =~"^https?://"
+
+// #filename matches a Markdown filename of safe
+// characters: ASCII letters, digits, `.`, `_`, `-`,
+// and a trailing `.md`. Path separators are rejected.
+#filename: =~"^[A-Za-z0-9._-]+\\.md$"
+
+// #nonEmpty is a non-empty string. Useful for fields
+// that must carry content (titles, summaries).
+#nonEmpty: string & !=""
diff --git a/cue/types/types.go b/cue/types/types.go
@@ -0,0 +1,27 @@
+// Package types embeds the canonical mdsmith
+// field-type-shortcut library so schema parsing can
+// resolve `created: date` and friends without
+// touching the network. The library source itself
+// lives in `types.cue` next to this file.
+//
+// The intended import path for external CUE consumers
+// is `github.com/jeduden/mdsmith/types`. The literal
+// CUE import syntax is not yet implemented; today's
+// surface is the bare-name YAML scalar handled by
+// internal/schema's frontmatterExpr. The Go package
+// name matches the directory so the Go and CUE
+// import paths line up for future module wiring.
+//
+//nolint:revive // "types" mirrors the CUE-side import path
+package types
+
+import _ "embed"
+
+//go:embed types.cue
+var source string
+
+// Source returns the embedded `types.cue` contents
+// verbatim. internal/schema reads this once to seed
+// its runtime registry and to drive the drift test
+// that pins registry entries to the documented CUE.
+func Source() string { return source }
diff --git a/docs/guides/file-kinds.md b/docs/guides/file-kinds.md
@@ -329,3 +329,8 @@ For a quick primer on the same model from the CLI, run
 - [Placeholder grammar](../background/concepts/placeholder-grammar.md)
   — opt-in tokens that let kinds keep template files
   green under the same rules used for content.
+- [Schema field types](../reference/schema-types.md)
+  — named shortcuts (`date`, `email`, `url`, …) for
+  schema frontmatter values, so a kind's `schema:`
+  block does not have to re-derive the same CUE regex
+  every project lands on.
diff --git a/docs/guides/schemas.md b/docs/guides/schemas.md
@@ -60,6 +60,13 @@ kinds:
 The `frontmatter:` mapping reuses CUE expressions per
 key: regex, disjunction, list, and any other CUE form
 is accepted. Trailing `?` on a key marks it optional.
+Named shortcuts —
+`date`, `datetime`, `time`, `email`, `url`, `filename`,
+`nonEmpty` — substitute for their canonical CUE so a
+schema can write `created: date` instead of repeating
+the ISO regex; see
+[Schema field types](../reference/schema-types.md)
+for the registered names and how they are matched.
 
 `require.filename:` is a glob the document basename
 must match.
diff --git a/docs/reference/schema-types.md b/docs/reference/schema-types.md
@@ -0,0 +1,144 @@
+---
+summary: >-
+  Named field-type shortcuts for inline schema
+  frontmatter values — the registered names, the
+  canonical CUE each one resolves to, and example
+  usage.
+---
+# Schema field types
+
+A **field-type shortcut** is a short name a schema
+frontmatter value can use instead of spelling out a CUE
+expression. `created: date` is shorter and harder to
+typo than `created: '=~"^\\d{4}-\\d{2}-\\d{2}$"'`, and
+every project using the shortcut gets the same regex —
+no three projects land on three slightly different ISO
+patterns.
+
+Shortcuts work the same way for inline schemas
+(`kinds.<name>.schema:`) and for proto.md frontmatter.
+The library ships embedded in the mdsmith binary; no
+network access is needed to resolve a shortcut.
+
+## How a value is interpreted
+
+A frontmatter value (right-hand side of `key: value` in
+the schema's `frontmatter:` block) is classified by
+shape:
+
+| Shape                                       | Treatment                                                              |
+|---------------------------------------------|------------------------------------------------------------------------|
+| Bare identifier in the shortcut registry    | Substituted with the canonical CUE expression                          |
+| Bare identifier that is a CUE built-in type | Passes through verbatim (`string`, `int`, `bool`, `float`, `bytes`, …) |
+| Bare identifier that is neither             | **Config error** naming the field and the unknown name                 |
+| Anything else (operators, quotes, …)        | Passes through verbatim as raw CUE                                     |
+
+A "bare identifier" is a YAML scalar matching
+`[a-zA-Z_][a-zA-Z0-9_-]*` — letters, digits,
+underscores, and hyphens, starting with a letter or
+underscore. Anything containing whitespace, operators,
+quotes, brackets, or other punctuation is treated as
+raw CUE.
+
+The strict third row catches typos at config-load
+time. A schema that writes `created: iso-date` errors
+with `unknown shortcut "iso-date"` instead of sliding
+through to an undefined-reference error deep in CUE
+evaluation.
+
+## Registered shortcuts
+
+The following names are accepted in a schema
+frontmatter value:
+
+| Name       | Canonical CUE                                                             | Accepts                | Rejects               |
+|------------|---------------------------------------------------------------------------|------------------------|-----------------------|
+| `date`     | `=~"^\\d{4}-\\d{2}-\\d{2}$"`                                              | `2024-05-01`           | `2024-5-1`            |
+| `datetime` | `=~"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z\|[+-]\\d{2}:\\d{2})?$" ` | `2024-05-01T12:30:00Z` | `2024-05-01 12:30:00` |
+| `time`     | `=~"^\\d{2}:\\d{2}(:\\d{2})?$"`                                           | `12:30`                | `12:3`                |
+| `email`    | `=~"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"`                                      | `user@example.com`     | `user@@example`       |
+| `url`      | `=~"^https?://"`                                                          | `https://example.com`  | `ftp://example.com`   |
+| `filename` | `=~"^[A-Za-z0-9._-]+\\.md$"`                                              | `notes.md`             | `notes.txt`           |
+| `nonEmpty` | `string & !=""`                                                           | `hello`                | `""`                  |
+
+The regex bodies are shape-only. `date` accepts
+`2024-02-30` even though February never has 30 days;
+semantic validation is out of scope.
+
+## Inline schema example
+
+```yaml
+kinds:
+  rfc:
+    schema:
+      frontmatter:
+        created: date
+        modified: datetime
+        contact: email
+        homepage: url
+      require:
+        filename: "RFC-[0-9][0-9][0-9][0-9].md"
+```
+
+`mdsmith check` validates every file in the `rfc` kind:
+`created` must match the ISO-date regex, `contact` must
+look like an email, and so on.
+
+## proto.md example
+
+The same shortcuts work in a proto.md schema's YAML
+frontmatter:
+
+```markdown
+---
+created: date
+homepage: url
+---
+# ?
+
+## Goal
+
+## Tasks
+```
+
+Substitution happens at schema-load time. After that
+the validator treats the canonical CUE the same way
+whether a user typed it out or the loader expanded
+the shortcut.
+
+## Composing a shortcut with extra constraints
+
+A value that needs both a shortcut and an extra
+constraint is **not** a bare name. Write the canonical
+CUE directly:
+
+```yaml
+frontmatter:
+  created: '=~"^\\d{4}-\\d{2}-\\d{2}$" & >="2020-01-01"'
+```
+
+The shortcut form is only triggered when the value is
+exactly the bare name. Anything more complex passes
+through as raw CUE.
+
+## Adding a shortcut
+
+The library lives at `cue/types/types.cue` in this
+repository. The runtime registry is in
+`internal/schema/shortcuts.go`; a drift test pins the
+two to each other. User-defined shortcuts are not yet
+a configuration surface — a project that needs a
+custom shortcut should write the canonical CUE in a
+shared proto.md (or wait for a follow-up plan if the
+need recurs).
+
+## See also
+
+- [Schemas](../guides/schemas.md) — the broader story
+  on inline schemas, proto.md, and per-scope rule
+  overrides.
+- [MDS020](../../internal/rules/MDS020-required-structure/README.md)
+  — the rule that surfaces schema diagnostics.
+- [File kinds](../guides/file-kinds.md) — how kinds
+  attach schemas (and other rule config) to file
+  groups.
diff --git a/internal/rules/MDS020-required-structure/README.md b/internal/rules/MDS020-required-structure/README.md
@@ -345,12 +345,12 @@ Describe the goal here.
 - **Status**: ready
 - **Default**: enabled
 - **Fixable**: index side-output only (when `schema.index:` is set)
-- **Implementation**:
-  [source](./)
+- **Implementation**: [source](./)
 - **Guide**:
   [directive guide](../../../docs/guides/directives/enforcing-structure.md)
 - **Category**: meta
 
 ## See also
 
 - [Placeholder grammar](../../../docs/background/concepts/placeholder-grammar.md)
+- [Schema field types](../../../docs/reference/schema-types.md)
diff --git a/internal/schema/parse_inline.go b/internal/schema/parse_inline.go
@@ -105,13 +105,28 @@ func parseInlineFrontmatter(raw map[string]any, sch *Schema) error {
 // string. Strings pass through (the canonical form). Numbers, bools,
 // nulls become their JSON encoding. Maps and lists are JSON-encoded
 // so the value carries its structure verbatim into CUE.
+//
+// A YAML scalar that is a single bare identifier (`date`, `bool`,
+// `iso-date`) goes through the shortcut registry first: registered
+// names are rewritten to their canonical CUE expression, CUE
+// built-ins pass through verbatim, and an unknown bare name is
+// rejected with a clear error so a typo surfaces at config-load
+// time instead of as an undefined CUE reference deep in
+// validation. See `internal/schema/shortcuts.go` and plan 148.
 func frontmatterExpr(v any) (string, error) {
 	switch x := v.(type) {
 	case string:
 		expr := strings.TrimSpace(x)
 		if expr == "" {
 			return "", fmt.Errorf("expression must be non-empty")
 		}
+		resolved, handled, err := resolveBareName(expr)
+		if err != nil {
+			return "", err
+		}
+		if handled {
+			return resolved, nil
+		}
 		return expr, nil
 	case bool, int, int64, float64, nil:
 		b, err := json.Marshal(x)
diff --git a/internal/schema/shortcuts.go b/internal/schema/shortcuts.go
diff --git a/internal/schema/shortcuts_test.go b/internal/schema/shortcuts_test.go
diff --git a/plan/148_named-field-type-shortcuts.md b/plan/148_named-field-type-shortcuts.md
