HIP-412: Updating NFT JSON metadata schema standards

[Ashe-Oro]

A discussion around HIP412 and its updates to HIP10.

#412

[web3-nomad]

re: localization, you may want/need to put in a file reference to which file is being localized.
(in the example there are two URIs in the example NFT, and two localizations, but it is unclear which the localization is pointing too)

[rocketmay]

So, the localization in the example would point to different localized metadata that describe the root metadata, it doesn't actually point to the files themselves. The localized metadata would presumably point to localized files as well, as applicable.

[Ashe-Oro]

inside the Files[] section, an individual file could have it's own localization metadata. In the example below, the first file "Example Video" doesn't contain localization data, but the second file [Example second file, a PDF" does.

{
    "name": "Example NFT",
    "creator": "Jane Doe, John Doe",
    "creatorDID": "did:hedera:mainnet:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm;hedera:mainnet:fid=0.0.123",
    "description": "This is an example NFT metadata",
    "format": "none",
    "files": [
        {
            "uri": "ipfs://bawlkjaklfjoiaefklankfldanmfoieiajfl",
            "type": "video/mp4",
            "metadata": {
                "name": "Example Video"
            }
        },
        {
            "uri": "ipfs://bawlkjaklfjoiaefklankfldanmfoieiajfl",
            "type": "application/pdf",
            "metadata": {
                "name": "Example second file, a PDF",
                "description": "The description is recommended but optional. The image provided is an optional preview",
                "image": "ipfs://bawlkjaklfjoiaefklankflda1313ieiajfl",
                "type": "image/jpeg",
                "localization": [    //per file localization    
                {
                    "uri": "ipfs://wgslkjaklfjoiaefklankflda132zafafewee",
                    "locale": "es"
                },
                {
                    "uri": "ipfs://ghasdgkjaklfjoiaefklankf12554wa6aga43ag",
                    "locale": "jp"
                }
                ]
            }
        }
    ]

The primary NFT (most likely the "Collection" would still have it's localization defined at the root. I've removed all files from the example here.

{
    "name": "Example NFT",
    "creator": "Jane Doe, John Doe",
    "creatorDID": "did:hedera:mainnet:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm;hedera:mainnet:fid=0.0.123",
    "description": "This is an example NFT metadata",
    "format": "none",
    "localization": [
        {
            "uri": "ipfs://bawlkjaklfjoiaefklankflda132zafga3tfa",
            "locale": "es"
        },
        {
            "uri": "ipfs://bawlkjaklfjoiaefklankf12554wa6aga4fda",
            "locale": "jp"
        }
    ]
}

Would this adequately cover all cases simply enough?

[robkainz]

Is there a default locale specified? If only Spanish and Japanese are supported, which one should we display by default if the user reads only English?

[Ashe-Oro]

Per the ERC-721 specs on ethereum.org, the tokenId for each NFT must be:

• uint256
• globally unique

Since tokenId's on Hedera will be in the format 0.0.xxxx (where xxxx is a unique number) will this pose an issue when bridging HTS NFTs to other chains?

[rocketmay]

Yes, Ashe and I briefly talked about this, but this actually seems like an issue. It's out of scope of NFT Metadata and more something to be addressed by the base platform.

Right now the unique identifier for an NFT is the collection ID + the serial number. For example, 0.0.12345-1 would be a globally unique identifier. However it seems awkward/difficult to find a way to represent this in a UINT.

[Ashe-Oro]

the unique uint256 identifier for each NFT, in this example, seems to be 123451...where we drop the 0.0. and append the serial number '1'.

While this would be unique on Hedera, it cannot be provable unique on ETH. I'm actually not sure how ERC721 NFT tokenId's are guaranteed unique, but I imagine they are assigned by the protocol. I'll research and report back.

[Ashe-Oro]

Ok, based on https://ethereum.stackexchange.com/questions/91292/how-to-set-tokenid-in-erc721-openzeppelin

....it seems our internal tokenId for NFTs should simply remove the dash and be used. That would ensure unique tokenId globally. On ETH, each contract assigns the tokenId and it must be unique within the ERC721 contract, but since the native Hedera protocol is assigning tokenId for each NFT, we already have globally unique IDs.

Now...if our NFTs were to be bridged to a different chain (ETH, for example), we'd need to deploy an ERC721 like smart contract (or 1155, i'm not sure) that identifies 0.0.12345-1 as 123451, for example, as the proper tokenId. Other chains will expect an actual ERC721 contract to manage NFTs with their associated actions().

Does this make sense @rocketmay @web3-nomad @Cooper-Kunz @paulatcalaxy

If so, how can tokenId be included in the json metadata? Chicken and Egg problem, no?

[rocketmay]

The issue with removing the dash is that collection ID and serial ID are both arbitrary lengths, so there's no way to distinguish where the break is in a UINT.

(As discussed with you) I think that this is worth exploring in another discussion or another HIP, but for the purposes of getting this HIP out, this topic is strictly out of the scope of NFT Metadata since we wouldn't be storing the token ID/serial # in the metadata.

As a thought, what if there was a SDK function which took the token-serial (0.0.12345-1) and run it through a hash function or similar process which produced a unique UINT, which could then be queried for? I'm sure there are plenty of performance/computational/technical considerations but could be a potential avenue for a solution.

[topshef]

is this a typo, should localization be within the metadata element?

[rocketmay]

Yes, this is a typo.

[robkainz]

HIP 412 states "For resources that are on the world wide web, the standard http and https protocols are acceptable", however it is not acceptable to Apple by default for mobile apps built using Xcode (nor should it be IMHO) and therefore security must be reduced globally for the mobile app to allow any resource to be accessed via http. I would recommend only supporting https for this reason, to prevent potentially mistakenly-coded http calls for sensitive data that should be using secure communication. Can the requirement to support the insecure http protocol be removed? Or must we move forward without a wise safeguard in our mobile financial apps that need to query NFT data that could result in insecure communications elsewhere in the app should a mistake be made? It's like disabling an important firewall rule to make NFT creators happy that don't use secure urls for their metadata or resources.

[gregscullard]

I would tend to agree that https is preferable in almost all cases to http. Maybe the specification should mandate use of https and suggest http should only be used if/when there is no alternative.

[robkainz]

Unfortunately if we need to support http at all, I have to lower the shield. But I suppose a properly implemented countermeasure can be put into place on my part to ensure no Wallawallet developer inadvertently uses http to interact with other 3rd-party services we may depend on in the future.

[rocketmay]

Agreed. Let's slot removing HTTP from the specification in as a change for the next version.

[nigelg71]

I can see this feature would be useful for us at TYMLEZ. As the properties can be any JSON objects, they could be used to provide additional information about the token without the need to retrieve the full VP e.g. for a Carbon Removal Unit (CRU) token, we could provide information about the project and the nature of the removals, or for a Carbon Emissions Token (CET), we could include the green house gas breakdown. This would make it easier to exchange tokens via a marketplace.

Are there any thoughts about how this would be incorporated into the Guardian? I think we would need the guardian to allow us to specify a scheme for the properties, with the values able to be set in the policy before minting. It may be worth considering using the files property to link to the VP instead of navigating from the MEMO field.

Also, what are the likely cost implications for token minting? I assume the cost would increase based on the size of the metadata (much like it does for the MEMO field).

[mattsmithies]

I believe that the HIP412 spec should be stricter in the JSON definition, particularly around the optional array of objects, like files and localization, I would assume that we would require those particular sub-fields.

For example, for localization sub-objects there are uri and locale which I suspect are hard requirements, I might go as far as to say that those are the only properties that are needed.

Furthermore, perhaps it would be a good idea to integrate the validation of the types we are seeking within the JSON schema so we can be stricter for all downstream clients. Using schema.org as a base.

This snippet could be an example of the updated JSON schema for NFT spec conformance.

@rocketmay @gregscullard, is this something you could buy into, would it be useful?

"localization": {
    "type": "object",
    "description": "Array of localized metadata.",
    "properties": {
        "uri": {
            "type": "string",
            "description": "A URI pointing to the localized metadata json file for this locale.",
            "$ref": "https://schema.org/url"
        },
        "locale": {
            "type": "string",
            "description": "A two-letter locale.",
            "$ref": "https://schema.org/addressCountry"
        }
     "required": [ "uri", "locale" ]
     "additionalProperties": false
}             

[rocketmay]

I have no strong opinions on this. Stricter JSON definition to adhere to existing standards sounds like a good plan. Localization is not anywhere near my area of knowledge, so if you say it should be formatted this way and the community agrees then this is a fine suggestion.

[michielmulders]

Hi all, I took some time to review the NFT spec and wanted to add some thoughts/questions. Let me know what you think?

Suggestions

1. Add a preview_image field to quickly load an image rather than loading it from IPFS.
   Motivation: NFT explorers, wallets, and related tooling will first load the image from IPFS, which can take a while if it hasn't been cached on their servers. Therefore, allow creators to upload an optimized version of their NFT hosted at a traditional cloud provider.

2. Include an image_integrity field to add a sha256 of the NFT. This can be useful for the original work but also for the preview_image to ensure the preview_image doesn't get swapped for another image because it's hosted at a cloud provider.

3. Make a stronger specification for defining "rarity properties" of NFT collections. It will make it easier for NFT tooling to calculate rarity scores and display their properties. OpenSea and other chains implement an attributes field with the following values.

• trait_type: string
• value: string (Default: "None")
• max_value: string -> optional (if set, it indicates that you can parse the value field as an integer - created by OpenSea)

Examples can be found here: MetaPlex standard and Algorand ARC0003 standard.

4. Add a field that indicates the token standard used. Standards evolve, so it would be useful to indicate the standard in a separate field. This makes it easier for NFT tooling to detect how to parse the data. e.g. @HIP412

5. Add an external_url field that links to the project's main website/social.

Thoughts

1. What are the possible use cases for indefinitely nested files?

2. Do we support fractionalized NFTs? Like owning a share of a piece of art represented by an NFT? It can be achieved by including two more properties in a standard:

• units: Must be a power of 10: 1, 10, 100, 1000, ...
• decimals: Must be equal to the logarithm in base 10 of the total number of units

e.g. 10 units and 1 decimals equals 10 fractional shares

[hashaxis]

@michielmulders Just a note on point 3 here:

Incase you were unaware, currently many projects are already using 'attributes' to define traits and then 'rarity' is deduced from that based on the percentage of tokens within a TokenID possessing specific properties.

This method is already wide spread across the majority of major projects that are using traits at all.

"attributes": [
        {
            "trait_type": "coolness",
            "value": "50",
            "max-value": "100",
        },
        {
            "trait_type": "colour",
            "value": "red"
        },
    ],

Example NFT from a popular collection:
https://cloudflare-ipfs.com/ipfs/bafyreiemzhyltoedjwlkcvsxlgglwxxrucvs7vmz6fuvuxpgvg752atn4y/metadata.json

[michielmulders]

Draft for an extension HIP for Web3 NFTs has been created here as a PR: #565 - Any feedback is welcome!

[justynspooner]

Great points to raise @michielmulders

There is a recently submitted HIP covering Fractionalised NFTs here.

1. Add a preview_image field to quickly load an image rather than loading it from IPFS

I think @HGraphPunks and @rocketmay cover this well already. I like the idea of optional fields at the file level such as is_default_file and not introducing another top level field.

2. Include an image_integrity field to add a sha256 of the NFT

If files are on IPFS then there's no need for this. If we feel this is useful, then @rocketmay suggestion naming this optional field as sha256_checksum sounds good.

3. Make a stronger specification for defining "rarity properties" of NFT collections

Agree with @hashaxis. The opensea attributes standard works really well for this and is already a widely adopted standard. Would be good to formalise that as a standard way of defining rarity traits rather than forcing the format to be "opensea" to use them as is the case with 412 currently.

4. Add a field that indicates the token standard used

As already mentioned, format is designed for this although I think we could go one step further and use existing standards to formalise this.

Here is an examples of how Microsoft express the format/schema in their JSON files:
https://github.com/Azure/azure-quickstart-templates/blob/master/100-blank-template/metadata.json

{
  "$schema": "https://aka.ms/azure-quickstart-templates-metadata-schema#",
  "type": "QuickStart",
  "itemDisplayName": "Blank Template",
  "description": "A blank template and empty parameters file.",
  "summary": "A blank template and empty parameters file.  Use this template as the framework for your custom deployment.",
  "githubUsername": "bmoore-msft",
  "dateUpdated": "2022-07-05"
}

The $schema is a URL to the schema definition which is published separately: https://aka.ms/azure-quickstart-templates-metadata-schema#

We're half way there with the format field, all we need to do is rename to $schema, publish the schema definition and link to it. The schema could be hosted on IPFS or some publicly accessible schema repository.

An example metadata that says it follows the standard base HIP 412 schema:

{
    "$schema": "ipfs://<CID>/hip412.schema.json",
    "name": "Token name",
    "creator": "Artist name",
    "image": "ipfs://<CID>/image.jpg"
    …etc
}

If someone wants to extend the base schema, then they can just create their own schema or link to an existing one that extends the base hip412.schema.json then put a link to their custom schema in the $schema field. As long as they are using HIP 412 schema as the base schema then they can be guaranteed that the NFTs base data will be displayed correctly.

For example, here is a custom JSON Schema that inherits all the properties of HIP 412 but designed specifically to describe the properties of a game character.

This schema could be published to ipfs://<CID>/hip412GameCharacter.schema.json for example

{
  // Use all the properties of the base HIP 412 schema
  "allOf": [{ "$ref": "ipfs://<CID>/hip412.schema.json" }],
  // Now describe the extended properties we want to add
  "properties": {
    "character_attributes": {
      "type": "object",
      "properties": {
        "strength": { "type": "number" },
        "speed": { "type": "number" },
        "intelligence": { "type": "number" }
      }
    }
  }
}

Then the actual metadata could be:

{
    "$schema": "ipfs://<CID>/hip412GameCharacter.schema.json",
    "name": "Token name",
    "creator": "Artist name",
    …etc
    "character_attributes": {
        "strength": 5,
        "speed": 8,
        "intelligence": 9
    }
}

NFT listing services such as marketplaces/wallets could then decide to just support the base HIP 412 schema or they could start opting in to start supporting other custom schemas that extend HIP 412 that become popular in the community.

The other great thing about having a published schema definition that is referenced in the JSON metadata is that we can write automatic JSON schema validators / parsers in our minting tools and NFT listing services using libraries such as AJV.

[michielmulders]

@justynspooner I really like the schema idea and how you can define your own JSON schema. Instead of naming it $schema (which is the default outside of blockchain), I'm seeing a lot of use for the format property.

[justynspooner]

It doesn't really matter what we name it, the main thing is that it links to a JSON Schema file which describes exactly what the structure is.

[topshef]

Maybe worth casting an eye on the current LG format, and connecting with them.. it seems slightly off from HIP-412
https://gomint.me/explore/NFT/?network=mainnet&tokenId=0.0.1182876-1

[michielmulders]

Thanks for your reply. I see they have defined the following properties which can go into the properties array.

"edition_no": 1,
"total_of_editions": 350,

Not sure why they need width and height for the files array? But other than that, the standard defined in the PR is very similar to what they have done.

[justynspooner]

They also need to make sure the files array is it at the top level if following HIP 412 or define format as opensea in order to have the files array in the properties object like it currently is.

The metadata is also stored centrally at https://api.lgartlab.com/api/v1/meta/e215489f56d6ed3dbac92e26f72a643d so could be changed at any time. Ideally it should be stored on IPFS.

[michielmulders]

I would argue to follow opensea in this case, put it in the properties object. Unless there's a clear reason why not to do it (e.g. follow our base HIP 412 standard)?

[jaycoolslm]

Very late to the party but have just noticed that 'creator / creatorDID' is not referenced in the json schema defnition

https://deploy-preview-412--hedera-hips.netlify.app/hip/hip-412