Crypto Gloss

NFT Metadata

NFT metadata is the structured data that defines what an NFT actually is — typically a JSON file containing the token’s name, description, image URL, and an array of attributes (traits) — stored on IPFS, a centralized server, or directly on the blockchain itself, and referenced by the smart contract via a tokenURI() function that returns the location of this data when queried by wallets, marketplaces, and explorers.

The Metadata Structure

Most NFTs use the ERC-721 or ERC-1155 metadata standard — a JSON file with this structure:

“`json

{

“name”: “Bored Ape #1234”,

“description”: “A unique Bored Ape from the Bored Ape Yacht Club.”,

“image”: “ipfs://QmXxx…/1234.png”,

“attributes”: [

{“trait_type”: “Background”, “value”: “Army Green”},

{“trait_type”: “Fur”, “value”: “Brown”},

{“trait_type”: “Eyes”, “value”: “Bored”},

{“trait_type”: “Mouth”, “value”: “Bored Pizza”},

{“trait_type”: “Clothes”, “value”: “Leather Jacket”}

]

}

“`

The smart contract doesn’t store the image or attributes — it stores the tokenURI (a URL pointing to where this JSON lives).

Storage Options

1. Centralized server (HTTP):

  • Fastest and cheapest to implement
  • The metadata URL looks like: https://api.project.com/tokens/1234
  • Risk: If the server goes down, the metadata disappears. The project can also change the metadata at will.
  • Not considered permanent; a single point of failure

2. IPFS (InterPlanetary File System):

  • Decentralized content-addressed storage
  • URL looks like: ipfs://QmHash...
  • The hash is derived from the content — if the content changes, the hash changes
  • Risk: IPFS content must be “pinned” to remain accessible. If no one pins it, it can disappear.
  • More permanent than centralized servers; requires ongoing pinning by the project or community

3. Arweave:

  • Permanent decentralized storage with a one-time fee
  • Designed specifically for permanent storage
  • “Store once, access forever” model
  • More expensive upfront; considered more reliable than IPFS for permanence

4. On-chain:

  • The metadata and image data are stored directly in the smart contract
  • No external dependencies; as permanent as the blockchain itself
  • Base64-encoded SVGs or other compact formats used for art
  • Most expensive in gas; only feasible for certain art styles
  • Used by: CryptoPunks (image data on-chain), Autoglyphs (algorithm on-chain), Nouns (art on-chain), Checks VV (on-chain SVG)

tokenURI and How Wallets Read NFTs

When a wallet or marketplace displays your NFT, it:

  1. Calls the tokenURI(tokenId) function on the smart contract
  2. Gets the metadata URL (IPFS hash, HTTP URL, or base64 data)
  3. Fetches the JSON at that location
  4. Reads the image field in the JSON to display the artwork
  5. Reads the attributes array to display traits

Frozen Metadata vs. Editable Metadata

Frozen: The tokenURI cannot be changed after minting; metadata is permanent.

Editable: The contract owner can update the tokenURI, changing what the metadata points to — and therefore changing what the NFT “is.”

Most reputable collections freeze metadata. “Ruggable” contracts where metadata can be changed are a risk.

The Right-Click-Save Argument

Metadata is central to the “right-click save” debate:

  • Anyone can download the image file
  • The NFT’s metadata and smart contract record the ownership of the token — not the image
  • The value proposition of an NFT is the on-chain record (token ID, owner, provenance) plus the metadata linking that record to specific art

History

  • 2017–2018 — ERC-721 standard defines tokenURI; early NFTs experiment with centralized and IPFS metadata
  • 2019 — Centralized metadata risks are realized when some early projects go offline
  • 2020–2021 — IPFS becomes standard for NFT metadata; Pinata and NFT.Storage emerge as pinning services
  • 2021 — On-chain metadata gains prestige with Art Blocks (algorithm on-chain), Nouns, and other projects
  • 2022 — Some NFT projects experience metadata loss when servers go down or IPFS pins lapse; awareness of permanence risk grows
  • 2023–2024 — Arweave becomes more common for permanent storage; on-chain metadata is the gold standard for serious art projects

Common Misconceptions

  • “The NFT contains the image.” — The NFT is a token ID on a smart contract. The image lives elsewhere (IPFS, server, Arweave) and is referenced by the metadata. The NFT points to data; it doesn’t store it (unless on-chain).
  • “IPFS metadata is permanent.” — IPFS content can disappear if no one pins it. “The content is on IPFS” is not the same as “the content is permanently stored.” Proper IPFS usage requires active pinning.

Social Media Sentiment

  • X/Twitter: NFT metadata is a frequent technical discussion topic; “frozen metadata” is a quality signal that sophisticated collectors look for.
  • Developer community: Metadata storage and permanence are foundational topics in NFT development; the on-chain vs. off-chain debate is central to project architecture discussions.
  • Collector community: Advanced collectors check metadata storage quality before significant purchases; IPFS without guaranteed pinning is a red flag.

Last updated: 2026-04

Related Terms

See Also

  • On-Chain NFT — the storage model where metadata and art are stored directly on the blockchain; the most permanent and trust-minimized option
  • NFT Provenance — the ownership history record; provenance is the on-chain side of the NFT; metadata is the content side
  • IPFS — the decentralized storage protocol most commonly used for NFT metadata; understanding IPFS is essential for evaluating metadata permanence

Sources

  • ERC-721 Metadata Standard — the standard specification including the tokenURI function and metadata JSON format.
  • OpenSea Metadata Standards — OpenSea’s documentation on the metadata JSON format used by most NFTs.
  • NFT.Storage — decentralized NFT metadata storage service; free IPFS pinning for NFT data.