Fix TypeBox schema consistency and add TypeBox patterns research

- schemas.md: Replace interface ResolvedTaskAttributes with TypeBox schema
  + Static<typeof> derivation (was the only raw interface in the doc set)
- schemas.md: Add explicit TypeBox naming convention table and pattern guide
- schemas.md: Use Nullable() helper for TaskInput optional categorical fields
  that can be explicitly set to null in YAML
- schemas.md: Reference typebox-patterns.md research for full analysis
- api-surface.md: Add note about Static<typeof> pattern consistency
- errors-validation.md: Use Value.Errors() for structured validation instead
  of bare Value.Check()
- New: docs/research/typebox-patterns.md — comprehensive TypeBox pattern
  evaluation covering Static, Values, Convert, Pointer, TemplateLiteral,
  generics, defaults, and concrete schema recommendations
This commit is contained in:
2026-04-26 07:57:23 +00:00
parent 235328813e
commit ac9dee9c10
4 changed files with 1076 additions and 39 deletions

View File

@@ -65,7 +65,7 @@ Two validation levels, consistent with the Rust CLI's `validate` command:
### 1. Schema validation (`validateSchema()`)
TypeBox `Value.Check` on input data — frontmatter fields, enum values, required fields. Returns `ValidationError[]`. Catches:
TypeBox `Value.Check()` on input data — frontmatter fields, enum values, required fields. Returns `ValidationError[]`. The validation pipeline uses `Value.Errors()` for structured field-level detail (path, message, value) rather than `Value.Assert()` which throws without detail. `Value.Clean()` strips unknown properties before validation when processing untrusted input (e.g., frontmatter from external files). Catches:
- Missing required fields (`id`, `name`)
- Invalid enum values (e.g., `risk: "extreme"`)
- Type mismatches (e.g., `dependsOn: "not-an-array"`)