Frontmatter Spec v1.3 adds dual-delivery for AI consumption via SEO and API with checksums, CORS, and v1.2 compatibility.
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 + Open Graph in HTML) 2) API / Partner A Is (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, E Tag/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 - cajv-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, Dev Ops, 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. - I Pv4/I Pv6: 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 - E Tag + 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