HIP-766: NFT Collection Metadata JSON Schema

Abstract

This specification provides a standard scheme for NFT Collection token metadata on Hedera Token Service (HTS).

NFT Collection tokens minted to this specification will be able to be served by explorers, wallets, and other applications, allowing those applications to display information about the token that is additional to that stored directly on-ledger in the token.

Motivation

Metadata is typically associated with indivdiual non-fungible tokens (NFTs), for which metadata such as artwork is typically stored off-ledger.

HIP-412 normalizes a metadata model for individual NFTs on Hedera where the metadata value defined on the individual NFT asset points to a JSON file that itself carries information about the characteristics of the token such as links to media, attribute and property descriptors, creator information, etc.

As is the case for individual NFTs, it may be helpful to provide information about an NFT Collection beyond that which is stored on-ledger. This specification follows the HIP-412 model to allow a NFT Collection HTS token (ie tokenID, token class) to point to a JSON file carrying that additional information. The key difference between this proposal and HIP-412 is that this specification defines a JSON schema specifically optimized for NFT Collections rather than for each individual NFT token itself.

At the time of writing, NFT Collections do not yet have such a metadata field and it is advised to utilize the memo field on the NFT Collection token to define the metadata “pointer”. An additional HIP will be submitted to address its absence and help align the usage of a metadata field across token types on HTS. When this is resolved and a proper metadata field exists on NFT Collections, we expect this field will be used to capture the pointer to the JSON object adhering to the schema specified here.

Rationale

This design is expected to

• Provide sufficient flexibility on which JSON metadata parameters are required and which optional
• Not mandate a particular storage location for either the JSON or any media it points to, i.e. IPFS, HFS, or a web server.
• Avoid duplication or conflict with the on-ledger token attributes

User Stories

As an NFT Collection creator, I want to provide more information about my NFT Collection than what is made available on-chain.

As a wallet developer, network explorer, systems integrator, or NFT marketplace, I want to be able to query the metadata for an NFT Collection consistently so that I can display that information to my users in a consistent & intuitive interface. This is far easier than manually requesting NFT Collection-specific information and media for each.

Specification

The HTS token schema allows for the name and symbol for an NFT Collection token to be carried on-ledger. To avoid redundancy & potential conflict, the JSON metadata does not include these two attributes. Instead, the JSON metadata holds additional attributes of the NFT Collection that may be useful for its interpretation, evaluation, and display.

The JSON for a non-fungible token includes the following information.

• description - human-readable description of the NFT Collection and corresponding project
• creator - the entity that created the token
• creatorDID - the decentralized identifier of the creator
• admin - if the token has an admin key, the entity that manages that key
• website -the address at which additional information on the token or corresponding project
• whitepaper - the address at which the project’s whitepaper can be found
• socials - JSON container for social links - Expected social link labels include discord, twitter, linkedin, reddit, telegram, facebook, and youtube
• properties - JSON container for arbitrary token attributes not specifically listed above

Light Backgrounds

• lightLogo - a logo for the Collection designed for light backgrounds. 350×350 pixels recommended
• lightLogoType - lightLogo mime type
• lightBanner - a banner for the Collection designed for light backgrounds. 2800×1000 pixels recommended
• lightBannerType - lightBanner mime type
• lightFeaturedImage - a featured image for the NFT Collection designed for light backgrounds. 600×400 pixels recommended
• lightFeaturedImageType - lightFeaturedImage mime type

Dark Backgrounds

• darkLogo - a logo for the Collection designed for light backgrounds. 350×350 pixels recommended
• darkLogoType - darkLogo mime type
• darkBanner - a banner for the Collection designed for light backgrounds. 2800×1000 pixels recommended
• darkBannerType - darkBanner mime type
• darkFeaturedImage - a featured image for the NFT Collection designed for light backgrounds. 600×400 pixels recommended
• darkFeaturedImageType - darkFeaturedImage mime type

Schema

Below is the human-readable schema:

{
    "description": "description of NFT Collection - max. of 500 characters - RECOMMENDED",
    "creator": "creator(s) - RECOMMENDED",
    "creatorDID": "DID  - OPTIONAL",
    "admin": "admin(s) - OPTIONAL",
    "website": "link to website -  OPTIONAL", 
    "discussion": "link to discussion/discord -  OPTIONAL", 
    "whitepaper": "link to whitepaper -  OPTIONAL",
    "properties": {
        // arbitrary additional JSON data relevant to the token - OPTIONAL
    },
    "socials": [ // Array acting as a container for social links
        {
            "url": "link to social - REQUIRED",
            "label": "textual identifier for social url - REQUIRED",
            "info": "additional information about the social URL - OPTIONAL"
        }
    ],
    "lightLogo": "IPFS CID or path to the token's light background logo file - RECOMMENDED",
    "lightLogotype": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL",
    "lightBanner": "IPFS CID or path to the token's light banner file - RECOMMENDED",
    "lightBannerType": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL",
    "lightFeaturedImage": "IPFS CID or path to the token's light featured image file - RECOMMENDED",
    "lightFeaturedImageType": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL",
    "darkLogo": "IPFS CID or path to the token's dark background logo file - RECOMMENDED",
    "darkLogotype": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL ",
    "darkBanner": "IPFS CID or path to the token's dark banner file - RECOMMENDED",
    "darkBannerType": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL",
    "darkFeaturedImage": "IPFS CID or path to the token's dark featured image file - RECOMMENDED",
    "darkFeaturedImageType": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL"
}

URI Formatting

URI’s shall follow the following format: protocol://resource_location

For resources that are on the world wide web, the standard http and https protocols are acceptable. Ie. http://www.example.org/image/file.jpg

For resources that are on IPFS, the protocol must be ipfs:// and the resource location must be the cid of the file. I.e. ipfs://bafkreibwci24bt2xtqi23g35gfx63wj555u77lwl2t55ajbfjqomgefxce

For resources that stored are on the Hedera file service, the protocol is hedera:mainnet//0.0.123456

A complete list of URIs can be found here: https://en.wikipedia.org/wiki/List_of_URI_schemes

Mime Formatting

Mime formatting shall follow the following format: type/subtype

As a rule, mime types are all lowercase. However, apps should be programmed to accept any case for robustness.

A list of common mime types can be found here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types

Note that mime types for directories are not uniformly defined. Some IPFS CIDs point to directories rather than files, so this type is useful. This standard shall define it using the format: text/directory

Reference Implementation

Example JSON Document

This is an example of a basic JSON metadata file for an NFT Collection token as described by this schema.

{
    "description": "ClankCats is an NFT Collection comprising 10,000 unique cats from different backgrounds and life stories. While they are all different, they all share one common experience; they all grew up in The Clank.",
    "creator": "ClankCats LLC",
    "website": "www.clankcats.com",
    "admin": "ClankCats DAO",
    "discussion": "https://discord.com/invite/HnSgaGWy69",
    "whitepaper": "www.clankcats.com/whitepaper.pdf",
    "properties": {
        "creationDate": "2023-07-28"
    },
    "socials": [
        {
            "url": "https://hedera.com/discord",
            "label": "Discord",
            "info": "Chat with other developers"
        },
        {
            "url": "https://linkedin.com/profile-xyz",
            "label": "LinkedIn",
            "info": "Connect with me via LinkedIn"
        }
    ],
    "lightLogo": "ipfs://bafkreihic3gwjsekbuvte2dquonz7wl2u3evztledvobntfdt575ludtcm",
    "lightLogotype": "image/jpg",
    "lightBanner": "ipfs://bafkreigwu2co2425csky7ebney4cv46rs4fpsrcgcfzic5gueo6d2dxd4q",
    "lightBannerType": "image/jpg",
    "lightFeaturedImage": "ipfs://bafkreigwu2co2425csky7ebney4cv46rs4fpsrcgcfzic5gueo6d2dxd4q",
    "lightFeaturedImageType": "image/jpg",
    "darkLogo": "ipfs://bafkreihic3gwjsekbuvte2dquonz7wl2u3evztledvobntfdt575ludtcm",
    "darkLogotype": "image/jpg",
    "darkBanner": "ipfs://bafkreigwu2co2425csky7ebney4cv46rs4fpsrcgcfzic5gueo6d2dxd4q",
    "darkBannerType": "image/jpg",
    "darkFeaturedImage": "ipfs://bafkreigwu2co2425csky7ebney4cv46rs4fpsrcgcfzic5gueo6d2dxd4q",
    "darkFeaturedImageType": "image/jpg"
}

Backwards Compatibility

This HIP is entirely opt-in and does not break any existing functionality. It simply provides standards to facilitate integration for the display of metadata for NFT Collection HTS tokens throughout the ecosystem.

Security Implications

Mutability of the metadata for a token will depend on

• whether or not the token itself has an admin key. When an admin key is set, the memo can be updated to point to a different JSON metadata file
• whether the storage location of the JSON metadata file guarantees immutability (e.g. IPFS of HFS)
• whether the storage location of any media the JSON references guarantees immutability.

In the future, if a proper metadata field exists on the NFT Collection, an associated metadataKey is available which offers mutability.

How to Teach This

Wallet and token explorer implementations interrogate HTS tokens using this standard to display additional metadata for NFT Collection tokens such as logos and descriptions.

Open Issues

• What is the appropriate maximum length for a token’s description? Wallets, exchanges, explorers, etc., will need to display these within their UI, and there need to be some restrictions to ensure consistent display lengths.

References

[0] https://github.com/hashgraph/did-method/blob/master/did-method-specification.md

[1] https://w3c.github.io/did-core/

[4] https://docs.ipfs.io/how-to/best-practices-for-nft-data/#persistence-and-availability

[5] https://en.wikipedia.org/wiki/List_of_URI_schemes

[6] https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Acknowledgements

Big thanks to the author and working group of HIP-405 which was used extensively in both the content and formatting of this HIP.

Citation

Please cite this document as: