Structure Your Token Metadata Using JSON Schema V2
When you create a new fungible or non-fungible token, you have the ability to add metadata. It's common to add metadata for NFTs, but also fungible tokens. The biggest problem with metadata is that it's often unstructured or doesn't follow a set of guidelines.
Therefore, Hedera has developed the "Token Metadata JSON Schema V2" for developers and creators who want to structure their metadata in an organized way. The biggest benefit of using this community-accepted standard is that most of the tooling on the Hedera network can scrape and interpret your metadata, like NFT explorers listing rarity attributes based on your metadata.
We recommend you complete one of the two tutorials below that teach you how to create a fungible or non-fungible token on the Hedera network.
It's essential to understand that the token metadata JSON schema V2 requires you to store metadata using a storage solution, centralized or decentralized, such as IPFS or Arweave.
When creating a non-fungible token using the Hedera Token Service, you set the metadata value to the metadata JSON file to define your NFT, wherever it’s stored. This technique allows you to connect the metadata to the token created on the Hedera network. It's not allowed to use the "memo" or "symbol" fields on the NFT.
Java
JavaScript
Go
// IPFS content identifier (CID) that points to your metadata
String CID = ("QmTzWcVfk88JRqjTpVwHzBeULRTNzHY7mnBSG42CpwHmPa") ;
// Mint a new NFT
TokenMintTransaction mintTx = new TokenMintTransaction()
.setTokenId(tokenId)
.addMetadata(CID.getBytes())
.freezeWith(client);
// IPFS content identifier (CID) that points to your metadata
let CID = "ipfs://QmTzWcVfk88JRqjTpVwHzBeULRTNzHY7mnBSG42CpwHmPa";
// Mint new NFT
let mintTx = await new TokenMintTransaction()
.setTokenId(tokenId)
.setMetadata([Buffer.from(CID)])
.freezeWith(client);
// IPFS content identifier (CID) that points to your metadata
CID := "QmTzWcVfk88JRqjTpVwHzBeULRTNzHY7mnBSG42CpwHmPa"
//Mint new NFT
mintTx, err := hedera.NewTokenMintTransaction().
SetTokenID(tokenId).
SetMetadata([]byte(CID)).
FreezeWith(client)
First of all, you can find the full reference implementation of this JSON schema here:
- IPFS: ipfs://bafkreidcsqzr5su356thecwuyzrhsgekfdsqzuyuqxtsu4vh7oc34iv5oy
Let's take a look at the different fields you can specify.
name, type, and image
The schema defines three required fields:
- name: Full name of the NFT
- image: A URI pointing to an image (decentralized or centralized storage).
The
image
field can both serve as a preview or full-resolution image for your NFT to ensure cross-platform compatibility. The image field will be displayed in wallets and marketplaces by default.Creators are recommended to point to a thumbnail in the
image
field and put the high-resolution image in the files
array with the is_default_file
boolean set to indicate that this file represents the default image for the NFT. (This is shown in the next section)Here's a small example of an implementation.
{
"name": "My first NFT",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png"
}
files
properties
attributes
localization
description, creator, creatorDID, checksum, and format
The
files
field represents an array containing file objects. For collectible NFTs, the files array allows you to store the high-resolution image of your NFT. However, you can also use this field for multi-file NFTs. Each file object requires a URI and type. It's recommended to use the is_default_file field to indicate which file is the main file for your NFT. Besides that, the files array allows you to upload or link file-specific metadata. This allows you to nest files indefinitely.
{
"name": "My first NFT",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png",
"files": [
{
"uri": "https://myserver.com/high-resolution-nft-001.png",
"checksum": "9defbb6402d4bf39f2ea580099c73194647b24a659b6f6b778e3dd71755b8862",
"is_default_file": true,
"type": "image/png"
}
]
}
It's not allowed to define additional fields on the root level of the metadata object.
// ❌ Not allowed to add "website" to the root of the object
{
"website": "https://mysite.com",
"name": "My first NFT",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png"
}
If you want to add custom fields, you can add them to the
properties
object. For example, you are linking to a website or social media pages. You can structure the metadata within the properties
field as needed. Some developers even prefer defining their own standard for the properties field, not for the entire metadata object.// ✅ Good example
{
"name": "My first NFT",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png",
"properties": {
"website": "https://mysite.com",
"socials": {
"linkedin": "https://www.linkedin.com/in/myprofile/"
}
}
}
The
attributes
field is specifically used to calculate rarity of NFTs. It's an industry-accepted way to define traits and their values for a collectible NFT collection in order to calculate the rarity score of the NFT. The
attributes
fied consists of an array of attribute
objects. This is the structure of such an object:- trait_type: (required) Name of the trait.
- value: (required) Value for the trait, e.g. for a
trait_type = clothing
, values can bepants
,shirt
, ort-shirt
. - display_type: (optional) Allows you to specify how the trait should be displayed. For instance, you can set it to
datetime
so the person or bot knows the value should be interpreted as a date. - max_value: (optional) It's possible to set a
max_value
for a numerical value.
{
"name": "My first NFT",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png",
"attributes": [
{
"trait_type": "clothing",
"value": "pants"
},
{
"trait_type": "color",
"display_type": "color",
"value": "rgb(255,0,0)"
},
{
"trait_type": "hasPipe",
"display_type": "boolean",
"value": true
},
{
"trait_type": "coolness",
"display_type": "boost",
"value": 10,
"max_value": 100
},
{
"trait_type": "stamina",
"display_type": "percentage",
"value": 83
},
{
"trait_type": "birth",
"display_type": "datetime",
"value": 732844800
}
]
}
Extra resources: You can find all information about the
attributes
field in the detailed schema specification.The standard also allows for localization. Each locale links to another metadata file containing localized metadata and files. This allows for a clean metadata structure. Don't define a new localization object for a localized metadata file to avoid infinite looping when parsing an NFT's metadata file.
Note that the
localization.uri
property contains {locale}
. The {locale}
part references a locale in the locales
array. You should use two-letter language codes according to the ISO 639-1 standard to define languages.{
"name": "My first NFT",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png",
"localization": {
"uri": "ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/{locale}.json",
"default": "en",
"locales": ["es", "fr"]
}
}
In this example, the default locale is set to English (
en
) and the schema provides localization for Spanish (es
) and French (fr
). The schema assumes it can find the Spanish and French version under the following URIs because of the way it has been specified using the interpolation notation {locale}.json
. This is what the resulting URIs should look like:ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/es.json
ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/fr.json
A localized file would have the same structure, but doesn't specify any localization field. Here's an example for the French version.
// metadata for ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/fr.json
{
"name": "Mon NFT (French)",
"type": "image/png",
"image": "https://myserver.com/preview-image-nft-001.png"
}
Here's a list of remaining optional fields you can define according to the Token Metadata JSON Schema V2 specification.
- description: A text that describes your token or NFT collection.
- creator: Identifies the artist name(s).
- creatorDID: Points to a decentralized identifier to identify the creator.
- checksum: Cryptographic SHA-256 hash of the representation of the
image
resource or resources in thefiles
array. It allows browsers or other tooling to verify the integrity of any file you list. - format: Indicates the implemented metadata schema specification. Currently, the default version (Token Metadata JSON Schema V2) is represented by
[email protected]
. If you wonder why, each update to the JSON Schema requires a new Hedera Improvement Proposal (HIP). Therefore, theformat
field lists the HIP number and the associated version of the Token Metadata JSON Schema.
Full schema implementation
This is what a full Token Metadata JSON Schema V2 specification looks like.
{
"name": "Example NFT 001",
"creator": "Jane Doe, John Doe",
"creatorDID": "did:hedera:mainnet:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm;hedera:mainnet:fid=0.0.123",
"description": "This describes my NFT",
"image": "https://myserver.com/preview-image-nft-001.png",
"checksum": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
"type": "image/png",
"format": "[email protected]",
"properties": {
"external_url": "https://nft.com/mycollection/001"
},
"files": [
{
"uri": "https://myserver.com/high-resolution-nft-001.png",
"checksum": "9defbb6402d4bf39f2ea580099c73194647b24a659b6f6b778e3dd71755b8862",
"is_default_file": true,
"type": "image/png"
},
{
"uri": "ipfs://yusopwpksaioposjfopiapnnjlsl",
"type": "image/png"
}
],
"attributes": [
{
"trait_type": "clothing",
"value": "pants"
},
{
"trait_type": "birth",
"display_type": "datetime",
"value": 732844800
}
],
"localization": {
"uri": "ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/{locale}.json",
"default": "en",
"locales": ["es", "fr"]
}
}
When you create token metadata for the first time, you want to verify your metadata against the Token Metadata JSON Schema V2. To help you in this, Hedera has created an NFT utilities SDK (only for JavaScript) to verify your metadata against the JSON Schema V2.
You can install the package using Yarn or NPM.
npm i -s @hashgraph/nft-utilities
Next, you need to import the
validator
function which accepts your metadata as a JSON object and the schema version against which you want to verify the metadata (2.0.0
). Here's the code.const metadata = {
attributes: [
{ trait_type: "Background", value: "Yellow" }
],
creator: "NFT artist",
};
const version = '2.0.0';
const issues = validator(metadata, version);
console.log(issues);
The package will return errors and warnings using the below interface. This snippet of example output tells you that you have incorrectly used the
percentage
display_type
in the attributes field, and you have defined a custom field called imagePreview
on the root of the metadata object, which is not allowed (use the properties
field).{
"errors": [
{
"type": "attribute",
"msg": "Trait stamina of type 'percentage' must be between [0-100], found 157",
"path": "instance.attributes[0]"
}
],
"warnings": [
{
"type": "schema",
"msg": "is not allowed to have the additional property 'imagePreview'",
"path": "instance"
}
]
}
Here's a video that talks about the importance of structuring your token metadata and how to do it according to Token Metadata JSON Schema V2.
You can find examples in this blog post in the section "Token Metadata V2 NFT Examples". If you still have questions, reach out on Discord or ask it on StackOverflow.
Besides that, you can read up on the full implementation of token metadata in the Hedera Improvement Proposals GitHub Repository under HIP-412.
Last modified 5d ago