La norme ISO 8601 définit non seulement un format de dates, mais aussi un format d'écriture des durées — une chaîne comme PT1H30M, qui décrit sans ambiguïté et de façon lisible par une machine « 1 heure 30 minutes ».
La structure du format
La chaîne commence toujours par la lettre P (period). Les composants de date (années, mois, jours) viennent juste après P, tandis que les composants de temps (heures, minutes, secondes) viennent après la lettre T, qui sépare la partie date de la partie heure. Par exemple, P2DT4H signifie « 2 jours et 4 heures ».
Pourquoi la lettre T est nécessaire
Sans le séparateur T, la lettre M serait ambiguë — elle désigne à la fois les mois (dans la partie date) et les minutes (dans la partie heure). C'est pourquoi P1M signifie « 1 mois », tandis que PT1M signifie « 1 minute ».
Un scalaire personnalisé dans les API GraphQL
GraphQL n'a pas de type natif pour représenter une durée, donc plusieurs bibliothèques de scalaires personnalisés (comme graphql-scalars) définissent un type Duration qui valide et sérialise précisément selon la syntaxe ISO 8601. Un schéma GraphQL exposant un champ duration: Duration renverra donc typiquement une chaîne du type PT1H30M plutôt qu'un nombre de secondes brut.
Pourquoi c'est utile
- Déchiffrer la durée d'une vidéo ou d'un événement à partir de la réponse d'une API tierce.
- Générer une chaîne de durée ISO 8601 valide pour sa propre API ou son propre flux de données.
- Convertir des durées entre un format lisible par un humain et la notation ISO lisible par une machine.
Les secondes décimales dans la notation
La norme ISO 8601 autorise une partie décimale uniquement sur le dernier (le plus petit) composant de la chaîne — par exemple, PT1.5S signifie « 1,5 seconde », et PT1H30.5M signifie « 1 heure 30,5 minutes ». Une partie décimale sur tout autre composant que le dernier n'est pas prévue par la norme.