JSONHTL allows top-level keys alongside content. This document defines the conventional metadata keys used in this system and how to keep routing guidance visible to humans.
title (string) — human-readable title for the document.
version (integer) — version number for the document. An LLM or tool that remembers the version it last read can skip re-reading unchanged documents.
created (string, ISO date) — date the document was created.
updated (string, ISO date) — date the document was last modified.
tags (list of strings) — freeform tags for categorisation and search.
Skill-style metadata is useful because it tells an agent when a document should be read. In notes, that guidance must also be visible in the UI browser and HTML renderer. Until JSONHTL, the linter, and both renderers support dedicated routing fields, put this information in normal content near the top of the note.
Recommended visible sections:
• Purpose — one short paragraph explaining what the note is for.
• Read When — a short list of situations that should trigger reading the note.
Use these sections for convention notes, operational guides, and any note that governs agent behaviour. Keep them concise so the note remains cheap to scan.
A future JSONHTL/schema change may add top-level fields such as description and read_when. Do not rely on those fields until the JSONHTL schema, linter, UI browser, and HTML renderer all handle them. Otherwise agents may read them while humans cannot see them, or the linter may reject otherwise useful notes.
Per the JSONHTL spec, consumers should ignore any top-level keys they do not recognise. The strict linter may still flag unregistered keys. Register new metadata here and in the schema/linter notes before using it broadly.