Skip to main content
NFTs (briefly)

NFT Metadata and Standards

Pomegra Learn

NFT Metadata and Standards

The invisible infrastructure that makes NFTs functional lies in their metadata—the structured information that describes what an NFT is, what it represents, and what properties it possesses. While a blockchain transaction records ownership, metadata determines how that ownership is displayed, understood, and valued. This layer of standardization transforms NFTs from mere accounting entries into meaningful digital assets that humans can interact with and understand.

What Is NFT Metadata?​

Metadata is structured data that describes other data. In the NFT context, it's a standardized document that describes a specific token. Metadata answers fundamental questions: What is this NFT's name? What image represents it? Who created it? What properties does it have? Does it have any unlockable content?

The smart contract itself doesn't store this metadata. Instead, the contract stores a URI (Uniform Resource Identifier)—essentially a pointer to where the metadata lives. The URI typically points to a JSON file hosted on IPFS or a web server. When a marketplace or wallet displays an NFT, it reads the smart contract to find the URI, retrieves the metadata from that location, and renders it for users.

This architecture provides several advantages. It keeps blockchain storage lean, focused on ownership and transfers rather than large data payloads. It allows metadata to be updated by the creator (depending on immutability choices) without changing the token itself. And it separates concerns—the token is immutable on the blockchain, while metadata exists in a more flexible storage layer.

The ERC-721 Metadata Standard​

The most foundational metadata standard for NFTs is defined within ERC-721, the Ethereum smart contract standard for non-fungible tokens. The standard specifies a minimal required metadata structure, which most platforms have adopted and expanded upon.

The core ERC-721 metadata schema includes several required or strongly recommended fields. The name field provides the NFT's title. The description field offers explanatory text about the piece. The image field contains a URL pointing to the actual visual representation—typically a JPEG, PNG, or GIF. The external_url field directs users to additional information, like an artist's website or portfolio.

Beyond these basics, implementers typically include an attributes array. Attributes are key-value pairs that describe properties of the NFT. For algorithmically-generated collections, attributes might include things like "Background: Blue," "Head: Crown," or "Rarity: Legendary." These attributes serve practical purposes—they enable filtering and searching, inform rarity calculations, and provide granular understanding of what makes an NFT unique within a collection.

Some metadata schemas add animation_url for animated content beyond still images. This field points to an MP4, WebGL file, or other animated format that represents the NFT. Background_color, a simple hex code, provides a fallback color if media fails to load. The OpenSea Metadata Standard extends ERC-721 with fields like youtube_url for video NFTs and traits for more detailed rarity information.

Decentralized File Storage and IPFS​

The metadata JSON file must exist somewhere accessible. Historically, many creators hosted metadata on traditional web servers or databases they controlled. This introduced risk—if the server goes offline or the creator deletes content, the NFT becomes orphaned, pointing to a broken link.

The solution is IPFS (InterPlanetary File System), a distributed file storage protocol that fundamentally differs from traditional web hosting. Rather than storing files on a server at a specific address, IPFS stores files based on their content. Each file receives a cryptographic hash—a unique fingerprint of its content. To retrieve the file, anyone on the IPFS network can provide that hash, and the network locates the file by its content rather than its location.

This design creates permanence. As long as any node on the IPFS network has a copy of your file, it remains accessible via its hash. If your computer goes offline, others can still access it. If IPFS.io (the web gateway) experiences issues, other gateways maintain access. The content's immutability is cryptographically guaranteed—any attempt to modify the file changes its hash, creating a different (invalid) reference.

Many creators use pinning services like Pinata, NFT.Storage, or Fleek to ensure their content persists on IPFS. These services run dedicated nodes that maintain copies of uploaded content, creating redundancy that prevents files from disappearing if casual nodes drop offline.

The metadata JSON file itself should also live on IPFS. The smart contract stores the IPFS hash of the metadata (formatted as an IPFS URI), creating an immutable chain: blockchain points to metadata hash, metadata file points to content hash, content hash points to the actual media.

Metadata Immutability and Updatability​

One critical design decision involves whether metadata should be immutable or updatable. Truly immutable metadata means the URI in the smart contract never changes—what's recorded at creation persists forever. This provides absolute proof of original specifications but prevents corrections or enhancements.

Many modern NFTs use updateable metadata, where the creator retains ability to modify metadata after minting. This enables correcting errors, updating descriptions, or adding properties as the NFT's significance evolves. The blockchain still proves who minted it and when; the metadata update doesn't erase that history but does change what's currently displayed.

Some contracts implement a compromise: metadata is updateable by the creator during a defined period, then becomes immutable. This allows corrections during the initial phase while eventually freezing the asset's properties for permanence.

From a collector's perspective, immutable metadata offers stronger guarantees about what you're purchasing. You know exactly what specifications existed at the time of minting. Updateable metadata offers more flexibility but requires trust that creators won't modify it in ways that diminish value.

Collection-Level Metadata​

Beyond individual token metadata, most NFT projects maintain collection-level metadata describing the overall project. This typically includes the collection's name, description, image (the collection logo), external URL, creator information, and details about the project's story and purpose.

Collection-level metadata provides context that helps collectors understand the broader project. It might explain an artist's vision, a project's utility, or the story behind a game's collectible characters. Marketplaces use collection metadata to organize NFTs, display project information, and verify authenticity through verification marks applied to collections rather than individual tokens.

Attributes, Rarity, and Generative Collections​

For collections with algorithmic generation—where an algorithm creates numerous combinations of visual properties—attributes become crucial. A collection might have 10,000 NFTs, each generated by combining traits from predefined lists: 100 backgrounds, 50 body shapes, 200 outfits, 75 accessories, and so on.

Each NFT's metadata explicitly lists which traits it has. Rarity arises naturally from this—if 5,000 NFTs have a "Common Background" but only 50 have a "Legendary Background," the legendary version becomes rarer and typically commands higher prices.

Metadata attributes enable this market segmentation. Collectors and automated tools can filter NFTs by specific traits, identify rare combinations, and value accordingly. Projects like CryptoPunks and Bored Ape Yacht Club gained value partly through sophisticated trait systems where certain combinations became highly sought after.

Unlockable Content and Encryption​

Some NFT platforms support unlockable content—data that's not publicly visible in the metadata but becomes accessible to the NFT's owner. Creators might include original high-resolution files, digital downloads, access credentials, or other private information as unlockable content.

OpenSea supports this through their unlockable content mechanism. When a user purchases an NFT with unlockable content, they receive access to a private message or file from the creator. This enables business models like selling original artwork with private high-res versions included, offering digital downloads with NFT purchases, or providing exclusive access to communities.

The implementation typically involves storing encrypted data on the platform (not the blockchain) that's decrypted for the owner's wallet address only. This provides practicality—you can include substantial files without bloating blockchain data—while maintaining privacy.

Standards Beyond ERC-721​

The ERC-721 standard established conventions, but alternatives and extensions exist. ERC-1155, Ethereum's semi-fungible token standard, allows a single smart contract to manage both unique items (like traditional NFTs) and fungible tokens or quantity-based items. This efficiency appeals to creators managing diverse token types.

Different blockchains have their own standards. Solana's Token Metadata Program serves similar purposes. Flow's NFT standard reflects that blockchain's particular architecture. The fundamental principles remain consistent—metadata describes tokens, stored separately from ownership records, enabling flexible representation without blockchain bloat.

Validation and Marketplace Integration​

Marketplaces like OpenSea validate metadata to ensure proper formatting and render NFTs correctly. They parse the metadata JSON, extract specified fields, and display them in standardized formats. If metadata is malformed or missing required fields, NFTs may display incorrectly or not at all.

This creates practical incentives for proper metadata creation. Creators whose NFTs display beautifully with complete information gain advantages in discoverability and marketability. Incomplete or incorrect metadata results in listings that appear broken or confusing, deterring potential buyers.

Marketplace validation also combats fraud. Some platforms check whether metadata accurately reflects actual content and flag suspicious inconsistencies. If the metadata claims an image but the image is missing or incorrect, it raises red flags.

Evolution and Extensibility​

The NFT metadata ecosystem remains young and evolving. Early standards are being extended to support new use cases. Some projects are adding fields for dynamic metadata—NFTs that can update based on external data or on-chain state. Others implement hierarchical metadata for complex digital assets that contain sub-assets.

The principle of forward compatibility means new fields can be added without breaking existing implementations. A marketplace that doesn't recognize a new metadata field simply ignores it rather than failing to display the NFT. This allows gradual evolution while maintaining backward compatibility.

Practical Implications for Creators and Collectors​

Understanding metadata directly impacts creation and purchasing decisions. As a creator, properly structured metadata enables your work to display beautifully across all platforms, attracts collectors through clear description and visible properties, and creates permanent records on distributed systems.

As a collector, metadata tells you exactly what you're purchasing. Examining an NFT's metadata reveals the creator's identity, the minting timestamp, and all properties and attributes. This information helps evaluate authenticity and value. Metadata stored on IPFS demonstrates durability—your purchase will remain valid and displayable indefinitely, not dependent on centralized infrastructure.

Security Considerations​

Metadata security concerns differ from token security. Since metadata lives outside the blockchain, it could theoretically be modified if stored on mutable infrastructure. Using IPFS eliminates this risk—the content's hash ensures any modification becomes immediately detectable as a different file.

However, metadata hosted on traditional servers remains vulnerable. If an attacker gains access to a server, they could modify displayed metadata, though the blockchain would still point to the original hash if it was recorded there. This illustrates why IPFS-based metadata represents best practices for permanence.

The chain of custody through hashing creates provable authenticity. If you verify that an NFT's URI hashes match a known metadata file, you've confirmed nothing has been modified since minting. This applies whether you're evaluating an artist's authentic works or investigating counterfeits.

References: