Learn

How NFT metadata works

A token-by-token guide to tokenURI, JSON metadata, images, animations, attributes, and the control points between a contract and what an NFT app displays.

What is NFT metadata?

NFT metadata is the structured description that gives a token its name, image, traits, and other display information. Ownership is recorded by the NFT contract, but most wallets and marketplaces need a separate metadata response to know what to show.

For ERC-721 tokens, an app usually calls tokenURI(tokenId). ERC-1155 commonly uses uri(tokenId), sometimes with an ID template that the app must substitute. The returned value may contain the metadata itself or point somewhere else.

What does a token URI contain?

A token URI commonly takes one of these forms:

  • A data: URI containing JSON inline.
  • An ipfs:// or ar:// content reference.
  • An HTTPS endpoint controlled by a web server.
  • A contract-aware URI such as web3:// that requires another on-chain call.

The JSON response can then reference an image, animation_url, attributes, and project-specific fields. Each referenced asset can use a different storage method, so an IPFS metadata document does not automatically mean its image is also on IPFS.

Can NFT metadata change?

Yes. A contract can generate a different URI, change a base URI, reveal hidden metadata, or be upgraded through a proxy. An unchanged HTTPS URI can return different JSON later. IPNS and ENS names can be repointed. Even fixed JSON can load mutable images or scripts from elsewhere.

To evaluate mutability, inspect both the URI and the contract controls that produce it. A content-addressed URI protects the identity of the referenced bytes, while renounced or otherwise constrained control reduces the chance that the reference itself can be replaced.

What should an inspection verify?

  1. Record the original URI returned by the contract.
  2. Resolve the metadata without discarding the original scheme or content identifier.
  3. Classify every primary media reference separately.
  4. Check nested dependencies in supported SVG and HTML media.
  5. Review owners, roles, and upgrade paths that can change resolution.

NFT Inspector follows this chain and reports the evidence by component. A fetch failure is also evidence: even correctly addressed content cannot be rendered if no available provider can return it at inspection time.