Types supportés et schémas JSON

Les briques de vos schémas

Pour définir la structure de vos réponses, vous disposez de sept types JSON. Chacun correspond à un besoin précis dans la modélisation de vos données. Comprendre ces types est essentiel pour concevoir des schémas efficaces.

Les sept types supportés

string

Le type le plus courant. Utilisé pour les noms, descriptions, identifiants, et tout contenu textuel.

{
  "type": "object",
  "properties": {
    "nom": { "type": "string" },
    "description": { "type": "string" }
  }
}

number

Couvre les entiers et les flottants. Pas de distinction entre integer et float — un seul type number gère les deux.

{
  "properties": {
    "prix": { "type": "number" },
    "quantite": { "type": "number" }
  }
}

boolean

Vrai ou faux. Parfait pour les flags, les validations, les décisions binaires.

{
  "properties": {
    "en_stock": { "type": "boolean" },
    "livraison_express": { "type": "boolean" }
  }
}

object

Permet d’imbriquer des structures. Un objet peut contenir d’autres objets, des tableaux, des scalaires — sans limite de profondeur.

{
  "type": "object",
  "properties": {
    "adresse": {
      "type": "object",
      "properties": {
        "rue": { "type": "string" },
        "ville": { "type": "string" },
        "code_postal": { "type": "string" }
      }
    }
  }
}

array

Listes d’éléments du même type. Vous pouvez avoir des tableaux de strings, de numbers, d’objets, ou même de tableaux.

{
  "properties": {
    "competences": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

enum

Un ensemble fini de valeurs autorisées. Indispensable pour les catégorisations et les classifications.

{
  "properties": {
    "priorite": {
      "type": "string",
      "enum": ["basse", "moyenne", "haute", "critique"]
    }
  }
}

anyOf

Permet de définir des unions de types. Un champ peut accepter plusieurs structures différentes. Utile quand un même champ peut avoir des formes variées.

{
  "properties": {
    "contact": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "email": { "type": "string" }
          }
        },
        {
          "type": "object",
          "properties": {
            "telephone": { "type": "string" }
          }
        }
      ]
    }
  }
}

Combiner les types

La puissance des schémas vient de la combinaison de ces types. Voici un schéma réaliste pour analyser un produit :

{
  "type": "object",
  "properties": {
    "nom": { "type": "string" },
    "prix": { "type": "number" },
    "en_stock": { "type": "boolean" },
    "categorie": {
      "type": "string",
      "enum": ["electronique", "vetement", "alimentaire", "autre"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "fabricant": {
      "type": "object",
      "properties": {
        "nom": { "type": "string" },
        "pays": { "type": "string" }
      }
    }
  }
}

Ce schéma mélange des scalaires, un enum, un tableau et un objet imbriqué. Le modèle respectera chaque contrainte à chaque appel.

Champs optionnels

Pour rendre un champ optionnel, utilisez anyOf avec null :

{
  "properties": {
    "telephone": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  }
}

En Pydantic, cela correspond à telephone: str | None.

Points clés à retenir

• Sept types disponibles : string, number, object, array, boolean, enum, anyOf
• Les types se combinent librement pour modéliser des structures complexes
• Les champs optionnels utilisent anyOf avec null
• Pas de distinction integer/float — un seul type number
• enum force des valeurs prédéfinies pour les classifications