Der NFT-Metadaten-JSON-Standard ist die kleine Datei, die einem Marktplatz mitteilt, was Ihr Token eigentlich ist: sein Name, sein Bild und seine Eigenschaften. Wenn Sie drei Felder richtig setzen (name, image, attributes), rendert OpenSea Ihr NFT perfekt. Wenn Sie sie subtil falsch setzen, wird Ihr Token als grauer Platz ohne Eigenschaften angezeigt, obwohl der Vertrag einwandfrei gemintet hat. Diese Anleitung führt Feld für Feld durch den Standard, behandelt die Unterschiede zwischen ERC-721 und ERC-1155, die die offiziellen Dokumentationen übersehen, und zeigt Ihnen, wie Sie saubere Metadaten für eine ganze Sammlung generieren, ohne 10.000 Dateien manuell zu bearbeiten.
Die meisten Ersteller entdecken den Standard auf die harte Tour, nach dem Deployment. Der Vertrag funktioniert, das Token existiert on-chain, und dann sieht die Auflistung kaputt aus. Die Lösung liegt fast immer im JSON, nicht im Solidity. Bevor Sie also minen, lohnt es sich, genau zu verstehen, was Marktplätze lesen und wo die häufigen Fallstricke liegen.
Was der NFT-Metadaten-JSON-Standard eigentlich ist#
Wenn eine Wallet oder ein Marktplatz Ihr NFT anzeigen möchte, schaut er nicht direkt auf das Bild. Er ruft eine Funktion Ihres Vertrags auf, tokenURI(tokenId) für ERC-721, die eine URL zurückgibt. Diese URL verweist auf eine JSON-Datei. Die JSON-Datei sind Ihre Metadaten, und sie sind das, was der Standard regelt.
Die Kette speichert also den Link, und der Link speichert die Beschreibung. Es gibt eigentlich zwei Standards, die sich im Kern einig sind, sich aber im Rahmen unterscheiden:
- ERC-721 / ERC-1155 (die On-Chain-Schnittstelle): definiert die
tokenURI- (oderuri-) Funktion und ein minimales empfohlenes Schema mitname,descriptionundimage. - Der OpenSea-Metadatenstandard (das De-facto-Anzeigeschema): eine Obermenge, die
attributes,external_url,animation_url,background_colorund dasdisplay_type-System hinzufügt. Dies ist das Schema, das Marktplätze tatsächlich rendern.
In der Praxis schreiben Sie nach dem OpenSea-Schema, weil das angezeigt wird. Es ist abwärtskompatibel mit der ERC-Schnittstelle, sodass die Befolgung beide erfüllt.
Wichtiger Punkt: Die Blockchain speichert fast nie Ihr Bild oder Ihre Eigenschaften. Sie speichert einen Zeiger. Wenn dieser Zeiger bricht oder das dahinterliegende JSON fehlerhaft ist, sieht das NFT kaputt aus, obwohl der Token auf der Kette vollkommen gültig ist.
Die Kernfelder, die jedes NFT braucht#
Hier ist eine minimale, gültige Metadatendatei. Dieses Format wird auf OpenSea, Blur, Magic Eden (EVM) und den meisten Wallets korrekt dargestellt.
{
"name": "Cosmic Fox #042",
"description": "Ein handgezeichneter Fuchs aus der Cosmic Foxes Kollektion.",
"image": "ipfs://bafybeigdyr.../042.png",
"external_url": "https://cosmicfoxes.xyz/042",
"attributes": [
{ "trait_type": "Hintergrund", "value": "Nebel" },
{ "trait_type": "Fell", "value": "Orange" },
{ "trait_type": "Augen", "value": "Laser" }
]
}
Vier Felder leisten die Hauptarbeit:
name: Der Anzeigetitel. Üblich istKollektion Name #TokenID. Dies wird als große Überschrift auf der Artikelseite angezeigt.description: Unterstützt auf OpenSea einfaches Markdown (Zeilenumbrüche, Fett, Links). Halte es kurz und verständlich.image: Die URL zum Kunstwerk. PNG, JPG, GIF und SVG funktionieren alle. Dies ist die häufigste Fehlerquelle (dazu weiter unten mehr).attributes: Das Array von Eigenschaften, das die Seltenheitsfilter antreibt, mit denen Käufer deine Kollektion durchsuchen und bewerten.
Wenn du nur name, description und image auslieferst, wird das NFT trotzdem angezeigt. Es hat dann nur keine filterbaren Eigenschaften, was bei einer generativen Kollektion ein schwerwiegender Fehler ist.
Das Bildfeld und die ipfs://-Falle#
Die häufigste Ursache für „mein NFT ist leer“ ist, dass das image-Feld auf eine Quelle verweist, die der Marktplatz nicht abrufen kann. Drei Regeln halten dich sicher:
- Verwende eine stabile, gateway-auflösbare URL.
ipfs://CID/datei.pngwird bevorzugt, da Marktplätze dasipfs://-Schema nativ auflösen. Ein HTTPS-Link zu deinem eigenen Server funktioniert auch, bindet das Überleben des Kunstwerks aber an dein Hosting. - Verwende keine Localhost- oder temporäre URL. Marktplätze cachen Metadaten. Wenn sie einmal einen defekten Link abrufen, musst du oft manuell eine Aktualisierung auslösen.
- Stimme die Datei mit der Erweiterung ab. Eine
.png-URL, die ein JPEG ausliefert, kann in manchen Renderern stillschweigend fehlschlagen.
Zur Entscheidung zwischen IPFS und einem normalen Server (und was „Rug-Risk“ für Käufer bedeutet) gibt der kostenlose NFT-Metadatengenerator ipfs://-fertige Dateien aus, sodass du die URIs nicht von Hand zusammenstellen musst.
Wie attributes und display_type wirklich funktionieren#
Das attributes-Array ist der Punkt, an dem der Standard interessant wird und die offiziellen Dokumentationen am dünnsten sind. Standardmäßig wird jedes Attribut als Textmerkmal dargestellt. Aber display_type ändert, wie ein Wert angezeigt wird, und die richtige Umsetzung unterscheidet eine ausgefeilte Sammlung von einer laienhaften.
| display_type | Funktion | Beispiel |
|---|---|---|
| (keine) | Reines Textmerkmal, als Pill dargestellt | Hintergrund: Nebel |
number | Numerisches Merkmal mit sammlungsweiter Rangfolge | Generation: 2 |
boost_number | Fügt ein + hinzu und zeigt einen Boost-Balken | Geschwindigkeit: +20 |
boost_percentage | Wie Boost, dargestellt als Prozentsatz | Ausdauer: +10% |
date | Zeigt einen Unix-Zeitstempel als Kalenderdatum | Geburtstag: Jan 2024 |
Hier ist der Haken, den die meisten Anleitungen auslassen: Bei Verwendung eines numerischen display_type muss der value eine tatsächliche Zahl sein, kein String. "value": 20 funktioniert; "value": "20" kann falsch dargestellt oder ignoriert werden.
{
"attributes": [
{ "trait_type": "Level", "display_type": "number", "value": 7 },
{ "trait_type": "Kraft", "display_type": "boost_number", "value": 40 },
{ "display_type": "date", "trait_type": "Geprägt", "value": 1704067200 }
]
}
Beachten Sie, dass der letzte Eintrag in manchen Konfigurationen einen display_type und kein trait_type-Label für das Datum hat. Beide Formen existieren in der Praxis; die Angabe von trait_type ist die sicherere und klarere Wahl.
Rangfolge-Merkmale und das max_value-Feld#
Für numerische Statistiken können Sie max_value hinzufügen, um einen konsistenten Nenner in der gesamten Sammlung zu erzwingen, sodass ein Wert als 7 / 10 statt nur 7 angezeigt wird. Dies ist rein eine Darstellungsverbesserung, lässt aber RPG-artige Sammlungen durchdacht wirken.
{ "trait_type": "Stärke", "display_type": "number", "value": 7, "max_value": 10 }
ERC-721 vs ERC-1155 Metadaten: Der Unterschied, den niemand erklärt#
Dies ist die Lücke, die Kreative stolpern lässt, wenn sie von Einzelkunstwerken zu Editionen oder Spielgegenständen wechseln. Die beiden Standards handhaben den Metadaten-URI unterschiedlich, und die offiziellen OpenSea-Dokumente erwähnen es kaum.
| Aspekt | ERC-721 | ERC-1155 |
|---|---|---|
| Token-Modell | Ein eindeutiger Token pro ID | Mehrere Kopien pro ID (Editionen) |
| URI-Funktion | tokenURI(uint256 id) | uri(uint256 id) |
| ID-Ersetzung | Meist eine vollständige URL pro Token | Standard unterstützt einen {id}-Platzhalter |
| Typische Metadaten | Eine JSON-Datei pro Token | Oft eine Vorlage, die pro ID aufgelöst wird |
| Dezimalfeld | Nicht verwendet | Optional decimals für fungible Token |
Der Hauptunterschied ist der {id}-Platzhalter. ERC-1155 ermöglicht Ihrem Vertrag, eine einzelne URI-Vorlage wie ipfs://CID/{id}.json zurückzugeben, und Clients ersetzen die Token-ID. Die offizielle ERC-1155-Spezifikation verlangt, dass die ersetzte ID eine kleingeschriebene, mit Nullen aufgefüllte 64-stellige Hexadezimalzeichenfolge ohne 0x-Präfix ist. Token-ID 1 wird also zu 0000000000000000000000000000000000000000000000000000000000000001.
In der Praxis sind OpenSea und die meisten Marktplätze nachsichtig und akzeptieren auch eine einfache Dezimal-ID, aber wenn Sie spezifikationskonform sein wollen, füllen Sie sie auf. Dieses einzelne Detail verursacht stundenlange Verwirrung ("Warum laden meine 1155-Metadaten nicht?"), vor der kein Anfänger-Tutorial warnt.
ERC-1155-Metadaten können auch ein decimals-Feld (für semi-fungible Token) und ein properties-Objekt neben attributes enthalten. Wenn Sie Spielgegenstände oder Tickets statt Kunst erstellen, lesen Sie beide Felder.
Metadaten für eine Sammlung mit 10.000 Artikeln generieren#
Eine einzelne JSON-Datei von Hand zu schreiben ist einfach. 10.000 mit konsistenten Eigenschaften, korrekten numerischen Typen und passenden Bild-CIDs zu erstellen, ist der Punkt, an dem Projekte scheitern. Manuelle Arbeit garantiert Tippfehler, und ein Tippfehler in einer Datei bedeutet einen defekten NFT, über den sich ein Käufer beschweren wird.
Der zuverlässige Ansatz ist, Metadaten als generierte Ausgabe zu behandeln, nicht als manuell bearbeitete Dateien. Ob Sie ein Skript schreiben oder ein Tool verwenden, die Pipeline ist dieselbe.
Schritt 1: Legen Sie zuerst Ihr Eigenschaftsschema fest#
Bevor Sie etwas generieren, notieren Sie jeden trait_type und seine zulässigen Werte. "Hintergrund" sollte immer "Hintergrund" geschrieben werden, niemals "HG" in einigen Dateien. Inkonsistente Eigenschaftsnamen spalten Ihre Seltenheitsfilter auf dem Marktplatz in nutzlose Duplikate. Eine kanonische Liste verhindert das.
Schritt 2: Entscheiden Sie sich für das Image-Hosting und holen Sie Ihre CID#
Laden Sie Ihren gesamten Bildordner auf IPFS hoch (über Pinata, NFT.Storage oder ähnliches), um eine Basis-CID für das Verzeichnis zu erhalten. Ihr image-Feld wird dann zu ipfs://BASE_CID/042.png. Das einmalige Pinnen des gesamten Ordners hält alle URIs konsistent und vermeidet dateiweise Uploads.
Schritt 3: Generieren Sie eine JSON-Datei pro Token#
Für jeden Token setzen Sie name, description, image (Basis-CID plus Dateiname) und das attributes-Array für diese spezifische Kombination zusammen. Behalten Sie numerische Eigenschaften als reale Zahlen bei. Der schnellste No-Code-Weg ist, Ihre Eigenschaftsdaten in den NFT-Metadatengenerator einzufügen, der spezifikationskonforme Dateien mit dem richtigen display_type und ipfs://-URIs erstellt und dann den Batch exportiert.
Schritt 4: Validieren Sie vor dem Hochladen#
Führen Sie jede Datei durch einen JSON-Validator, damit ein einzelnes abschließendes Komma keinen Token zerstört. Das Einfügen eines Beispiels in einen JSON-Formatierer und Validator fängt fehlerhafte Klammern, falsche Anführungszeichen und das überflüssige Komma, das JSON.parse zerstört. Tun Sie dies bei einigen zufälligen Dateien aus dem Batch, nicht nur bei Datei #1.
Schritt 5: Metadaten hochladen und Ihre baseURI setzen#
Laden Sie den Metadatenordner auf IPFS hoch, um eine zweite CID zu erhalten, und setzen Sie diese dann als baseURI Ihres Vertrags (damit tokenURI ipfs://METADATA_CID/{id}.json oder token-spezifische URLs zurückgibt). Bestätigen Sie, dass ein Token auf einem Testnetz durchgängig aufgelöst wird, bevor Sie die gesamte Auflage prägen.
Warnung: Marktplätze cachen Metadaten aggressiv. Überprüfen Sie immer, ob Ihre Metadaten auf einem Testnetz (oder mit einem einzigen Mint) korrekt dargestellt werden, bevor Sie die gesamte Sammlung veröffentlichen. Das Beheben einer CID nach einem Reveal von 10.000 Mints ist mühsam und erfordert manchmal, dass jeder Inhaber manuell aktualisiert.
On-Chain-Metadaten: Wenn das JSON im Vertrag lebt#
Es gibt eine vollständig on-chain Variante, bei der tokenURI einen base64-kodierten Daten-URI anstelle eines IPFS-Links zurückgibt, sodass die Metadaten (und manchmal ein SVG-Bild) vollständig auf Ethereum leben. So gewährleisten Projekte wie vollständig on-chain generative Kunst Dauerhaftigkeit ohne externe Abhängigkeiten.
Das Metadatenschema ist identisch. Der einzige Unterschied ist die Auslieferung: Statt eines ipfs://-Links gibt tokenURI Folgendes zurück:
data:application/json;base64,eyJuYW1lIjoiQ29zbWlj...
Der Browser dekodiert diesen base64-String in dasselbe oben beschriebene JSON-Objekt. Wenn Sie eines davon debuggen, können Sie den kodierten String in einen Base64-Kodierer und -Dekodierer einfügen, um das zugrunde liegende JSON zu lesen. On-Chain-Speicherung kostet weitaus mehr Gas und ist daher Sammlungen vorbehalten, die Dauerhaftigkeit als Hauptzweck betrachten. Für alles andere ist IPFS plus eine saubere JSON-Datei der Standard.
Häufige Fehler, die Ihr NFT leer rendern lassen#
Eine schnelle Checkliste der Fehler, die für die meisten Support-Threads mit „gemintet, aber sieht kaputt aus“ verantwortlich sind:
- Nachgestellte Kommas oder nicht in Anführungszeichen gesetzte Schlüssel. In JavaScript-Objekten gültig, in JSON ungültig. Ein einziges Komma zerstört die gesamte Datei.
- Zeichenfolgenwerte, wo Zahlen hingehören.
"value": "7"mitdisplay_type: numberkann das Merkmal entfernen. Verwenden Sie7. - Uneinheitliche Schreibweisen von
trait_type. „Eye Color“ in einer Datei und „Eyes“ in einer anderen fragmentiert Ihre Filter. - Eine defekte oder private Bild-URL. Localhost, ein abgelaufener Link oder eine falsch geschriebene CID rendert ein leeres Bild.
- ERC-1155-ID nicht aufgefüllt. Wenn ein Marktplatz streng ist, kann eine nicht aufgefüllte
{id}nicht aufgelöst werden. - Vergessen, Metadaten zu aktualisieren. Nachdem Sie eine Datei korrigiert haben, müssen Sie oft eine Metadatenaktualisierung auf dem Marktplatz auslösen, da diese zwischengespeichert werden.
Wenn Ihr Vertrag erstellt ist, Sie sich aber nicht sicher sind, ob die Standardschnittstelle korrekt verdrahtet ist, bestätigt ein schneller Durchlauf mit einem Token-Vertragsprüfer, dass die Funktion tokenURI / uri so freigegeben ist, wie Marktplätze es erwarten, bevor Sie Gas für das Minten ausgeben.
Der NFT-Metadaten-JSON-Standard in einem Satz#
Der NFT-Metadaten-JSON-Standard ist eine kleine JSON-Datei mit name, description, image und einem attributes-Array, die über tokenURI (ERC-721) oder uri (ERC-1155) bereitgestellt wird. Numerische Eigenschaften verwenden einen display_type mit reellen Zahlen und das Bild liegt auf einer stabilen ipfs://-URL. Halten Sie sich an diese Struktur, validieren Sie vor dem Hochladen und überprüfen Sie auf einem Testnetz, dann wird Ihre Sammlung so dargestellt, wie Sie es entworfen haben. Generieren Sie die Dateien mit dem NFT-Metadatengenerator und Sie vermeiden die manuelle Bearbeitung vollständig.
Häufig gestellte Fragen#
Was ist der NFT-Metadaten-JSON-Standard?
Es ist das vereinbarte JSON-Schema, das Marktplätze lesen, um ein NFT anzuzeigen. Mindestens enthält es name, description und image sowie ein attributes-Array für Merkmale. Die Datei wird über die tokenURI-Funktion (ERC-721) oder uri (ERC-1155) Ihres Vertrags bereitgestellt, und die Erweiterung dieses Schemas durch OpenSea wird von den meisten Plattformen tatsächlich gerendert.
Wo werden NFT-Metadaten gespeichert, on-chain oder off-chain?
Normalerweise off-chain. Die Blockchain speichert in der Regel nur einen Verweis (einen ipfs://-Link oder eine HTTPS-URL), der von tokenURI zurückgegeben wird, und das JSON selbst befindet sich auf IPFS oder einem Server. Eine vollständig on-chain Variante gibt einen base64-kodierten Data-URI zurück, sodass die Metadaten im Vertrag leben, aber das kostet deutlich mehr Gas und ist die Ausnahme, nicht die Regel.
Warum wird mein NFT auf OpenSea leer angezeigt?
Fast immer ein Metadatenproblem, kein Vertragsproblem. Die üblichen Ursachen sind eine defekte oder private image-URL, fehlerhaftes JSON (ein nachgestelltes Komma ist der Klassiker), ein CID-Tippfehler oder eine ERC-1155-Token-ID, die nicht mit Nullen aufgefüllt ist. Beheben Sie die Datei und lösen Sie dann eine Metadatenaktualisierung aus, da Marktplätze aggressiv cachen.
Was ist der Unterschied zwischen ERC-721- und ERC-1155-Metadaten?
Das Schema ist nahezu identisch, aber die Auslieferung unterscheidet sich. ERC-721 stellt tokenURI bereit und verweist normalerweise auf eine JSON-Datei pro Token. ERC-1155 stellt uri bereit und unterstützt einen {id}-Platzhalter, wobei die Spezifikation vorschreibt, dass die ID in Kleinbuchstaben und auf 64 Hexadezimalzeichen mit Nullen aufgefüllt sein muss. ERC-1155 fügt auch optionale Felder wie decimals für semi-fungible Token hinzu.
Wie füge ich Merkmale mit Seltenheit zu NFT-Metadaten hinzu?
Fügen Sie sie im attributes-Array ein, jedes als Objekt mit trait_type und value. Marktplätze berechnen die Seltenheit automatisch, indem sie zählen, wie oft jeder Wert in der Sammlung vorkommt, daher ist eine konsistente Schreibweise wichtig. Verwenden Sie display_type von number, boost_number oder boost_percentage für numerische Statistiken und halten Sie diese Werte als echte Zahlen, nicht als Zeichenketten.
Brauche ich IPFS für NFT-Metadaten? Nein, aber es wird dringend empfohlen. IPFS bietet inhaltsadressiertes, manipulationssicheres Hosting, sodass Käufer wissen, dass die Kunst nicht stillschweigend ausgetauscht oder gelöscht werden kann. Ein normaler HTTPS-Server funktioniert und Marktplätze lesen ihn, aber das Überleben der Kunst hängt dann davon ab, dass Ihr Hosting online bleibt, was das "Rug-Risiko" ist, das Käufer befürchten.
