feat: validate and coerce date, path, and wikilink formats

- Coerce Date objects (from gray-matter/js-yaml YAML parsing) to YYYY-MM-DD
  strings in the markdown plugin read phase, before schema validation
- Register real validators for date (YYYY-MM-DD), path (non-empty, no null
  bytes), and wikilink ([[...]]) formats in the AJV instance
- Add wikilink as a format annotation alternative to the existing $ref-based
  definition — both options now work
- Add shared test fixture schema (tests/fixtures/test-schema.json) covering
  all three formats, usable across future tests
- Document custom format annotations and date coercion in docs/schemas.md

Closes #79

Author: mindsocket

docs/schemas.md

@@ -48,6 +48,38 @@ Main types:
 
 This schema composes shared structural defs and strict metadata/rules from partials.
 
+## Custom format annotations
+
+`ost-tools` registers the following `format` annotations beyond standard JSON Schema. All apply to `string` properties and are validated at schema validation time.
+
+| Format | Validates | Example |
+|--------|-----------|---------|
+| `date` | ISO 8601 date (`YYYY-MM-DD`) | `"2026-03-31"` |
+| `path` | Non-empty filesystem path — absolute, relative, or a plain name | `"notes"`, `"./subdir/file.md"`, `"/abs/path"` |
+| `wikilink` | Obsidian wikilink syntax (`[[...]]`) | `"[[Parent Node]]"` |
+
+`path` and `wikilink` are also available as shared `$ref` definitions in `_ost_tools_base.json`:
+
+```json
+{ "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" }
+```
+
+Using `format` directly is more concise when the full definition isn't needed:
+
+```json
+{ "type": "string", "format": "wikilink" }
+```
+
+### Date coercion
+
+YAML parsers (gray-matter, js-yaml) coerce unquoted ISO dates to JavaScript `Date` objects:
+
+```yaml
+published_date: 2026-03-31   # parsed as a Date object by gray-matter
+```
+
+The markdown plugin automatically coerces `Date` objects to `YYYY-MM-DD` strings before validation, so unquoted dates in frontmatter and embedded YAML blocks work correctly with `format: "date"` fields.
+
 ## Metadata dialect
 
 Schemas use this metaschema URL:

src/plugins/loader.ts

@@ -89,7 +89,7 @@ export async function loadPlugins(
 ): Promise<LoadedPlugin[]> {
   const builtinsByName = new Map(builtinPlugins.map((p) => [p.name, p]));
   const ajv = new Ajv();
-  ajv.addFormat('path', () => true);
+  ajv.addFormat('path', (value: string) => value.length > 0 && !value.includes('\0'));
   const loaded: LoadedPlugin[] = [];
 
   // External plugins: entries in the map that are not built-in names

src/plugins/markdown/parse-embedded.ts

@@ -12,7 +12,7 @@ import type {
   SchemaMetadata,
   SharedEmbeddingFields,
 } from '../../plugin-api';
-import { applyFieldMap } from './util';
+import { applyFieldMap, coerceDates } from './util';
 
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export const ON_A_PAGE_TYPES = ['ost_on_a_page', 'space_on_a_page'];
@@ -831,7 +831,7 @@ export function extractEmbeddedNodes(body: string, options: ExtractEmbeddedOptio
         const code = child as Code;
         const parsed = yamlLoad(code.value);
         if (parsed && !Array.isArray(parsed) && typeof parsed === 'object') {
-          Object.assign(activeNode.schemaData, applyFieldMap(parsed as Record<string, unknown>, fieldMap));
+          Object.assign(activeNode.schemaData, coerceDates(applyFieldMap(parsed as Record<string, unknown>, fieldMap)));
         } else if (Array.isArray(parsed)) {
           throw new Error(`YAML block must be an object at "${activeNode.label}".`);
         } else {

src/plugins/markdown/read-space.ts

@@ -6,7 +6,7 @@ import type { BaseNode } from '../../plugin-api';
 import type { ParseResult, PluginContext } from '../util';
 import type { MarkdownPluginConfig } from '.';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
-import { applyFieldMap } from './util';
+import { applyFieldMap, coerceDates } from './util';
 
 type ReadSpaceDirectoryOptions = {
   includeOnAPageFiles?: boolean;
@@ -83,7 +83,7 @@ export async function readSpaceDirectory(
       continue;
     }
 
-    const data = applyFieldMap(parsed.data, fieldMap);
+    const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
 
     if (!data.type) {
       nonSpace.push(file);

src/plugins/markdown/util.ts

@@ -1,3 +1,22 @@
+/**
+ * Coerce Date objects in frontmatter/YAML data to ISO date strings (YYYY-MM-DD).
+ * gray-matter and js-yaml parse unquoted ISO dates (e.g. `date: 2026-03-31`) as
+ * JavaScript Date objects, which are not valid JSON and fail string type validation.
+ */
+export function coerceDates(data: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value instanceof Date) {
+      result[key] = value.toISOString().slice(0, 10);
+    } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      result[key] = coerceDates(value as Record<string, unknown>);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 /**
  * Apply field remapping to a data object.
  * Renames keys according to fieldMap (file field name → canonical field name).

src/schema/schema.ts

@@ -84,8 +84,9 @@ function compileValidator(
   schemaRefRegistry: Map<string, AnySchemaObject>,
 ): ValidateFunction {
   const ajv = new Ajv();
-  ajv.addFormat('path', () => true);
-  ajv.addFormat('date', () => true);
+  ajv.addFormat('path', (value: string) => value.length > 0 && !value.includes('\0'));
+  ajv.addFormat('date', (value: string) => /^\d{4}-\d{2}-\d{2}$/.test(value));
+  ajv.addFormat('wikilink', (value: string) => /^\[\[.+\]\]$/.test(value));
   ajv.addKeyword({
     keyword: '$metadata',
     schemaType: 'object',

tests/fixtures/date-coercion/valid/article.md

@@ -0,0 +1,7 @@
+---
+type: note
+title: Article Note
+date: 2026-03-31
+---
+
+A note with an unquoted YAML date in frontmatter.

tests/fixtures/test-schema.json

@@ -0,0 +1,31 @@
+{
+  "$id": "test://test-schema",
+  "description": "Minimal schema for unit and integration tests. Extend with additional types as test coverage requires new scenarios.",
+  "oneOf": [
+    {
+      "type": "object",
+      "description": "A simple note type with an optional date field for testing date coercion and format validation.",
+      "properties": {
+        "type": { "const": "note" },
+        "title": { "type": "string" },
+        "date": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO 8601 date (YYYY-MM-DD)"
+        },
+        "path": {
+          "type": "string",
+          "format": "path",
+          "description": "A filesystem path (absolute, relative, or plain filename)"
+        },
+        "related": {
+          "type": "string",
+          "format": "wikilink",
+          "description": "An Obsidian wikilink, e.g. [[Other Note]]"
+        }
+      },
+      "required": ["type", "title"],
+      "additionalProperties": true
+    }
+  ]
+}

tests/plugins/markdown/util.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'bun:test';
+import { coerceDates } from '../../../src/plugins/markdown/util';
+
+describe('coerceDates', () => {
+  it('converts a Date object to YYYY-MM-DD string', () => {
+    const result = coerceDates({ date: new Date('2026-03-31') });
+    expect(result.date).toBe('2026-03-31');
+  });
+
+  it('leaves string values unchanged', () => {
+    const result = coerceDates({ date: '2026-03-31', title: 'hello' });
+    expect(result.date).toBe('2026-03-31');
+    expect(result.title).toBe('hello');
+  });
+
+  it('leaves numbers and booleans unchanged', () => {
+    const result = coerceDates({ count: 3, active: true });
+    expect(result.count).toBe(3);
+    expect(result.active).toBe(true);
+  });
+
+  it('recurses into nested objects', () => {
+    const result = coerceDates({ meta: { created: new Date('2025-01-01') } });
+    expect((result.meta as Record<string, unknown>).created).toBe('2025-01-01');
+  });
+
+  it('does not recurse into arrays', () => {
+    const dates = [new Date('2025-01-01')];
+    const result = coerceDates({ items: dates });
+    expect(result.items).toBe(dates);
+  });
+});

tests/validate/date-coercion.test.ts

@@ -0,0 +1,51 @@
+import { beforeAll, describe, expect, it } from 'bun:test';
+import { join } from 'node:path';
+import { readSpaceDirectory } from '../../src/plugins/markdown/read-space';
+import { createValidator } from '../../src/schema/schema';
+import { makePluginContext } from '../helpers/context';
+
+const TEST_SCHEMA_PATH = join(import.meta.dir, '../fixtures/test-schema.json');
+const VALID_DIR = join(import.meta.dir, '../fixtures/date-coercion/valid');
+
+const validateNode = createValidator(TEST_SCHEMA_PATH);
+
+describe('date coercion and format validation', () => {
+  describe('readSpaceDirectory with unquoted YAML date', () => {
+    let nodes: Awaited<ReturnType<typeof readSpaceDirectory>>['nodes'];
+
+    beforeAll(async () => {
+      ({ nodes } = await readSpaceDirectory(makePluginContext(VALID_DIR, TEST_SCHEMA_PATH)));
+    });
+
+    it('produces one node', () => {
+      expect(nodes).toHaveLength(1);
+    });
+
+    it('coerces Date object to ISO date string', () => {
+      expect(nodes[0]?.schemaData.date).toBe('2026-03-31');
+      expect(nodes[0]?.schemaData.date).toBeTypeOf('string');
+    });
+
+    it('coerced date passes schema validation', () => {
+      expect(validateNode(nodes[0]?.schemaData)).toBe(true);
+    });
+  });
+
+  describe('format: "date" schema validation', () => {
+    it('accepts a valid ISO date string', () => {
+      expect(validateNode({ type: 'note', title: 'Test', date: '2026-03-31' })).toBe(true);
+    });
+
+    it('rejects a non-date string', () => {
+      expect(validateNode({ type: 'note', title: 'Test', date: 'not-a-date' })).toBe(false);
+    });
+
+    it('rejects a datetime string for a date field', () => {
+      expect(validateNode({ type: 'note', title: 'Test', date: '2026-03-31T00:00:00Z' })).toBe(false);
+    });
+
+    it('rejects a Date object (unconverted)', () => {
+      expect(validateNode({ type: 'note', title: 'Test', date: new Date('2026-03-31') })).toBe(false);
+    });
+  });
+});