Schema and entities

Work schema-first: decide the types and fields, push the schema document, then add content. The schema is a document you pull, edit, and push back with a change key — pushes converge, so re-pushing an identical schema is a no-op.

Field roles

Roles tell the renderer what a field means, independent of its name:

• title — the entity's display name, everywhere.
• summary — the one-paragraph lede under the page title and on cards.
• subtitle — a secondary line (an editor's note under a link).
• body — long-form markdown; renders with reading typography.
• image — the lead image (cards and the entity page hero).
• external_url — the click-through target; gives cards a domain chip and pages a visit link.
• date — the meta-line date on feeds and cards.
• search_text — indexed for search but never displayed or served: the home for extracted third-party text. Findable, not republished.

Search declarations

Per field, opt into search: { enabled, filter, facet, sortable, weight }. Facet + sortable fields automatically produce the catalog experience on list routes: filter panels, sort bars, counts. Number fields carry display config (unit, unitPosition, precision) used everywhere they render.

Relationships

Typed, directional, optionally ordered (ordered: true makes the relationship's order editorial — a board's pin order, an issue's story order). Relationship types are schema like everything else.

Shapes

Shapes are predefined starting points — link is the most used: apply it and you get a link-entity type wired for ingestion. Shapes are catalog data plus a conformance check, not a runtime concept; extend the fields freely after applying.