SEO Schema JSON-LD avec Codex : SKILL.md copiable et workflow de validation

Réponse courte : Schema doit être une copie structurée des faits de la page

Si vous cherchez un prompt Codex SKILL.md pour SEO Schema JSON-LD, vous trouverez plus bas un modèle prêt à copier. La règle qui le sous-tend compte davantage que le code : les données structurées doivent exprimer des faits qu'un visiteur peut vérifier sur la page. Elles ne servent pas à produire l'objet JSON le plus volumineux possible.

Codex est utile parce qu'il peut examiner la page, ses données de contenu et le balisage existant avant de recommander un type ou d'écrire du JSON-LD. Cet ordre est important. Une demande vague comme « ajoute tout le Schema possible » produit souvent des aggregateRating, des prix, des auteurs ou des dates de publication inventés. Ces champs peuvent être syntaxiquement valides tout en décrivant mal la page.

Google recommande JSON-LD lorsque la configuration du site le permet, car il est généralement plus simple à mettre en œuvre et à maintenir. Google précise aussi que le balisage doit décrire la page où il se trouve, refléter le contenu visible et rester exact. Réussir le Rich Results Test ne garantit pas un résultat enrichi.

Choisissez le type principal avant les objets de soutien

Commencez par une question simple : que regarde principalement le visiteur ? La réponse doit déterminer le type Schema.org principal. Le fil d'Ariane, les données d'organisation et la vidéo peuvent compléter cet objet lorsqu'ils décrivent des informations visibles sur la même page.

Le vocabulaire de Schema.org est beaucoup plus large que les fonctions de résultats enrichis de Google. Pour Google Search, le guide Search Central actuel de la fonction visée fait davantage autorité que la simple existence d'une propriété Schema.org.

Commencez par l'objectif de la page. Le type découle des faits visibles, pas l'inverse.

Un workflow Codex plus sûr comporte quatre contrôles

1. Inventaire des faits. Extrayez uniquement le texte visible, les champs CMS fiables rendus sur la page ou les données explicitement confirmées. Marquez chaque champ comme confirmé, absent ou à confirmer par une personne.
2. Décision de type. Choisissez un type principal qui correspond à l'objectif central. Expliquez les alternatives au lieu d'empiler tous les types plausibles.
3. Code et correspondance. Produisez le JSON-LD avec une source pour chaque valeur. Omettez les propriétés inconnues plutôt que de créer des valeurs de remplacement.
4. Validation et publication. Vérifiez la syntaxe JSON, les exigences propres à la fonction, le DOM rendu, URL Inspection et le rapport Search Console adapté.

Le Skill ci-dessous formalise ces contrôles. Il demande à Codex d'auditer avant de modifier le code, ce qui limite le risque d'un balisage apparemment valide mais déconnecté du contenu réel.

Copiez ce Skill Codex SEO Schema JSON-LD (SKILL.md)

Enregistrez le bloc suivant comme configuration de Skill. Il ne contient ni répertoire local, ni nom d'utilisateur, ni jeton d'accès, ni valeur de variable d'environnement, ni chemin privé. Il impose aussi à Codex d'exclure le contexte sensible de ses réponses.

---
name: seo-schema-jsonld
description: Audit visible page facts, recommend accurate Schema.org JSON-LD, implement it safely, and validate it against Google structured-data requirements.
---

# SEO Schema JSON-LD

Use this skill when a user asks to add, repair, review, or validate Schema.org JSON-LD / structured data for a website page, template, CMS entry, or component.

## Primary rule

Treat structured data as a structured representation of the page's user-visible facts. Never use it to invent, hide, exaggerate, or imply information that the page does not support.

## Privacy and output safety

- Never print absolute local paths, home directories, usernames, credentials, tokens, cookies, API keys, environment-variable values, private URLs, or repository-specific secrets.
- Refer to files with short, project-relative labels when needed, such as `src/pages/article.tsx` or `the page template`.
- Do not copy sensitive values into JSON-LD, examples, logs, commit messages, screenshots, or explanations.
- If input contains secrets or private identifiers, omit them and state that sensitive values were excluded.

## Required workflow

### 1. Inspect before generating

Read the relevant page, template, content data, and any existing structured data. Build a fact inventory using only:

- visible page text and user-visible UI;
- trusted CMS fields that are rendered on that page;
- verified product, organization, author, or breadcrumb data supplied by the user.

For every candidate property, label it `confirmed`, `missing`, or `needs human confirmation`. Do not infer missing values from brand names, URLs, conventions, or unrelated pages.

### 2. Choose the narrowest suitable type

Identify the page's primary purpose first. Recommend one primary Schema.org type that truthfully describes it. Add supporting objects only when they also describe user-visible information on the same page.

Explain the recommended primary type, supporting types, why each applies, and types deliberately rejected.

For Google rich-result eligibility, consult the current Google Search Central documentation for the target feature. Schema.org support alone does not establish Google feature support.

### 3. Apply strict data guardrails

Never generate these values unless they are confirmed and visible or otherwise explicitly verified by the user:

- `aggregateRating`, `review`, or review counts;
- price, currency, availability, offer dates, shipping, or return policy;
- author, publisher, logo, address, phone, social profile, or `sameAs`;
- publication dates, modification dates, images, video duration, or interaction counts;
- FAQ questions and answers that are not visibly present;
- event, job, medical, financial, legal, or local-business claims.

Never add misleading `FAQPage`, fake reviews, hidden content, keyword lists, or unrelated types. Prefer fewer complete and accurate properties over many uncertain ones.

### 4. Produce the implementation

Return these sections in order:

1. `Fact inventory` - property, value or status, and visible source.
2. `Schema decision` - primary type, supporting types, assumptions, and exclusions.
3. `JSON-LD` - valid JSON inside one `application/ld+json` script block. Use placeholders only in a clearly labeled illustrative example; never present placeholders as production-ready values.
4. `Implementation note` - the safe insertion point for the site's framework or CMS, without exposing private paths.
5. `Validation checklist` - syntax, rendered-page check, Google Rich Results Test when applicable, Schema Markup Validator, URL Inspection after deployment, and Search Console monitoring.
6. `Open questions` - every field that needs a human decision.

If editing code is requested, make the smallest scoped change. Preserve existing valid markup, avoid duplicate entities, and explain any conflict before replacing it.

## JSON-LD quality checks

Before finalizing, verify all of the following:

- JSON parses and uses `https://schema.org` as `@context`.
- The main type matches the page's main user-visible purpose.
- Every emitted value has a page-level source or explicit user confirmation.
- Required fields for the intended Google feature are present and accurate.
- URLs are canonical, publicly reachable URLs when the property requires a URL.
- Dates use ISO 8601 where required.
- Multiple entities are connected deliberately, not duplicated accidentally.
- The markup remains available to crawlers in the rendered response.
- The result contains no secrets, local paths, private identifiers, or fabricated claims.

## Limitations to state plainly

Valid structured data can help search engines understand a page and make it eligible for certain search appearances. It does not guarantee rich results, rankings, traffic, citations, or inclusion in AI answers.

Utilisez le Skill avec une étape d'approbation

Ne vous contentez pas de demander « ajoute Schema à cette page ». Donnez à Codex la page et les critères d'acceptation. Ce prompt constitue un bon départ :

Use the SEO Schema JSON-LD skill to review this article page.

Goal: add accurate Article and BreadcrumbList JSON-LD if the visible content supports them.
First return the fact inventory and schema decision. Do not edit code until I approve the decision.
Do not create ratings, reviews, author details, dates, images, or organization fields that are absent from the page.
After approval, make the smallest implementation change and provide the validation checklist.

Pour un grand modèle, conservez l'étape « inventaire et décision avant modification ». Elle ajoute une courte revue, mais empêche une hypothèse erronée de se propager à des milliers d'URL.

De l'audit à la publication en 30 minutes

Après publication, utilisez URL Inspection pour vérifier que Google récupère et analyse la page. Consultez ensuite le rapport d'amélioration Search Console concerné afin de repérer les erreurs de modèle, de déploiement ou de source de données à grande échelle. Le premier vérifie une URL, le second révèle les problèmes systémiques.

Chaque couche détecte un défaut différent. Un objet syntaxiquement valide peut encore échouer sur les faits ou le déploiement.

Un exemple de page d'article volontairement minimal

Ce code est illustratif, pas prêt pour la production. Il montre la forme de BlogPosting et BreadcrumbList. Utilisez des valeurs réelles confirmées sur la page pour le titre, la description, l'URL, l'auteur, la date et l'image. Si un fait n'existe pas, ne l'ajoutez pas uniquement pour compléter l'objet.

L'exemple omet volontairement la note, l'auteur, la date de publication, l'image et l'éditeur. Ce ne sont pas des décorations SEO facultatives, mais des affirmations qui exigent une source fiable.

Cinq façons dont un balisage techniquement valide échoue encore

L'analyse JSON ne vérifie pas la vérité

Un validateur JSON indique si la syntaxe peut être analysée. Il ne sait pas si la page contient réellement les avis, le prix ou l'auteur déclarés, ni si Product décrit un produit ou une simple page de service. L'inventaire des faits intercepte tôt la plupart de ces erreurs.

Plus d'objets ne signifie pas un meilleur balisage

Une recette avec une vidéo visible peut légitimement contenir Recipe, VideoObject et un fil d'Ariane. Son objectif principal doit néanmoins rester clair. Ajouter Article, Product, FAQPage et HowTo à une page générique augmente généralement la maintenance et le risque d'incohérence.

Visibilité et fraîcheur ont besoin du même responsable

Les consignes générales de Google demandent que les données structurées représentent la page et que les informations sensibles au temps restent à jour. Prix, stocks, dates d'événements, offres d'emploi et notes ne doivent pas être des valeurs collées une fois pour toutes. Reliez les faits dynamiques à une source contrôlée et retestez après tout changement de modèle.

FAQPage n'est pas une décoration générique de questions

Seules les questions et réponses réellement visibles appartiennent au balisage FAQ. Les fonctions Google peuvent imposer des conditions supplémentaires. Publiez d'abord une FAQ authentique et complète, puis vérifiez le guide actuel. N'inventez pas des questions uniquement pour viser une apparence de résultat.

Schema ne contourne ni l'exploration, ni l'indexation, ni la qualité

Une page bloquée par noindex, un contrôle d'accès ou des règles d'exploration ne devient pas éligible grâce à JSON-LD. Schema est une couche du SEO technique, pas un substitut à l'explorabilité, au contenu utile ou à l'expérience. Pour un audit plus large, choisissez le workflow adapté dans le répertoire des outils SEO Auspia .

Liste de contrôle avant publication

• [ ] Le type principal est indiqué et peut être justifié en une phrase.
• [ ] Chaque valeur JSON-LD possède une source visible ou fiable et rendue.
• [ ] Notes, avis, prix, stock, auteur, date, image et données d'organisation n'ont pas été inventés.
• [ ] La modification ne duplique pas des entités du CMS, d'un plugin ou d'un autre composant.
• [ ] Le JSON est valide et le balisage apparaît dans le DOM rendu après déploiement.
• [ ] Les propriétés obligatoires de la fonction Google ont été vérifiées dans la documentation actuelle.
• [ ] Rich Results Test, le cas échéant, et Schema Markup Validator ont été utilisés.
• [ ] URL Inspection et une revue Search Console sont programmés après publication.
• [ ] L'équipe comprend qu'un balisage valide crée une éligibilité et de la clarté, pas une garantie de résultat ou de classement.

Questions fréquentes

Un SKILL.md peut-il décider du Schema nécessaire à mon site ?

Il peut recommander à partir des faits et identifier les inconnues, mais ne remplace pas la confirmation. Prix, avis, données d'organisation, auteurs et dates doivent provenir d'une source fiable ou du responsable concerné.

JSON-LD doit-il être placé dans <head> ou <body> ?

Google accepte JSON-LD dans <head> comme dans <body>. Utilisez l'emplacement stable que votre framework ou CMS peut synchroniser avec le contenu. Le test important consiste à vérifier que Google peut explorer un balisage valide correspondant au rendu.

Pourquoi rien n'a changé après un Rich Results Test réussi ?

Un test réussi confirme des signaux techniques, mais n'oblige pas Google à afficher un résultat enrichi. Le traitement dépend de la requête, de l'appareil, du lieu, de la page et d'autres signaux. Vérifiez la cohérence et l'indexabilité au lieu d'ajouter des propriétés sans preuve.

Codex doit-il remplir toutes les propriétés Schema.org ?

Non. Google préfère quelques propriétés recommandées complètes et exactes à un grand nombre de propriétés incomplètes ou erronées. Cette contrainte doit figurer dans le Skill, pas seulement dans un prompt ponctuel.

Références officielles

• Google Search Central: Introduction to structured data markup
• Google Search Central: General structured data guidelines
• Google Rich Results Test
• Schema.org

Auteur : Julian Mercer, praticien du SEO technique avec 14 ans d'expérience chez Auspia. Il écrit sur l'exploration, le rendu, les données structurées et les systèmes techniques que les équipes peuvent exploiter de manière fiable.