Définition du document

La définition du document est le cœur de DocPayload. C'est un objet JSON qui décrit déclarativement l'intégralité de votre document — mise en page, styles, contenu, en-têtes, pieds de page et bien plus. La même définition s'affiche en PDF, DOCX ou SVG.

Structure racine

{
  "document": {
    "metadata":          { ... },
    "pageSetup":         { ... },
    "styles":            { ... },
    "fonts":             { ... },
    "images":            { ... },
    "header":            { ... },
    "footer":            { ... },
    "watermarks":        [ ... ],
    "content":           [ ... ],
    "use":               [ ... ],
    "encryption":        { ... },
    "signature":         { ... },
    "attachment":        { ... },
    "bookmark":          { ... },
    "diagnostics":       { ... }
  }
}

Seul content est requis. Les autres clés sont optionnelles — omettez celles que vous ne besoin.

Clés racine

L'API accepte trois clés racine — toutes mappent à la même structure interne :

Clé racine	Objectif
`"document"`	Définition complète du document. La clé racine primaire et recommandée.
`"component"`	Un élément réutilisable d'un document (styles + contenu, pas de configuration de page requise). Utilisé pour composition.
`"documentDefinition"`	Alias rétro-compatible pour `"document"`. Fonctionne de manière identique mais `"document"` est préféré.

Une clé "$schema" optionnelle peut être ajoutée aux côtés de la clé racine pour activer la validation de l'IDE — elle est ignorée par le moteur. Voir Configuration de l'éditeur ci-dessous.

Configuration de l'éditeur

Le schéma JSON est publié à :

https://docpayload.com/docs/schemas/v1/document-definition.schema.json

Faire pointer votre éditeur dessus vous donne l'autocomplétion sur chaque propriété, des conseils d'ensemble de valeurs sur les champs liés à des énumérations (par ex. textAlign, fontWeight, taille de page size), et des traits ondulés rouges sur les fautes de frappe et les discriminateurs inconnus — avant que vous ne rendiez.

Option 1 — mot-clé `$schema` (par fichier)

Ajoutez une clé $schema au début du document. Tout éditeur conscient du schéma JSON la récupère automatiquement :

{
  "$schema": "https://docpayload.com/docs/schemas/v1/document-definition.schema.json",
  "document": {
    "content": [
      { "p": "Hello." }
    ]
  }
}

Le moteur ignore $schema au moment du rendu, donc c'est sûr de le laisser dans les fichiers de production.

Option 2 — paramètre d'espace de travail VS Code

Associez chaque fichier JSON dans un dossier (ou correspondant à une expression glob) au schéma une fois, dans .vscode/settings.json :

{
  "json.schemas": [
    {
      "fileMatch": ["templates/**/*.json", "documents/**/*.json"],
      "url": "https://docpayload.com/docs/schemas/v1/document-definition.schema.json"
    }
  ]
}

Ajustez les expressions glob fileMatch à l'endroit où vous gardez vos sources DocPayload. Pas besoin d'ajouter $schema à chaque fichier avec cette approche.

Option 3 — IDEs JetBrains (IntelliJ, WebStorm, Rider, …)

Paramètres → Langages & Frameworks → Schémas et DTD → Mappages de schémas JSON → +. Définissez l'URL du schéma sur l'URL ci-dessus, puis ajoutez un motif de chemin de fichier correspondant à l'endroit où votre JSON DocPayload se trouve.

Option 4 — Cursor et autres éditeurs conscients du schéma JSON

Le mot-clé $schema (Option 1) est le chemin universel — tout éditeur qui honore le schéma JSON draft-07 le résoudra.

Ce que l'application fait réellement

Erreur	Détectée ?
Propriété de style inconnue (`fontWieght` au lieu de `fontWeight`)	Trait ondulé rouge sur la clé
Discriminateur de contenu inconnu (`{ "canvas": { … } }` au lieu de `{ "shapes": [...] }`)	Trait ondulé rouge sur la clé
Type de valeur incorrect (`fontSize: "big"`)	Erreur de type
Énumération hors liste (`textAlign: "diagonal"`)	Erreur d'énumération avec la liste autorisée
Raccourci de bordure incorrect (`borderTop: { width: 1 }` au lieu de `"1pt solid #000"`)	Erreur de type
Taille de page non dans le catalogue (`size: "QUARTO"`)	Erreur d'énumération suggérant `LETTER`, `A4`, etc.

Les clés mal cadrées (FontWeight au lieu de fontWeight) peuvent également être ondulées, même si le moteur d'exécution les honore — écrivez avec IntelliSense et vous obtenez la casse canonique gratuitement.

Propriétés

Propriété	Type	Requis	Description
`metadata`	object	Non	Titre, auteur, sujet, mots-clés
`pageSetup`	object	Non	Taille de page, orientation, marges, bordures de page
`styles`	object	Non	Définitions de style nommées réutilisables
`fonts`	object	Non	Définitions de famille de polices personnalisées chargées à partir de fichiers de police
`images`	object	Non	Dictionnaire d'images indexées référencées par nom à partir de Codes courts `[image, key]` ou de nœuds du corps `{ "image": "key" }`
`header`	object	Non	En-tête de page répétitif
`footer`	object	Non	Pied de page répétitif avec numérotation des pages
`watermarks`	array	Non	Superpositions de chromage de page appliquées à chaque page (contenu textuel, image ou forme ; une entrée par couche)
`content`	array	Oui	Tableau d'éléments de contenu
`use`	array	Non	Références de composants fusionnées dans le document (utilisées pour composition)
`encryption`	object	Non	Protection par mot de passe et permissions
`signature`	object	Non	Signature numérique (PAdES ou CMS détaché)
`attachment`	object	Non	Intégrez une pièce jointe de fichier dans le PDF
`bookmark`	object	Non	Arborescence des signets / contour du document
`diagnostics`	object	Non	Diagnostics par rendu — ajoute une annexe de développement listant chaque style, police, image et composant (`use`) résolu pendant le rendu

Éléments de contenu

Le tableau content accepte les types d'éléments suivants. Chaque élément est un objet portant exactement l'une de ces clés de discriminateur (plus les frères optionnels comme style, colspan, rowspan).

Élément	Clé	Description
Paragraphe	`p`	Texte avec formatage en ligne
Titre	`h1`–`h5`	Titres sémantiques avec dimensionnement intégré
Tableau	`table`	Lignes et colonnes avec style de cellule, `colspan` / `rowspan`
Liste ordonnée	`ol`	Liste numérotée
Liste non ordonnée	`ul`	Liste à puces
Colonnes	`columns`	Mise en page multi-colonnes
Règle horizontale	`hr`	Règle horizontale avec styles de ligne, alignement, remplissage et espacement
Image	`image`	Élément image autonome
Code-barres	Codes courts / canevas	63 symbologies prise en charge via le Code court `[barcode, …]` dans le texte, ou en tant que forme `barcode` dans un tableau de canevas `shapes`
Champ de formulaire	Codes courts	7 types de champs interactifs — texte, zone de texte, case à cocher, bouton radio, choix, boîte de liste, sélecteur de date
Canevas	`shapes`	Primitives de dessin alignées sur SVG (ligne, rectangle, cercle, chemin, texte, image…) avec optionnel `viewBox` et `padding`
Saut de page	`break`	Saut de page `page`, `section`, ou `line`
Table des matières	`toc`	TOC auto-généré à partir des titres `h1`–`h5`

Les clés de discriminateur inconnues sont rejetées au moment de la validation — les fautes de frappe comme { "canvas": { … } } (l'ancien wrapper, non plus reconnu) ne s'afficheront pas silencieusement vides ; le moteur génère une erreur pour que la faute de frappe soit évidente.

Exemple minimal

Le document valide le plus simple :

{
  "document": {
    "content": [
      { "h1": "Hello, World!" },
      { "p": "Generated by DocPayload." }
    ]
  }
}

Structure racine​

Clés racine​

Configuration de l'éditeur​

Option 1 — mot-clé $schema (par fichier)​

Option 2 — paramètre d'espace de travail VS Code​

Option 3 — IDEs JetBrains (IntelliJ, WebStorm, Rider, …)​

Option 4 — Cursor et autres éditeurs conscients du schéma JSON​

Ce que l'application fait réellement​

Propriétés​

Éléments de contenu​

Exemple minimal​