Skip to content

Commit 23f8656

Browse files
richlanderclaude
richlander
and
claude
committed
Add vocabulary reference and expand HAL documentation
- Add release-notes/queries/vocabulary.md documenting HAL graph terms - Expand llms/README.md with Timeline Navigation section and Key Properties Reference - Add prev-security link relation to llms.txt month index table - Update metrics.md with current file sizes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 007b6f5 commit 23f8656

File tree

4 files changed

+268
-38
lines changed

4 files changed

+268
-38
lines changed

‎llms.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ From a **month index** (e.g., `timeline/2025/01/index.json`):
8787
|---------------|---------|
8888
| `cve-json` | Full CVE details for that month |
8989
| `prev` | Navigate to previous month |
90+
| `prev-security` | Navigate to previous security month |
9091

9192
## CVE data
9293

‎llms/README.md‎

Lines changed: 56 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -502,7 +502,8 @@ jq -r '.breaks[] | select(.category == "sdk") | .references[] | select(.type ==
502502
| Link | Purpose |
503503
|------|---------|
504504
| `self` | Current document |
505-
| `prev` | Previous document (months, patches) |
505+
| `prev` | Previous in sequence (patches, months, years) |
506+
| `prev-security` | Previous security release in sequence |
506507

507508
### Version Navigation
508509

@@ -511,15 +512,27 @@ jq -r '.breaks[] | select(.category == "sdk") | .references[] | select(.type ==
511512
| `latest` | Most recent release |
512513
| `latest-lts` | Most recent LTS release |
513514
| `latest-security` | Most recent security patch |
515+
| `latest-patch` | Latest patch for a major version |
514516
| `releases-index` | Root releases index |
515517

518+
### Timeline Navigation
519+
520+
| Link | Purpose |
521+
|------|---------|
522+
| `timeline-index` | Root timeline index |
523+
| `year-index` | Parent year index |
524+
| `latest-year` | Most recent year index |
525+
| `latest-month` | Most recent month index |
526+
| `latest-security-month` | Most recent month with security releases |
527+
| `release-month` | Timeline month for a patch |
528+
516529
### Cross-Links
517530

518531
| Link | Purpose |
519532
|------|---------|
520-
| `timeline-index` | From releases to timeline |
521533
| `releases-index` | From timeline to releases |
522-
| `release-month` | From patch to timeline month |
534+
| `release-major` | Parent major version index |
535+
| `release-patch` | Patch index for an SDK release |
523536

524537
### Resources
525538

@@ -529,6 +542,9 @@ jq -r '.breaks[] | select(.category == "sdk") | .references[] | select(.type ==
529542
| `release-manifest` | External resource links |
530543
| `cve-json` | Full CVE details |
531544
| `supported-os-json` | OS support matrix |
545+
| `downloads` | Downloads index for binaries |
546+
| `release-json` | Full release information |
547+
| `release-notes-markdown` | Release notes (Markdown) |
532548

533549
### Link Properties
534550

@@ -537,6 +553,43 @@ jq -r '.breaks[] | select(.category == "sdk") | .references[] | select(.type ==
537553
- **`title`** — Human-readable description
538554
- **`type`** — Media type (`application/hal+json`, `application/json`)
539555

556+
## Key Properties Reference
557+
558+
Properties that appear frequently across index types:
559+
560+
### Filtering
561+
562+
| Property | Type | Purpose |
563+
|----------|------|---------|
564+
| `supported` | boolean | Version is currently receiving updates |
565+
| `security` | boolean | Release includes security fixes |
566+
| `release_type` | enum | `lts` or `sts` |
567+
| `support_phase` | enum | `active`, `maintenance`, `eol`, `preview`, `go-live` |
568+
569+
### Versioning
570+
571+
| Property | Type | Purpose |
572+
|----------|------|---------|
573+
| `latest` | string | Latest version in context |
574+
| `latest_lts` | string | Latest LTS version |
575+
| `latest_security` | string | Latest security patch version |
576+
| `latest_release` | string | Latest major version in time period |
577+
578+
### Dates
579+
580+
| Property | Type | Purpose |
581+
|----------|------|---------|
582+
| `date` | ISO 8601 | Release date |
583+
| `ga_date` | ISO 8601 | General Availability date |
584+
| `eol_date` | ISO 8601 | End of Life date |
585+
586+
### CVE
587+
588+
| Property | Type | Purpose |
589+
|----------|------|---------|
590+
| `cve_count` | integer | Number of CVEs in release |
591+
| `cve_records` | array | CVE identifiers (e.g., `["CVE-2025-21172"]`) |
592+
540593
## Response Templates
541594

542595
**Opening**:

‎release-notes/queries/metrics.md‎

Lines changed: 35 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -22,23 +22,23 @@ The tables below show theoretical update frequency based on practice and design,
2222

2323
| File | Size | Updates/Year | Description |
2424
|------|------|--------------|-------------|
25-
| `index.json` | 8 KB | ~1 | Root index with all major versions |
26-
| `10.0/index.json` | 14 KB | ~12 | All 10.0 patches (fewer releases so far) |
27-
| `9.0/index.json` | 28 KB | ~12 | All 9.0 patches with CVE references |
28-
| `8.0/index.json` | 33 KB | ~12 | All 8.0 patches with CVE references |
29-
| `timeline/index.json` | 8 KB | ~1 | Timeline root (all years) |
30-
| `timeline/2025/index.json` | 15 KB | ~12 | Year index (all months) |
31-
| `timeline/2024/07/index.json` | 9 KB | ~1 | Month index with embedded CVE summaries |
25+
| `index.json` | 7 KB | ~1 | Root index with all major versions |
26+
| `10.0/index.json` | 10 KB | ~12 | All 10.0 patches (fewer releases so far) |
27+
| `9.0/index.json` | 20 KB | ~12 | All 9.0 patches with CVE references |
28+
| `8.0/index.json` | 24 KB | ~12 | All 8.0 patches with CVE references |
29+
| `timeline/index.json` | 6 KB | ~1 | Timeline root (all years) |
30+
| `timeline/2025/index.json` | 13 KB | ~12 | Year index (all months) |
31+
| `timeline/2025/10/index.json` | 10 KB | ~1 | Month index with embedded CVE summaries |
3232
| `timeline/2025/01/cve.json` | 14 KB | ~1 | Full CVE details for a month |
3333

3434
### Releases-Index Files
3535

3636
| File | Size | Updates/Year | Description |
3737
|------|------|--------------|-------------|
3838
| `releases-index.json` | 6 KB | ~12 | Root index (version list only) |
39-
| `10.0/releases.json` | **433 KB** | ~12 | All 10.0 releases with full download metadata |
40-
| `9.0/releases.json` | **751 KB** | ~12 | All 9.0 releases with full download metadata |
41-
| `8.0/releases.json` | **1,214 KB** | ~12 | All 8.0 releases with full download metadata |
39+
| `10.0/releases.json` | **440 KB** | ~12 | All 10.0 releases with full download metadata |
40+
| `9.0/releases.json` | **769 KB** | ~12 | All 9.0 releases with full download metadata |
41+
| `8.0/releases.json` | **1,234 KB** | ~12 | All 8.0 releases with full download metadata |
4242

4343
### Measurements
4444

@@ -77,7 +77,7 @@ These massive commits are difficult to review and analyze. Mixing markdown docum
7777

7878
| Schema | Files Required | Total Transfer |
7979
|--------|----------------|----------------|
80-
| hal-index | `index.json` | **8 KB** |
80+
| hal-index | `index.json` | **7 KB** |
8181
| releases-index | `releases-index.json` | **6 KB** |
8282

8383
**hal-index:**
@@ -117,8 +117,8 @@ curl -s "$ROOT" | jq -r '.["releases-index"][] | select(.["support-phase"] == "a
117117

118118
| Schema | Files Required | Total Transfer |
119119
|--------|----------------|----------------|
120-
| hal-index | `index.json` → `8.0/index.json` → `8.0/8.0.21/index.json` | **51 KB** |
121-
| releases-index | `releases-index.json` + `8.0/releases.json` | **1,220 KB** |
120+
| hal-index | `index.json` → `8.0/index.json` → `8.0/8.0.21/index.json` | **40 KB** |
121+
| releases-index | `releases-index.json` + `8.0/releases.json` | **1,240 KB** |
122122

123123
**hal-index:**
124124

@@ -161,18 +161,18 @@ curl -s "$RELEASES_URL" | jq -r '[.releases[] | select(.security == true)] | .[0
161161
- **Completeness:** ✅ Equal—both return the CVE identifiers
162162
- **Ergonomics:** The releases-index requires downloading a 1.2 MB file to extract 3 CVE IDs. The hal-index uses a dedicated `latest-security` link, avoiding iteration through all releases.
163163
- **Link syntax:** Counterintuitively, the deeper HAL structure `._links.self.href` is more ergonomic than `.["releases.json"]` because snake_case enables dot notation throughout. The releases-index embeds URLs directly in properties, but kebab-case naming forces bracket notation.
164-
- **Data efficiency:** hal-index is 23x smaller
164+
- **Data efficiency:** hal-index is 31x smaller
165165

166-
**Winner:** hal-index (**23x smaller**)
166+
**Winner:** hal-index (**31x smaller**)
167167

168168
### High Severity CVEs with Details
169169

170170
#### Query: "What High+ severity CVEs were fixed in the latest .NET 8.0 security patch, with titles?"
171171

172172
| Schema | Files Required | Total Transfer |
173173
|--------|----------------|----------------|
174-
| hal-index | `index.json` → `8.0/index.json` → `8.0/8.0.21/index.json` | **51 KB** |
175-
| releases-index | `releases-index.json` + `8.0/releases.json` | **1,220 KB** (cannot answer) |
174+
| hal-index | `index.json` → `8.0/index.json` → `8.0/8.0.21/index.json` | **40 KB** |
175+
| releases-index | `releases-index.json` + `8.0/releases.json` | **1,240 KB** (cannot answer) |
176176

177177
**hal-index:**
178178

@@ -219,8 +219,8 @@ curl -s "$RELEASES_URL" | jq -r '[.releases[] | select(.security == true)] | .[0
219219

220220
| Schema | Files Required | Total Transfer |
221221
|--------|----------------|----------------|
222-
| hal-index | `index.json` → `8.0/index.json` → 3 patch indexes (via `prev-security`) | **~60 KB** |
223-
| releases-index | `releases-index.json` + `8.0/releases.json` | **1,220 KB** |
222+
| hal-index | `index.json` → `8.0/index.json` → 3 patch indexes (via `prev-security`) | **58 KB** |
223+
| releases-index | `releases-index.json` + `8.0/releases.json` | **1,240 KB** |
224224

225225
**hal-index:**
226226

@@ -274,15 +274,15 @@ curl -s "$RELEASES_URL" | jq -r '
274274
- **Ergonomics:** The hal-index uses `prev-security` links to skip non-security patches (SDK-only releases), directly navigating to security releases. The releases-index requires downloading a 1.2 MB file and filtering in memory.
275275
- **Navigation model:** The `prev-security` link enables efficient backward traversal through security history without fetching intermediate non-security releases.
276276

277-
**Winner:** hal-index (**20x smaller**, with component information)
277+
**Winner:** hal-index (**21x smaller**, with component information)
278278

279279
### CVE Details for a Month
280280

281281
#### Query: "What CVEs were disclosed in January 2025 with full details?"
282282

283283
| Schema | Files Required | Total Transfer |
284284
|--------|----------------|----------------|
285-
| hal-index | `timeline/index.json` → `timeline/2025/index.json` → `timeline/2025/01/cve.json` | **37 KB** |
285+
| hal-index | `timeline/index.json` → `timeline/2025/index.json` → `timeline/2025/01/cve.json` | **33 KB** |
286286
| releases-index | All releases.json (13 versions) | **8.2 MB** (cannot answer) |
287287

288288
**hal-index:**
@@ -339,8 +339,8 @@ done | sort -u
339339

340340
| Schema | Files Required | Total Transfer |
341341
|--------|----------------|----------------|
342-
| hal-index | `timeline/index.json` → 6 month indexes (via `prev-security`) | **~60 KB** |
343-
| releases-index | All version releases.json files | **2.4+ MB** |
342+
| hal-index | `timeline/index.json` → `timeline/2025/index.json` → 6 month indexes (via `prev-security`) | **65 KB** |
343+
| releases-index | All version releases.json files | **2.4 MB** |
344344

345345
**hal-index:**
346346

@@ -396,16 +396,16 @@ done | sort -u | head -12
396396
- **Ergonomics:** The hal-index uses `prev-security` links to jump directly between security months, skipping non-security months entirely. The releases-index requires downloading all version files (2.4+ MB), filtering by security flag, and deduplicating results.
397397
- **Navigation model:** The `prev-security` link on timeline months enables efficient backward traversal through security history. The releases-index has no concept of time-based navigation.
398398

399-
**Winner:** hal-index (**40x smaller**, with version and component information)
399+
**Winner:** hal-index (**37x smaller**, with version and component information)
400400

401401
### Critical CVE This Month
402402

403403
#### Query: "Is there a critical CVE in any supported release this month?" (November 2025)
404404

405405
| Schema | Files Required | Total Transfer |
406406
|--------|----------------|----------------|
407-
| hal-index | `timeline/index.json` → `timeline/2025/index.json` → `timeline/2025/11/index.json` | **28 KB** |
408-
| releases-index | `releases-index.json` + all supported releases.json | **2.4+ MB** (incomplete—no severity data) |
407+
| hal-index | `timeline/index.json` → `timeline/2025/index.json` → `timeline/2025/11/index.json` | **24 KB** |
408+
| releases-index | `releases-index.json` + all supported releases.json | **2.4 MB** (incomplete—no severity data) |
409409

410410
**hal-index:**
411411

@@ -446,17 +446,17 @@ done | sort -u
446446

447447
- **Completeness:** ❌ The releases-index cannot answer this query. Even if there were CVEs in November, the schema only provides CVE IDs and URLs—no severity information. You would need to fetch each CVE URL from cve.mitre.org and parse the CVSS score.
448448
- **Ergonomics:** The hal-index embeds `cvss_severity` directly in the disclosure records, enabling single-query filtering for CRITICAL vulnerabilities.
449-
- **Use case:** This is a common security operations query ("Do I need to patch urgently?"). The hal-index answers it in 28 KB; the releases-index cannot answer it at all.
449+
- **Use case:** This is a common security operations query ("Do I need to patch urgently?"). The hal-index answers it in 24 KB; the releases-index cannot answer it at all.
450450

451-
**Winner:** hal-index (**88x smaller**, and releases-index cannot answer this query—CVE severity is not available)
451+
**Winner:** hal-index (**100x smaller**, and releases-index cannot answer this query—CVE severity is not available)
452452

453453
### Breaking Changes Summary
454454

455455
#### Query: "How many breaking changes are there in .NET 10 by category?"
456456

457457
| Schema | Files Required | Total Transfer |
458458
|--------|----------------|----------------|
459-
| hal-index | `index.json` → `10.0/index.json` → `10.0/compatibility.json` | **162 KB** |
459+
| hal-index | `index.json` → `10.0/index.json` → `10.0/compatibility.json` | **156 KB** |
460460
| releases-index | N/A | N/A (not available) |
461461

462462
**hal-index:**
@@ -503,7 +503,7 @@ curl -s "$BC_HREF" | jq -r '[.breaks[].category] | group_by(.) | map({category:
503503

504504
| Schema | Files Required | Total Transfer |
505505
|--------|----------------|----------------|
506-
| hal-index | `index.json` → `10.0/index.json` → `10.0/compatibility.json` | **162 KB** |
506+
| hal-index | `index.json` → `10.0/index.json` → `10.0/compatibility.json` | **156 KB** |
507507
| releases-index | N/A | N/A (not available) |
508508

509509
**hal-index:**
@@ -552,7 +552,7 @@ curl -s "$BC_HREF" | jq -r --arg cat "core-libraries" '.breaks[] | select(.categ
552552

553553
| Schema | Files Required | Total Transfer |
554554
|--------|----------------|----------------|
555-
| hal-index | `index.json` → `10.0/index.json` → `10.0/compatibility.json` | **162 KB** |
555+
| hal-index | `index.json` → `10.0/index.json` → `10.0/compatibility.json` | **156 KB** |
556556
| releases-index | N/A | N/A (not available) |
557557

558558
**hal-index:**
@@ -642,10 +642,10 @@ The HAL `_embedded` pattern ensures that any data referenced within a document i
642642

643643
| Metric | hal-index | releases-index |
644644
|--------|-------------|----------------|
645-
| Basic version queries | 8 KB | 6 KB |
646-
| CVE queries (latest security patch) | 51 KB | 1,220 KB |
647-
| Last 3 security releases (version) | ~60 KB | 1,220 KB |
648-
| Last 6 security months (timeline) | ~60 KB | 2.4 MB |
645+
| Basic version queries | 7 KB | 6 KB |
646+
| CVE queries (latest security patch) | 40 KB | 1,240 KB |
647+
| Last 3 security releases (version) | 58 KB | 1,240 KB |
648+
| Last 6 security months (timeline) | 65 KB | 2.4 MB |
649649
| Cache coherency | ✅ Atomic | ❌ TTL mismatch risk |
650650
| Query syntax | snake_case (dot notation) | kebab-case (bracket notation) |
651651
| Link traversal | `._links.self.href` | `.["releases.json"]` |

0 commit comments

Comments
 (0)