Specifications for Hedera-based NFTs
Features and specifications described in this documentation are in an early stage. Any distributions or codebases that can be deployed are at an early state and is meant for feedback or testing only. Please avoid sharing this page with end-users looking for a stable release. Contents are subject to change without notice.
Overview
This page documents the specifications set to standardize and allow hashport to seamlessly integrate third-party NFT collections onto the platform. The intent is to provide a flexible specification which will serve as the base format for all NFT collections. Collectiions that follow the specifications outlined below will be eligible for hashport to integrate and enable porting across to supported networks.
Specification
Below is the human-readable schema, which references the OpenSea metadata standards to ensure compatibility between the Hedera and EVM networks.
{
"name": "token name - REQUIRED",
"creator": "creator - OPTIONAL",
"creatorDID": "DID URI - OPTIONAL",
"description": "human readable description of the asset - REQUIRED",
"image": "cid or path to the NFT's image file (see below) - REQUIRED",
"type": "mime type (e.g. image/jpeg) - REQUIRED",
"format": "format designation (e.g. opensea) - OPTIONAL",
"external_url": "external url - OPTIONAL",
"background_color": "hexadecimal color without a pre-pended # - OPTIONAL",
"animation_url": "cid or path to the NFT's multi-media attachment - OPTIONAL",
"youtube_url": "a URL to a YouTube video - OPTIONAL",
"attributes": [ // https://docs.opensea.io/docs/metadata-standards#attributes - OPTIONAL
{
"trait_type": "trait name",
"value": "trait value"
},
… arbitrary, multiple …
],
"properties": { // OPTIONAL
"files": [ // object array that contains uri, type and metadata - OPTIONAL
{
"uri": "uri to file",
"type": "mime type",
"metadata": "uri to metadata"
},
… multiple …
],
… arbitrary, multiple …
},
"localization": [ // OPTIONAL
{
"uri": "uri to file",
"locale": "uri to metadata"
},
],
// additional fields defined per the format
}
name, description & image
The name, description, and image are three basic fields in the ERC721 NFT standards. In the case of hashport, these are required fields.
name
The name is the token name, and should be formatted as a string.
description
The description is a human readable description of the item formatted as a string or in Markdown format.
image
For NFTs with images, the content identifier (CID) should be in the correct URI format resolving to one of these services:
The image is a required field on hashport for cross-network compatibility. This requirement might change at a later time depending on the use-case of the proposed NFT to be added to the hashport ecosystem. If the NFT contains one or more CIDs to non-image files (e.g. a video or a directory), defined within the files array under the properties object, a meaningful and contextual image-type thumbnail is still required.
creator
The creator should be formatted as a string. For multiple creators, attribution should be formatted as comma-separated values into a single string.
creatorDID
The creatorDID is an optional field to carry a decentralised identifier for the creator. This allows a creator to lay claim to a creation even if the current ownership is different. If used, the creatorDID should resolve to a DID document with a public key, to which a signature can be signed to prove ownership.
References: https://github.com/hashgraph/did-method/blob/master/did-method-specification.md https://w3c.github.io/did-core/
type
The MIME type of the image file formatted as a string. See MIME format for more information. Since image is a required property, type is also required. Including the MIME type allows hashport to handle the file and simplifies the code required to display the data.
format
The format property allows NFT creators, communities, and platforms to explicitly define the schema that they are using, which simplifies the implementation for ecosystems such as hashport to integrate. If the format is not defined, it is assumed to be "opensea", which is what hashport currently supports, described above and here.
properties
The properties are a collection of arbitrary fields and provides a common place for information to be stored about the token. The files attribute under properties is an array of objects described below. It follows the "opensea" standard of placing files under the properties field for cross-compatibility with other NFTs. Other than files, hashport will try to support those properties that are defined and standardised. Important information should not be stored under properties as they may not show up within hashport and other communities or platforms.
files
files is an optional array of objects under properties. Each file object may contain three properties: uri, type, and metadata.
| Property | Description | Required? |
|---|---|---|
uri | A URI to the file. See URI format for more information. | yes |
type | The MIME type of the file pointed to by the URI. See MIME type for more information. | yes |
metadata | A URI to the metadata associated to the file defined by uri above. The metadata json file should still be in the same "opensea" format described in this document. | no |
localization
localization is an optional array of localization objects, which allow NFTs to present data uniformly across multiple languages. Each localization object should contain two required properties: uri and locale.
| Property | Description | Required? |
|---|---|---|
uri | A URI to the localized metadata in the specified locale. The NFT creator must ensure that all fields, properties, and attributes are duplicated across the localized and base metadata. | yes |
locale | Specified locale, described as a 2-character string defined by ISO 639-1:2002. A list of ISO 639-1:2002 codes can be found here: https://www.loc.gov/standards/iso639-2/php/code_list.php. | yes |
URI format
URIs must follow the following format: protocol://resource_location
For resources that are on IPFS, the protocol must be ipfs:// and the resource location must be the cid of the file.
ipfs://QmXbckisH6hHqRcq2GDJ5ogktTyoHxpD5AaFBMxnDT2VJU
For resources that are on HFS, the protocol must be hedera:// and the resource location must be an asset reference in the format of realm, shard, and topic ID separated with a period (.). The format of the realm, shared, and file ID are unsigned integer in decimal representation. An optional checksum may be added after the file identifier delimited by a dash (-).
MIME format
MIME formats must follow the following: type/subtype
MIME types should be in lowercase. 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. For directories, please use text/directory.
Example Schema
This is an example of an opensea-compatible metadata that includes the important collectible NFT field "attributes" which is used for rarity.
{
"name": "DanFan",
"creator": "DanFan",
"description": "This is an example of an NFT metadata",
"image": "ipfs://QmXbckisH6hHqRcq2GDJ5ogktTyoHxpD5AaFBMxnDT2VJU",
"type": "image/jpg",
"format": "opensea",
"attributes": [
{
"trait_type": "str",
"value": "15"
},
{
"trait_type": "con",
"value": "16"
},
{
"trait_type": "int",
"value": "10"
},
{
"trait_type": "dex",
"value": "18"
},
{
"trait_type": "chr",
"value": "18"
},
],
}