Release Notes — Frontmatter Spec v1.3

Built: 2025-10-15 • Source: /ai/spec/v1.3/release-notes-v1.3.md # Release Notes — Frontmatter Spec v1.3 **Date:** 2025-10-15 **Status:** Stable ## Overview Frontmatter v1.3 consolidates our dual-delivery strategy for AI consumption: 1) **SEO / Google Rich Results** (JSON‑LD + OpenGraph in HTML) 2) **API / Partner AIs** (manifest + meta.json/meta.yaml + content.md + checksums) The release strengthens **AI‑tooling**, formalizes an **open‑source production stack**, and embeds **Experience Innovation** as a guiding method to keep content and structured data aligned. --- ## Highlights - **AI‑Tooling integrated:** Two standard prompts (API & Google paths), stricter byte‑identical hash policy, and CORS/Preflight guidance for LLM fetchers. - **Open‑Source Stack set:** Ubuntu LTS + Caddy 2 as reference stack; Odoo Website (or any CMS) as content source; Cloudflare DNS‑only guidance. - **Experience Innovation embedded:** 7C CI/CD and delivery artifacts (JSON‑LD snippets, content.md DE/EN, meta.* with checksums, manifest, llms.txt, sitemap_ai.xml) kept in sync. - **Validation pipeline:** AJV (draft 2020‑12) w/ `ajv-formats`; per‑doc checksums; healthcheck script extended. - **Developer ergonomics:** Precise content types, OPTIONS 204 for preflight, ETag/Last‑Modified consistency, and troubleshooting snippets. --- ## Changes since v1.2 ### Spec - **Frontmatter keys:** No breaking changes; clarified **required** vs **recommended** for Rich Results per document type. - **Checksums:** Explicit `checksums.content_sha256` in `meta.json` is **mandatory** and must match byte‑for‑byte the served `content.md`. - **hreflang & canonical:** Pattern for DE/EN pages (canonical + alternate + x‑default) documented; dynamic insertion allowed when server‑side templating is limited. ### Delivery - **AI manifest:** `/ai/manifest.json` remains the primary discovery entry. - **AI sitemap:** `/ai/sitemap_ai.xml` referenced from `robots.txt` and `llms.txt`. - **CORS/Preflight:** Required headers and 204 OPTIONS response codified; `Alt-Svc` on OPTIONS discouraged. - **Cloudflare:** Recommend DNS‑only (or cache bypass) for `/ai/*`; avoid content mutation that breaks hashes. ### Tooling - **Validation:** `ajv validate --spec=draft2020 -c ajv-formats` for all `meta.json` files. - **Healthcheck:** Script covers reachability, schema validation, checksum verification, HEAD checks (types/CORS/cache). --- ## New Documents - **Annex A — Technik & Tools (v1.3):** Open‑source stack, AI‑tooling, Experience Innovation alignment, DevOps, QA and checklists. Path: `/ai/spec/v1.3/annex-tech.md` _Notes:_ - **Annex B — Kommunikationsmodelle (Watzlawick/Thun)** and **Annex C — Erstellungsprozess (CAISE)** are planned to formalize content tone & delivery workflow alignment. (Optional for 1.3.1) --- ## Compatibility & Migration - **From v1.2 → v1.3:** No schema breaking changes. - Ensure every `content.md` has an accurate SHA‑256 in `meta.json`. Mismatches **must** block downstream processing. - Keep JSON‑LD snippets and `content.md` semantically aligned (same facts, titles, images where applicable). --- ## Operational Guidance - **TLS:** TLS 1.2/1.3, full chain; HSTS recommended. - **IPv4/IPv6:** Verify A/AAAA; server listening on `*:443` (dual stack). - **Headers:** - `Access-Control-Allow-Origin: *` - `Access-Control-Allow-Methods: GET, HEAD, OPTIONS` - `Access-Control-Allow-Headers: Authorization, Content-Type` - `Content-Type` precise for `.json`, `.yaml`, `.md`, `.schema.json` - `ETag` + `Last-Modified` stable - **No-cache fetch for QA:** `curl -sL --compressed -H "Cache-Control: no-cache" URL | sha256sum` --- ## Test Prompts (Copy‑Paste) ### Scenario A — API & Partners > You are an API agent. Fetch `https:// /ai/manifest.json`. Select document ` ` version ` `. Load `meta.json` for ` ` and `content.md`. Verify `sha256(content.md)` equals the value in `meta.json`. If matched: output 5 bullet points + locations + one contact person. If not: report checksum error only. ### Scenario B — Google Path > You are an AI agent. Summarize `https:// / ` in 5 bullet points and name locations and one contact person. Use **only** structured data (JSON‑LD/schema.org) and visible page content. --- ## Known Caveats - Some LLM browsers mutate bytes (encoding/whitespace). Enforce **raw bytes** fetch for checksum verification. - OPTIONS requests must not return `Alt-Svc` or unexpected content; keep 204 with CORS headers only. - CDN caches can serve stale content; for `/ai/*` use DNS‑only or cache bypass rules. --- ## Next Steps - Freeze **Annex B** (Watzlawick/Thun) and **Annex C** (Process, including n8n flow where applicable). - Add CI job for automated schema/hash checks on commit. - Extend manifest to expose `latest` per doc/locale and historical versions (`v1.2`, `v1.3`). --- **Owner:** Tolksdorf.digital **Contact:** admin-ch@tolksdorf.digital