[IDEA] Field schema

[linonetwo]

Is your idea related to a problem? Please describe.

TiddlyWiki/Cerebrus#11 because a caption is changed to singular field, cause program depend on it to fail.
But without context, you won't know why that field is neceessary.

In JSON world we use JSON-LD with RDFSchema or simply use JSONSchema to solve this.

Describe the solution you'd like

Use tag or schema or @type field that point to a tiddler or url, which contains a schema.
And that schema tiddler could contains necessary description, and we could use CI to auto check tiddlers matching schema, and show text for human to get context.

And each field is documended in a tiddler, with fields like field-type enum-values

Similar to what we planned to document filter operator and action widgets for auto building UI:

My instinct would be for each item of data to be stored as a separate tiddler, but I appreciate that that might lead to a proliferation of tiddlers.
#8154 (comment)

Describe alternatives you've considered

https://github.com/tiddly-gittly/super-tag/ use text fiels for real JSON Schema, and type use application/json, I think it is bad now, because it is hard to read and edit, also waste the text field.

Additional context

(Below is Plan mode claude sonnet 4.6 AI generated detailed explaination)

Proposal: Native Schema Convention for Flat TiddlyWiki5 Tiddler Fields

Problem:
TiddlyWiki5 tiddlers use a flat key-value structure with no field contract or schema. This means that when a field name changes (e.g., caption → singular), tools and plugins relying on the old name silently break. Storing a JSON Schema in the text field (as in super-tag) prevents that field from being used for human/LLM-readable content.

Design Goal:
Leverage TiddlyWiki’s native “tag as type” paradigm and sub-tiddler namespaces to define schemas, without using JSON or occupying the text field. The schema should be fully discoverable and filterable using TiddlyWiki’s own mechanisms.

---

Layer 1 — schema Pointer Field

Any tiddler (including tag tiddlers) can have a schema field pointing to the root tiddler of its schema:

title: $:/tags/ChangeType
text: Used for classifying change types in release notes, shown in UI labels.
schema: $:/schemas/ChangeType

This avoids polluting the type field (which is for MIME type) and keeps text free for human/LLM content. Tools can easily query [[$:/tags/ChangeType]get[schema]].

---

Layer 2 — Schema Root Tiddler

Located at a conventional path like $:/schemas/TypeName:

title: $:/schemas/ChangeType
tags: $:/tags/Schema
fields: singular plural description
text: Schema for ChangeType entries. Each ChangeType must have a singular field for UI and changenote enum validation...

• text: Human/LLM-readable schema description
• fields: List field enumerating all defined field names
• tags: $:/tags/Schema: For easy discovery of all schemas

---

Layer 3 — Field Definition Sub-Tiddlers

Each field is a separate tiddler under $:/schemas/TypeName/FIELDNAME:

title: $:/schemas/ChangeType/singular
text: The singular display name for this change type, used in UI and changenote validation.
field-type: string
required: yes
aliases: caption
deprecated-aliases: caption

title: $:/schemas/ChangeType/plural
text: Plural form, optional.
field-type: string
required: no

Key fields:

Field	Meaning
text	Human/LLM-readable field description
field-type	string / number / boolean / date / list / reference / enum
required	yes / no
aliases	Historical/alternate field names (space-separated list)
deprecated-aliases	Aliases that are deprecated (tools should warn but still accept)
enum-values	Allowed values for enum fields (list field or filter expression)

---

Layer 4 — Declaring Type on Constrained Tiddlers

Two supported ways:

A. Direct schema field:

title: $:/config/ReleasesInfo/change-types/bugfix
schema: $:/schemas/ChangeType
singular: Bugfix
plural: Bugfixes

B. Via tag inheritance (preferred in TW5):

title: $:/config/ReleasesInfo/change-types/bugfix
tags: $:/tags/ChangeType
singular: Bugfix

The tag tiddler $:/tags/ChangeType carries schema: $:/schemas/ChangeType, so tools can infer the schema from the tag.

---

Solving the caption → singular Problem

Add a field definition tiddler:

title: $:/schemas/ChangeType/singular
text: The singular display name for this change type.
field-type: string
required: yes
aliases: caption
deprecated-aliases: caption

Tools like Cerebrus can then:

1. Read the aliases field from $:/schemas/ChangeType/singular
2. Dynamically build regexes or enum lists for validation, with no hardcoded field names

---

Comparison with Existing Approaches

Approach	text for human content	Native to TW5	Queryable	Tool-friendly
JSON Schema in text (super-tag)	❌	❌	Weak	Good
schema field with JSON URL	Partial	❌	Weak	Good
This proposal (sub-tiddler)	✅	✅	Strong	Good
Tags only	✅	✅	Medium	Weak

---

Verification

• [tag[$:/tags/Schema]] lists all schemas
• [[$:/schemas/ChangeType]get[fields]] gets the field list
• [[$:/schemas/ChangeType/singular]get[aliases]] gets field aliases
• Tools (like Cerebrus) can read these tiddlers at build time, eliminating hardcoded field names
• text remains free for human/LLM content

---

Decisions

• Use sub-tiddler namespace ($:/schemas/Type/field) instead of dot notation (field.name.attr), so each field definition can have its own text
• Use native TW5 list fields (space-separated) for aliases, matching tags/list conventions
• This is a convention, not a core code change—no need to patch boot.js, just a plugin or external tool can implement validation

---

Feedback and discussion welcome!