# Frontmatter Spezifikation **v1.3** (Tolksdorf.digital)

    # Frontmatter Spezifikation **v1.3** (Tolksdorf.digital) > **Zweck:** Einheitliches Frontmatter (YAML/JSON) für Webseiten & KI-Feeds. > **Ziele:** SEO/Rich Results (Google), KI-Konsumierbarkeit (Perplexity, ChatGPT & Partner), saubere JSON‑LD‑Einbettung auf kanonischen HTML‑Seiten, Versionierung & Integrität. > **Kompatibilität:** Rückwärtskompatibel zu v1.2. v1.3 ergänzt JSON‑LD‑Pflichten, `same_as`, `syndication` und präzisere Minimalsets. --- ## 0) Geltungsbereich & Dateitypen - **Frontmatter-Dateien:** `*.yaml` oder `*.json` (gleichwertig). - **Content-Dateien:** korrespondierendes `content.md` (UTF‑8). - **AI-Publishing:** optionale, versionierte Auslieferung unter `/ai/<doc-id>/<locale>/<version>/{ meta.yaml, meta.json, content.md, checksum.sha256 }`. - **Kanonische HTML‑Seiten:** führen **immer** JSON‑LD `<script type="application/ld+json">` aus (siehe §6). --- ## 1) Grundstruktur (Top-Level Keys) ```yaml # 1) Core type: blog|home|profile|pillar|service lang: de|en|… locale: de-DE|en-US|… title: "Seitentitel" summary: "Kurzbeschreibung / Teaser" canonical: "https://example.com/pfad" slug: "pfad-ohne-domain" image: "https://…/banner.jpg" # 2) SEO & Meta date_published: "2025-10-13" date_modified: "2025-10-13" og: title: "..." description: "..." image: "https://…/social.jpg" twitter: card: "summary_large_image" site: "@tolksdorfdigital" # 3) Hreflang hreflang: x_default: "https://example.com/pfad" alternates: - { lang: de, url: "https://example.com/pfad" } - { lang: en, url: "https://example.com/en/pfad" } # 4) Publisher / Organization publisher: name: "Tolksdorf.digital" logo: "https://…/logo-112.png" organization: name: "Tolksdorf.digital" url: "https://tolksdorf.digital" logo: "https://…/logo-112.png" address: streetAddress: "Musterstrasse 1" postalCode: "8000" addressLocality: "Zürich" addressRegion: "ZH" addressCountry: "CH" contactPoint: - { telephone: "+41 44 000 00 00", contactType: "customer service" } vatID: "CHE-123.456.789 MWST" taxID: "CH-123.456.789" eori: "CHE123456789" register_number: "HRB 123456, Handelsregister Kanton ZH" identifiers: - scheme: "DUNS" value: "12-345-6789" - scheme: "LEI" value: "5493001KJTIIGC8Y1R12" # 5) Person (für Profile) person: name: "Vorname Nachname" url: "https://example.com/team/vorname-nachname" image: "https://…/portrait.jpg" jobTitle: "Berufsbezeichnung" worksFor: - name: "Tolksdorf.digital" address: { ... } same_as: - "https://www.linkedin.com/in/..." - "https://x.com/..." email: "vorname@example.com" telephone: "+41 44 000 00 00" # 6) Service (für Pillar/Leistungsseiten) service: name: "Experience Innovation" description: "Kurzpitch der Leistung" areaServed: "CH" provider_id: "https://tolksdorf.digital/#organization" # Referenz auf Organization # 7) Artikel/Blog article: headline: "Überschrift" description: "Beschreibung" author_name: "Autor:in" reading_time_minutes: 6 # 8) Website (optional) website: name: "Tolksdorf.digital" # Sitelinks Search Box nicht mehr ausspielen search_action: null # 9) KI-spezifische Felder content: path: "/ai/experienceinnovation/de-DE/v1.2/content.md" format: "markdown" encoding: "utf-8" bytes: 12345 sha256: "<HASH>" updated_at: "2025-10-13T20:23:52+02:00" same_as: - "https://www.linkedin.com/company/tolksdorf-digital/" syndication: - platform: "LinkedIn" url: "https://www.linkedin.com/posts/..." variant: "teaser" # teaser|full|thread|recap posted_at: "2025-10-14T09:05:00+02:00" # 10) Emitter-Hints schema_override: "Organization|BlogPosting|Service|Person" main_entity_type: "Service" # 11) Breadcrumb (optional) breadcrumb: - { name: "Home", url: "https://example.com/" } - { name: "Leistungen", url: "https://example.com/leistungen" } - { name: "Experience Innovation", url: "https://example.com/experienceinnovation" } ``` --- ## 2) Datentypen & Konventionen - **Datumsformat:** ISO‑8601 (`YYYY‑MM‑DD`), Zeitstempel ISO‑8601 mit Offset. - **URLs:** absolute URLs für Bilder/Canonicals; Slugs ohne Domain. - **IDs:** Für JSON‑LD `@id = canonical + "#fragment"` (stabile, bookmarkbare IDs). - **Währungen/Sprachen/Länder:** `ISO 4217`/`BCP 47`/`ISO 3166‑1 alpha‑2`. --- ## 3) Minimalsets (required_if / recommended_if) ### 3.1 `type: blog` → WebPage + BlogPosting **required_if** - `title` **oder** `article.headline` - `canonical` - `image` - `date_published` **recommended_if** - `publisher.name`, `publisher.logo` - `article.author_name` - `date_modified` - `same_as[]` ### 3.2 `type: home` → WebPage + Organization **required_if** - *(keine harten Pflichtfelder)* **dringend empfohlen** - `organization.name`, `organization.url`, `organization.logo` **recommended_if** - `organization.address.*` - `organization.identifiers[]` - `vatID`, `taxID`, `eori`, `register_number` - `same_as[]` ### 3.3 `type: profile` → WebPage(ProfilePage) + Person **required_if** - `person.name` **recommended_if** - `person.url`, `person.image`, `person.jobTitle` - `person.worksFor[]`, `person.same_as[]` ### 3.4 `type: pillar` (Leistung) → WebPage + Service **required_if** - `title`, `canonical`, `image` **recommended_if** - `main_entity_type: "Service"` - `service.name`, `service.description`, `service.areaServed` - `organization.@id` als `provider` --- ## 4) JSON‑LD Einbettung (Pflicht in v1.3) Auf **jeder kanonischen HTML‑Seite** wird **ein** `<script type="application/ld+json">` ausgeliefert: - **WebPage** (immer) + `@id = canonical + "#webpage"` - **mainEntity** je Seitentyp (oder `main_entity_type`): - `blog` → `BlogPosting` (`@id = canonical + "#post"`) - `home` → `Organization` (`#organization`), optional `WebSite` zusätzlich - `profile` → `Person` (`#person`) – Page‑Typ kann implizit ProfilePage sein - `pillar`/`service` → `Service` (`#service`) **Mindestfelder WebPage:** `url`, `inLanguage`, `name`, `description`, `image` (gern als `ImageObject`). **Mindestfelder mainEntity:** siehe §3 je Typ. **Provenance/Links:** `sameAs[]` direkt auf WebPage/mainEntity; **Syndication** via `subjectOf` (Array von `WebPage`/`CreativeWork` mit `url`). **Beispiel (Pillar/Service):** ```html <script type="application/ld+json"> { "@context":"https://schema.org", "@type":"WebPage", "@id":"https://tolksdorf.digital/experienceinnovation#webpage", "url":"https://tolksdorf.digital/experienceinnovation", "inLanguage":"de-DE", "name":"Experience Innovation by Tolksdorf.digital", "description":"Planbare Innovation für KMU …", "image":{"@type":"ImageObject","url":"https://tolksdorf.digital/web/image/8465-76b165fe/compressed%20ExperienceInnovation_Dodekaeder_Blog.png"}, "sameAs":["https://www.linkedin.com/company/tolksdorf-digital/"], "mainEntity":{ "@type":"Service", "@id":"https://tolksdorf.digital/experienceinnovation#service", "name":"Experience Innovation by Tolksdorf.digital", "description":"Planbare Innovation für KMU …", "provider":{"@id":"https://tolksdorf.digital/#organization"} }, "subjectOf":[{"@type":"WebPage","url":"https://www.linkedin.com/posts/..."}] } </script> ``` --- ## 5) Mapping (Frontmatter → JSON‑LD) | Frontmatter | JSON‑LD (Schema.org) | |--- |--- | | `title` | `WebPage.name` / `BlogPosting.headline` / `Service.name` | | `summary` | `WebPage.description` / `BlogPosting.description` | | `canonical` | `WebPage.url`, `@id` (mit `#webpage`) | | `image` | `WebPage.image` (`ImageObject` empfohlen) | | `date_published`, `date_modified` | `BlogPosting.datePublished` / `.dateModified` | | `publisher.*` / `organization.*` | `Organization` (+ `@id="#organization"`) | | `person.*` | `Person` (+ `@id="#person"`) | | `service.*` | `Service` (+ `@id="#service"`) | | `same_as[]` | `WebPage.sameAs[]` und/oder `mainEntity.sameAs[]` | | `syndication[].url` | `WebPage.subjectOf[]` (oder `mainEntity.subjectOf[]`) | | `content.path/sha256` (AI Feed) | (nur Feed) | --- ## 6) Internationalisierung - `locale` ↔ `inLanguage` konsistent. - `hreflang.alternates` **wechselseitig**; `x_default` auf primäre Sprache. - `canonical` pro Sprache korrekt (z. B. `/experienceinnovation` vs. `/en/experienceinnovation`). --- ## 7) Integrität, Versionierung & Auslieferung - **Versionen:** `vX.Y` pro Locale nebeneinander. `manifest.json.docs[].latest` zeigt auf aktuelle Version. - **Checksummen:** `checksum.sha256` enthält **meta.json**, **meta.yaml**, **content.md** (je Zeile: `<sha256> <dateiname>`). - **Signaturen (optional):** `meta.json.sig` (Ed25519); Public Key in `/ai/policy.txt`. - **HTTP‑Header (Empfehlung):** korrekte `Content‑Type`, `ETag`, `Last‑Modified`, `Cache‑Control`; CORS für `/ai/`. - **Robustheit (optional):** für `/ai/` `Alt‑Svc` leeren, Kompression für JSON/MD auf „identity“. --- ## 8) Linting‑Regeln (Beispiel) ```yaml rules: - id: blog-minimal when: { type: blog } required: [ { anyOf: [ title, article.headline ] }, canonical, image, date_published ] recommended: [ { anyOf: [ article.author_name, publisher.name ] }, publisher.logo, date_modified, same_as ] - id: home-org when: { type: home } recommended: [ organization.name, organization.url, organization.logo, organization.address.streetAddress, organization.address.postalCode, organization.address.addressLocality, organization.address.addressCountry, vatID, taxID, eori, register_number ] - id: profile-person when: { type: profile } required: [ person.name ] recommended: [ person.url, person.image, person.jobTitle, person.worksFor, person.same_as ] - id: pillar-service when: { type: pillar } required: [ title, canonical, image ] recommended: [ main_entity_type, service.name, service.description, service.areaServed ] ``` --- ## 9) Beispiele (kurz) ### 9.1 Pillar (de-DE) ```yaml type: pillar lang: de locale: de-DE canonical: "https://tolksdorf.digital/experienceinnovation" title: "Experience Innovation by Tolksdorf.digital" summary: "Planbare Innovation für KMU …" image: "https://tolksdorf.digital/web/image/8465-76b165fe/compressed%20ExperienceInnovation_Dodekaeder_Blog.png" main_entity_type: "Service" service: name: "Experience Innovation" description: "…" areaServed: "CH" same_as: ["https://www.linkedin.com/company/tolksdorf-digital/"] syndication: - platform: "LinkedIn" url: "https://www.linkedin.com/posts/..." variant: "teaser" posted_at: "2025-10-14T09:05:00+02:00" content: path: "/ai/experienceinnovation/de-DE/v1.2/content.md" format: "markdown" encoding: "utf-8" bytes: 205 sha256: "<HASH>" ``` ### 9.2 Blog (en-US) ```yaml type: blog lang: en locale: en-US canonical: "https://example.com/en/blog/post" title: "How SMEs de-risk innovation" image: "https://example.com/og/post.jpg" date_published: "2025-10-01" publisher: { name: "Tolksdorf.digital", logo: "https://…/logo-112.png" } article: headline: "How SMEs de-risk innovation" author_name: "Jane Doe" ``` --- ## 10) Changelog - **v1.3** - JSON‑LD ist Pflicht auf kanonischen HTML‑Seiten (WebPage + mainEntity). - Neue Felder: `same_as[]`, `syndication[]`, `main_entity_type`. - Minimalsets geschärft (Service/Pillar). - Integrität: Empfehlung, Checksummen auf **alle** Artefakte auszuweiten. - **v1.2** - Konsolidierung von Feldern; AI‑Publishing‑Struktur (manifest/sitemap); EORI & Handelsregister‑Nr. ergänzt; Sitelinks Search Box de‑priorisiert. --- © Tolksdorf.digital – v1.3