Skip to content

Commit 9e79115

Browse files
committed
site: the landing-page YAML teaches YAML, and both examples now load
Two defects in the metadata examples on the front page, both found by extracting the fenced blocks and running them through the loader rather than by reading them. 1. THE SIGIL. Both examples are presented as YAML — `metadata.root:`, list items, block scalars — but wrote their attributes in canonical-JSON form: "@table", "@required", "@maxlength", "@values", "@fields", "@generation", "@objectref", "@Cardinality", "@agg", "@Of", "@via", and nine more. YAML authoring is sigil-free (ADR-0006); the desugar re-adds the "@" when it lowers to canonical JSON. 25 occurrences, all in index.html — the llms mirrors were already clean, and getting-started.html already had it right, so the front page was the only place teaching the wrong convention, and it is the first thing an adopter or an agent reads. This was NOT a correctness bug: both forms load identically — verified, the desugar tolerates and strips the sigil. It is a convention bug, which is why it survived. The regex VALUE "^[^@]+@[^@]+$" is untouched and stays a string; only its key went bare. 2. THE ADVANCED EXAMPLE NEVER LOADED. The blog/Author/Post/AuthorSummary block elided its primary keys behind a "# … id, title, authorId …" comment, so `identity.primary { fields: [id] }` named a field that did not exist, and AuthorSummary's `extends: blog::Author.id` and `origin.aggregate @Of: Post.id` both pointed at nothing. Loading it failed with "the SuperClass 'blog::Author.id' does not exist". Author and Post now declare `field.long: { name: id }`; the comment keeps eliding the rest. Verified by extraction, not by eye: both fenced examples are pulled out of the committed HTML, stripped of span markup, and loaded. Before this change example 1 failed and example 0 passed; after it, both load. The sigil half was proven neutral first — example 1 failed IDENTICALLY before and after the sigil rewrite, so the convention fix and the missing-key fix are independent. This is the class docs/check-doc-examples.ts gates in the library repo (#337: three times a doc taught vocabulary the loader had already retired). The website sits outside that gate's reach, which is how an example that cannot load stayed on the front page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NynrRND6ZUwGvq3ZUTCfxG
1 parent 6bce2f8 commit 9e79115

1 file changed

Lines changed: 20 additions & 18 deletions

File tree

www/index.html

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -241,16 +241,16 @@ <h2 class="section-label">From one schema, five languages.</h2>
241241
- <span class="keyword">object.entity</span>:
242242
<span class="key">name</span>: Subscriber
243243
<span class="key">children</span>:
244-
- <span class="keyword">source.rdb</span>: { <span class="string">"@table"</span>: subscribers }
244+
- <span class="keyword">source.rdb</span>: { <span class="key">table</span>: subscribers }
245245
- <span class="keyword">field.long</span>: { <span class="key">name</span>: id }
246-
- <span class="keyword">field.string</span>: { <span class="key">name</span>: email, <span class="string">"@maxLength"</span>: 320, <span class="string">"@required"</span>: true }
246+
- <span class="keyword">field.string</span>: { <span class="key">name</span>: email, <span class="key">maxLength</span>: 320, <span class="key">required</span>: true }
247247
- <span class="keyword">field.string</span>: { <span class="key">name</span>: name }
248248
- <span class="keyword">field.enum</span>:
249249
<span class="key">name</span>: status
250-
<span class="string">"@values"</span>: [active, paused, cancelled]
251-
<span class="string">"@required"</span>: true
252-
- <span class="keyword">field.timestamp</span>: { <span class="key">name</span>: createdAt, <span class="string">"@autoSet"</span>: onCreate }
253-
- <span class="keyword">identity.primary</span>: { <span class="string">"@fields"</span>: [id], <span class="string">"@generation"</span>: increment }</code></pre>
250+
<span class="key">values</span>: [active, paused, cancelled]
251+
<span class="key">required</span>: true
252+
- <span class="keyword">field.timestamp</span>: { <span class="key">name</span>: createdAt, <span class="key">autoSet</span>: onCreate }
253+
- <span class="keyword">identity.primary</span>: { <span class="key">fields</span>: [id], <span class="key">generation</span>: increment }</code></pre>
254254

255255
<p class="example-section-label">TypeScript — Drizzle + Zod from <code>codegen-ts</code></p>
256256
<pre class="example-code"><code><span class="comment">// generated/Subscriber.ts</span>
@@ -422,36 +422,38 @@ <h2 class="section-label">The metamodel goes deep.</h2>
422422
- <span class="keyword">object.entity</span>:
423423
<span class="key">name</span>: Author
424424
<span class="key">children</span>:
425+
- <span class="keyword">field.long</span>: { <span class="key">name</span>: id }
425426
- <span class="keyword">field.string</span>:
426427
<span class="key">name</span>: email
427-
<span class="string">"@required"</span>: true
428+
<span class="key">required</span>: true
428429
<span class="key">children</span>: <span class="comment"># child metadata on a field</span>
429430
- <span class="keyword">validator.required</span>: { <span class="key">name</span>: req }
430-
- <span class="keyword">validator.regex</span>: { <span class="key">name</span>: emailFmt, <span class="string">"@pattern"</span>: <span class="string">"^[^@]+@[^@]+$"</span> }
431+
- <span class="keyword">validator.regex</span>: { <span class="key">name</span>: emailFmt, <span class="key">pattern</span>: <span class="string">"^[^@]+@[^@]+$"</span> }
431432
- <span class="keyword">field.string</span>:
432433
<span class="key">name</span>: bio
433434
<span class="key">children</span>:
434-
- <span class="keyword">validator.length</span>: { <span class="key">name</span>: bioLen, <span class="string">"@min"</span>: 0, <span class="string">"@max"</span>: 500 }
435-
- <span class="keyword">relationship.composition</span>: { <span class="key">name</span>: posts, <span class="string">"@objectRef"</span>: Post, <span class="string">"@cardinality"</span>: many }
436-
- <span class="keyword">identity.primary</span>: { <span class="string">"@fields"</span>: [id], <span class="string">"@generation"</span>: increment } <span class="comment"># name optional → defaults to "primary"</span>
435+
- <span class="keyword">validator.length</span>: { <span class="key">name</span>: bioLen, <span class="key">min</span>: 0, <span class="key">max</span>: 500 }
436+
- <span class="keyword">relationship.composition</span>: { <span class="key">name</span>: posts, <span class="key">objectRef</span>: Post, <span class="key">cardinality</span>: many }
437+
- <span class="keyword">identity.primary</span>: { <span class="key">fields</span>: [id], <span class="key">generation</span>: increment } <span class="comment"># name optional → defaults to "primary"</span>
437438
- <span class="keyword">object.entity</span>:
438439
<span class="key">name</span>: Post
439440
<span class="key">children</span>:
440441
- <span class="keyword">field.currency</span>:
441442
<span class="key">name</span>: price
442-
<span class="string">"@currency"</span>: USD
443+
<span class="key">currency</span>: USD
443444
<span class="key">children</span>:
444-
- <span class="keyword">view.currency</span>: { <span class="key">name</span>: money, <span class="string">"@locale"</span>: en-US } <span class="comment"># Intl formatting, integer minor units</span>
445-
<span class="comment"># … id, title, authorId, identity.reference (FK to Author) …</span>
445+
- <span class="keyword">view.currency</span>: { <span class="key">name</span>: money, <span class="key">locale</span>: en-US } <span class="comment"># Intl formatting, integer minor units</span>
446+
- <span class="keyword">field.long</span>: { <span class="key">name</span>: id }
447+
<span class="comment"># … title, authorId, identity.reference (FK to Author) …</span>
446448
- <span class="keyword">object.projection</span>: <span class="comment"># derived, read-only</span>
447449
<span class="key">name</span>: AuthorSummary
448450
<span class="key">children</span>:
449-
- <span class="keyword">source.rdb</span>: { <span class="string">"@kind"</span>: view, <span class="string">"@view"</span>: v_author_summary }
451+
- <span class="keyword">source.rdb</span>: { <span class="key">kind</span>: view, <span class="key">view</span>: v_author_summary }
450452
- <span class="keyword">field.long</span>: { <span class="key">name</span>: id, <span class="key">extends</span>: blog::Author.id,
451-
<span class="key">children</span>: [ { <span class="keyword">origin.passthrough</span>: { <span class="string">"@from"</span>: Author.id } } ] }
453+
<span class="key">children</span>: [ { <span class="keyword">origin.passthrough</span>: { <span class="key">from</span>: Author.id } } ] }
452454
- <span class="keyword">field.int</span>: { <span class="key">name</span>: postCount,
453-
<span class="key">children</span>: [ { <span class="keyword">origin.aggregate</span>: { <span class="string">"@agg"</span>: count, <span class="string">"@of"</span>: Post.id, <span class="string">"@via"</span>: Author.posts } } ] }
454-
- <span class="keyword">identity.primary</span>: { <span class="key">extends</span>: blog::Author.primary, <span class="string">"@fields"</span>: [id] }</code></pre>
455+
<span class="key">children</span>: [ { <span class="keyword">origin.aggregate</span>: { <span class="key">agg</span>: count, <span class="key">of</span>: Post.id, <span class="key">via</span>: Author.posts } } ] }
456+
- <span class="keyword">identity.primary</span>: { <span class="key">extends</span>: blog::Author.primary, <span class="key">fields</span>: [id] }</code></pre>
455457

456458
<p class="example-section-label">Field validators → Zod refinements <code>(generated/Author.ts)</code></p>
457459
<pre class="example-code"><code><span class="comment">// validator.required + validator.regex + validator.length, straight from the field children</span>

0 commit comments

Comments
 (0)