Resolver Text
# 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: street Address: "Musterstrasse 1" postal Code: "8000" address Locality: "Zürich" address Region: "ZH" address Country: "CH" contact Point: - { telephone: "+41 44 000 00 00", contact Type: "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" job Title: "Berufsbezeichnung" works For: - 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" area Served: "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: "Linked In" 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|Blog Posting|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. - **UR Ls:** absolute UR Ls für Bilder/Canonicals; Slugs ohne Domain. - **I Ds:** Für JSON‑LD `@id = canonical + "#fragment"` (stabile, bookmarkbare I Ds). - **Währungen/Sprachen/Länder:** `ISO 4217`/`BCP 47`/`ISO 3166‑1 alpha‑2`. --- ## 3) Minimalsets (required_if / recommended_if) ### 3.1 `type: blog` → Web Page + Blog Posting **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` → Web Page + 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` → Web Page(Profile Page) + Person **required_if** - `person.name` **recommended_if** - `person.url`, `person.image`, `person.job Title` - `person.works For[]`, `person.same_as[]` ### 3.4 `type: pillar` (Leistung) → Web Page + Service **required_if** - `title`, `canonical`, `image` **recommended_if** - `main_entity_type: "Service"` - `service.name`, `service.description`, `service.area Served` - `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: - **Web Page** (immer) + `@id = canonical + "#webpage"` - **main Entity** je Seitentyp (oder `main_entity_type`): - `blog` → `Blog Posting` (`@id = canonical + "#post"`) - `home` → `Organization` (`#organization`), optional `Web Site` zusätzlich - `profile` → `Person` (`#person`) – Page‑Typ kann implizit Profile Page sein - `pillar`/`service` → `Service` (`#service`) **Mindestfelder Web Page:** `url`, `in Language`, `name`, `description`, `image` (gern als `Image Object`). **Mindestfelder main Entity:** siehe §3 je Typ. **Provenance/Links:** `same As[]` direkt auf Web Page/main Entity; **Syndication** via `subject Of` (Array von `Web Page`/`Creative Work` mit `url`). **Beispiel (Pillar/Service):** ```html <script type="application/ld+json"> { "@context":"https://schema.org", "@type":"Web Page", "@id":"https://tolksdorf.digital/experienceinnovation#webpage", "url":"https://tolksdorf.digital/experienceinnovation", "in Language":"de-DE", "name":"Experience Innovation by Tolksdorf.digital", "description":"Planbare Innovation für KMU …", "image":{"@type":"Image Object", "url":"https://tolksdorf.digital/web/image/8465-76b165fe/compressed%20Experience Innovation_Dodekaeder_Blog.png"}, "same As":["https://www.linkedin.com/company/tolksdorf-digital/"], "main Entity":{ "@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"} }, "subject Of":[{"@type":"Web Page", "url":"https://www.linkedin.com/posts/..."}] } </script> ``` --- ## 5) Mapping (Frontmatter → JSON‑LD) | Frontmatter | JSON‑LD (Schema.org) | |--- |--- | | `title` | `Web Page.name` / `Blog Posting.headline` / `Service.name` | | `summary` | `Web Page.description` / `Blog Posting.description` | | `canonical` | `Web Page.url`, `@id` (mit `#webpage`) | | `image` | `Web Page.image` (`Image Object` empfohlen) | | `date_published`, `date_modified` | `Blog Posting.date Published` / `.date Modified` | | `publisher.*` / `organization.*` | `Organization` (+ `@id="#organization"`) | | `person.*` | `Person` (+ `@id="#person"`) | | `service.*` | `Service` (+ `@id="#service"`) | | `same_as[]` | `Web Page.same As[]` und/oder `main Entity.same As[]` | | `syndication[].url` | `Web Page.subject Of[]` (oder `main Entity.subject Of[]`) | | `content.path/sha256` (AI Feed) | (nur Feed) | --- ## 6) Internationalisierung - `locale` ↔ `in Language` 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`, `E Tag`, `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: [ { any Of: [ title, article.headline ] }, canonical, image, date_published ] recommended: [ { any Of: [ 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.street Address, organization.address.postal Code, organization.address.address Locality, organization.address.address Country, vatID, taxID, eori, register_number ] - id: profile-person when: { type: profile } required: [ person.name ] recommended: [ person.url, person.image, person.job Title, person.works For, person.same_as ] - id: pillar-service when: { type: pillar } required: [ title, canonical, image ] recommended: [ main_entity_type, service.name, service.description, service.area Served ] ``` --- ## 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%20Experience Innovation_Dodekaeder_Blog.png" main_entity_type: "Service" service: name: "Experience Innovation" description: "…" area Served: "CH" same_as: ["https://www.linkedin.com/company/tolksdorf-digital/"] syndication: - platform: "Linked In" 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 SM Es 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 SM Es de-risk innovation" author_name: "Jane Doe" ``` --- ## 10) Changelog - **v1.3** - JSON‑LD ist Pflicht auf kanonischen HTML‑Seiten (Web Page + main Entity). - 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