Carte Context Mapping #7 : Published Language

17 novembre 2025

📇 Carte #7 : Published Language

Vue Rapide

🎯 Objectif : Upstream publie un langage standard pour tous les downstream

👥 Relation d’équipe : Upstream/Downstream (nombreux downstream)

📊 Couplage : Bas (via langage public)

Concept

L’équipe upstream publie un langage commun (formats, événements, API) que tous les downstream adopent.

Upstream Service
    ↓
Published Language (JSON Schema, Events, OpenAPI)
    ↓ ↓ ↓ ↓ ↓
Downstream 1, 2, 3, 4, 5... (nombreux)

La philosophie : “Voici notre langage public. Si vous le respectez, ça fonctionne.”

Quand l’Utiliser ? ✅

✅ Vous avez nombreux downstream (5+)
✅ Vous voulez éviter une Anticorruption Layer pour chacun
✅ Le langage est stable et bien conçu
✅ Tous les downstream acceptent cette convention
✅ Vous gérez une plateforme ou infrastructure

Exemples

Platform Core Services : publishing standard APIs
REST APIs publiques : votre API, mon code
Event Stream (Kafka) : tous publient au même format
Database Schema public : tous lisent selon le même structure
Message Format : tous les services parlent gRPC/Protobuf

Quand l’Éviter ? ❌

❌ Le langage est instable ou change fréquemment
❌ Les downstream ont des besoins très différents
❌ C’est une dépendance unique/critique (plutôt: deux relations upstream/downstream)
❌ Il n’y a que 1-2 downstream (overkill)

Questions Clés à se Poser 💭

Le langage est-il réellement public et stable ?
Comment communiquez-vous les changements du langage ?
Versioning : comment gérez-vous les évolutions ?
Compliance : comment vérifiez-vous que tous suivent le langage ?
Support : qui aide les downstream à implémenter ?

Implications pour Upstream

Responsabilités

✓ Publier le langage (schémas, documentation)
✓ Maintenir rétro-compatibilité autant que possible
✓ Communiquer les breaking changes en avance
✓ Fournir des examples et tooling

Avantages

✓ Scalabilité : nombreux downstream sans surcharge
✓ Contrôle : votre langage = votre règles
✓ Clareté : tout le monde parle la même langue
✓ Flexibilité downstream : chacun implémente différemment

Risques

⚠️ Erreurs de design : mauvais langage = coûteux de changer
⚠️ Versioning : gérer plusieurs versions du langage
⚠️ Adoption : les downstream comprennent-ils le langage ?
⚠️ Responsabilité : vous êtes source de vérité

Implications pour Downstream

Responsabilités

✓ Respecter le langage publié
✓ Tester contre le langage
✓ Adapter votre contexte au langage

Avantages

✓ Simplicité : langage défini, pas de négociation
✓ Couplage bas : chacun implémente sa traduction
✓ Autonomie : comment tu implémentes, c’est ton problème
✓ Zero intégration : langage = contrat

Risques

⚠️ Langage peut ne pas fit : tu dois te contorsionner
⚠️ Lent à évoluer : si le langage n’est pas bon
⚠️ Responsabilité partagée : si le langage casse

Types de Published Languages

1. API REST avec OpenAPI

Upstream publishes OpenAPI spec:

openapi: 3.0.0
paths:
  /api/v1/customers:
    get:
      responses:
        '200':
          schema: Customer

Downstream:
  - Client 1: Implémente avec JS
  - Client 2: Implémente avec Python
  - Client 3: Implémente avec Go

2. Event Schema (Kafka)

Upstream publishes Avro/Protobuf:

OrderPlaced {
  orderId: UUID
  customerId: UUID
  items: OrderItem[]
  placedAt: timestamp
}

Downstream:
  - Analytics: consomme et agrège
  - Billing: crée invoice
  - Shipping: prépare expédition

3. Database Schema Public

Upstream publishes schema:

CREATE TABLE public_orders (
  id UUID,
  customer_id UUID,
  amount DECIMAL,
  created_at TIMESTAMP
)

Downstream:
  - Reads directement (avec restrictions)
  - Chacun transforme selon besoin local

4. gRPC/Protobuf

Upstream defines service:

service OrderService {
  rpc CreateOrder(OrderRequest) 
    returns (OrderResponse);
  rpc GetOrder(GetOrderRequest) 
    returns (Order);
}

Downstream:
  - Client généré automatiquement
  - Type-safe, versionned, performant

Exemple Concret : Plateforme Core Publishes Product

Contexte

Vous gérez Product Catalog.

5 services en ont besoin: Pricing, Inventory, Search, Recommendation, Analytics

Published Language (OpenAPI)

# product-service/openapi.yaml

paths:
  /api/v1/products/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
        sku:
          type: string
        name:
          type: string
        category:
          type: string
        price:
          type: object
          properties:
            amount:
              type: number
            currency:
              type: string
        tags:
          type: array
          items:
            type: string

Chaque Downstream Implémente Différemment

Pricing Service

GET /api/v1/products/{id}
→ Parse Product
→ Crée Price strategy
→ Calcule dynamic pricing

Inventory Service

GET /api/v1/products/{id}
→ Parse Product  
→ Mappe à Inventory Item
→ Attache stock levels

Search Service

GET /api/v1/products/{id}
→ Parse Product
→ Enrich avec metadata
→ Index dans Elasticsearch

Versioning Strategy

Conservative (Breaking Change Rare)

v1 → v1.1 (additive: new optional fields)
  → v1.2 (additive: new endpoints)
  → v1.3 (additive: new enum values)

v2 (breaking change):
  - Announced 12 months in advance
  - v1 support 18+ months
  - Deprecation headers
  - Migration guide

Aggressive (Fast Evolution)

v1 → v2 → v3 → v4 → ...

- Faster innovation
- Downstream must upgrade frequently
- Only last 2 versions supported

Pragmatic (Most Common)

v1 (stable, widely used)
  ├→ v1.x (bug fixes, minor improvements)
  └→ v2 (major improvement, some breaking)
      ├→ v2.x (iterations)
      └→ v3 (next major)

Support: 
  - v2 (current)
  - v1 (extended support 12mo)
  - v0 (legacy, no support)

Documenting the Language

Essential Documentation

1. Schema Definition
   - Types, fields, constraints
   - Examples

2. API Reference
   - Endpoints
   - Request/Response
   - Error codes
   - Rate limits

3. Migration Guide
   - v1 → v2 breaking changes
   - How to upgrade

4. Examples
   - Code samples in multiple languages
   - Integration tests

Governance & Evolution

Review Process

Proposal: Upstream wants to add feature
    ↓
Review with downstream representatives
    ↓
Is it backward compatible?
  ├→ Yes: approve, deploy
  └→ No: deprecation, timeline
    ↓
Communicate (blog, newsletter, doc update)
    ↓
Give time for adoption
    ↓
Monitor compliance

Checklist de Mise en Place ✓

Le langage est clairement défini (schema, documentation)
Vous avez plusieurs downstream (justifie l’effort)
Versioning strategy est claire
Il y a un deprecation process clair
Vous avez examples et tooling pour intégrer
Support process : qui aide les downstream ?

Ressources et Lectures

Domain-Driven Design par Eric Evans - Published Language
RESTful API Design - OpenAPI Specification
DDD Crew - Context Mapping
Protocol Buffers for gRPC/Protobuf

Notes de Facilitation pour l’Atelier

Animation

Demandez : “Comment communiquez-vous vos contrats ?”
Testez : “Vos downstream comprennent-ils le langage ?”
Documentez : “Quel est le processus d’évolution ?”

Pièges Communs

⚠️ Langage mal défini : ambiguïté cause des bugs
⚠️ Pas de versioning : changements cassent tout
⚠️ Mauvaise documentation : downstream ne l’utilisent pas
⚠️ Pas de support : downstream frustrés

Questions Provocatrices

“Vos downstream sont vraiment dans la même langue ?”
“Pouvez-vous changer le langage sans casser les downstream ?”
“Comment découvrez-vous des erreurs de langage ?”
“Y a-t-il un coût à maintenir plusieurs versions du langage ?”