NFT Metadata Standards and Structure: A Practical Guide to On-Chain and Off-Chain Data

Most people think an NFT is just a picture or a digital collectible. But what makes that NFT valuable, searchable, and usable across platforms isn’t the image itself - it’s the NFT metadata. Without properly structured metadata, your NFT is just a token with no identity. It won’t show up right on OpenSea. It won’t display traits in games. And if the file hosting goes down, your entire collection could vanish overnight.

What Exactly Is NFT Metadata?

NFT metadata is the structured data that describes your token. Think of it like a product label on a physical item - it tells you the name, description, features, and where to find the real thing. For NFTs, this data includes the asset’s name, description, image, traits, and links to external content. All of this is stored as a JSON file, which is read by marketplaces, wallets, and games to display your NFT correctly.

The metadata doesn’t live on the blockchain itself. That would be too expensive and slow. Instead, the blockchain stores a URL - a pointer - to where the metadata file is hosted. This is called the tokenURI in Ethereum’s ERC-721 standard or uri in ERC-1155. When you open an NFT on OpenSea, your wallet asks the smart contract for that URL, fetches the JSON file, and renders the NFT using the data inside.

Core Fields Every NFT Metadata File Must Have

While the ERC-721 standard only requires name and description, no serious NFT project skips the recommended fields. Here’s what a complete metadata file looks like:

• name: The title of your NFT. OpenSea limits this to 50 characters. Example: Bored Ape #4879
• description: A detailed explanation of the NFT. Supports Markdown for formatting. Example: A rare Bored Ape with laser eyes and a gold fur coat. Part of the Bored Ape Yacht Club collection.
• image: A direct URL to the image file. Must be absolute, not relative. Recommended size: 350x350px minimum, but art NFTs often use 5,200x5,200px for high-res viewing.
• external_url: A link to your project’s website, Discord, or additional info. Helps with trust and provenance.
• attributes: An array of traits that define your NFT’s uniqueness. Each trait has three parts:

1. trait_type: The category - like Fur, Eyes, or Clothes
2. value: The specific value - like Golden, Laser, or Leather Jacket
3. display_type (optional): How to show the value - number, boost_percentage, or date. For example, a rarity score might use "display_type": "number" to show it as a numeric rank.

According to TokenMinds’ 2024 analysis of 4.3 million NFTs, collections that include all 12 of OpenSea’s recommended metadata fields see 47% higher discoverability. Gaming NFTs average 5.8 traits per token, while art NFTs average 3.2. More traits mean better filtering, better rarity rankings, and higher sales.

Where Is Metadata Stored? On-Chain vs Off-Chain

This is where things get critical. Most NFTs store metadata off-chain, meaning the JSON file lives on a server or decentralized network, not on the blockchain. The blockchain only holds the URL to that file.

There are three main hosting options:

• HTTP (Centralized): 38.2% of NFTs use regular web servers (like AWS S3 or Cloudflare). Cheap and easy, but vulnerable. If the server goes down, your NFT breaks. The DigitalDreams project lost 92% of its value when their HTTP host shut down in 2023.
• IPFS (Decentralized): 59.1% of NFTs use IPFS, a peer-to-peer file system. Files are hashed and distributed across nodes. But here’s the catch: if no one "pins" (keeps a copy of) your file, it disappears. Pinata and Textile offer pinning services for $0.004 per GB/month.
• Arweave: 2.7% use Arweave, which pays once for permanent storage. It’s more expensive upfront but guarantees your metadata lasts forever.

Solana’s Metaplex standard takes a different approach. It stores key metadata - like name, image, and traits - directly on-chain using its Metadata Program. Only the animation or external link points off-chain. This reduces the risk of metadata decay but increases transaction costs. Creating metadata on Solana costs about $0.00025, while on Ethereum it’s $1.20-$5.00 depending on gas prices.

How Standards Differ Across Blockchains

Not all NFT standards are the same. Here’s how they compare:

Comparison of NFT Metadata Standards

Standard	Chain	Storage Model	Key Features	Average Cost per Metadata Tx
ERC-721	Ethereum	Off-chain	Basic fields only. Requires tokenURI method.	$1.20 - $5.00
ERC-1155	Ethereum	Off-chain	Supports batch minting. Used by 78% of blockchain games.	$1.20 - $5.00
Metaplex	Solana	On-chain + off-chain URI	Includes properties, collection, and uses fields. More secure.	$0.00025
BEP-721	Binance Smart Chain	Off-chain	Almost identical to ERC-721. Lower fees.	$0.03
OpenSea Standard	Multi-chain	Off-chain	De facto industry standard. Recommends 12 fields.	N/A

OpenSea’s metadata guidelines aren’t a formal standard, but 89% of Ethereum NFTs follow them. That’s because marketplaces rely on consistency. If your NFT doesn’t match OpenSea’s expected format, it might not display properly - even if the blockchain is correct.

Common Mistakes That Break NFTs

A shocking 42.7% of NFT issues come from bad metadata, according to Consensys. Here are the top errors:

• Relative image paths: Using "image": "/assets/ape.png" instead of "image": "https://yourdomain.com/assets/ape.png". This breaks on any platform that doesn’t serve from your root domain.
• Invalid JSON: Missing commas, extra commas, unquoted keys, or using single quotes. JSON requires double quotes and strict formatting.
• Missing required fields: Forgetting name or description - even though they’re "optional," most platforms won’t display the NFT without them.
• Broken URIs: Hosting metadata on a free service that shuts down, or forgetting to pin on IPFS.
• Missing CORS headers: If your metadata is on an HTTP server, it must allow cross-origin requests. Otherwise, browsers block the fetch. This affects 28.7% of HTTP-hosted NFTs.

One Reddit user lost $42,000 in sales because they used a relative path. Another project had 4,382 NFTs become invisible when their server went offline. These aren’t hypotheticals - they happen every week.

How to Validate Your Metadata

Before you launch, test your metadata. Use these free tools:

• OpenSea Metadata Validator: Paste your JSON or URI. It checks for missing fields, image size, and formatting. Used over 14,000 times in April 2024.
• IPFS Metadata Checker: Verifies if your file is pinned and accessible on IPFS. Has 2,384 GitHub stars.
• Metaplex Validator: For Solana projects. Checks if your on-chain metadata matches the off-chain URI.
• JSONLint: A simple tool to validate JSON syntax. Paste your file and fix errors before deploying.

Also, test your NFT on multiple wallets and marketplaces. What works on OpenSea might not render on LooksRare or Blur. Metadata consistency = better user experience = higher sales.

Future of NFT Metadata

The industry is moving toward more resilient standards. The NFT Metadata Alliance - formed in May 2024 by OpenSea, Coinbase, and Rarible - is working on a cross-chain metadata specification to be released by Q4 2024. Ethereum’s EIP-5169 proposes embedding metadata directly into contract bytecode, eliminating URI dependency. Solana’s Metaplex 2.1.0 added a new uses field to track how many times an NFT’s utility (like game access) has been claimed.

Meanwhile, regulatory pressure is rising. The EU’s MiCA regulation, effective December 30, 2024, will require NFTs classified as digital tokens to include creator identification and origin proof in their metadata. This isn’t just a technical issue anymore - it’s a legal one.

But the biggest threat remains metadata decay. According to Tableland’s 2024 report, 18.3% of NFTs created before 2022 already have broken links. That’s nearly 1 in 5 NFTs that no longer display correctly. If you’re building today, don’t gamble on HTTP. Use IPFS with pinning. Or go permanent with Arweave. Your collectors will thank you.

What You Should Do Now

If you’re creating an NFT project:

1. Use OpenSea’s metadata template as your base.
2. Include at least 5 traits for gaming NFTs, 3 for art.
3. Host your image and JSON on IPFS with Pinata or Arweave.
4. Test your metadata with OpenSea’s validator.
5. Verify CORS headers if using HTTP.
6. Never use relative paths.
7. Document your metadata structure for your team and community.

Metadata isn’t glamorous. But it’s the foundation. Without it, your NFT is invisible. With it, your collection can last for decades.