id: fragment-format title: Fragment format — the page model and its YAML scope: public updated: 2026-08-07 tags: - fragment - specification - yaml
Status: working specification — experimental, and it evolves over time. Once published, changes to this document are versioned; earlier versions stay readable. Purpose: make the page model precise enough that a reader, an export, or an integration can be built against it.
A fragment is one page: one note, one URL, one small piece of material. Most of the time you write the narrative in Markdown. When more structure helps, you add small YAML alongside it.
Fragment is an AI-native structured document format — a structured unit of context, not an application. Markdown carries the narrative a person reviews; YAML carries the explicit structure a tool can rely on; both layers are read by people and by AI.
Fragment は 1 ページ分の最小単位です。日記、議事録、仕様、レビュー、講義ノート ——ほとんどのものがこの 1 単位で収まります。そのうえで必要になったときだけ、 YAML や図をそっと足していきます。
This document is the format specification. It covers the page model, the header fields, both layers of YAML, and the limits. For the behaviour profile that goes inside a page see Prism Protocol; for diagrams see Scene and Flow.
1. What a page holds
Three layers.
[Header] id, title, scope, tags, timestamps
[Content] the Markdown body you read and write
[Blocks] small YAML islands — Prism, config, Scene, Flow
One fragment = one page, plus a few structured islands.
You do not need the full schema in mind while writing. Title, body, and a few blocks nearby is enough. The rest of this document makes that model precise for anyone building a reader, an export, or an integration.
2. Conceptual shape
A schema-like view. Storage details can change; this is the stable reference.
fragment:
id: "def5d6b2-d52c-4b96-ab6d-52808f051d11"
title: "Example Fragment"
slug: "example-fragment"
scope: "private" # private | unlisted | public
tags: ["journal", "study"]
author: "@you"
created_at: "2025-01-01T10:00:00Z"
updated_at: "2025-01-03T08:12:00Z"
content:
markdown: |
# Heading
This is the main note, written in Markdown.
blocks:
- kind: "prism"
label: "study-partner"
value: |
prism:
persona:
name: "Study partner"
tone: "kind, patient"
- kind: "scene"
label: "layout-diagram"
value: |
scene:
# ...
meta:
versions:
count: 5
While writing you deal with Markdown and fenced blocks. The header, meta, and block list are what let a reader, an index, or a model make sense of the same page.
3. Header fields
Identity and visibility
| Field | Meaning |
|---|---|
id | Stable identifier (UUID-like) |
title | Human-readable title. May be empty |
slug | Optional URL slug, used for public and unlisted links |
scope | private / unlisted / public |
Classification
| Field | Meaning |
|---|---|
tags | Free-form tags for grouping and search. Three to eight per page is a healthy range |
author | Handle or user identifier |
Timestamps and versions
| Field | Meaning |
|---|---|
created_at / updated_at | When the page was created and last saved |
versions | Version count and pointers for history |
Hints
| Field | Meaning |
|---|---|
prism | Default Prism profile to prefer on this page |
layout | Reader hint: article, slides, mixed |
4. Scope
Scope controls who can see a page. It is independent of version history and of any Prism setting.
| Scope | Who can read it | Listed in the index |
|---|---|---|
private | Only you | No |
unlisted | Anyone with the URL | No |
public | Anyone | Yes |
Most notes start private and stay there. unlisted suits work in progress and
trusted readers. public suits essays, templates, and teaching material.
5. YAML, in two layers
The YAML here is not a backend schema. It exists to say what this page is and how it should be handled, at a size a person can read.
Layer 1 — front-matter, about the page
A triple-dash block at the very top. Optional, and designed to stay small, predictable, and scannable.
---
id: "weekly-review-2025-03-01"
title: "Weekly review — work & family"
updated: "2025-03-01"
scope: "private" # private | unlisted | public
tags: ["weekly", "journal"]
prism: "weekly-reflection"
layout: "article"
---
The fields are the header fields from section 3. Front-matter is where you set them by hand; an editor may also set the same values through its own interface.
Layer 2 — inline blocks, inside the page
Fenced code blocks annotated block:<type>, sitting beside the Markdown. Each
type does one thing.
| Block | Purpose | Specified in |
|---|---|---|
block:prism | How AI should behave here — persona, tone, boundaries | Prism Protocol |
block:scene | A layout or moment, as a diagram | Scene and Flow |
block:flow | A process, as a diagram | Scene and Flow |
block:config | Small local hints — audience, language, mode | below |
audience: ["self", "partner"]
language: "ja-en"
notes:
- "Private weekly reflection"
block:config is optional and mostly for people who want it. It lets a page
carry small structured hints without putting them in the prose.
Other block types — block:tasks, block:calendar, block:relations — follow
the same shape: a small structured island next to Markdown. They are not
specified here.
6. A complete example
Front-matter, a behaviour block, and ordinary Markdown.
---
id: "weekly-review-2025-03-01"
title: "Weekly review — work & family"
updated: "2025-03-01"
scope: "private"
tags: ["weekly", "journal"]
prism: "weekly-reflection"
---
```yaml block:prism
persona:
name: "Gentle weekly coach"
role: "helps me reflect on the week without guilt"
tone:
style: "calm, concrete"
directness: "low"
boundaries:
avoid:
- "productivity guilt"
- "pushing extra commitments"
always_check:
- "energy"
- "family load"
```
# This week — quick recap
- Work
- Family / home
- Health / energy
## What went well
## What felt heavy
## Next week — one small adjustment
Asking for help with this page loads the block:prism first, so the reply starts
from a calm, concrete, non-guilt stance instead of you retyping that each time.
7. How a page travels together
[Body] the Markdown note
[Prism] how AI should behave here
[Config] local hints — audience, language, layout
[Scene/Flow] diagrams for structure and process
These pieces can be passed as one unit, so a model reads the same context you do rather than an isolated paragraph. This is the core idea: one page, one shared structure. Everything else is layered on top of that unit.
8. Keep it small
YAML here is not meant to capture everything. Use it for small, stable facts and rules — scope, roles, tone, links — the kind of thing that will still make sense in a year. Let the prose carry the story.
You do not need a designed schema on day one. One front-matter block, then one Prism block, then whatever the work actually asks for.
9. Limits
- The header is not a database.
tagsandlayoutare hints, not constraints; nothing validates that a reader honours them. - Front-matter is optional. A page with no front-matter is a valid page.
- Block types are open-ended. An unknown
block:<type>is text a renderer does not understand yet. It should not break the page. - Field names can change. The shape in section 2 is the stable reference; exact storage is not part of it.
- Scope is visibility, not security.
unlistedmeans unlisted — anyone holding the URL can read it.
10. Origin and evolution
The format began inside a notebook application (2025): pages, front-matter, and typed blocks were product features first. The application converged; the format was then extracted as this specification (2026), because the useful part turned out to be the document model, not the tool around it.
The same ideas were later carried into how Fragment Practice runs its own records: structured Markdown/YAML documents under Git as the canonical source of decisions and state. Where this specification and that operational practice diverge, each side stays canonical for its own domain — this document specifies the format; it does not prescribe anyone's operations.
この形式はノートアプリ（2025）の中で生まれ、ページ・front-matter・型付き ブロックはまず製品機能でした。アプリの収束後、残す価値があったのは道具では なくドキュメントモデルだったため、仕様として抽出しました（2026）。同じ 考え方は、その後 Fragment Practice 自身の記録運用 —— 構造化した Markdown/YAML 文書を Git 上で判断と状態の正本として扱う —— にも引き継がれています。