NFT Metadata Explained: What Is Inside the JSON File

Table of Contents
Every NFT looks simple on the surface: a picture, a name, maybe a list of traits. Behind that picture sits a small JSON file called the token’s metadata. It is the part of an NFT that marketplaces and wallets actually read to decide what to show you, and it is also one of the most misunderstood pieces of the whole system. If you are minting your own collection, understanding this file helps you avoid broken listings, missing traits, and images that never load.
What Metadata Actually Is
An NFT’s smart contract does not usually store an image. Instead, each token has a function called tokenURI that returns a web address. That address points to a JSON document, and that document is the metadata. When you open a token on a marketplace, the marketplace fetches this JSON, reads its fields, and builds the page you see: the artwork, the title, the description, and the trait list on the side.
The ERC-721 standard that defines NFTs on Ethereum only requires a loose format for this file. In practice, almost every wallet and marketplace, including the major ones, follows a shared convention that grew out of early NFT projects rather than the strict letter of the original proposal. That convention is what most minting tools, including mobile apps, generate automatically.
The Core Fields
A typical metadata file includes a small, predictable set of keys:
- name: the title shown for the token, such as “Sunset Fox #42.”
- description: a short text block explaining the piece or the collection.
- image: a link to the actual artwork file, usually a PNG, JPG, GIF, or sometimes an animation URL for video or 3D work.
- external_url: an optional link back to a project website or collection page.
- attributes: an array of trait objects that marketplaces turn into the filterable trait list buyers browse through.
How Attributes and Traits Work
The attributes array is where rarity lives. Each entry is a small object with a trait_type key and a value key, for example a trait_type of “Background” with a value of “Forest,” or “Eyes” with a value of “Blue.” Some fields also use a display_type key so a marketplace knows to render a value as a number or a percentage rather than plain text, which matters for things like a numeric “Power Level” stat.
Marketplaces scan every token in a collection, tally how often each trait value appears, and use that to calculate rarity rankings. This is why two collections with visually similar art can have very different rarity tools available: it depends entirely on whether the metadata actually lists clean, consistent attribute values for every token.
On-Chain Versus Off-Chain Metadata
Most metadata is stored off-chain, meaning the JSON file and the image both live outside the blockchain itself, on a server or on decentralized storage such as IPFS or Arweave. The blockchain only holds the short tokenURI pointer. This keeps minting cheap, since storing large files directly on-chain would be expensive, but it introduces a dependency: if the server hosting that file goes offline, or a centralized link breaks, the NFT can end up showing a blank image even though the token itself still exists on the blockchain.
Decentralized storage reduces this risk because the file is addressed by its content rather than by a single server’s uptime, though it does not remove the risk entirely if nothing is pinning the data long term. A smaller number of projects write metadata fully on-chain, encoding the JSON or even the image directly into the smart contract. This costs more gas at mint time but removes the external dependency altogether.
Why Mutability Matters
A detail many collectors overlook is that metadata can sometimes be changed after minting, if the project’s contract or hosting setup allows it. For a buyer, this means a token’s traits are only as trustworthy as the project’s control over that file. Many reputable collections “freeze” their metadata once a collection is fully revealed, often by moving the final files to immutable storage and publishing the resulting address, so that no one, including the creators, can quietly alter traits later. When you are evaluating a collection, whether the metadata has been frozen is a reasonable question to ask.
Practical Tips for Creators
If you are minting your own NFTs rather than just collecting them, a few habits keep metadata clean:
- Keep trait_type names consistent across every token in a collection, since inconsistent capitalization or spacing can split what should be one trait into several.
- Host images and JSON on decentralized storage when possible, rather than a server you might later shut down.
- Test how a token actually renders on a marketplace before announcing a collection publicly, since a small formatting mistake in the JSON can prevent an image or trait list from displaying at all.
- Decide early whether metadata will be frozen after mint, and say so clearly to collectors, since this is a trust signal buyers increasingly look for.
Mobile minting tools such as Simple NFT Creator generate this metadata file automatically behind the scenes, so creators do not need to hand write JSON to launch a collection. Understanding what that file contains still helps, though, since it is the layer that determines how your art actually appears once it reaches a wallet or a marketplace.
If you are getting ready to mint your first collection, Simple NFT Creator is available on the App Store and Google Play, and handles metadata formatting as part of the minting flow.



