HIP-10: NFT Metadata JSON Schema

[sam-at-luther]

A key accelerator to the adoption of the ERC721 [0] Non Fungible Tokens (NFT) standard for the Ethereum network is the "ERC721 Metadata JSON Schema" definition. This schema is part of the optional metadata extension of that standard, and provides a guidelines for the format of the data that served for a token's metadata URI. This standard is how the plethora of wallets in that ecosystem (for example OpenSea [1] and d'cent [2]) display asset attributes for many ERC721 implementations, including an image for each NFT.

Building on the success of that standard, I propose optionally adopting this same JSON schema standard for NFT metadata on HTS. Specifically,

{
    "title": "Asset Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this NFT represents"
        },
        "description": {
            "type": "string",
            "description": "Describes the asset to which this NFT represents"
        },
        "image": {
            "type": "string",
            "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
        }
    }
}

I also would like to solicit feedback on how the community thinks is best to include URIs that serve metadata in the above format within HTS NFTs.

Based on these discussions, I'm eager to draft a HIP and be a champion for such a standard.

[0] https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md#specification
[1] https://opensea.io/
[2] https://dcentwallet.com/

[rahul-kothari]

for images/videos - probably use IPFS to ensure authenticity? Pinata is also another interesting idea!

[cylon56]

Here is a potential add-on to this proposal or a separate HIP for NFTs. HTS should support the creation of numerous non-fungible tokens of a single type.

Currently, it seems that NFTs can only work on HTS if you create a token with a supply of one and treat it as an NFT. This seems like a workaround for now and leaves a lot to be desired. In addition to having embedded metadata, HTS should also allow users to create a single class of NFTs that can each be recognized as the same type while still being individually distinct tokens.

[rahul-kothari]

At this point, it might be easier to just create an HNFTS (Hedera Non-Fungible Token Service).

[sam-at-luther]

Re: IPFS: The proposed spec discusses how this URI can point to IPFS:
NFTs optionally specify a URI in the token "name" attribute. This URI MAY link to data on the Hedera File Service, IPFS, a DID, AWS, or any other URI the issuer specifies.
So it allows IPFS 👍

Re: NFTs, I agree that standardization is necessary for the best way to do NFTs on HTS today, and possibly this may be a separate API or service. I think it's best to break that out into a separate specification, so as to limit the scope of this spec just to the linking of asset metadata.

[cylon56]

Re: NFTs, I agree that standardization is necessary for the best way to do NFTs on HTS today, and possibly this may be a separate API or service. I think it's best to break that out into a separate specification, so as to limit the scope of this spec just to the linking of asset metadata.

Metadata asset linking is mainly a core NFT feature so it would make sense to formally support NFTs on HTS before adopting NFT-specific features.

I propose we create a single HIP that requests formal NFT support on Hedera with a list of critical features including asset metadata and the ability to create multiple unique tokens of an associated type.

[pckrell]

Also the question remains to which extend providers hosting meta data content really can provide something I would refer to as "virtual eternity"... Maybe IBM? They exist since 1911...

[sam-at-luther]

Folks are deploying NFTs today on HTS. This HIP gives them a standard way to link to token metadata.

[cylon56]

I agree that it makes sense to support metadata on HTS as it is today. I could see scenarios where someone might want to host metadata that applies to fungible tokens as well while also supporting the current NFTs being created on HTS.

The main difference between this proposal and full NFT support is that metadata links could be unique to each token created under a common type. So this proposal could target metadata JSON as a general standard and focus on defining a schema structure that can be used for both fungible tokens and NFTs. A separate proposal could then be made to create NFTs as a formal standard on HTS using the same schema proposed here.

So I propose the following:

1. Redefine this proposal to target metadata JSON as a general standard. HTS could then be the first use-case that applies to both fungible tokens and the current NFTs being created on HTS.
2. File a new proposal to formally support NFTs on Hedera as either an extension of HTS or a separate service. This would allow the creation of multiple unique tokens of the same type that also use the same metadata standard defined here.

Happy to hear feedback on this. My main goal is to ensure the standard we come with up here doesn't need to be duplicated later and that metadata JSON support on HTS isn't confused with the full NFT support that is still needed.

[rahul-kothari]

I propose a few modifications (and yes I know this will make it incompatible with ETH):

• Removing the "images" key to uri since the NFT could be for any digital asset - video, music, art etc.
• name and description will be parent key values
• Have a custom_attributes key to have any custom key-value pairs specific to the NFT. E.g. "strength": 20 (useful for game related NFTs). This would be supercharged if per @cylon56, we can have several NFTs of one type.

To summarize, here is an example JSON schema:

{
    "title": "Asset Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this NFT represents"
        },
        "description": {
            "type": "string",
            "description": "Describes the asset to which this NFT represents"
        },
        "uri": {
            "type": "string",
            "description": "A URI pointing to a resource"
        },
       "custom_attributes": {
             "type": "object",
            "description": "a nested json"
       }
    }
}

Sanity check: the metadata of an actual NFT wouldn't actually have title or type and everything within properties would be the actual key-value pairs (instead of being nested within properties)

[pckrell]

Where would these meta data files be hosted for a period of mere "virtual eternity"?

[teacoat]

Agreed - needs to be more flexible than just images. 3D assets, videos, music, documents, etc., could all be stored as a NFT.

[sam-at-luther]

Hi @cylon56 ,

Redefine this proposal to target metadata JSON as a general standard. HTS could then be the first use-case that applies to both fungible tokens and the current NFTs being created on HTS.

This sounds reasonable to me. I will update the proposal to indicate that it's a general way to link to token metadata on HTS, regardless of the type of token.

[sam-at-luther]

Hi @rahul-kothari , I think it's important to keep the image attribute (note that none of the properties in the schema are marked required) that specifically has requirements around the image format, so as to facilitate the integrations with different wallets (software & hardware) and explorers that display the content. (see example in HIP-10).

Note that in this JSON schema additional properties are allowed, so messages conforming to your example schema above would still be allowed as part of the proposal.

[sam-at-luther]

@cylon56 and @rahul-kothari: thinking about this more, since I agree that it makes sense to make this token metadata broader than just NFTs, what do you think about the following JSON schema? It is an extension of the one presently described in the HIP-10 draft, and has adoption already in ERC-1155 which is used heavily by some NFT explorers?

It includes properties which is equivalent to the proposed custom_attributes @rahul-kothari, and decimals which is relevant for fungible tokens:

{
    "title": "Token Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this token represents"
        },
        "decimals": {
            "type": "integer",
            "description": "The number of decimal places that the token amount should display"
        },
        "description": {
            "type": "string",
            "description": "Describes the asset to which this token represents"
        },
        "image": {
            "type": "string",
            "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
        },
        "properties": {
            "type": "object",
            "description": "Arbitrary properties. Values may be strings, numbers, object or arrays."
        }
    }
}

[cylon56]

@sam-at-luther I like this approach. It covers all our bases and leaves room for future changes in Hedera-based tokens.

[rahul-kothari]

Yea I think erc1155 like json makes so much more sense. I also agree to your previous point about keeping images for wallet integration.

[sam-at-luther]

Hi @cylon56 and @rahul-kothari . I've updated the PR above to incorporate feedback from this discussion.

[rahul-kothari]

Cool saw it. Makes sense to me. Not sure how technical HIP docs need to be/who would end up actually implementing but yea excited to see what happens next!

[BooneTB]

I would love to work with you Sam on some NFTs for pilot projects to test out this HIP.
Please see attached NFT in process :)

[BooneTB]

https://eadonforest.club/

[topshef]

I agree with Rahul re removing image so NFT can be any type (video etc)
#50 (comment)

FYI example 3D model on GoMint using custom json, but would like to align with work here.
https://labs.gomint.me/query/?network=testnet&tokenId=0.0.457840

{
    "data": [
        {
            "tokenAssetType": "GLB",
            "tokenAssetURL": "https:\/\/labs.gomint.me\/data\/client\/313d48882e2ba7bb25a340dbfd3d6f9bbc7f012372d54f518dc52e4299e3a24e.octet-stream",
            "tokenAssetHash": "313d48882e2ba7bb25a340dbfd3d6f9bbc7f012372d54f518dc52e4299e3a24e",
            "tokenDescription": "https:\/\/modelviewer.dev\/",
            "tokenAssetKeyholder": "GoMint",
            "tokenAssetCreator": "ZV2238",
            "tokenContractType": "GMC007"
        }
    ],
    "roothash": "313d48882e2ba7bb25a340dbfd3d6f9bbc7f012372d54f518dc52e4299e3a24e",
    "hashmethod": "SHA256(tokenAsset)"
}

The roothash links the metadata to the token symbol, and could be expanded to any nested structure.

[sam-at-luther]

Hi Topshef. I think it's important to have an explicit field with images that the spec has guidelines on with respect to the format, dimensions, aspect ratio, etc, so that the various explorers, wallets, and exchanges can provide a predictable user experience.

There is an open ended properties field which can be used to associate non-image data particular to an application or use case, and the image field is not mandatory.

[topshef]

How would having a generic type limit explorers etc? NFTs representing images would of course have an image, but a predictable user experience for a blind person might be that Alexa provides an audible "thumbnail", or a future zoom meeting might project a hologram of the attendants.

[sam-at-luther]

See my reply below to @andrewantar . The "properties" fields are intended for exactly these generic types where you can put anything custom/specific to your token types.

[teacoat]

@sam-at-luther I highly suggest defining some other typical types in the example, so everyone is on the same page.

For example in addition to the "image" structure defined here, define one for videos. Should it be called "video", "movie", etc. having these just defined for people to know what to expect would be helpful.

[andrewantar]

Correct me if I’m wrong, but it seems as though HTS is its own standard for all token types whereas fungibility is a spectrum. Ethereum took an entirely different approach having a set of overall ERC standards and specific groups of standards for different use cases (20,721,1155).

A true 1:1 no-decimals token on HTS is an NFT for all intensive purposes. While the schema might differ from 721 or 1155, it still has a description and images field for tagging actual assets on either centralized dbs, Hedera file service, or IPFS. Also many real world rewards/experiences can be tied to tokens that are offline, or simply promises by the issuer. There’s also use cases for 10:10 or 100:100 NFTs sortof like limited edition prints. While there’s a higher degree of “fungibility” since there are equal copies of each, they are not meant to be divisible and the supply is limited and scarce imputing a higher value. There’s also the ability to have a 1:1 with 1 decimal making a single asset divisible into 10 possible owners. Of course more decimals add more divisibility for fractional ownership. One could also mint 10 separate 1:1s so make 10 unique tokens that all tie to the same asset or reward. At the end of the day it’s all about how you actually use HTS. One of the key features on OpenSea is the ability for setting a residual reward to the creator every time it is traded like 10%. I’d like to know if this is possible with HTS, and what metadata if any is missing from the HTS schema which would prevent HTS tokens from having the same end functionality as any number of ERC token standards.

[rahul-kothari]

So a couple of points 1. HTS can be used for NFTs except you can’t add ANY metadata. So you can’t link the token to an image, video or document, which effectively makes the NFT worthless. 2. (Not related to the HIP but an answer to one of your questions): HTS doesn’t provide any programmability and so it can’t replicate an ERC. Apart from admin stuff like freezing/pausing/minting/burning, you can “only” transfer tokens. That said, HTS wasn’t created to be the ERC of ethereum. HTS was created to create a basic token very very quickly.

…

Am 19/04/2021 um 19:47 schrieb Andrew Antar ***@***.***>:  Correct me if I’m wrong, but it seems as though HTS is its own standard for all token types whereas fungibility is a spectrum. Ethereum took an entirely different approach having a set of overall ERC standards and specific groups of standards for different use cases (20,721,1155). A true 1:1 no-decimals token on HTS is an NFT for all intensive purposes. While the schema might differ from 721 or 1155, it still has a description and images field for tagging actual assets on either centralized dbs, Hedera file service, or IPFS. Also many real world rewards/experiences can be tied to tokens that are offline, or simply promises by the issuer. There’s also use cases for 10:10 or 100:100 NFTs sortof like limited edition prints. While there’s a higher degree of “fungibility” since there are equal copies of each, they are not meant to be divisible and the supply is limited and scarce imputing a higher value. There’s also the ability to have a 1:1 with 1 decimal making a single asset divisible into 10 possible owners. Of course more decimals add more divisibility for fractional ownership. One could also mint 10 separate 1:1s so make 10 unique tokens that all tie to the same asset or reward. At the end of the day it’s all about how you actually use HTS. One of the key features on OpenSea is the ability for setting a residual reward to the creator every time it is traded like 10%. I’d like to know if this is possible with HTS, and what metadata if any is missing from the HTS schema which would prevent HTS tokens from having the same end functionality as any number of ERC token standards. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[andrewantar]

There is a memo field in both the token itself when minting (1/1 NFT) and on each transaction. So couldn't any relevant metadata be added or linked there?

[sam-at-luther]

The memo field has a field length (IIRC 100 characters) which wouldn't be suitable to store a collection of keys/values, or URIs to images. This HIP standardizes the process of linking to a metadata JSON document stored elsewhere (via a URI) by including a URI in the memo field of the token. The HIP also standardizes the schema of the JSON document, which itself may link to other URIs (e.g, an image of the token).

[lmulligan2020]

Hi, Just as a use case example, i am starting to concept a VR experience using HTS and would like to be able to retrieve an image preview from an NFT stored/associated with someones account. It would be great if this was a reasonable dimension (large preview) might be unreasonable i am not sure on your size limitations etc.?. As an alternative if this has to be kept light, could perhaps the file service be able to act as a source location to host say a video preview or a light 3d model for the object?. Can someone please explain what the MVP for the metadata and images might look like. Kind regards.

[sam-at-luther]

Please see the Reference Implementation section for an example of how to use this HIP for an image.

[andrewantar]

Thanks for linking the HIP and I like the more fleshed out JSON schema. I think instead of image URI it should be file URI since NFTs can be linked to images, videos, audio, or simply files. Also couldn't 100 characters include any shortened URI?

…

On Wed, May 12, 2021 at 2:35 PM Sam Wood ***@***.***> wrote: Please see the Reference Implementation <https://github.com/hashgraph/hedera-improvement-proposal/blob/master/HIP/hip-10.md#reference-implementation> section for an example of how to use this HIP for an image. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#50 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG2KXPHZWZJFFG4S4D7TDDTNLC6JANCNFSM42THOTHQ> .

[sam-at-luther]

By having an explicit field with constraints on the file type it allows 3rd parties to predictably load the content, and not need to infer the content after loading the content. Think of an embedded hardware wallet such as d'cent which displays only static images on a small display. You can always include a URI to some other content in one of the other properties. For example, you could set properties.file to refer to a file specific to your assets.

[topshef]

I assume to avoid inference there'd be a type field "If type=image then load"
The market is currently dominated by image-based NFTs but who's knows what the future will hold... maybe we'll all go blind staring at our screens and switch to Alexa sound-bytes ;-)

[lmulligan2020]

https://youtu.be/rXgvEQrXHJc alot of interesting uses like this

[gregscullard]

It may be beneficial to include a version number to the "specification" so that later revisions of the specification can be handled accordingly by consumers of the data. It is of course always possible to check for the presence/absence of an attribute in JSON, but a version number could be useful still.

[sam-at-luther]

Agree that this would be beneficial. Does "version": "0.0.1", sound reasonable with semantic versioning? Also, this would just be on the metadata JSON specification?

[gregscullard]

Suggesting an alternative for localization, IPFS doesn't allow for custom URLs

for example change from

{
  "name": "Chloe Artwork",
  "description": "Chloe Searching For Light Artwork Test Token",
  "image": "https://dev.luthersystemsapp.com/chloe_assets/SearchingForLightNo_81_20/image_part_005.jpg",
  "localization": {
    "uri": "https://dev.luthersystemsapp.com/nft-test-{locale}.json",
    "default": "en",
    "locales": ["en", "es", "fr"]
  }
}

to

{
  "name": "Chloe Artwork",
  "description": "Chloe Searching For Light Artwork Test Token",
  "image": "https://ipfs-cid",
  "localization": {
    "default": "en",
    "locales": [
        {
            "locale": "en",
            "uri": "https://ipfs-cid-for-en"
        },
        {
            "locale": "es",
            "uri": "https://ipfs-cid-for-es"
        },
        {
            "locale": "fr",
            "uri": "https://ipfs-cid-for-fr"
        }
    ]
  }
}

[sam-at-luther]

ERC-1155 addressed this issue by adding templating support in the URI. I am considering updating the HIP to include templating, both for the token ID {id} (and serial number for NFTs), and for {locale}. Does this approach address your needs?

For example,

{
  "name": "Advertising Space",
  "description": "Each token represents a unique Ad space in the city.",
  "localization": {
    "uri": "ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/{locale}.json",
    "default": "en",
    "locales": ["en", "es", "fr"]
  }
}

[sam-at-luther]

This PR makes reference to HIP-30 CAIDs for referencing metadata JSON stored on the hedera network, along with adding versioning, and reference to the token metadata field for non-fungible token types.

[vova-yatsyk-theraven]

Hi

1. Why aspect ratio for the image is limiting to 4:5 (=0.8)?
   I understand that it was taken from EIP-1155 but I think it should be expanded a little bit to fulfill gaming assets requirements. Standard playing card has a size of 2.5 inches x 3.5 inches (=0.714), most board games (including the most popular collectible game Magic: The Gathering) have cards 63mm x 88mm (=0.716). This size is playing around B8 paper size from ISO 216, which is 62mm X 88mm (=0.705).
   I propose to expand it a little bit to be at least 0.7:1
2. the name property for the field with custom properties:

   "properties": {
       "type": "object",
       "description": "Arbitrary properties. Values may be strings, numbers, object or arrays."
   }
   

   It is also taken from EIP-1155, but the thing is that de-facto standard is the name that used by Opensea specification: attributes. It is possible that Opensea supports both names, if so - then everything is good.
   A lot of other marketplaces are following Opensea specifications.

[sam-at-luther]

Why aspect ratio for the image is limiting to 4:5 (=0.8)?

The wording is more of a recommendation, but I have no problem adjusting to 0.7 especially given the huge interest in collectable trading cards.

It is possible that Opensea supports both names, if so - then everything is good.

OpenSea does support both. See this example with this metadata JSON.

[sergmetelin]

Are all the questions addressed, and we can move it to the Accepted state from Last Call, or is there something that still needs to be addressed?

[sam-at-luther]

I have a PR open that incorporates most of the feedback from the above discussion: #243

[sergmetelin]

@sam-at-luther are we good to move this HIP to Accepted from your perspective?

Also, what's your take on changing the type of this HIP from Standards Track/Application to Informational?

[sam-at-luther]

Hi Serge, yes it's good from my perspective. I need to defer to hedera on the most appropriate category. I do want it to be a go-to standard that applications use to ensure ecosystem compatibility and flexibility.

[teacoat]

Would it be more versatile to have a structure something like this? Images aren't the only thing to be cognizant of, and support for multi-file metadata would be nice.

{
    "name": "NFT Name",
    "description": "NFT Description",
    "thumbnail": "//link to image",
    "files": [
        {
            "file": "https://dev.luthersystemsapp.com/chloe_assets/SearchingForLightNo_81_20/image_part_005.jpg",
            "type": "image"
        },
        {
            "file": "//IPFS LINK",
            "type": "pdf"
        }
    ]
}

[vova-yatsyk-theraven]

I like this files structure, but think that it's better to leave image field instead of thumbnail to be more compatible and "friendly" with other blockchains and existing solutions.