🧩 Schemas — Guide PRO (Web & Dev)

Client
                    |
                    v
                    API (OpenAPI/JSON Schema)
                    |  (1) Validate input -> 400/422 (details)
                    v
                    Service (business rules + auth)
                    |
                    |  (2) Persist with DB constraints -> 409/constraint mapped
                    v
                    Database (PK/FK/UNIQUE/CHECK)
                    |
                    |  (3) Publish event with schema -> registry compat gate
                    v
                    Message Broker (Avro/Proto)
                    |
                    v
                    Consumers (validate/parse) -> storage/analytics

Producer owns schema:
                    - API team owns OpenAPI
                    - DB team owns DB constraints
                    - Event producer owns message schema
                    Consumers:
                    - can request changes
                    - must be notified for breaking/deprecation

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

openapi: 3.1.0
                    info: { title: Users API, version: "1.0.0" }
                    paths:
                    /users:
                    post:
                    requestBody:
                    required: true
                    content:
                    application/json:
                    schema: { $ref: "#/components/schemas/UserCreate" }
                    responses:
                    "201":
                    description: Created
                    content:
                    application/json:
                    schema: { $ref: "#/components/schemas/User" }
                    components:
                    schemas:
                    UserCreate:
                    type: object
                    required: [email]
                    properties:
                    email: { type: string, format: email }
                    age: { type: integer, minimum: 18 }
                    User:
                    allOf:
                    - $ref: "#/components/schemas/UserCreate"
                    - type: object
                    required: [id]
                    properties:
                    id: { type: integer }

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

syntax = "proto3";
                    message UserCreated {
                    int64 id = 1;
                    string email = 2;
                    int32 age = 3;
                    }
                    // Règle: ne jamais réutiliser/renuméroter les IDs de champs.

<script type="application/ld+json">
                    {
                    "@context": "https://schema.org",
                    "@type": "Organization",
                    "name": "Ideo-Lab",
                    "url": "https://ideo-lab.com"
                    }
                    </script>

Comme tu le souhaites : URLs listées “brutes” dans un bloc code (pratique à copier).

JSON Schema:
                    https://json-schema.org/
                    https://json-schema.org/draft/2020-12/json-schema-core.html

                    OpenAPI:
                    https://spec.openapis.org/oas/latest.html
                    https://swagger.io/specification/

                    GraphQL:
                    https://spec.graphql.org/
                    https://graphql.org/learn/schema/

                    Protocol Buffers:
                    https://protobuf.dev/

                    schema.org (SEO):
                    https://schema.org/
                    https://developers.google.com/search/docs/appearance/structured-data/intro

                    General:
                    https://martinfowler.com/articles/consumerDrivenContracts.html

• Schema décoratif : écrit mais pas testé / pas enforced.
• Tout en “any/opaque” : plus aucune protection (dette cachée).
• Breaking change silencieux : rename / type change sans versioning.
• Pas d’inventaire consumers : tu ne sais même pas qui tu casses.
• DB sans contraintes : tu repousses le problème… dans la data (c’est pire).

1. Contrat explicite pour chaque objet métier (types + required + invariants).
2. Exemples (valides & invalides) versionnés à côté du schema.
3. Versioning + politique de dépréciation (deadline claire).
4. Compat gate en CI (refuse breaking changes non gérés).
5. Enforcement runtime : validation à l’entrée + mapping erreurs DB.
6. Ownership : qui maintient le schema, qui valide les changements.
7. Observabilité : métriques sur erreurs de validation et versions en prod.

1) EXPAND:
                            - ajouter colonne nullable / nouvelle table
                            - ajouter index en mode non bloquant (si possible)
                            2) BACKFILL:
                            - remplir progressivement (batchs) + monitoring
                            3) CONTRACT:
                            - NOT NULL, contraintes finales
                            - switch code/queries
                            - supprimer ancien champ après fenêtre

-- (1) colonne existe en NULL
                            ALTER TABLE users ADD COLUMN country text;

                            -- (2) backfill (en batch côté app/cron)
                            -- UPDATE users SET country='FR' WHERE country IS NULL LIMIT ...

                            -- (3) contrainte finale
                            ALTER TABLE users ALTER COLUMN country SET NOT NULL;

• Tu dois pouvoir reconstruire la DB “from scratch” via migrations (CI).
• Évite modifications manuelles en prod (ou alors : scriptées + commit dans repo).
• Ajoute des checks automatiques : diff schema prod vs attendu.

Application Layer
                    - business rules (complex)
                    - validations (shape)
                    |
                    v
                    Database Layer (hard guarantees)
                    - PK / FK / UNIQUE / CHECK  => integrity
                    - types                     => meaning
                    - indexes                   => performance contract
                    - grants                    => security boundaries

More constraints  -> more correctness  (usually good)
                    More indexes       -> faster reads      (but slower writes)
                    Goal:
                    keep constraints strong
                    keep indexes purposeful (query-driven)

auth.users (id PK, email UNIQUE, ...)
                    1
                    |
                    |  FK orders.user_id -> users.id
                    |
                    orders (id PK, user_id FK, created_at, status, ...)

                    Index:
                    idx_orders_user_created (user_id, created_at DESC)
                    Partial:
                    idx_orders_open WHERE status='OPEN'

-- contraintes
                    SELECT conname, contype, conrelid::regclass AS table_name
                    FROM pg_constraint
                    WHERE connamespace = 'auth'::regnamespace
                    ORDER BY table_name, conname;

                    -- index d'une table
                    SELECT indexname, indexdef
                    FROM pg_indexes
                    WHERE schemaname='public' AND tablename='orders';

SELECT table_schema, table_name, column_name, data_type, is_nullable
                    FROM information_schema.columns
                    WHERE table_schema IN ('auth','public')
                    AND column_name IN ('email','created_at','user_id')
                    ORDER BY table_schema, table_name;

SELECT constraint_name, constraint_type, status
                    FROM user_constraints
                    WHERE table_name = 'USERS'
                    ORDER BY constraint_type, constraint_name;

URLs en bloc code (copiable), comme tu l’aimes.

PostgreSQL:
                    https://www.postgresql.org/docs/current/ddl-schemas.html
                    https://www.postgresql.org/docs/current/ddl-constraints.html
                    https://www.postgresql.org/docs/current/indexes.html
                    https://www.postgresql.org/docs/current/sql-createindex.html

                    Oracle:
                    https://docs.oracle.com/en/database/
                    (chercher: "Oracle Database constraints", "CREATE TABLE", "CREATE INDEX")

                    General (design):
                    https://use-the-index-luke.com/

• Tout nullable + aucune contrainte → incohérences de data assurées.
• “Pas de FK pour la perf” sans stratégie alternative → orphelins, deletes dangereux.
• Types fourre-tout (text/json) sans validation → dette de données.
• Index partout → writes lents + bloat + maintenance pénible.
• Migrations destructrices sans plan (drop/rename direct) → downtime/rollback.
• Rôle applicatif trop puissant (DROP/ALTER) → catastrophe si compromis.

1. PK sur chaque table.
2. FK là où relation réelle + stratégie ON DELETE explicitée.
3. UNIQUE sur clés métier (email/slug/idempotency key).
4. CHECK pour invariants simples (enum, bornes, règles locales).
5. Index selon requêtes + index sur FKs si nécessaire.
6. Naming clair (constraints/index) pour diagnostic rapide.
7. Migrations safe (expand/backfill/contract), surtout sur grosses tables.
8. Rôles séparés (runtime vs migrations) + least privilege.
9. Audit : détecter drift (prod vs repo) + monitoring erreurs contraintes.

# 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.”