What is the correct format for Stacks NFT metadata CSV files?

If you're a creator deploying your collection using our no-code launchpad for Bitcoin NFTs, you'll have the option to create and upload a custom CSV file containing custom NFT metadata. While this is an optional association, it can help set your collection apart from others, and provide added benefits relative to collections without them. We'll explain exactly how to format your file, so you can easily add it to your collection if desired.

You can create a CSV file using many different applications, but the most common method would be to use Microsoft Excel or Google Sheets. These files can be exported as a CSV file when downloading them.

NFT Metadata CSV File

The NFT metadata CSV file is fully dependent on your specific collection requirements, and there is no single correct method of entering values. That said, there is a format required for the system to correctly read and interpret your metadata in the way you intend. This might be a little confusing for some less technical creators, but it's really quite simple once you understand the basics. For this, we've put together a visual guide to help explain how to correctly input and format your file.

______________________

Why Include Metadata?

NFT metadata can take time and effort to create, so it's important to understand why this time investment can be worthwhile for your collection. Suppose you have a simple NFT collection consisting of a series of shapes, each with different colors and attributes. Looking at the NFT visually might give you all the information you need to understand what is depicted. But, adding descriptive traits can help elevate your collection in several ways.

• Adding written metadata improves accessibility for your collection and describes what is contained within the image.
• Metadata is the mechanism by which rarity can be determined, since marketplaces can read the frequency of a given trait and calculate how common or rare the aggregate of all of an NFTs traits are. After performing this calculation, the system can definitively rank a collection's NFTs from most rare, to least rare.
• Metadata allows users to filter and sort for specific attributes without having to scan the entire collection. This is particularly useful if your collection is large, and might otherwise be difficult to track down a specific attribute using visuals alone.
• There are qualities or utility to some attributes that are not visible on the NFT image. Perhaps you are describing a sound, or perhaps you are describing a hidden utility or benefit of one NFT over another. For example, your most special NFTs might have an attribute that is then checked for on your collection's website. If the attribute exists, it might allow access to an exclusive portion of the website. The possibilities are endless if you have the development resources to enable your concept.

______________________

Summary of Metadata CSV Formatting

Below is a summary of the tutorial example outlined below. If you follow these steps, your collection's metadata will be a worthwhile time investment as a creator.

• Your document should be saved and uploaded as a CSV file.
• Your document's first row should represent the attribute names. For example, row 1 might include "Background Color" and each subsequent row might include "Red" and "Blue" based on the color of the NFT's background.
• Each row following the header, row 2 and beyond, will correspond sequentially to each NFT token ID in your collection. In other words, row 2 will associate to token 1, row 3 will associate to token 2, and so on.
• There is no need, and it is not generally recommended, to include a column for token ID. These are generated automatically if you have not enabled file names for your NFTs.
• You must have one single row for each token in your collection. If the attribute in question is not applicable to a given NFT, you may leave this blank or define a consistent value for the absence of this attribute.
• You must not have empty rows at the end of your document. All rows below your bottom row must be deleted before downloading the file as a CSV document.

While this isn't a specific requirement, it's not recommended to include long descriptions as part of your NFT metadata. Visually, these traits will be difficult to filter and sort and may limit the practical application of that attribute.

______________________

Example Collection Metadata

Using the same example above, we've outlined a visual guide on how you would create a metadata file for a collection of ten sample tokens (NFTs).

Pictured: a visual guide to ten NFTs, a series of shapes of alternating colors and with differing emojis. P.S. this caption is a form of metadata, explaining the contents of this image in an indexable way.

Notice the ten tokens and recognize the visual differences between them. Some are circles, some are triangles, and some are squares. Some have a blue background color, some green, and some yellow. And some contain smiley emojis, some contain angry emojis, and some have no emoji at all. Below each image is a text-based description of the token. This text-based description will become our metadata for our CSV file.

For the purposes of this example, suppose also that these NFTs were able to be used in a simple game, whereby some NFTs serve as characters with some hidden abilities or talents. These talents are not visually present, but our game wouldn't be able to enable these hidden talents if we didn't associate it as metadata to the NFT. So, our CSV file will contain these hidden talents and they will be associated with the NFT in a non-visual way.

We can convert the descriptors into categories, each relating to one column in our CSV file. We'll include one header row with the names of the attribute. In most cases, we'll want to use the singular form of the descriptor as each NFT will only have one such attribute. For example, we wouldn't say "Colors" since the NFT will only have a single "Color" associated with it. The value we use as our header will be visually depicted beside the NFT on the marketplace.

As a final mention, notice that some NFTs in our example collection do not have emojis associated with them. As such, we can do one of two things. First, we can leave the field blank which will automatically group blanks as a null or, practically speaking, "None" value in cases like sorting and filtering. A second option would be to describe the absence of a trait as another trait altogether. The use case for this would depend on your collection, but it might make more sense to describe the trait than not. For example, if you had a trait for "Hair", you might want the absence of a trait to not be "None", but rather, be "Bald". Use your discretion in determining whether values should be left blank or described.

When all is said and done, your collection CSV should look like this:

Notice that row 2 is representative of token 1, row 3 is representative of token 2, and so on. Notice also that there are no additional empty rows at the bottom of the file. Empty rows will not be accepted by the portal.

Additionally, notice that row 2 is automatically related to token 1 simply by virtue of its ordering in the document. There is no need for a specific column for ID. If a column is included for ID, this will be present as an additional attribute, which will make things like sorting and filtering unnecessarily cluttered. We recommend not including this as an attribute unless you have a specific need for it.