Skip to content

Check every page the family edits against the schema of its type #192

Open

Description

@arthware-dev

Story

As a family member who edits the family's pages by hand (Forgejo, Obsidian, stack memory write), I want every page checked against the schema of its type, so that a mistake is named with its path instead of silently read as an empty page.

Context

lib/stack/frontmatter.py holds the format's parser and a schema per type (SCHEMAS, and DECLARED_SCHEMAS for the person files from #191). Two gaps remain:

  • Types and fields without a schema. todos (a state document, docs/design/brain/vault-format.md §7) has none, so it cannot be validated at all. The validator knows required, list and single-value fields, but not allowed values: relation_kind lists nine values in vault-format §5 and anything passes.

  • Readers that bypass the validator. They parse frontmatter on their own and turn an error into an empty dict, so a broken page reads as a page without metadata:

    • stacklets/memory/lib.py _parse_frontmatter wraps the strict parser and returns {} on any exception (search).
    • stacklets/memory/bot/cli/diary.py:388 and stacklets/docs/bot/vault_entry.py:668 parse with PyYAML and return {} on a YAML error.
    • stacklets/memory/bot/cli/wiki.py:164 uses PyYAML to decide whether a page's frontmatter is broken.

    PyYAML accepts more than the format allows, so these readers and the validator can disagree about the same file.

The person files in #191 show the pattern: one reader, strict parse plus validate(), a broken file passed to a report callback with its path and left out, and nothing destructive done while one is broken.

Proposal

  • Add a schema for todos, and allowed values for enum fields (relation_kind first), in lib/stack/frontmatter.py, with vault-format.md updated in the same change.
  • Move the four readers above onto stack.frontmatter.parse and validate(). A page that fails is reported by path where the reader's operator looks (curator log, stack memory prompt, archivist log) and left out, never read as empty.
  • Drop PyYAML from the frontmatter paths it then no longer serves.

Out of scope: new page types, the dream cycle, changing the format itself.

Definition of done

  • A todos.md with a field outside its schema is reported by path by the curator, and its todos are left untouched.
  • A person page with relation_kind: cousin fails validate() with a message naming the allowed values.
  • A vault entry with frontmatter outside the format is named by path in the archivist log, instead of surfacing in search without metadata.
  • Caller-side tests pin each of the three, against the format in vault-format.md, not against the implementation.
  • No frontmatter is parsed with PyYAML outside lib/stack/frontmatter.py; the archivist's message catalogue (archivist.py:190) is not frontmatter and stays.
  • docs/design/brain/vault-format.md lists every schema the validator enforces.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions