Why not use JSON Schema for frontmatter validation?

[tonyxiao]

Summary

Has the project considered adopting JSON Schema for frontmatter validation instead of a separate custom field/type format in _types/*.md?

Context

I'm evaluating mdbase for a typed Markdown collection and the path/type matching model makes sense, but the schema layer appears to reinvent functionality that JSON Schema already covers for validating YAML frontmatter fields.

Examples of the current custom schema surface include:

• custom scalar/object/list field definitions
• required, enum, nested fields, nested items
• collection-specific validation semantics layered on top

Question

Was the custom schema format chosen intentionally over JSON Schema for a specific reason?

More concretely:

1. Was JSON Schema considered and rejected?
2. If so, what limitations made it a poor fit?
3. Could mdbase support JSON Schema for frontmatter validation while keeping the markdown-specific parts (match.path_glob, link, query/formula features, rename semantics, etc.) in its own config layer?
4. If not, what is the main advantage of the current custom schema format over reusing JSON Schema for field validation?

Why I'm asking

From a consumer perspective, JSON Schema would seem to offer a few advantages:

• reuse of existing tooling and validators
• less custom syntax to learn
• easier interoperability with TypeScript/codegen/editor tooling
• a clearer separation between document validation and collection-specific behavior

I can see why mdbase needs custom collection behavior, but I don't yet see why that necessarily implies a custom field schema language too.

Curious whether this was a deliberate product decision, an implementation simplification, or something else.

[callumalpass]

Thanks for the question, @tonyxiao, I think it is a good one!

JSON Schema has appeal here, especially for frontmatter validation. A lot of the field-level surface in mdbase overlaps with things it already handles well: required fields, enums, nested objects, lists, numeric bounds, string lengths, and regex checks.

What makes me hesitant is how much behavior in mdbase depends on the collection rather than the current document. The spec describes the shape of frontmatter as well as how files get associated with types, how they refer to one another, how values can be derived, and how validation can depend on the rest of the collection.

Type matching is one place where this shows up quickly. A schema is not always chosen explicitly by the caller. A file can pick up a type from its path, from the presence of certain fields, or from a match condition. More than one type can apply at once, and explicit type keys change the flow again. JSON Schema can validate once you know which schema to apply, though the logic that decides which schema applies would still need to live somewhere else.

The multi-type case seems important too. When two types describe the same field differently, mdbase defines what happens: some constraints tighten by intersection, some settings must agree exactly, and some combinations are errors. JSON Schema composition can express “must satisfy both,” though it does not really capture mdbase’s multi-type merge rules or conflict behavior.

Links feel like another strong example. A link field can be a wikilink, a markdown link, or a bare path. Resolution depends on the current file, the collection root, the configured id field, and sometimes the target type. Validation can depend on whether the destination currently exists. Cross-file uniqueness has a similar shape: requiring a field to be unique across all records of a type means looking outside the current file. Tooling around JSON Schema could enforce those things, though the rules would still be coming from mdbase.

Generated and computed fields, like uuid, now, sequence, and related features describe write-time behavior that can depend on ordering or collection state. Computed fields go further: they are evaluated at read time, not persisted, queryable, and able to shadow a persisted key.

I also like the type file format itself. Definitions are readable markdown files that live inside the collection and can carry body text. That gives a natural place for examples, conventions, and caveats that would otherwise drift into separate docs. I have found that useful.

Working on the mdbase lsp has made the value of the collection-aware parts of the schema much clearer. Matching, links, cross-file checks, generated values, and path conventions have all turned out to matter quite a bit. mdbase is very much collection-focused, and I think that is one of its stronger ideas.

JSON Schema compatibility still seems worth pursuing, just not as the primary model. A more plausible direction might be derivation: tooling could generate a JSON Schema from the subset of an mdbase type that maps cleanly to JSON Schema, covering ordinary fields and constraints while leaving collection-specific behavior in mdbase itself. That would capture some ecosystem benefits without requiring the spec to use JSON Schema as the canonical source of truth.