SPACESORTIUM ORBIT HACKATHON™. Spécifications communes des données, API et événements d’intégration

ORBIT COMMON API & DATA SPECIFICATIONS

Spécifications communes des données, API et événements d’intégration

Première édition — 2026
Référentiel technique commun

BUILD THE COMPONENTS · CONNECT THE SYSTEM · INTEGRATE THE FUTURE

PRÉAMBULE

Le SPACESORTIUM ORBIT HACKATHON™ repose sur six missions technologiques distinctes mais interdépendantes :

ORBIT 01 — SOCIAL CORE
ORBIT 02 — NATION DIGITAL TWIN
ORBIT 03 — NATIOMETRIC AI
ORBIT 04 — NATIOSCOPE
ORBIT 05 — CITIZEN
ORBIT 06 — DATA & INFRASTRUCTURE

Ces six missions ne doivent pas produire six systèmes incompatibles.

Elles doivent contribuer à la construction progressive d'une même infrastructure SPACESORTIUM™.

Le présent document fixe donc le contrat technique commun portant sur :

les objets métier ;
les identifiants ;
les relations ;
les structures JSON ;
les API ;
les règles d'authentification ;
les permissions ;
les erreurs ;
la pagination ;
le versionnement ;
les événements ;
la provenance ;
la traçabilité ;
les règles d'intégration.

Son principe directeur est :

UNE ENTITÉ · UN IDENTIFIANT · UN CONTRAT · PLUSIEURS USAGES

1. OBJECTIF DU DOCUMENT

Le présent référentiel doit permettre à une équipe ORBIT de répondre sans ambiguïté à des questions comme :

Comment identifier une Nation ?

Comment rattacher une institution à un territoire ?

Comment récupérer les indicateurs d'une région ?

Comment une contribution citoyenne est-elle transmise à NATIOMETRIC AI ?

Comment NATIOSCOPE récupère-t-il les résultats d'analyse ?

Comment SOCIAL CORE associe-t-il une publication à une Nation ou à un événement ?

Comment les six missions reconnaissent-elles le même utilisateur ?

Comment savons-nous qu'une donnée est réelle, synthétique, expérimentale ou produite par une IA ?

Le document constitue ainsi le contrat d'interopérabilité de la première édition.

2. PRINCIPES NORMATIFS

Les termes suivants sont utilisés dans le document :

MUST / DOIT
Exigence obligatoire pour l'interopérabilité.

SHOULD / DEVRAIT
Règle recommandée pouvant faire l'objet d'une dérogation justifiée.

MAY / PEUT
Option laissée à l'équipe.

Toute dérogation à une règle MUST nécessite la validation du Comité technique ORBIT.

3. PRINCIPES GÉNÉRAUX

Les six équipes doivent respecter les principes suivants.

API-FIRST

Toute fonction destinée à être consommée par plusieurs missions doit disposer d'une interface documentée.

CONTRACT-FIRST

Le contrat d'échange doit être défini avant ou simultanément à son implémentation.

ONE SOURCE OF TRUTH

Une donnée métier critique doit disposer d'un propriétaire fonctionnel identifiable.

STABLE IDENTIFIERS

Un même objet conserve le même identifiant dans l'ensemble de SPACESORTIUM™.

EXPLICIT PROVENANCE

Toute donnée importante doit pouvoir indiquer son origine.

SECURITY BY DESIGN

Authentification, permissions et protection des données sont intégrées dès la conception.

VERSION EVERYTHING

API, objets critiques et contrats doivent être versionnés.

4. CONVENTIONS TECHNIQUES GÉNÉRALES

4.1 Format d'échange

Le format standard de la première édition est :

JSON — UTF-8

Les API utilisent :

HTTPS

et privilégient :

REST

4.2 Base URL

Exemple :

https://api.spacesortium.com/api/v1/

Pour les environnements ORBIT :

https://api-dev.spacesortium... https://api-test.spacesortium... https://api-demo.spacesortium...

Les domaines définitifs seront fournis par ORBIT 06.

4.3 Convention des routes

Les routes sont :

en minuscules ;
au pluriel ;
explicites ;
stables.

Exemples :

/api/v1/users /api/v1/nations /api/v1/territories /api/v1/institutions /api/v1/indicators /api/v1/events /api/v1/publications /api/v1/contributions /api/v1/documents /api/v1/notifications

5. IDENTIFIANTS

Principe

Chaque entité dispose d'un identifiant unique appelé :

Pour ORBIT 2026, le format recommandé est :

UUID

Exemple :

{ "id": "6a60d78d-540f-46a0-aaf2-e8be8d948cd0" }

Une fois créé, cet identifiant ne doit pas être modifié.

6. MÉTADONNÉES COMMUNES

Toute entité majeure devrait disposer des champs suivants :

{ "id": "uuid", "status": "active", "visibility": "public", "version": 1, "created_at": "2026-09-19T12:00:00Z", "updated_at": "2026-09-19T12:00:00Z", "created_by": "uuid", "updated_by": "uuid" }

Les dates utilisent :

ISO 8601 — UTC

Exemple :

2026-09-19T14:30:00Z

7. STATUTS COMMUNS

Lorsque cela est pertinent :

draft active inactive archived deleted pending validated rejected

Les suppressions fonctionnelles devraient privilégier le :

soft delete

plutôt que la suppression physique immédiate.

8. VISIBILITÉ

Les niveaux communs sont :

public authenticated community institution restricted private

Ils doivent être distingués des permissions individuelles.

Une donnée peut être institution tout en étant accessible uniquement à certains rôles de cette institution.

9. PROVENANCE DES DONNÉES

Toute donnée significative devrait pouvoir préciser :

{ "data_origin": "public", "source_type": "official", "source_name": "Example Source", "source_url": "https://...", "source_date": "2026-09-01", "confidence": 0.95, "validation_status": "validated" }

Les origines peuvent comprendre :

public official user_submitted partner synthetic simulated experimental ai_generated derived

Cette règle est particulièrement importante pour :

NATIOMETRIC AI
NATIOSCOPE
NATION DIGITAL TWIN

10. ENTITÉ USER

User représente l'identité technique commune d'un utilisateur.

Structure minimale

{ "id": "uuid", "email": "user@example.com", "display_name": "Amir", "locale": "fr", "status": "active", "roles": [ "user" ], "created_at": "2026-09-19T12:00:00Z" }

Les données sensibles d'authentification ne doivent jamais apparaître dans les réponses publiques.

11. PROFILE

Le Profile contient les informations de présentation.

{ "id": "uuid", "user_id": "uuid", "first_name": "Amir", "last_name": "Example", "bio": "Developer", "avatar_url": "https://...", "organization_id": "uuid", "territory_id": "uuid", "visibility": "public" }

Relation :

USER 1 ─── 1 PROFILE

12. NATION

Une Nation constitue une entité centrale du système.

{ "id": "uuid", "code": "DZ", "name": "Algérie", "official_name": "République algérienne démocratique et populaire", "iso_code": "DZA", "status": "active", "capital_territory_id": "uuid", "default_locale": "fr", "created_at": "..." }

Une Nation peut être reliée à :

Territories
Institutions
Indicators
Events
Documents
Organizations

13. TERRITORY

Les territoires doivent permettre une représentation hiérarchique.

{ "id": "uuid", "nation_id": "uuid", "parent_id": "uuid", "name": "Alger", "type": "wilaya", "administrative_level": 1, "code": "16", "geometry": {}, "centroid": { "lat": 36.75, "lng": 3.05 } }

Relation :

NATION │ └── TERRITORY │ └── TERRITORY │ └── TERRITORY

La hiérarchie ne doit pas être codée spécifiquement pour un seul pays.

14. INSTITUTION

Une institution peut être nationale ou territoriale.

{ "id": "uuid", "nation_id": "uuid", "territory_id": "uuid", "name": "Institution Example", "type": "public_administration", "level": "national", "website": "https://...", "status": "active" }

15. INDICATOR

Un indicateur décrit ce qui est mesuré.

{ "id": "uuid", "code": "POP_TOTAL", "name": "Population totale", "description": "...", "unit": "persons", "category": "demography", "methodology": "...", "validation_status": "validated" }

La valeur d'un indicateur doit être séparée de sa définition.

16. INDICATOR VALUE

Entité support nécessaire au modèle.

{ "id": "uuid", "indicator_id": "uuid", "nation_id": "uuid", "territory_id": "uuid", "period": "2025", "value": 47000000, "unit": "persons", "source_id": "uuid", "confidence": 0.98, "validation_status": "validated" }

Cette séparation permet :

un indicateur → plusieurs territoires → plusieurs périodes → plusieurs observations.

17. EVENT

Attention : ici, Event désigne un événement du monde réel, et non un événement logiciel.

{ "id": "uuid", "title": "Example Event", "event_type": "economic", "description": "...", "nation_id": "uuid", "territory_id": "uuid", "start_at": "2026-09-19T10:00:00Z", "end_at": null, "source_ids": [ "uuid" ] }

Catégories possibles :

political economic social scientific cultural environmental institutional technological other

18. PUBLICATION

Publication appartient principalement au domaine SOCIAL CORE.

{ "id": "uuid", "author_user_id": "uuid", "content_type": "text", "body": "Example publication", "nation_id": "uuid", "territory_id": "uuid", "institution_id": null, "event_id": null, "visibility": "public", "published_at": "..." }

Une publication peut ainsi être contextualisée territorialement ou institutionnellement.

19. CONTRIBUTION

Contribution représente une participation citoyenne ou une contribution structurée.

{ "id": "uuid", "author_user_id": "uuid", "type": "suggestion", "title": "Example contribution", "body": "...", "nation_id": "uuid", "territory_id": "uuid", "institution_id": "uuid", "status": "submitted", "submitted_at": "..." }

Types possibles :

suggestion observation request signal proposal consultation_response other

Cycle possible :

draft → submitted → received → under_review → processed → closed

20. DOCUMENT

Le système doit distinguer le document lui-même de ses métadonnées.

{ "id": "uuid", "title": "Rapport exemple", "document_type": "report", "mime_type": "application/pdf", "storage_url": "https://...", "nation_id": "uuid", "territory_id": null, "institution_id": "uuid", "source_name": "...", "published_at": "...", "visibility": "public" }

Tout document utilisé par NATIOMETRIC AI doit conserver sa provenance.

21. NOTIFICATION

{ "id": "uuid", "user_id": "uuid", "type": "contribution_status_changed", "title": "Mise à jour", "message": "...", "related_entity_type": "contribution", "related_entity_id": "uuid", "read": false, "created_at": "..." }

22. RELATIONS PRINCIPALES

La première version du graphe métier peut être résumée ainsi :

USER ├── PROFILE ├── PUBLICATION └── CONTRIBUTION NATION ├── TERRITORY ├── INSTITUTION ├── EVENT └── INDICATOR VALUE TERRITORY ├── INSTITUTION ├── EVENT ├── CONTRIBUTION └── INDICATOR VALUE INDICATOR └── INDICATOR VALUE DOCUMENT ├── NATION ├── TERRITORY └── INSTITUTION

23. RESPONSABILITÉ DES DONNÉES

Pour éviter les conflits, chaque domaine possède une équipe référente.

Domaine	Source de référence
Identité / Auth	ORBIT 06
User technical account	ORBIT 06
Profile / Social	ORBIT 01
Nation	ORBIT 02
Territory	ORBIT 02
Institution	ORBIT 02
Events	ORBIT 02
Indicators / observations	ORBIT 02, avec interfaces 03/04
Publications	ORBIT 01
Contributions citoyennes	ORBIT 05
AI enrichments	ORBIT 03
Visualisations	ORBIT 04
Infrastructure / API Gateway	ORBIT 06

Règle fondamentale

Le consommateur d'une donnée ne doit pas recréer une seconde source de vérité.

24. AUTHENTIFICATION

Les API protégées utilisent :

Authorization: Bearer <access_token>

Pour ORBIT v0.1, l'identité doit être :

centralisée ou centralisable

Les mécanismes définitifs pourront évoluer vers OAuth2 / OpenID Connect.

25. RÔLES

Rôles initiaux proposés :

visitor user contributor moderator researcher institution_representative builder admin service

Un rôle n'est pas une permission.

26. PERMISSIONS

Les permissions devraient suivre une convention :

resource:action

Exemples :

nation:read nation:write publication:create publication:moderate indicator:read indicator:write contribution:create contribution:review admin:manage_users

Cette approche permettra de faire évoluer les rôles sans modifier tout le système.

27. FORMAT STANDARD DES RÉPONSES

Réponse réussie :

{ "success": true, "data": {}, "meta": { "request_id": "uuid", "timestamp": "..." } }

Liste :

{ "success": true, "data": [], "meta": { "next_cursor": "...", "has_more": true } }

28. FORMAT STANDARD DES ERREURS

{ "success": false, "error": { "code": "RESOURCE_NOT_FOUND", "message": "Nation not found", "details": {} }, "meta": { "request_id": "uuid" } }

Codes communs :

VALIDATION_ERROR AUTHENTICATION_REQUIRED PERMISSION_DENIED RESOURCE_NOT_FOUND RESOURCE_CONFLICT RATE_LIMITED DEPENDENCY_UNAVAILABLE INTERNAL_ERROR

29. CODES HTTP

Utiliser notamment :

200 OK 201 Created 204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 409 Conflict 422 Unprocessable Entity 429 Too Many Requests 500 Internal Server Error 503 Service Unavailable

30. PAGINATION

Pour les listes importantes, le mode recommandé est :

cursor-based pagination

Exemple :

GET /api/v1/publications?limit=25&cursor=abc123

Réponse :

{ "meta": { "next_cursor": "def456", "has_more": true } }

La pagination par page peut être tolérée pour certaines interfaces simples de démonstration.

31. FILTRES

Convention :

?nation_id=... &territory_id=... &status=active &from=... &to=...

Exemple :

GET /api/v1/events?nation_id=...&from=2026-01-01

32. TRI

?sort=created_at &order=desc

Valeurs :

asc desc

33. ENDPOINTS — NATIONS

GET /api/v1/nations POST /api/v1/nations GET /api/v1/nations/{id} PATCH /api/v1/nations/{id}

Sous-ressources :

GET /api/v1/nations/{id}/territories GET /api/v1/nations/{id}/institutions GET /api/v1/nations/{id}/indicators GET /api/v1/nations/{id}/events

34. ENDPOINTS — TERRITORIES

GET /api/v1/territories POST /api/v1/territories GET /api/v1/territories/{id} PATCH /api/v1/territories/{id}

Exemple stratégique :

GET /api/v1/territories/{id}/indicators

35. ENDPOINTS — INSTITUTIONS

GET /api/v1/institutions POST /api/v1/institutions GET /api/v1/institutions/{id} PATCH /api/v1/institutions/{id}

36. ENDPOINTS — INDICATORS

GET /api/v1/indicators GET /api/v1/indicators/{id} GET /api/v1/indicators/{id}/values

Exemple :

GET /api/v1/indicators/{id}/values?territory_id=...&from=2020&to=2026

37. ENDPOINTS — EVENTS

GET /api/v1/events POST /api/v1/events GET /api/v1/events/{id} PATCH /api/v1/events/{id}

38. ENDPOINTS — SOCIAL CORE

GET /api/v1/profiles/{id} GET /api/v1/publications POST /api/v1/publications GET /api/v1/publications/{id} POST /api/v1/publications/{id}/comments POST /api/v1/publications/{id}/reactions

39. ENDPOINTS — CITIZEN

POST /api/v1/citizen/contributions GET /api/v1/citizen/contributions/{id} GET /api/v1/citizen/contributions PATCH /api/v1/citizen/contributions/{id}/status

40. ENDPOINTS — DOCUMENTS

GET /api/v1/documents POST /api/v1/documents GET /api/v1/documents/{id}

41. ENDPOINTS — NOTIFICATIONS

GET /api/v1/notifications PATCH /api/v1/notifications/{id}/read

42. ENDPOINTS — NATIOMETRIC AI

La première version pourra exposer des fonctions comme :

POST /api/v1/ai/analyze POST /api/v1/ai/classify POST /api/v1/ai/summarize POST /api/v1/ai/search

Une réponse IA doit idéalement fournir :

{ "result": "...", "sources": [], "confidence": 0.72, "experimental": true, "model": "...", "generated_at": "..." }

Règle essentielle

Une production IA ne doit jamais être présentée automatiquement comme :

un fait validé,
une décision institutionnelle,
une conclusion scientifique définitive
ou une décision juridique.

43. NATIOSCOPE

NATIOSCOPE doit principalement consommer des API métier plutôt que créer des copies de données.

Exemples :

GET /api/v1/nations/{id}/indicators GET /api/v1/territories/{id}/indicators GET /api/v1/events GET /api/v1/ai/...

NATIOSCOPE est principalement :

consumer + visualization layer

44. ÉVÉNEMENTS SYSTÈME

Il faut distinguer :

Event

événement du monde réel ;

DomainEvent

événement logiciel indiquant qu'une modification a eu lieu.

Exemples :

identity.user.created social.publication.created nation.territory.updated nation.institution.created indicator.value.updated citizen.contribution.submitted citizen.contribution.status_changed document.created ai.analysis.completed

45. FORMAT D'UN DOMAIN EVENT

{ "event_id": "uuid", "event_type": "citizen.contribution.submitted", "event_version": 1, "occurred_at": "2026-09-19T14:30:00Z", "producer": "citizen-service", "subject_id": "uuid", "data": {} }

Ces événements pourront ultérieurement être transportés via un broker ou une architecture événementielle.

Pour ORBIT 2026, une implémentation plus simple peut être retenue.

46. IDEMPOTENCE

Pour les opérations critiques pouvant être répétées accidentellement, l'API devrait accepter :

Idempotency-Key: <uuid>

Particulièrement pour :

POST contributions POST publications POST documents

Cela évite la création de doublons en cas de retry.

47. VERSIONNEMENT API

Les routes de la première édition utilisent :

/api/v1/

Toute rupture incompatible majeure nécessite :

/api/v2/

Une API publiée ne doit pas être modifiée de façon incompatible sans :

notification → période de transition → documentation de migration.

48. VERSIONNEMENT DES OBJETS

Certaines entités critiques devraient disposer de :

{ "version": 4 }

afin de faciliter :

la traçabilité ;
les mises à jour concurrentes ;
les migrations ;
les audits.

49. TRACEABILITY

Chaque requête importante devrait disposer d'un :

request_id

Les services devraient pouvoir transmettre :

X-Request-ID

afin de suivre une opération à travers plusieurs composants.

50. AUDIT

Les opérations sensibles doivent alimenter un AuditLog.

Exemples :

modification d'un rôle ;
changement de statut d'une contribution ;
suppression logique ;
modification institutionnelle ;
modification d'un indicateur validé ;
accès administratif.

Les journaux ne doivent jamais contenir :

passwords
access tokens
API keys
données personnelles sensibles inutiles.

51. DATA CLASSIFICATION

Je recommande quatre niveaux :

PUBLIC

Données publiables.

INTERNAL

Données réservées à l'écosystème.

CONFIDENTIAL

Données à accès contrôlé.

RESTRICTED

Données fortement sensibles nécessitant une autorisation spécifique.

Chaque jeu de données sensible doit connaître sa classification.

52. DEMO DATASET

La première édition doit disposer d'un jeu de données partagé :

ORBIT COMMON DEMO DATASET — v0.1

Il doit inclure au minimum :

Nations de démonstration ;
territoires ;
institutions ;
utilisateurs fictifs ;
publications ;
indicateurs ;
valeurs historiques ;
événements ;
documents ;
contributions citoyennes fictives.

Tous les IDs doivent être identiques dans les six environnements.

53. DATA ORIGIN

Chaque donnée de démonstration devra être qualifiée :

REAL_PUBLIC SYNTHETIC SIMULATED EXPERIMENTAL

L'interface devra éviter toute confusion entre données simulées et réelles.

54. CONTRAT D'INTÉGRATION MINIMAL

Pour considérer une équipe comme CONNECTED au Gate J3, elle doit disposer au minimum de :

1 API publiée ou consommée

1 interaction documentée avec une autre mission.

Au Gate J4 :

au moins un échange réel de données doit fonctionner.

55. SCÉNARIO E2E DE RÉFÉRENCE

Le scénario commun recommandé reste :

Un utilisateur s'authentifie.

SOCIAL CORE récupère son profil.

Le profil est relié à un territoire.

NATION DIGITAL TWIN expose les informations territoriales.

Les indicateurs sont récupérés.

NATIOMETRIC AI analyse certaines données.

NATIOSCOPE visualise les résultats.

L'utilisateur transmet une contribution dans CITIZEN.

La contribution génère un Domain Event.

10.

Une notification est créée.

11.

L'ensemble de la chaîne est journalisé.

56. DEFINITION OF API READY

Une API n'est pas considérée comme prête uniquement parce qu'elle répond 200.

Elle doit disposer de :

route ;
payload défini ;
réponse définie ;
erreurs ;
authentification ;
permissions ;
exemple ;
documentation ;
test minimal ;
propriétaire identifié.

57. DEFINITION OF DATA READY

Une donnée partagée doit posséder :

un identifiant ;
une définition ;
un format ;
une provenance ;
un propriétaire ;
un statut ;
des relations documentées ;
un niveau de qualité connu.

58. API CONTRACT FREEZE

Conformément au Runbook :

besoins API identifiés.

premières interfaces implémentées.

API CONTRACT FREEZE v0.1

Après ce jalon, toute modification incompatible doit être coordonnée avec les consommateurs concernés.

59. GOUVERNANCE TECHNIQUE

Le référentiel est administré par :

TECHNICAL DIRECTOR

arbitrage.

DATA / API LEAD

schémas et contrats.

INTEGRATION LEAD

compatibilité interéquipes.

SECURITY LEAD

authentification et sécurité.

DOMAIN OWNERS

responsables métier de chaque famille de données.

60. REGISTRE DES CONTRATS

Un registre central doit contenir :

API	Provider	Consumer	Version	Status
Identity	ORBIT 06	All	v1	Ready
Nation	ORBIT 02	03/04/05	v1	Build
Indicators	ORBIT 02	03/04	v1	Build
Citizen	ORBIT 05	03/04	v1	Planned

Les statuts possibles :

PROPOSED
DESIGNED
BUILDING
READY
TESTED
DEPRECATED

61. LIVRABLES TECHNIQUES ASSOCIÉS

Le présent référentiel devra progressivement être accompagné de :

OpenAPI Specification

orbit-api-v1.yaml

JSON Schemas

pour les principales entités.

Entity Relationship Diagram

modèle relationnel commun.

Domain Event Catalog

registre des événements.

Postman / Bruno / Insomnia Collection

pour les tests des API.

Demo Seed Dataset

jeu de données reproductible.

API Contract Registry

registre des dépendances interéquipes.

62. CONDITIONS DE VALIDATION

La Version 1.0 des spécifications communes pourra être déclarée opérationnelle lorsque :

les entités communes sont validées ;
les identifiants sont stabilisés ;
le modèle de données commun est publié ;
l'authentification commune est disponible ;
les routes prioritaires sont documentées ;
les API critiques disposent d'exemples ;
le Demo Dataset est chargé ;
au moins deux missions communiquent réellement ;
les conventions d'erreur sont appliquées ;
le système peut supporter le scénario E2E minimal.

CONCLUSION

L'interopérabilité n'est pas une conséquence heureuse du développement.

Elle doit être conçue.

Sans modèle commun de données, six équipes peuvent produire six applications.

Avec des identifiants communs, des API documentées, une identité partagée, des règles de provenance, des événements et des contrats explicites, elles peuvent commencer à produire :

UN SYSTÈME.

Le rôle du présent document est précisément d'établir ce langage commun.

La première édition d'ORBIT doit donc passer de :

« Voici mon application. »

à :

« Voici mon composant, voici son contrat, voici ce qu'il fournit au système et voici comment les autres composants peuvent l'utiliser. »

C'est à partir de ce moment qu'ORBIT cesse d'être simplement un Hackathon.

Il devient une opération d'ingénierie distribuée.