NFT metadata is the JSON file describing what the NFT represents: its name, description, image URL, and any attributes or traits. The blockchain token itself stores only a pointer (tokenURI) to this metadata file. The metadata tells wallets and marketplaces how to display the NFT, what it looks like, and what properties make it unique within a collection.
What Is Metadata (In the NFT Context)?
3 min read
The short version
The NFT on-chain is just a ticket stub with a number. The metadata is the concert poster it points to. Without metadata, your wallet would show a blank entry with just an ID number. With metadata, it shows the image, the name ("CryptoPunk #3100"), and traits ("Alien, Headband") that make each NFT visually and informationally distinct.
How It Works
Metadata JSON structure (OpenSea standard): { "name": "Cool Cat #1234", "description": "A unique Cool Cat", "image": "ipfs://QmXyz.../1234.png", "attributes": [{"trait_type": "Background", "value": "Blue"}, {"trait_type": "Hat", "value": "Crown"}] }. The tokenURI function on the contract returns the URL where this JSON lives. Storage options: IPFS (content-addressed, permanent if pinned), Arweave (permanent by design, paid once), centralized servers (fastest but fragile, depends on the company staying online), and on-chain (stored directly in contract storage, most expensive but truly permanent). Marketplaces like OpenSea fetch and cache metadata to display NFTs in their UI. If metadata changes (some contracts allow this), the display updates.
How metadata determines rarity and display
Bored Ape #8817 has metadata showing: Background: "New Punk Blue" (8% of apes), Fur: "Solid Gold" (0.5% of apes), Eyes: "Closed" (7%), Mouth: "Bored Cigarette" (7%). Rarity tools (rarity.tools, howrare.is) parse all 10,000 metadata files, calculate trait distribution percentages, and rank each NFT. #8817 ranks highly because "Solid Gold" fur appears in only 46 of 10,000 apes. The metadata directly determines the rarity score, which influences the market price. All of this information comes from the JSON file the tokenURI points to.
What People Get Wrong
Metadata is stored on the blockchain
Usually not. The token stores a pointer (URI) to metadata hosted elsewhere. Only fully on-chain NFTs store metadata in contract storage. This is a critical distinction: the blockchain guarantees ownership, but the metadata (and thus the image) depends on the storage layer.
Metadata cannot be changed after minting
Depends on the contract. Some contracts have frozen/immutable tokenURI (set once, never changeable). Others allow the owner or admin to update metadata (useful for reveal mechanics, evolving art). Mutable metadata means the NFT's appearance could change without your consent.
If I own the NFT, I own the metadata
You own the token (on-chain record). The metadata is just a description file. In most cases, the creator retains copyright over the artwork. Your ownership of the token gives you whatever rights the project's terms specify, which varies widely by collection.
Keep Reading
Sources & Further Reading
- OpenSea Metadata Standards
How marketplaces expect metadata to be structured for proper display
Questions People Also Ask
- What happens if the metadata server goes offline?
- If metadata is on a centralized server and that server shuts down, wallets and marketplaces cannot display the NFT (no image, no name). The token still exists on-chain with ownership intact, but it becomes a blank record. This is why IPFS or Arweave storage is strongly preferred for long-term collections.
- Can I check where an NFT's metadata is stored?
- Call the tokenURI(tokenId) function on the contract (via Etherscan "Read Contract"). If it starts with ipfs://, it is on IPFS. If it starts with ar://, it is on Arweave. If it starts with https://, it is on a centralized server. The URL tells you the durability of the metadata.
- What is a metadata reveal?
- Some collections launch with hidden metadata (all NFTs show a placeholder image). At a later "reveal" event, the tokenURI is updated to point to the real metadata. This prevents buyers from targeting specific rare traits during mint. After reveal, metadata is typically frozen permanently.