Le standard JSON des métadonnées NFT est le petit fichier qui indique à une marketplace ce qu'est réellement votre token : son nom, son image et ses attributs. Si vous remplissez correctement trois champs (name, image, attributes), OpenSea affiche parfaitement votre NFT. Si vous les remplissez mal, votre token apparaît comme un carré gris sans attributs, même si le contrat a bien été miné. Ce guide détaille chaque champ du standard, aborde les différences entre ERC-721 et ERC-1155 que la documentation officielle survole, et vous montre comment générer des métadonnées propres pour toute une collection sans éditer manuellement 10 000 fichiers.
La plupart des créateurs découvrent le standard à leurs dépens, après le déploiement. Le contrat fonctionne, le token existe sur la chaîne, mais l'affichage semble cassé. La solution est presque toujours dans le JSON, pas dans le Solidity. Avant de minter, il est donc utile de comprendre exactement ce que les marketplaces lisent et où se trouvent les pièges courants.
Ce qu'est réellement la norme JSON des métadonnées NFT#
Lorsqu'un portefeuille ou une marketplace souhaite afficher votre NFT, il ne regarde pas directement l'image. Il appelle une fonction sur votre contrat, tokenURI(tokenId) pour ERC-721, qui renvoie une URL. Cette URL pointe vers un fichier JSON. Le fichier JSON constitue vos métadonnées, et c'est ce que la norme régit.
Ainsi, la chaîne stocke le lien, et le lien stocke la description. Il existe en réalité deux normes en jeu, qui s'accordent sur l'essentiel mais diffèrent sur le cadre :
- ERC-721 / ERC-1155 (l'interface on-chain) : définit la fonction
tokenURI(ouuri) et un schéma minimal suggéré avecname,descriptionetimage. - La norme de métadonnées OpenSea (le schéma d'affichage de facto) : un sur-ensemble qui ajoute
attributes,external_url,animation_url,background_coloret le systèmedisplay_type. C'est celui que les marketplaces affichent réellement.
En pratique, vous écrivez selon le schéma OpenSea car c'est ce qui est affiché. Il est rétrocompatible avec l'interface ERC, donc le suivre satisfait les deux.
Point clé : la blockchain ne stocke presque jamais votre image ou vos attributs. Elle stocke un pointeur. Si ce pointeur se brise ou si le JSON derrière est mal formé, le NFT semble cassé même si le jeton est parfaitement valide sur la chaîne.
Les champs essentiels pour chaque NFT#
Voici un fichier de métadonnées minimal et valide. C'est le format qui s'affiche correctement sur OpenSea, Blur, Magic Eden (EVM) et la plupart des portefeuilles.
{
"name": "Cosmic Fox #042",
"description": "Un renard dessiné à la main de la collection Cosmic Foxes.",
"image": "ipfs://bafybeigdyr.../042.png",
"external_url": "https://cosmicfoxes.xyz/042",
"attributes": [
{ "trait_type": "Arrière-plan", "value": "Nébuleuse" },
{ "trait_type": "Fourrure", "value": "Orange" },
{ "trait_type": "Yeux", "value": "Laser" }
]
}
Quatre champs font le gros du travail :
name: le titre affiché. La convention estNom de la collection #TokenID. Cela apparaît comme le grand titre sur la page de l'objet.description: prend en charge le Markdown de base sur OpenSea (sauts de ligne, gras, liens). Restez court et lisible.image: l'URL de l'œuvre. PNG, JPG, GIF et SVG fonctionnent tous. C'est le point de défaillance le plus fréquent (plus de détails ci-dessous).attributes: le tableau de traits qui alimente les filtres de rareté que les acheteurs utilisent pour parcourir et évaluer votre collection.
Si vous ne fournissez que name, description et image, le NFT s'affichera quand même. Mais il n'aura aucun trait pour filtrer, ce qui est une grave lacune pour une collection générative.
Le champ image et le piège ipfs://#
La principale source de « mon NFT est vide » est le champ image qui pointe vers une ressource que la place de marché ne peut pas récupérer. Trois règles vous protègent :
- Utilisez une URL stable et résolvable par une passerelle.
ipfs://CID/fichier.pngest préféré car les places de marché résolvent le schémaipfs://nativement. Un lien HTTPS vers votre propre serveur fonctionne aussi, mais lie la survie de l'œuvre à votre hébergement. - N'utilisez pas d'URL locale ou temporaire. Les places de marché mettent en cache les métadonnées. Si elles récupèrent un lien cassé une fois, vous devez souvent déclencher manuellement un rafraîchissement.
- Faites correspondre le fichier à l'extension. Une URL
.pngservant un JPEG peut échouer silencieusement dans certains rendus.
Pour choisir entre IPFS et un serveur normal (et comprendre ce que signifie « risque de rug » pour les acheteurs), le générateur gratuit de métadonnées NFT produit des fichiers prêts pour ipfs:// afin que vous n'ayez pas à assembler les URI à la main.
Comment les attributs et display_type fonctionnent vraiment#
Le tableau attributes est l'endroit où le standard devient intéressant, et où la documentation officielle est la plus légère. Par défaut, chaque attribut est affiché comme un trait textuel. Mais display_type change la façon dont une valeur est montrée, et bien le maîtriser est ce qui distingue une collection soignée d'une collection amateur.
| display_type | Ce qu'il fait | Exemple d'utilisation |
|---|---|---|
| (aucun) | Trait textuel simple, affiché sous forme de pilule | Fond : Nébuleuse |
number | Trait numérique avec un classement sur toute la collection | Génération : 2 |
boost_number | Ajoute un + et s'affiche comme un indicateur de boost | Vitesse : +20 |
boost_percentage | Identique au boost, affiché en pourcentage | Endurance : +10% |
date | Convertit un timestamp Unix en date calendrier | Anniversaire : janv. 2024 |
Voici l'écueil que la plupart des guides omettent : lorsque vous utilisez un display_type numérique, la value doit être un nombre réel, pas une chaîne. "value": 20 fonctionne ; "value": "20" peut s'afficher incorrectement ou être ignoré.
{
"attributes": [
{ "trait_type": "Niveau", "display_type": "number", "value": 7 },
{ "trait_type": "Puissance", "display_type": "boost_number", "value": 40 },
{ "display_type": "date", "trait_type": "Créé le", "value": 1704067200 }
]
}
Remarquez que la dernière entrée a un display_type et aucun label trait_type pour la date dans certaines configurations. Les deux formes existent dans la nature ; inclure trait_type est le choix le plus sûr et le plus clair.
Classement des traits et le champ max_value#
Pour les statistiques numériques, vous pouvez ajouter max_value pour imposer un dénominateur cohérent dans toute la collection, de sorte qu'une statistique s'affiche comme 7 / 10 au lieu de simplement 7. C'est purement un raffinement d'affichage, mais cela donne un aspect intentionnel aux collections de type RPG.
{ "trait_type": "Force", "display_type": "number", "value": 7, "max_value": 10 }
Métadonnées ERC-721 vs ERC-1155 : La différence que personne n'explique#
Voici l'écueil qui fait trébucher les créateurs passant de l'art unitaire aux éditions ou aux objets de jeu. Les deux normes gèrent l'URI des métadonnées différemment, et la documentation officielle d'OpenSea l'évoque à peine.
| Aspect | ERC-721 | ERC-1155 |
|---|---|---|
| Modèle de jeton | Un jeton unique par ID | Plusieurs copies par ID (éditions) |
| Fonction URI | tokenURI(uint256 id) | uri(uint256 id) |
| Substitution d'ID | Généralement une URL complète par jeton | La norme prend en charge un espace réservé {id} |
| Métadonnées typiques | Un fichier JSON par jeton | Souvent un modèle résolu par ID |
| Champ decimals | Non utilisé | decimals optionnel pour les jetons de type fongible |
La différence principale est l'espace réservé {id}. ERC-1155 permet à votre contrat de renvoyer un modèle d'URI unique comme ipfs://CID/{id}.json, et les clients substituent l'ID du jeton. La spécification officielle ERC-1155 exige que l'ID substitué soit une chaîne hexadécimale de 64 caractères en minuscules, remplie de zéros, sans préfixe 0x. Ainsi, l'ID de jeton 1 devient 0000000000000000000000000000000000000000000000000000000000000001.
En pratique, OpenSea et la plupart des places de marché sont tolérants et acceptent également un ID décimal simple, mais si vous voulez être conforme à la spécification, remplissez-le. Ce seul détail cause des heures de confusion du type "pourquoi mes métadonnées 1155 ne se chargent-elles pas" qu'aucun tutoriel pour débutants ne signale.
Les métadonnées ERC-1155 peuvent également comporter un champ decimals (pour les jetons semi-fongibles) et un objet properties à côté de attributes. Si vous créez des objets de jeu ou des billets plutôt que de l'art, lisez les deux champs.
Générer les métadonnées d'une collection de 10 000 éléments#
Écrire un fichier JSON à la main est facile. En écrire 10 000 avec des traits cohérents, des types numériques corrects et des CIDs d'image correspondants, c'est là que les projets échouent. Le faire manuellement garantit des fautes de frappe, et une faute de frappe dans un fichier signifie un NFT cassé dont un acheteur se plaindra.
L'approche fiable consiste à traiter les métadonnées comme une sortie générée, et non comme des fichiers édités à la main. Que vous utilisiez un script ou un outil, le pipeline est le même.
Étape 1 : Verrouillez d'abord votre schéma de traits#
Avant de générer quoi que ce soit, notez chaque trait_type et ses valeurs autorisées. "Background" doit toujours être orthographié "Background", jamais "BG" dans certains fichiers. Des noms de traits incohérents divisent vos filtres de rareté en doublons inutiles sur la marketplace. Une liste canonique unique empêche cela.
Étape 2 : Choisissez l'hébergement des images et obtenez votre CID#
Téléchargez votre dossier d'images complet sur IPFS (via Pinata, NFT.Storage ou similaire) pour obtenir un CID de base pour le répertoire. Votre champ image devient alors ipfs://CID_BASE/042.png. Épingler tout le dossier une fois garantit des URI cohérents et évite les téléchargements fichier par fichier.
Étape 3 : Générez un fichier JSON par jeton#
Pour chaque jeton, assemblez name, description, image (CID de base plus nom de fichier) et le tableau attributes pour cette combinaison spécifique. Conservez les traits numériques comme des nombres réels. Le chemin le plus rapide sans code est de coller vos données de traits dans le générateur de métadonnées NFT, qui construit des fichiers conformes aux spécifications avec les bons display_type et URI ipfs://, puis exporte le lot.
Étape 4 : Validez avant de télécharger#
Exécutez chaque fichier via un validateur JSON pour qu'une virgule finale ne casse pas un jeton. Coller un échantillon dans un formateur et validateur JSON détecte les crochets mal formés, les guillemets incorrects et la virgule parasite qui casse JSON.parse. Faites-le sur quelques fichiers aléatoires du lot, pas seulement le fichier n°1.
Étape 5 : Téléchargez les métadonnées et définissez votre baseURI#
Téléchargez le dossier de métadonnées sur IPFS pour obtenir un deuxième CID, puis définissez-le comme baseURI de votre contrat (ainsi tokenURI renvoie ipfs://CID_METADATA/{id}.json ou des URL par jeton). Confirmez qu'un jeton se résout de bout en bout sur un testnet avant de mint la totalité de la collection.
Avertissement : les marketplaces mettent agressivement en cache les métadonnées. Vérifiez toujours que vos métadonnées s'affichent correctement sur un testnet (ou avec un mint) avant de finaliser toute la collection. Corriger un CID après un reveal de 10 000 mints est pénible et nécessite parfois que chaque détenteur rafraîchisse manuellement.
Métadonnées on-chain : quand le JSON réside dans le contrat#
Il existe une variante entièrement on-chain où le tokenURI renvoie un URI de données encodé en base64 au lieu d'un lien IPFS, de sorte que les métadonnées (et parfois une image SVG) vivent entièrement sur Ethereum. C'est ainsi que des projets d'art génératif entièrement on-chain garantissent la permanence sans dépendance externe.
Le schéma des métadonnées est identique. Le seul changement est la livraison : au lieu d'un lien ipfs://, tokenURI renvoie :
data:application/json;base64,eyJuYW1lIjoiQ29zbWlj...
Le navigateur décode cette chaîne base64 en l'objet JSON décrit ci-dessus. Si vous déboguez l'un d'eux, vous pouvez coller la chaîne encodée dans un encodeur et décodeur base64 pour lire le JSON sous-jacent. Le stockage on-chain coûte beaucoup plus de gaz, il est donc réservé aux collections qui considèrent la permanence comme l'objectif principal. Pour tout le reste, IPFS avec un fichier JSON propre est la norme.
Erreurs courantes qui rendent votre NFT vide#
Une liste de contrôle rapide des échecs qui expliquent la plupart des fils d'assistance « ça a été minté mais ça s'affiche cassé » :
- Virgules finales ou clés non guillemetées. Valides dans les objets JavaScript, invalides en JSON. Une seule virgule casse tout le fichier.
- Valeurs de chaîne là où des nombres sont attendus.
"value": "7"avecdisplay_type: numberpeut faire disparaître le trait. Utilisez7. - Orthographes de
trait_typenon cohérentes. « Couleur des yeux » dans un fichier et « Yeux » dans un autre fragmente vos filtres. - URL d'image cassée ou privée. Localhost, un lien expiré ou un CID mal saisi donne un affichage vide.
- ID ERC-1155 non rempli. Si une place de marché est stricte, un
{id}non rempli ne se résout pas. - Oubli de rafraîchir les métadonnées. Après avoir corrigé un fichier, vous devez souvent déclencher un rafraîchissement des métadonnées sur la place de marché à cause du cache.
Si votre contrat est construit mais que vous n'êtes pas sûr que l'interface standard soit correctement câblée, un passage rapide par un vérificateur de contrat de token confirme que la fonction tokenURI / uri est exposée comme les places de marché l'attendent avant de dépenser du gaz pour minter.
La norme JSON des métadonnées NFT en une phrase#
La norme JSON des métadonnées NFT est un petit fichier JSON avec name, description, image et un tableau attributes, servi depuis tokenURI (ERC-721) ou uri (ERC-1155), où les attributs numériques utilisent un display_type avec des nombres réels et l'image réside sur une URL stable ipfs://. Suivez cette structure, validez avant de télécharger et vérifiez sur un testnet, et votre collection s'affichera comme vous l'avez conçue. Générez les fichiers avec le générateur de métadonnées NFT et vous évitez toute édition manuelle.
Foire aux questions#
Qu'est-ce que le standard JSON des métadonnées NFT ?
C'est le schéma JSON convenu que les marketplaces lisent pour afficher un NFT. Il comprend au minimum name, description et image, ainsi qu'un tableau attributes pour les traits. Le fichier est servi depuis la fonction tokenURI (ERC-721) ou uri (ERC-1155) de votre contrat, et le sur-ensemble de ce schéma par OpenSea est ce que la plupart des plateformes affichent réellement.
Où sont stockées les métadonnées NFT, on-chain ou off-chain ?
Généralement off-chain. La blockchain ne stocke généralement qu'un pointeur (un lien ipfs:// ou une URL HTTPS) renvoyé par tokenURI, et le JSON lui-même réside sur IPFS ou un serveur. Une variante entièrement on-chain renvoie une URI de données encodée en base64 afin que les métadonnées vivent dans le contrat, mais cela coûte beaucoup plus de gas et constitue l'exception, pas la norme.
Pourquoi mon NFT apparaît-il vide sur OpenSea ?
Presque toujours un problème de métadonnées, pas un problème de contrat. Les causes habituelles sont une URL d'image cassée ou privée, un JSON mal formé (une virgule finale est le classique), une faute de frappe dans le CID, ou un ID de token ERC-1155 qui n'est pas complété par des zéros. Corrigez le fichier, puis déclenchez un rafraîchissement des métadonnées, car les marketplaces mettent en cache de manière agressive.
Quelle est la différence entre les métadonnées ERC-721 et ERC-1155 ?
Le schéma est presque identique, mais la livraison diffère. ERC-721 expose tokenURI et pointe généralement vers un fichier JSON par token. ERC-1155 expose uri et supporte un espace réservé {id}, où la spécification exige que l'ID soit en minuscules, complété par des zéros sur 64 caractères hexadécimaux. ERC-1155 ajoute également des champs optionnels comme decimals pour les tokens semi-fongibles.
Comment ajouter des traits avec rareté aux métadonnées NFT ?
Placez-les dans le tableau attributes, chacun comme un objet avec trait_type et value. Les marketplaces calculent automatiquement la rareté en comptant la fréquence d'apparition de chaque valeur dans la collection, donc une orthographe cohérente est importante. Utilisez display_type de number, boost_number ou boost_percentage pour les statistiques numériques, et conservez ces valeurs sous forme de nombres réels plutôt que de chaînes.
Ai-je besoin d'IPFS pour les métadonnées NFT ? Non, mais c'est fortement recommandé. IPFS offre un hébergement à adresse de contenu et infalsifiable, afin que les acheteurs sachent que l'art ne peut pas être silencieusement échangé ou supprimé. Un serveur HTTPS normal fonctionne et les marketplaces le liront, mais la survie de l'art dépend alors du maintien en ligne de votre hébergement, ce qui est le "risque de rug pull" que les acheteurs redoutent.
