Proposition de schéma pour l'API GraphQL

[ggrossetie]

Résumé des changements

Renommages

v1	v2
_id	id (sur tous les types)
Article.title	Article.name
Article.owner	Article.creator
Article.workingVersion	Article.workingCopy
WorkingVersion	WorkingCopy
Version	ArticleVersion
Version.version (Int)	ArticleVersion.major
Version.revision	ArticleVersion.minor
Version.md	ArticleVersion.text
Version.bib	ArticleVersion.bibliography
Version.bibPreview	ArticleVersion.bibliographyPreview
WorkingVersion.md	WorkingCopy.text
WorkingVersion.bib	WorkingCopy.bibliography
User.acquintances	User.contacts
Query.user	Query.me
UserPermission.user: User!	UserPermission.userId: ID!

Nouveaux éléments

• ArticleVersion.revisionNumber : champ formaté "major.minor" (ex: "2.3")
• UserIdentity : nouveau type léger pour remplacer User dans les champs creator, owner, etc. (évite les requêtes profondes)
• MetadataFilter : input permettant de filtrer par métadonnées (key/value)
• User.collaborators : liste des utilisateurs partageant un espace de travail ou un article
• Query.users : query admin avec filtres userId, username, email
• Query.articles : nouveaux filtres corpusId, workspaceId, tagId, metadata, name
• Query.corpuses : nouvelle query de liste (remplace corpus(filter:...)) avec filtres workspaceId, metadata, name
• Query.tags : filtre par name

Suppressions / simplifications

• Champs mutants sur les types supprimés (pattern v1 anti-GraphQL) : Article.delete, Article.rename, Version.rename, Workspace.leave, Corpus.addArticle, etc. → à déplacer vers
  des mutations racines
• WorkspaceArticle / WorkspaceMember supprimés (types intermédiaires pour mutations embarquées)
• CorpusArticle simplifié : ne contient plus que articleId et order (plus de référence à Article ni de mutations embarquées)
• Corpus.workspace (String) → Corpus.workspaceId (ID)
• Tag.owner supprimé (remplacé par creator: UserIdentity!)
• Tag.articles supprimé du type Tag
• Workspace.articles / Workspace.corpus supprimés

Philosophie générale du changement

Le schéma v2 applique les bonnes pratiques GraphQL :

1. id au lieu de _id — découplage de MongoDB
2. Mutations déplacées à la racine — fini les mutations embarquées sur les types
3. UserIdentity comme type léger pour les références d'auteur/créateur — évite la récursion
4. Filtres enrichis sur les queries de liste
5. Nommage sémantique plus clair (workingCopy, major/minor, text, bibliography)

[netlify]

✅ Deploy Preview for stylo-docs canceled.

Name	Link
🔨 Latest commit	4f34606
🔍 Latest deploy log	https://app.netlify.com/projects/stylo-docs/deploys/69c646a52386c2000817b077

[ggrossetie]

@davidbgk @sardinecan

[sardinecan]

Hello,
Grosse révision en vue 😅 !

Quelques remarques :

Renommage

• Article.owner me semble plus parlant que Article.creator. C'est la terminologie utilisée par le système de permissions d'UNIX et reprise dans nombre d'API.
• si on retire les références aux formats dans WorkingVersion.md -> WorkingCopy.text et WorkingVersion.bib -> WorkingCopy.bibliography alors ne pourrait-on pas aussi adopter WorkingVersion.yaml -> WorkingVersion.metadata ?

Suppressions/Simplifications

• Workspace.articles / Workspace.corpus/ CorpusArticle. Cela me semble une grosse régression, l'intérêt de ces endpoints c'est justement de pouvoir tout récupérer d'un coup, sans réfléchir.
• par contre pour Corpus.Articles cela serait super d'éliminer la clé intermédiaire Article pour l'aligner avec Workspace :

articles{                        articles{
   article{                         id
      _id                           workingCopy{
      workingVersion{    ===>          text
         md                            metadata
         yaml                          bibliography
         bib                        }
      }                          }   
   }
}

[ggrossetie]

Renommage
Article.owner me semble plus parlant que Article.creator. C'est la terminologie utilisée par le système de permissions d'UNIX et reprise dans nombre d'API.

La notion de "owner" (propriétaire/appartenance) n'est pas tellement adaptée à Stylo où une personne crée un article et collabore dessus. L'article appartient aux personnes qui contribuent. Cela permet aussi d'aligner creator et createdAt.

Le terme "owner" évoque quelque chose en lien avec des droits/permissions et je pense que c'est bien de faire une distinction claire entre les permissions et la personne qui crée un objet.

si on retire les références aux formats dans WorkingVersion.md -> WorkingCopy.text et WorkingVersion.bib -> WorkingCopy.bibliography alors ne pourrait-on pas aussi adopter WorkingVersion.yaml -> WorkingVersion.metadata ?

C'est le cas les métadonnées sont accessibles avec metadata (format JSON). J'ai conservé metadataYaml même si à terme ce format YAML "legacy" sera disponible uniquement côté Stylo export. À terme, on peut imaginer un attribute metadata(format: MetadataFormat) avec par défaut du JSON et éventuellement du YAML.

Suppressions/Simplifications
Workspace.articles / Workspace.corpus/ CorpusArticle. Cela me semble une grosse régression, l'intérêt de ces endpoints c'est justement de pouvoir tout récupérer d'un coup, sans réfléchir.

Je pense que tu peux toujours le faire avec les différents types:

query all {

  articles { id } 

  workspaces { id}

  corpuses { id }

  tags { id } 
}

Cela va récupérer les articles, les espace de travail, les corpus et les étiquettes de l'utilisateur.
Si tu veux récupérer les articles d'un corpus ou d'un espace de travail, il faut utiliser articles avec les filtres correspondants.

Cela permet de garder la même structure de réponse quand tu veux récupérer des articles.

par contre pour Corpus.Articles cela serait super d'éliminer la clé intermédiaire Article pour l'aligner avec Workspace :

Les articles dans un corpus sont ordonnées. Autrement dit, c'est une relation avec des attributs, on a pas uniquement une liste d'articles. C'est la raison pour laquelle on a une liste de CorpusArticle.

[sardinecan]

Renommage
Article.owner me semble plus parlant que Article.creator. C'est la terminologie utilisée par le système de permissions d'UNIX et reprise dans nombre d'API.

La notion de "owner" (propriétaire/appartenance) n'est pas tellement adaptée à Stylo où une personne crée un article et collabore dessus. L'article appartient aux personnes qui contribuent. Cela permet aussi d'aligner creator et createdAt.

Le terme "owner" évoque quelque chose en lien avec des droits/permissions et je pense que c'est bien de faire une distinction claire entre les permissions et la personne qui crée un objet.

Il me semble qu'il est entendu que le propriétaire est toujours le créateur, et je ne suis pas sûr que ce soit une bonne chose de distinguer ces deux notions : l’article appartient-il vraiment aux contributeurs ? Ils peuvent effectivement collaborer dessus, mais ils n'ont pas les mêmes droits que le propriétaire, qui seul peut le supprimer par exemple.

si on retire les références aux formats dans WorkingVersion.md -> WorkingCopy.text et WorkingVersion.bib -> WorkingCopy.bibliography alors ne pourrait-on pas aussi adopter WorkingVersion.yaml -> WorkingVersion.metadata ?

C'est le cas les métadonnées sont accessibles avec metadata (format JSON). J'ai conservé metadataYaml même si à terme ce format YAML "legacy" sera disponible uniquement côté Stylo export. À terme, on peut imaginer un attribute metadata(format: MetadataFormat) avec par défaut du JSON et éventuellement du YAML.

👌 mea culpa la sérialisation JSON m'avait échappé.

Suppressions/Simplifications
Workspace.articles / Workspace.corpus/ CorpusArticle. Cela me semble une grosse régression, l'intérêt de ces endpoints c'est justement de pouvoir tout récupérer d'un coup, sans réfléchir.

Je pense que tu peux toujours le faire avec les différents types:

query all {

  articles { id } 

  workspaces { id }

  corpuses { id }

  tags { id } 
}

Cela va récupérer les articles, les espace de travail, les corpus et les étiquettes de l'utilisateur. Si tu veux récupérer les articles d'un corpus ou d'un espace de travail, il faut utiliser articles avec les filtres correspondants.

Cela permet de garder la même structure de réponse quand tu veux récupérer des articles.

Ce qui est intéressant avec la formule actuelle, c'est de récupérer une hiérarchie à partir du Workspace :

{
  "Workspace": {
    "corpus": [
      {
        "articles": []
      },
    "articles": []
    ]
  }
}

Pendant le processing des données on peut facilement propager les héritages ou les dépendances aux niveaux inférieurs. Si on peut toujours récupérer cette hiérarchie c'est nickel !

par contre pour Corpus.Articles cela serait super d'éliminer la clé intermédiaire Article pour l'aligner avec Workspace :

Les articles dans un corpus sont ordonnées. Autrement dit, c'est une relation avec des attributs, on a pas uniquement une liste d'articles. C'est la raison pour laquelle on a une liste de CorpusArticle.

OK je comprends mieux ;)