Metadata standards

Using rich metadata in your ERC721 and ERC1155 NFTs

Providing metadata to universally recognized standards for your assets permits dApps, such as Sparkles, to pull in rich data for digital assets and display them as expected in-app. Digital assets on a given smart contract are typically represented solely by a unique identifier (e.g., token_id in ERC-721). The metadata associated to these unique identifiers allows the assets to have additional properties, such as a name, description, and image.

Why are metadata standards important?

Metadata standards ensure that universally recognised approaches are followed, giving confidence to NFT purchasers that an NFT's metadata is structured correctly.

This becomes particularly important as assets become cross-chain on EVM blockchains, as it ensures that your NFT will display correctly, regardless of the EVM chain it is on.

Failure to follow the official metadata standards means that your NFT is not structured correctly. This will lead to display issues within any application that does follow the proper and official metadata standards.

Token URI implementation

To allow Sparkles to pull off-chain metadata for ERC-721 and ERC-1155 assets, your contract needs to return a URI where the metadata can be found. To find this URI, Sparkles uses the tokenURI method in ERC-721 and the uri method in ERC--1155.

The tokenURI function in your ERC-721 contract or the uri function in your ERC-1155 contract needs to return either an HTTP or IPFS URL. Upon querying your URL, it should return the JSON data with the metadata for your token.

For more information on this, see the section on IPFS and Arweave for handling decentralized metadata URIs (below).

Metadata structure

Sparkles supports the metadata structures in accordance with the Official ERC721 Metadata Standards and/or the Enjin Metadata Suggestions.

Furthermore, Sparkles supports multiple other properties allowing multi-media attachments (e.g., audio, video, 3D models), allowing you to utilize filtering and sorting functionality on Sparkles.

Below is an example of metadata structuring within an NFT according to metadata standards:

{
"name": "The Sparkles Genesis Collection #742",
"image": "ipfs://QmZbZvhjja1qhMbZN3tCfntRa2XPC88QB8PBSowgJfw5vw/742.png",
"edition": 742,
"description": "The Songbird Canary Project",
"attributes": [ ... ],
"animation_url": "ipfs://QmeRu734ndhjfeEJDB1M3XgVTj2xMNJ/742.mp4"
}

This is how the properties work:

name	Name of the item.
image	URL to the item image. Can be most type of image (e.g., JPG, PNG, SVG, GIF), and can be IPFS URLs or paths. We recommend equal proportions with a minimum of 350 x 350 image.
edition	Number of the token within the collection.
description	Human readable description of the item.
attributes	Attributes for the item, which show as properties the on the item page of Sparkles. (see below)
animation_url	URL to a multi-media attachment for the item. The file extensions such as GLTF, GLB, WEBM, MP4, M4V, MOV, OGV, and OGG are supported, along with the audio-only extensions MP3, WAV, and OGA.
youtube_url	A URL to a YouTube video.
external_url	This is the URL that will appear below the asset's image on Sparkles and will allow users to leave Sparkles and view the item on your site.

⚠️ IMPORTANT ⚠️

When using the image property, use the official metadata standards.

You should use an image file type within an "image" property.

You should not use multi-media file types within an "image" field.

If you wish to include multi-media files within your metadata, you should include these within an "animation" field.

Failure to follow the official metadata standards means that your NFT is not structured correctly. This will lead to display issues within any application that does follow the proper and official metadata standards.

Attributes

To give your items more panache, your metadata can include "attributes" or "traits" which display as "Properties" under the "Info" tab within the NFT item page on Sparkles.

Below is an example of metadata structuring of traits within an NFT according to metadata standards:

...
{
"attributes": [
{
      "trait_type": "Background"
      "value": "Blue Grad",
    },
    {
      "trait_type": "Body"
      "value": "Rainbow Body",
    },
    {
      "trait_type": "Eyes"
      "value": "Money",
    },
    {
      "trait_type": "Bodywear"
      "value": "White Tank",
    },
    {
      "trait_type": "Headwear"
      "value": "No Hat",
    },
    {
      "trait_type": "Ear Feathers"
      "value": "Money",
    },
    {
      "trait_type": "Beaks"
      "value": "Golden Toothed Grin",
    },
    {
      "trait_type": "Extras"
      "value": "None",
    }

In the above example, trait_type is the name of the trait (displayed as a property on Sparkles), and value is the value of the trait.

IPFS and Arweave URIs

Storage of NFT metadata in decentralized file networks such as IPFS and Arweave, to prevent modification by a centralized entity, are supported by Sparkles.

Should you utilise IPFS for metadata hosting, your item URL should follow the format of ipfs://<hash>, e.g., ipfs://QmZbZvhjja1qhMbZN3tCfntRa2XPC88QB8PBSowgJfw5vw.png. If you do choose to store on IPFS, Pinata is a good and easy starting point to store data.

The Arweave equivalent format is ar://<hash>.