TypedMark Schema Boundary

The schema/json-schema/ directory contains machine-readable JSON Schemas (draft 2020-12) for the governed TypedMark artifacts. They validate document shape so that tools, editors, CI pipelines, and agents can catch authoring errors early without re-deriving the artifact contracts from prose.

The prose specification is the single source of truth. The schemas complement it and never override it: where a schema and the specification disagree, the specification wins and the schema has a bug.

conformance-vector.schema.json and conformance-query.schema.json are separate harness schemas for the non-normative vector.json setup and query-cases.json cases described in the conformance runner guide. They do not define governed collection artifacts. The fixture gate checks shape, declared requirements, disjointness, expected evaluated sets, query-case names, rule references, and projected columns. Actual adapter capabilities, scope selection, query results, and expected semantic failures are checked by the executable runner.

Artifact map#

Managed notes as complete documents are deliberately not covered: their frontmatter is validated against the collection's effective note-type schemas, which only exist after the semantic layer composes property sets and inheritance. A document schema cannot express them. Independently parseable content-expansion and template-region descriptors are covered by their descriptor schemas, and the core-defined template_regions value is covered separately by template-tracking.schema.json.

What the schemas enforce#

• required, defaultable, and allowed keys per artifact, with additionalProperties: false wherever the specification closes the key set
• scalar types, identifier grammars (name, slugs, field names), and enums (kind, property types, formats, severities, archive policies, history ops)
• scalar-only allowed_values entries under Field Definition Reference, with JSON-exact uniqueness; declared-type compatibility and normalized field-value equality remain semantic checks
• optional collection extensions declarations and report extension maps: namespaced identifier keys and exact complete SemVer string values, including prerelease and build suffixes; empty maps are accepted, ranges and whitespace in extension versions are not
• inert x_* metadata only at the top level of collection configurations, note-type schemas, property sets, automations, datasets, saved views, and history frontmatter; existing field constraints and closed structural blocks remain unchanged; extension identifiers and metadata keys use explicit end-of-input assertions so line terminators cannot trail a valid name
• local conditional rules: type: list requires items, type: link/time require a matching format, generation/constant/default exclusivity, per-type constraint applicability (not_blank, regex, min/max, allowed_values, unique, computed), abstract types not declaring composition references, archive-policy-dependent required keys, version requiring scaffold, mandatory-tag declaration grammar and uniqueness, field operations declaring exactly one of note_type/property_set, automation trigger and action variants, event snapshot and body-change combinations, causal producer variants, and automation run-report status/diagnostic combinations
• content-expansion descriptor keys, source variants, sync modes, persisted state, current-time restrictions, and render-block shape
• portable-query descriptor keys; recursive boolean, path, field, and relationship predicate variants; direct and mapped projection variants; mapped source shapes; ordering, grouping, count-range, and limit shapes
• dataset keys, nested query shape, row-identity grammar, and saved-view keys, embedded-query or dataset-reference exclusivity, presented-field entries, layout families, and board-layout configuration
• template-region descriptor keys and identifier grammar, plus baseline and detached receipt variants in a managed note's template_regions value
• Core field types and compatible declaration constraints, including the ban on a redundant note_type field definition; template_regions is runtime tracking state and cannot be schema-declared
• validation-report codes, severities, required extension context for unsupported_extension, and required evaluation, required_extensions, and evaluated_extensions fields; valid is true exactly when evaluation is complete and there are no emitted error results
• reports carrying an EXT-2, EXT-4, or EXT-6 declaration diagnostic have incomplete evaluation under CR-102

What stays in the semantic layer#

These rules are normative but cannot (or should not) be expressed in JSON Schema:

• Unicode-aware comparison and regex preprocessing under Foundations; schema keywords do not themselves perform NFC normalization
• filesystem checks: effective identifiers match basenames, explicitly named templates exist, implicit templates can be derived, and artifact locations derive from metadata_directory
• cross-file resolution: extends chains and cycle detection, property-set references, exclude_property_sets membership in default_property_sets, frontmatter_remove targeting inherited fields, relationship and field targets resolving to note types, scaffold note-type references (SCE-17), composition source resolution
• effective-schema computation: the local or enabled-Reuse evaluation pipeline, block merge rules, and the required effective keys for concrete note types
• mandatory-tag semantics: collection/note-type merge order, exact duplicate removal, compatibility with the effective tags field, template obligations, managed-note membership, and append-only materialization
• canonical expansion: applying effective defaults for omitted metadata_directory, exclude_paths, validation_defaults, abstract, labels, field values, and conventional/derived templates; absent archive blocks use active storage
• value semantics: default_value/const_value/allowed_values conformance to the declared type, min <= max, regex dialect, storage placeholder resolution, generation-strategy value production, shared expression-language syntax, consumer-specific reference resolution, transform validity, null handling, and stored-value agreement (all tool / validator-time behaviors)
• managed-note conformance: note-type association, sparse effective values, explicit normalization, note-link syntax and resolution, unresolved placeholder links, relationship instance counting and cardinality, heading rules, storage-path conformance including archived state
• link-value interpretation: Note Links owns internal-link UTF-8 percent decoding and anchors; Field Definition Reference owns the separate URI-field grammar, including fragments
• field compatibility and conversion: directional type-pair classification, conditional-value qualification, target-constraint evaluation, finite-set compatibility, and safe write-back eligibility
• content-expansion semantics: marker parsing and pairing, source resolution and scalar conversion, relationship, query, dataset, and saved-view evaluation, shared-expression evaluation, embedded-query version and column agreement, rendered-region equality, template materialization, drift, and ejection
• portable-query semantics: note-type and abstract-descendant resolution, effective-field compatibility, typed comparisons, relationship traversal, projection-alias uniqueness and resolution, mapped-source overlap, declared conversion-class agreement, target compatibility, count-range consistency, compatible ordering domains, deterministic row order, grouping, and limiting
• dataset semantics: query-version agreement, projection-contract resolution, row-identity validity and uniqueness, source-backed/read-only classification, reference resolution, and schema-evolution compatibility
• saved-view semantics: query or dataset version agreement, projection-reference resolution, visible-field uniqueness, layout interpretation, explicit board-column equality, fallback-column placement, schema-evolution compatibility, and Bases conversion loss diagnostics
• template-region semantics: marker parsing and pairing, nesting boundaries, marker-to-receipt correspondence, region extraction, digest calculation, enrollment, three-way drift classification, reconciliation, and detachment
• system evolution: history release ordering under SCE-99 in Change History, inventory replay across note types, property sets, automations, fields, datasets, and saved views; migration impact computation; composition determinism; and canonical serialization
• automation semantics: artifact basenames and reference resolution, schedule due-instant evaluation, event matching, action target compatibility, capability negotiation, staged execution, and propagation termination
• specification-version support: artifact-local version selection, template version inheritance, and tool support for the compatibility lines defined in Foundations; a shape-valid version string does not establish that a tool implements that version
• extension semantics: namespace ownership, supported exact contracts and their applicable core compatibility lines, dependency resolution including omitted transitive dependencies, exact-version conflicts and cycles, and required declarations for extension-owned constructs; accepting a declaration's shape does not select or evaluate a contract
• vendor-metadata semantics: inertness, preservation on rewrite/composition, and reporting conflicts when composing different values at the same key; neither managed-note frontmatter nor template starter frontmatter receives a general x_* exemption from effective-schema validation
• report coverage: the CR-99 well-formed-entry projection from the collection, CR-102 incompleteness for malformed declarations even without visible findings, exact evaluated subset membership (including prerelease/build suffixes), complete coverage of required extensions, and truthful claims about which core and extension contracts were actually interpreted; standard JSON Schema cannot compare these dynamic property maps or observe tool capabilities
• report rule ownership: a well-formed built-in identifier still needs to name an active rule, and a qualified extension rule needs matching extension context and an actually evaluated required contract; report shape permits qualified third-party IDs without assigning them a repository-global prefix
• conformance evaluation: resolving the target mode, assigning effective severities (including fixed structural-key error severity), producing findings, and ordering validation results

The extension declaration shape, metadata scope, and capability rules are authoritative in Extensions and Capabilities; report coverage and completeness are authoritative in Validation Reports. Unknown structural keys remain schema failures under implemented contracts. If a tool lacks a required extension contract, a bare Core schema's rejection of a potentially extension-owned key is not evidence that the construct is invalid. Such a tool reports incomplete evaluation while still checking known, independent Core constraints. These schemas are not an extension loader.

Fixtures#

schema/fixtures/ contains three artifact buckets and one end-to-end suite:

• valid/ — artifacts that MUST pass their schema
• invalid-shape/ — artifacts that MUST fail their schema; each file's body names the violated rule
• invalid-semantic/ — artifacts that MUST pass their schema but are invalid under the semantic layer; see the README in that folder
• golden/ — self-contained collection trees paired with expected portable validation reports for implementers; see the README in that folder

Run the expectations with:

bun run validate-fixtures

Fixtures are mapped to artifact schemas by filename prefix (typedmark-*, note-type-*, property-set-*, history*, marketplace*, validation-report-*, automation-*, automation-event-*, and automation-run-report-*, expansion-*, template-region-*, and template-tracking-*, query-*, dataset-*, and view-*). Markdown fixtures are validated through their extracted frontmatter; .json fixtures such as marker descriptors, tracking receipts, the marketplace catalog, and validation reports are validated directly.

The checker decodes inspected text files as UTF-8 without replacement, including artifact bodies even though those bodies do not determine artifact shape. This applies to the existing schema, fixture, specification-example and golden-input read sites; it does not expand file discovery or decode binary assets. Markdown frontmatter recognizes LF, CRLF and CR lines and consumes one leading BOM. JSON callers retain their existing BOM parsing behavior. Parsed frontmatter is checked as a mapping after YAML materialization, so a top-level tagged set is not an empty mapping; nested opaque tagged values remain intact. Source bytes are never rewritten.

Frontmatter extraction retains the final YAML content line break before the closing delimiter, so keep-chomp scalars retain their trailing blank lines. Classified YAML/YML fences likewise restore the content newline omitted from the Markdown parser's token text. Clipping and stripping remain YAML operations; neither extraction path trims scalar content. The governing grammar is in Foundations.

YAML parsing uses the fixed Core resolution profile from Foundations, including when a document contains a version directive. Legacy boolean words remain strings, leading-zero numbers use Core decimal resolution, and bare merge-looking keys stay ordinary mapping keys. Explicit known tags retain the existing Core-reader behavior. Duplicate-key checks use the resulting Core values; a directive does not switch their equality domain.

Before applying JSON Schema, the checker projects parsed YAML into a temporary shape view. Native tagged sets, ordered maps, timestamps and binary values do not count as JSON objects. Unconstrained vendor metadata, default and constant positions still accept them; declared-type conformance remains a semantic check. allowed_values instead has a scalar-only item shape, so malformed object/sequence entries cannot reach AJV's recursive object equality. The iterative projection preserves aliases and own property names without modifying the parsed model, and does not recurse through the JavaScript call stack for deep opaque metadata. This is checker behavior, not a new YAML-tag restriction.

The golden-vector check validates collection layout, governed-artifact shapes, schema, automation, dataset, and view basenames, referenced template existence, report shape, and canonical result ordering (including the final extension component). It also checks the expected report's required map against the collection's well-formed declared requirements, malformed-declaration incompleteness, exact evaluated-map subset membership, and coverage of every required extension for complete reports. These are fixture-integrity checks, not evidence of actual contract interpretation. Incomplete reports may have no missing extension entries because core interpretation can also be incomplete. The checker deliberately does not infer semantic findings; that behavior belongs to an executable conformance runner.

The extension capability matrix in fixtures/valid/README.md and the semantic-only cases in fixtures/invalid-semantic/README.md use illustrative external contract assumptions. They do not claim an executable extension-aware conformance runner exists.

The non-normative Conformance Runner Guide describes a proposed implementation architecture beyond these shape checks.

The malformed-extension report examples assume a declaration containing the retained typedmark:reuse and example:future requirements, an invalid bad identifier, and a numeric typedmark:queries version. The suppressed example uses the same declaration with its diagnostic category disabled. Source-aware coverage tests check that suppression does not make this declaration complete; the report schema alone cannot recover a suppressed source error.

Specification example annotations#

The same command checks fenced yaml, yml, json, markdown, and md examples in the root specification pages. Each has a preceding HTML comment classifying its validation scope; missing, malformed, unknown, and orphaned classifications fail the check. Backtick and tilde fences, including longer fences containing shorter ones, are recognized by the existing Markdown lexer. Diagnostics include the source page and opening fence line.

• <!-- typedmark-example: artifact=typedmark --> selects the full artifact schema explicitly, independently of keys present in the example. The target is a name in ARTIFACT_SCHEMAS in schema/validate-fixtures.ts, including standalone descriptors and reports. YAML and JSON are parsed directly; Markdown examples have their governed frontmatter extracted. Parse failures, missing identification fields, and missing versions are errors, not skips.
• <!-- typedmark-example: fragment: Individual field declaration. --> marks an intentional partial YAML or JSON example. A non-empty reason explains the scope. Fragments are syntax-checked, but not counted as full schema checks.
• <!-- typedmark-example: body: Managed-note template. --> marks a Markdown body, managed note, or template rather than a governed frontmatter artifact. A non-empty reason is required. These examples are not artifact-schema checks; managed-note conformance, embedded marker semantics, and template content are outside this check.

These non-rendered comments are repository authoring metadata, not a new TypedMark artifact format or normative contract. The command's fixture total counts full artifact examples, not fragments or body examples.

Recommended validation workflow for implementations#

1. extract the governed artifact's frontmatter per the Frontmatter Block Grammar and parse it as YAML
2. select supported artifact-local core and required extension contracts, then validate document shape with the applicable schemas; do not misclassify potentially extension-owned structure solely because a required contract is unsupported
3. build effective models (composition, inheritance, property sets)
4. run semantic validation against the prose rules
5. report shape failures separately from semantic failures, using the effective severity rules and recording evaluation completeness independently of diagnostic severity or suppression

Maintenance rules#

• every normative change to a governed artifact's shape MUST update the JSON Schemas and the fixtures in the same change
• every schema change MUST keep bun run validate-fixtures passing
• rules the schemas cannot express MUST be listed in this document
• schemas MUST NOT silently redefine or extend normative prose behavior