Skip to main content

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 nametypeValueDescription
typestring"Basic NFT"Constant name for this type
namestringName of the object
descriptionstringDescription of the object
previewobjectObject preview
preview.sourcestringLink to object. Contains protocol and data source. Delimiter is :
preview.mimetypestringMime type of object
filesarrayArray of objects.
file.sourcestringLink to object. Contains protocol and data source. Delimiter is :
file.mimetypestringMime type of object
external_urlstringURL to website

Example

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

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 nameTypeDescriptionValue
typestringNFT typemetaverse.region
versionstringModel version (for future compatibility)1.0
metaobjectRegion metadata
regionsarray<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 nameTypeDescriptionExample value
server.typestringType of metaverse that has issued the NFT tokenminecraft
server.urluri (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.pubkeystringPublic key issued by the compatible NFT adapter used to sign the NFT content data
signaturestringHEX 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.

TypeDescriptionReference model
cuboidBox-shaped regionLink
cylinderCylinder-shaped regionLink
sphereSpheric-shaped regionLink
polygon2d2D-polygonal-shaped regionLink

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 nameTypeDescriptionValue
shapestringType of shapecuboid
params.position1xyzFirst vertex of the cuboid
params.position2xyzSecond 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 nameTypeDescriptionValue
shapestringType of shapecylinder
params.centerxyzBasic central point of the cylinder
params.radiusstringRadius of the cylinder (number in string format for maximum compatibility)
params.heightstringHeight 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 nameTypeDescriptionValue
shapestringType of shapesphere
params.centerxyzBasic central point of the sphere
params.radiusstringRadius 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 nameTypeDescriptionValue
shapestringType of shapepolygon2d
params.pointslist<xyz>Coordinates of polygon vetices
params.heightstringHeight 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 nameTypeDescriptionDefault value
xstringX coordinate0
ystringY coordinate0
zstringZ coordinate0

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