What is NFT Metadata? The Complete Guide to JSON, IPFS, and Storage

You just bought a NFT for $500. You open your wallet, click the image, and see a broken link icon. Where did your art go? It didn't vanish from the blockchain-the metadata, which tells your wallet what to display, simply couldn't be found. This isn't rare; it happens because most people misunderstand where NFT data actually lives.

The Core Concept: What Actually Is NFT Metadata?

Think of an NFT as a digital receipt. The receipt itself (the token) lives permanently on the blockchain, proving you own something. But the receipt doesn't contain the picture of the cat or the song file. That's too big for the ledger. Instead, the receipt contains a pointer-a URL-that leads to a text file describing the asset. This text file is the NFT metadata. It is usually formatted in JSON (JavaScript Object Notation), a lightweight standard for storing and transporting data.

When you look at an NFT on OpenSea or Rarible, your browser isn't pulling the JPEG directly from Ethereum. It reads the token ID, asks the smart contract for the tokenURI, gets back a link to a JSON file, downloads that file, and then follows another link inside the JSON to fetch the actual image. If any step in this chain breaks-especially if the server hosting the JSON goes offline-your NFT appears "broken" even though you still own the token on-chain.

Anatomy of the JSON File

Most NFTs follow the ERC-721 standard, which dictates how this metadata looks. While developers can customize fields, three elements are critical for any marketplace to display your item correctly:

• Name: A string defining the title, e.g., "Bored Ape #8342".
• Description: Text explaining the project or specific traits.
• Image: A URI pointing to the visual asset. Note the plural potential here-some standards allow image, animation_url, or external_url.
• Attributes: An array of objects listing traits like "Hat: Beanie," "Background: Blue," or "Rarity Score: 99%." Marketplaces use these to filter and sort collections.

Here’s a simplified example of what that JSON looks like under the hood:

{
  "name": "Cyberpunk Cat #101",
  "description": "A rare feline with neon eyes.",
  "image": "ipfs://QmX...Hash...",
  "attributes": [
    { "trait_type": "Eyes", "value": "Neon Green" },
    { "trait_type": "Fur", "value": "Metallic Silver" }
  ]
}

The Storage Problem: Centralized vs. Decentralized

This is where things get risky. Because blockchains have strict size limits (Ethereum transactions can only hold about 256 bytes of arbitrary data efficiently), you can't stuff a 2MB PNG into the chain. So, projects host their JSON and images elsewhere. You have two main choices, and they come with very different risks.

Centralized Storage (AWS, Google Cloud): Many early projects hosted files on Amazon Web Services. It’s fast and cheap. But who owns the server? If the company running the NFT project goes bankrupt, cancels their AWS bill, or changes their domain name, the links die. Your NFT becomes a gray box. In 2022, when Nifty Gateway had service interruptions, thousands of users saw their assets disappear temporarily because the centralized servers were down.

Decentralized Storage (IPFS, Arweave): The InterPlanetary File System (IPFS) solves this by using content addressing. Instead of asking "where is this file?" (which relies on a location), IPFS asks "what is this file?" based on its cryptographic hash. As long as someone somewhere has pinned the file, it remains accessible. CryptoPunks, one of the oldest NFT projects, uses IPFS, which is why their collection has remained viewable since 2017 despite numerous platform shifts.

How TokenURI Works

The bridge between your token and its data is a function called tokenURI. When you interact with an ERC-721 smart contract, you can call this function with the Token ID. It returns a string. For older projects, this might look like https://api.example.com/metadata/123.json. For newer, decentralized ones, it looks like ipfs://QmZ...Hash....

Marketplaces know how to handle both. If they see ipfs://, they route the request through an IPFS gateway. If they see http://, they try to fetch it directly. However, relying on HTTP URLs introduces the "link rot" problem mentioned earlier. If the developer stops maintaining that API endpoint, the metadata is gone forever unless you saved a copy locally.

Why Metadata Quality Impacts Value

It’s not just about whether the image loads. The completeness of the metadata affects marketability. A study analyzing over 1 million NFT transactions showed that tokens with fully decentralized, immutable metadata fetched significantly higher prices than those with mutable or centralized links. Why? Trust. Collectors pay a premium for permanence.

Furthermore, attributes drive rarity algorithms. If your metadata says "Gold Skin" but the image shows silver, confusion spreads, and value drops. Poorly structured attribute data makes filtering difficult on platforms like Blur or Magic Eden, reducing visibility. Developers should treat metadata design as seriously as the artwork itself.

Common Pitfalls and How to Avoid Them

If you are creating an NFT or buying one, watch out for these red flags:

1. Mutable URIs: Check if the tokenURI can be changed by the contract owner. If yes, they could swap your high-res art for a blank white square tomorrow. Immutable contracts are safer.
2. Broken Attributes: Ensure the JSON structure matches the standard expected by major marketplaces. Non-standard keys often result in missing trait displays.
3. Gateway Dependency: Even with IPFS, if no nodes are "pinning" your content, it can eventually drop off the network. Using pinning services like Pinata or nft.storage ensures your data stays online.

Future Trends: On-Chain Metadata

Technology is evolving to solve the external dependency issue entirely. Newer standards and Layer 2 solutions are making it cheaper to store more data directly on-chain. Some projects now embed small SVG vectors or base64-encoded images directly into the transaction data. While this increases gas costs upfront, it guarantees 100% permanence without needing IPFS or web servers. As storage costs drop, expect to see more "fully on-chain" NFTs, eliminating the risk of broken links altogether.