Crypto
3 min read

Metadata

Off-chain or on-chain data describing the properties of a token or NFT — image, traits, name, description. NFT metadata is typically stored on IPFS or Arweave and referenced by URI from the contract.

What's in NFT metadata

A typical NFT metadata file (JSON format) contains:

  • Name — token name (e.g., "Bored Ape #1234").
  • Description — human-readable description.
  • Image — URI pointing to the image file.
  • Attributes/Traits — structured data describing properties (background, fur, eyes, mouth, etc. for PFP NFTs).
  • External URL — link to relevant external content.
  • Animation URL — for animated or interactive NFTs.

Different NFT types extend this structure. Music NFTs include audio links; video NFTs include video links; gaming NFTs include game-specific properties.

How NFTs reference metadata

Smart contracts typically store only a URI pointing to metadata, not the metadata itself:

  • Token URI function — tokenURI(tokenId) returns the URI for that specific token's metadata.
  • Often follows pattern — https://example.com/metadata/123.json or ipfs://Qm.../123.json.
  • Wallets and marketplaces fetch the URI to display the NFT.

This separation lets the contract be lightweight while the actual metadata can be rich and updateable (in some implementations).

Storage options

Where metadata actually lives:

  • On-chain. Stored directly in the smart contract or generated on-the-fly. Most expensive; strongest permanence. CryptoPunks, Nouns, Art Blocks (some implementations).
  • IPFS. Content-addressable; permanent if pinned. Most common for serious NFT projects.
  • Arweave. Pay-once-store-forever. Used by some projects prioritizing permanence.
  • Centralized HTTP. Easy but not durable. The team's server hosts metadata; if the team disappears, the NFT effectively breaks.

Why storage matters

NFT permanence depends on metadata storage:

  • On-chain or IPFS-with-good-pinning — actual artwork remains accessible long-term.
  • Centralized HTTP — only as durable as the hosting team.
  • Mixed approaches — some collections store images in centralized form but pin to IPFS as backup.

Sophisticated NFT collectors verify storage configuration before treating "stored on IPFS" as a guarantee.

Mutable vs. immutable metadata

Some NFTs have updateable metadata:

  • Frozen metadata — once set, can't be changed. Strongest commitment.
  • Reveal mechanics — metadata is initially generic, revealed at a specific block height. Common for PFP collections.
  • Updateable URI — contract owners can change where metadata lives. Convenient but reduces immutability.
  • Dynamic NFTs — metadata changes based on conditions (game state, time, achievements).

The tradeoff: mutability enables game-like and evolving NFTs but reduces the permanence guarantee.

Metadata standards

Several emerging standards:

  • ERC-721 / ERC-1155 metadata schemas — basic standards for token URI structure.
  • OpenSea metadata standard — widely adopted; defines structure for traits, images, etc.
  • Custom collection-specific extensions — many projects add fields beyond basic standards.

Most major NFT collections follow OpenSea's metadata convention regardless of which marketplace they list on.

Reading metadata

Tools that handle metadata:

  • Wallets (MetaMask, Rabby, etc.) display NFTs based on metadata.
  • Marketplaces (OpenSea, Blur, Magic Eden) parse metadata to show traits and rarity.
  • Block explorers display token URI and content.
  • Collection tools (Trait Sniper, others) compute rarity from metadata.

The standardization enables a rich tooling ecosystem.

Metadata in other contexts

The "metadata" concept appears beyond NFTs:

  • DeFi positions — descriptions of complex positions or strategies.
  • Identity attestations — signed claims about wallet attributes.
  • Document verification — hash + metadata describes verified content.
  • Token registries — lists of tokens with their properties.

Wherever digital objects need richer description than just an ID, metadata patterns appear.

Risks specific to metadata

A few concerns:

  • Permanence failures. Centrally-hosted metadata can disappear; "IPFS" claims sometimes fail to maintain pinning.
  • Mutability surprises. Some projects update metadata in ways collectors didn't expect.
  • Content rot. Linked external content (videos, animations) can break over time.
  • Traits manipulation. Project teams can occasionally update trait data, affecting rarity calculations.

For long-term holders, choosing collections with strong metadata practices matters more than is sometimes appreciated.

What individuals should know

For NFT collectors:

  • Verify metadata storage — on-chain, IPFS, Arweave, or centralized.
  • Check mutability — whether metadata can be changed.
  • Confirm pinning for IPFS-stored content.
  • Treat centralized-HTTP NFTs cautiously — they're only as durable as the hosting team.

For NFT creators and projects:

  • Choose storage that matches your permanence claims.
  • Use established pinning services for IPFS storage.
  • Document metadata structure clearly for collectors.
  • Plan for long-term hosting costs when using centralized infrastructure.

The basic principle: metadata is what makes an NFT meaningful beyond just a number on chain. Its quality, durability, and accessibility directly determine the long-term value of NFT holdings.