🧩 Schemas — Guide PRO (Web & Dev)

# Exemple “contrat” (humain)
User:
  id: integer (required)
  email: string (required, email format)
  age: integer (optional, min 18)
=> Si tu ne peux pas l’exprimer clairement, le schema manque.

• Écrire le schema avant l’implémentation (“contract-first”) si l’API est publique / multi-clients.
• Mettre des exemples (valides & invalides) à côté du schema.
• Automatiser : lint → tests → génération docs → compat checks.

• “Schema = documentation approximative” (non testée) → divergence inévitable.
• Champs “any/opaque” partout → le schema ne protège plus rien.
• Breaking changes silencieux (renommage champ, changement type).

1. Chaque objet métier a un contrat (types + règles).
2. Le contrat est versionné (tag, commit, registry).
3. Le contrat est testé (CI) et idéalement enforced (runtime).
4. Tu as une stratégie deprecation (deadline + fallback).

# Pattern utile : “valid/invalid fixtures”
fixtures/
  user.valid.json
  user.invalid_missing_email.json
  user.invalid_age_negative.json
=> tests de contrat simples, lisibles, robustes.

-- PostgreSQL (exemple)
CREATE SCHEMA IF NOT EXISTS auth;

CREATE TABLE auth.users (
  id         bigserial PRIMARY KEY,
  email      text NOT NULL UNIQUE,
  created_at timestamptz NOT NULL DEFAULT now(),
  age        int CHECK (age IS NULL OR age >= 18)
);

-- Contrat : email unique, age>=18, created_at toujours renseigné

• Mettre les règles critiques en DB : NOT NULL, UNIQUE, FK, CHECK.
• Éviter que l’appli soit le seul gardien (“business rules only in code” = drift).
• Nommer et documenter les contraintes : les erreurs DB deviennent lisibles.
• Contrôler le “schema drift” (prod ≠ migrations) via CI/CD.

• Tout en NULL + zéro contrainte → la DB ne protège rien.
• FK absentes “pour la perf” → incohérences, delete orphelins.
• Types “fourre-tout” (text/json) sans validation → dette de données.

1. PK sur chaque table.
2. FK explicites + index associés si nécessaire.
3. Contraintes CHECK pour invariants métier simples.
4. Types précis (éviter text/json “par défaut”).
5. Migrations idempotentes + rollback strategy.

# Exemple mental (peu importe le framework)
Model User:
  email: string unique not null
  created_at: datetime default now
Migration:
  add column / add constraint / add index
Drift typique:
  prod a une colonne en plus ou une contrainte manquante

• CI : appliquer migrations sur une DB “from scratch” + exécuter tests.
• Pour prod : migration safe (add column nullable → backfill → set not null).
• “Expand/Contract pattern” pour changements lourds (renommage, split table, etc.).
• Monitoring : détecter les migrations lentes/verrouillantes.

• Modifier la DB à la main en prod puis “oublier” de créer la migration.
• Migration qui fait data + schema sans stratégie (rollback impossible).
• Renommage champ = breaking change si clients / ETL / BI existent.

1. Migrations linéaires et reproductibles.
2. Stratégie rollback (ou forward-only documenté).
3. Validation “schema drift” automatisée (CI + check prod).
4. Changements “online” pour tables volumineuses.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id":    {"type":"integer"},
    "email": {"type":"string","format":"email"},
    "age":   {"type":"integer","minimum":18}
  },
  "required": ["id","email"]
}

# points clés
- required = champs obligatoires
- additionalProperties=false = pas de champs “surprise”
- format=email = validation sémantique minimale

• Verrouiller l’objet : additionalProperties=false (sinon dérive silencieuse).
• Factoriser via $ref (User, Money, Address…).
• Avoir des fixtures “valid/invalid” et tester en CI.
• Générer documentation + exemples automatiquement.

• “type: object” sans properties → useless.
• Tout en anyOf complexes → schema incompréhensible.
• Formats non testés (ou faux sentiment de sécurité).

1. Types + required définis.
2. Règles métier simples intégrées (min/max/enum).
3. Interdiction de champs inconnus si besoin.
4. Tests de validation en CI.

openapi: 3.1.0
info: { title: Users API, version: "1.0.0" }
paths:
  /users/{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id: { type: integer }
        email: { type: string, format: email }

• Définir des réponses d’erreur standard (400/401/403/404/409/422) avec schema commun.
• Mettre des examples request/response (très important pour les clients).
• Bloquer les breaking changes via tooling (diff de spec en CI).
• Contract tests : serveur conforme à la spec + clients générés compilent.

• Spec écrite “après” et jamais synchronisée → faux contrat.
• “schema: {}” partout → doc inutile.
• Changements sans versionning/deprecation → chaos côté clients.

1. Chaque endpoint a params + réponses typées.
2. Auth documentée (bearer, api key, oauth…).
3. Erreurs standardisées avec schema.
4. Spec versionnée + diff check en CI.

type User { id: ID!, email: String!, age: Int }
type Query { user(id: ID!): User }
input CreateUserInput { email: String!, age: Int }
type Mutation { createUser(input: CreateUserInput!): User! }

• Limiter la complexité : depth/complexity limits + timeouts.
• Résoudre N+1 (DataLoader pattern, batching).
• Déprécier proprement : @deprecated(reason: "...") + fenêtre de migration.
• Registry/federation si multi-services.

• Schémas trop “DB-like” (exposer tables internes) → couplage fort.
• Aucune limite → requêtes monstrueuses / DoS applicatif.
• Champs qui changent de sens sans versioning → clients cassés.

1. Schema SDL versionné.
2. Déprecations tracées.
3. Limits + protections perf.
4. Tests de contrat (introspection + snapshot).

// Protobuf (extrait)
message UserCreated {
  int64 id = 1;
  string email = 2;
  int32 age = 3; // optional by presence semantics depending on syntax/version
}

# Règles d’évolution (simplifiées)
- ajouter un champ : OK (si optional / default)
- supprimer un champ : dangereux (préférer "deprecated")
- renuméroter un field id : NON (breaking)

• Avoir un Schema Registry (même minimal) + validation à la publication.
• Politique d’évolution : backward-only vs full-compat selon tes consommateurs.
• Déprécier avant de supprimer, et attendre la fin de fenêtre de migration.
• Tester compat en CI (ex: “new schema is backward compatible”).

• Publier des events JSON sans schema → consumers fragiles.
• Breaking change silencieux → incidents cross-services.
• Pas d’ownership → “tout le monde change tout”.

1. Schema versionné + registry.
2. Compat checks en CI.
3. Deprecation policy claire.
4. Consumer tests (canaries) sur nouveaux schémas.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Schemas en dev : guide",
  "author": { "@type": "Person", "name": "Guillaume" },
  "datePublished": "2026-02-12"
}
</script>

• Utiliser JSON-LD (simple à injecter server-side).
• Rester fidèle au contenu visible (sinon risque de pénalité).
• Tester régulièrement (données structurées) et versionner les templates.

• Mettre du schema “fake” (FAQ inventée, reviews fausses) → mauvais plan.
• Dupliquer/injecter plusieurs JSON-LD incohérents sur la même page.

1. Type schema.org cohérent (Article/Product/Org…).
2. Champs essentiels présents.
3. Pas de divergence contenu vs markup.

# Exemple de config "attendue"
app:
  env: "prod"
  port: 8080
  database_url: "postgres://..."
limits:
  rate_per_min: 1200

# Un schema te permet d’empêcher :
# - port string au lieu d’int
# - database_url manquant
# - env hors {dev,staging,prod}

• Valider en CI (pré-merge) et au démarrage applicatif.
• Garder des defaults explicites (sinon comportement surprise).
• Documenter les “breaking config changes” (nouvelle clé requise, clé supprimée).

• Config “libre” sans validation → incidents “bêtes” en prod.
• Secrets directement dans les configs versionnées.

1. Schema de config (même minimal) + validation CI.
2. Defaults + required clarifiés.
3. Secrets externalisés (vault/variables d’env).

# REST (typique)
- add field optional => OK
- remove field       => breaking
- change type string->int => breaking
- rename field       => breaking (sauf alias/deprecation)

# DB
- add column nullable => OK
- set NOT NULL sans backfill => risque (breaking en runtime)
- drop column => breaking pour ETL/BI/old code

• Définir une policy deprecation : annonce + window + date de retrait.
• Prefer “additive changes” (ajout) plutôt que modifications destructives.
• Versionner les contrats : tags, releases, registry.
• Mettre un “compat gate” en CI : refuser un breaking change non versionné.

• “On change vite, les clients suivront” → non.
• Deprecation sans date → personne ne migre.
• Pas d’inventaire des consumers → impossible de savoir qui casse.

1. Types & champs stables.
2. Breaking change = version majeure ou endpoint v2.
3. Deprecation documentée avec deadline.
4. Compat checks automatisés.

Client
  |
  v
API Gateway / Router
  |
  v
(1) Validate request schema  -----> reject 400/422 (with details)
  |
  v
(2) Business rules + auth
  |
  v
(3) Persist with DB constraints  ---> reject 409/constraint error (mapped)
  |
  v
(4) Publish event with message schema -> registry compat gate
  |
  v
Consumers validate / parse -> store / act

• Validation “shape” (types/required) tôt, règles métier ensuite.
• Mapper proprement erreurs DB (unique/fk/check) vers erreurs API.
• Centraliser les contrats (repo “schemas” / registry) pour éviter la divergence.
• Tracer : quelles versions de schema sont utilisées en prod.

1. Validation request/response (au moins request).
2. DB constraints pour invariants critiques.
3. Contrat event (schema evolution gérée).
4. Observabilité des erreurs de validation.

# Idées d’automatisation (CI)
- Lint schema (format + conventions)
- Validate fixtures (valid/invalid)
- Diff compat (old vs new)
- Generate docs (HTML/markdown)
- Generate clients (si besoin)
- Publish schema artifact (registry)

# “Contract tests” minimalistes
Given: OpenAPI/JSON Schema
When: run tests against API
Then: responses match schemas + required fields are present

• Nommer les objets : User vs UserV2 (éviter V2 trop tôt, préférer compat).
• Éviter les duplications : un schema “User” réutilisé partout via ref.
• Limiter les “any/unknown” aux zones réellement extensibles.
• Mettre des “examples” dans les schemas (accélère FE & QA).

• Docs séparées du schema → drift.
• Règles d’évolution implicites (“au feeling”).
• Aucune ownership → personne n’ose dire non aux breaking changes.

1. Repo/registry des schemas + ownership.
2. Compat gate en CI.
3. Fixtures valid/invalid.
4. Docs auto + exemples.

• JSON Schema (spec + drafts)
• OpenAPI (3.0/3.1) + tooling codegen
• GraphQL SDL + deprecations
• Protocol Buffers / Avro + schema evolution
• schema.org + JSON-LD

1. Contrats centralisés + ownership.
2. Validation automatisée (CI) + erreurs propres (runtime).
3. Versioning & compat (deprecation policy).

SAFE (souvent) :
- ajouter un champ optional
- ajouter une colonne nullable
- ajouter un nouvel endpoint / nouveau type

BREAKING (souvent) :
- supprimer/renommer un champ
- changer type string->int
- rendre obligatoire un champ sans default/backfill
- supprimer une colonne utilisée par ETL/BI

“Pour moi un schema, c’est un contrat formel :
1) il définit les types et contraintes,
2) il est validé automatiquement (CI + runtime),
3) il est versionné avec une politique de compatibilité.
Ça évite les ambiguïtés FE/BE/DB et réduit les incidents de prod.”