Non-Fungible Token JSON Metadata (TIP-4.2)

Requires: TIP-6.1

Abstract

Token-specific metadata is stored as a string in smart contract. To facilitate an off-chain working with metadata, it is JSON object. The below metadata structure allows the marketplaces to read and display the details about the assets which your NFTs represent.

This standard provides optional JSON fields and contract interface.

Motivation

A standard fields facilitate displaying of NFT data for: wallets, explorers, marketplaces, etc.

Specification

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119

JSON metadata

Return the metadata as JSON

Every TIP4.2 compliant contract must implement the TIP4_2JSON_Metadata interface and TIP-6.1 interfaces

pragma ton-solidity >= 0.58.0;

interface TIP4_2JSON_Metadata {

    /// @notice metadata in JSON format
    /// @return json The JSON string with metadata
    function getJson() external view responsible returns (string json);

}

NOTE The TIP-6.1 identifier for this interface is 0x24D7D5F5.

TIP4_2JSON_Metadata.getJson()

function getJson() external view responsible returns (string json);

• json (string) - The JSON string with metadata

The function return metadata as a JSON string.

Empty JSON metadata

Empty JSON metadata is represented as a blank JSON object or an empty string.

{}

JSON metadata type

Not empty JSON must have "type" field

{"type":"string"}

Application that read JSON metadata use "type" field for parsing standard or custom JSON fields.

JSON metadata type: "Basic NFT"

The Basic NFT use for links to files stores in web. JSON fields contain information about item, files and preview info.

The Basic NFT describes fields that must be in JSON

Field name	type	Value	Description
type	string	"Basic NFT"	Constant name for this type
name	string		Name of the object
description	string		Description of the object
preview	object		Object preview
preview.source	string		Link to object. Contains protocol and data source. Delimiter is :
preview.mimetype	string		Mime type of object
files	array		Array of objects.
file.source	string		Link to object. Contains protocol and data source. Delimiter is :
file.mimetype	string		Mime type of object
external_url	string		URL to website

Example

{
    "type": "Basic NFT",
    "name": "Sample Name",
    "description": "Hello world!",
    "preview": {
        "source": "https://nft.venom/images/Backgrounds/Main/main-hero.png",
        "mimetype": "image/png"
    },
    "files": [
        {
            "source": "https://nft.venom/images/Backgrounds/Main/main-hero.png",
            "mimetype": "image/png"
        }
    ],
    "external_url": "https://nft.venom"
}

You can extend Basic NFT type for your custom fields.

JSON metadata type: metaverse.region

The metaverse.region JSON object stores the unique reference to a specific region (bundle of regions) inside a metaverse.

Field name	Type	Description	Value
type	string	NFT type	metaverse.region
version	string	Model version (for future compatibility)	1.0
meta	object	Region metadata
regions	array<object>	Region parameters (multi-component regions allowed)

Example

{
    "type": "metaverse.region",
    "version": "1.0",
    "meta": {
        "server": {
            "type": "minecraft",
            "url": "http://10.10.10.10:25565",
            "pubkey": "c843d424bba89625d64fb592975180023e46b499388856fa832e287484adc4aa"
        },
        "signature": "cc9d3377f78d33a3d2d412d173f2b6e9e6dd06af19749d95032ea7c78eb07d873ddfe0b241a190900422732207dbbdc987b1bbcfd74d56404f0ab0d65d4f930e"
    },
    "regions": [
        {
            "shape": "cuboid",
            "params": {
                "position1": {
                    "x": "0",
                    "y": "-50",
                    "z": "0"
                },
                "position2": {
                    "x": "16",
                    "y": "200",
                    "z": "16"
                }
            }
        }
    ]
}

Region metadata

This section must contain at least a minimum of the required information about the metaverse server where the region is located.

Field name	Type	Description	Example value
server.type	string	Type of metaverse that has issued the NFT token	minecraft
server.url	uri (optional)	Address where the server is located. Typically, the URL, from which the server actual metadata like name, description, etc. can be extracted.	10.10.10.10:25565
server.pubkey	string	Public key issued by the compatible NFT adapter used to sign the NFT content data
signature	string	HEX representation of the signature, generated using ed25519 algorithm based on the contents of regions array content (without the object name) and server private key. Before generation, the base JSON array must be compacted (i.e. all the whitespace and line breaks must be removed). In the example above, it will look as follows: [{"shape":"cuboid","params":{"position1":{"x":"0","y":"-50","z":"0"},"position2":{"x":"16","y":"200","z":"16"}}}]

Region shape types

The reference implementation is inspired by Minecraft's Worldedit primitive region models.

Type	Description	Reference model
cuboid	Box-shaped region	Link
cylinder	Cylinder-shaped region	Link
sphere	Spheric-shaped region	Link
polygon2d	2D-polygonal-shaped region	Link

Cuboid

Cuboid is the simplest and the most popular shape of a region typically used in most metaverses.

It is defined by X, Y and Z coordinates of two points in the space (the order is insignificant), one of which is considered as the start (bottom, minimum) and the other one as the end (top, maximum) of the region.

Cuboid object specification

Field name	Type	Description	Value
shape	string	Type of shape	cuboid
params.position1	xyz	First vertex of the cuboid
params.position2	xyz	Second vertex of the cuboid

Example usage

{
    "type": "metaverse.region",
    "version": "1.0",
    "meta": {},
    "regions": [
        {
            "shape": "cuboid",
            "params": {
                "position1": {
                    "x": "0",
                    "y": "-50",
                    "z": "0"
                },
                "position2": {
                    "x": "16",
                    "y": "200",
                    "z": "16"
                }
            }
        }
    ]
}

Cylinder

Cylinders are commonly used in central areas of large objects (lize plazas, fountains, etc).

They are defined by coordinates of basic central point, radius, and height.

Cylinder object specification

Field name	Type	Description	Value
shape	string	Type of shape	cylinder
params.center	xyz	Basic central point of the cylinder
params.radius	string	Radius of the cylinder (number in string format for maximum compatibility)
params.height	string	Height of the cylinder (number in string format for maximum compatibility) For the avoidance of doubt, the Y coordinate of the opposite cylinder's side is calculated as Y_basic + height

Example usage

{
    "type": "metaverse.region",
    "version": "1.0",
    "meta": {},
    "regions": [
        {
            "shape": "cylinder",
            "params": {
                "center": {
                    "x": "0",
                    "y": "-50",
                    "z": "0"
                },
                "radius": "16",
                "height": "100"
            }
        }
    ]
}

Sphere

Spheres are typically used as parts of complex objects like sculptures, buildings, etc.

Sphere is described by coordinates of central point and radius.

Spherical object specification

Field name	Type	Description	Value
shape	string	Type of shape	sphere
params.center	xyz	Basic central point of the sphere
params.radius	string	Radius of the sphere (number in string format for maximum compatibility)

Example usage

{
    "type": "metaverse.region",
    "version": "1.0",
    "meta": {},
    "regions": [
        {
            "shape": "sphere",
            "params": {
                "center": {
                    "x": "0",
                    "y": "-50",
                    "z": "0"
                },
                "radius": "16"
            }
        }
    ]
}

2D polygon

Polygons can represent an arbitrary set of vertices.

2D polygons assume that all vertices lay on the same plane. The whole object can be extended in height.

2D polygon object specification

Field name	Type	Description	Value
shape	string	Type of shape	polygon2d
params.points	list<xyz>	Coordinates of polygon vetices
params.height	string	Height of the object (number in string format for maximum compatibility). For the avoidance of doubt, the Y coordinate of the opposite object's side is calculated as Y_basic + height, where Y_basic is the Y coordinate of the first vertex in the array above.

Shared models

XYZ

Field name	Type	Description	Default value
x	string	X coordinate	0
y	string	Y coordinate	0
z	string	Z coordinate	0

Standard conventions

• Numbers and coordinates interpretation depends on the specific metaverse defined in the meta section of the NFT. For this standard purpose, the following convention is applied:
  • X axis is a horizontal one pointing East;
  • Y axis is a vertical one pointing up;
  • Z is the orthogonal axis pointing south;
    
    
• Numbers are stored as strings to ensure maximum compatibility;
• Numbers must not use scientific notation.

How to add the new JSON metadata type?

For added new metadata type of TIP-4.2

• Create product that use new JSON type.
• Send PR for change the docs.
• Explain why it will be in Standard.

References

info

The original TIP-4.2 standard was developed and maintained by the Everscale network community.

• Ethereum EIP-721
• Solana v1.2.0
• TON NFT, TON DATA
• Tezos TZIP12
• BNS BEP721