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://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 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.