Skip to content

Commit e6689b3

Browse files
kuan121kuan121
authored
Introduce compact keys for JSON metadata fields to reduce size of JSON metadata object (#390)
1 parent 8d806bd commit e6689b3

File tree

1 file changed

+54
-36
lines changed
  • XLS-0089-multi-purpose-token-metadata-schema

1 file changed

+54
-36
lines changed

‎XLS-0089-multi-purpose-token-metadata-schema/README.md‎

Lines changed: 54 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@
22
xls: 89
33
title: Multi-Purpose Token Metadata Schema
44
description: Standardized metadata schema for Multi-Purpose Tokens to improve discoverability, comparability, and interoperability
5-
author: Shawn Xie <shawnxie@ripple.com>, Greg Tsipenyuk <gtsipenyuk@ripple.com>, Shashwat Mittal <smittal@ripple.com>, Julian Berridi <jberridi@ripple.com>
5+
author: Shawn Xie <shawnxie@ripple.com>, Greg Tsipenyuk <gtsipenyuk@ripple.com>, Shashwat Mittal <smittal@ripple.com>, Julian Berridi <jberridi@ripple.com>, Kuan Lin <klin@ripple.com>
66
discussion-from: https://github.com/XRPLF/XRPL-Standards/discussions/264
7-
status: Draft
7+
status: Final
88
category: Ecosystem
99
requires: XLS-33
1010
created: 2025-01-27
11+
updated: 2025-10-29
1112
</pre>
1213

1314
---
@@ -38,17 +39,17 @@ MPTs include a 1024-byte field for arbitrary metadata. The metadata field is par
3839

3940
## 2. Base Metadata Schema
4041

41-
| Field | Description | Example | Allowed Values | Type | Required? |
42-
| ----------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------- | --------- |
43-
| `ticker` | Ticker symbol used to represent the token | EXMPL | Uppercase letters (A-Z) and digits (0-9) only. Max 6 characters recommended | string | ✔️ |
44-
| `name` | Display name of the token | Example Token | Any UTF-8 string | string | ✔️ |
45-
| `desc` | Short description of the token | A sample token used for demonstration | Any UTF-8 string | string | |
46-
| `icon` | URL to the token icon | https://example.org/token-icon.png | HTTPS URL that links to an image | string | ✔️ |
47-
| `asset_class` | Top-level classification of token purpose | rwa | rwa, memes, wrapped, gaming, defi, other | string | ✔️ |
48-
| `asset_subclass` | Optional subcategory, required if `asset_class = rwa` | See 2.2 _asset_subclass_ | See 2.2 _asset_subclass_ | string | |
49-
| `issuer_name` | The name of the issuer account | Example Issuer | Any UTF-8 string | string | ✔️ |
50-
| `urls` | List of related URLs (site, dashboard, social media, etc.) | See 2.3 _urls_ | See 2.3 _urls_ | array | |
51-
| `additional_info` | Freeform field for key token details like interest rate, maturity date, term, or other relevant info | `{ "interest_rate": "4.75%", "maturity_date": "2030-06-30", "term": "10Y", "issuer_type": "government" }` | Any valid JSON object or UTF-8 string | JSON object or string | |
42+
| Field | Key | Description | Example | Allowed Values | Type | Required? |
43+
| ----------------- | ---- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------- | --------- |
44+
| `ticker` | `t` | Ticker symbol used to represent the token | EXMPL | Uppercase letters (A-Z) and digits (0-9) only. Max 6 chars | string | ✔️ |
45+
| `name` | `n` | Display name of the token | Example Token | Any UTF-8 string | string | ✔️ |
46+
| `desc` | `d` | Short description of the token | A sample token used for demonstration | Any UTF-8 string | string | |
47+
| `icon` | `i` | URI to the token icon | example.org/token-icon, ipfs://token-icon.png | `hostname/path` (HTTPS assumed) or full URI for other protocols | string | ✔️ |
48+
| `asset_class` | `ac` | Top-level classification of token purpose | rwa | rwa, memes, wrapped, gaming, defi, other | string | ✔️ |
49+
| `asset_subclass` | `as` | Optional subcategory, required if `asset_class = rwa` | See 2.2 _asset_subclass_ | See 2.2 _asset_subclass_ | string | |
50+
| `issuer_name` | `in` | The name of the issuer account | Example Issuer | Any UTF-8 string | string | ✔️ |
51+
| `uris` | `us` | List of related URIs (site, dashboard, social media, etc.) | See 2.3 _uris_ | See 2.3 _uris_ | array | |
52+
| `additional_info` | `ai` | Freeform field for key token details like interest rate, maturity date, term, or other relevant info | {"interest_rate": "4.75%", "maturity_date": "2030-06-30", "term": "10Y", "issuer_type": "government"} | Any valid JSON object or UTF-8 string | JSON object or string | |
5253

5354
---
5455

@@ -67,7 +68,7 @@ MPTs include a 1024-byte field for arbitrary metadata. The metadata field is par
6768

6869
### 2.2 asset_subclass
6970

70-
| asset_type | Description |
71+
| Asset Type | Description |
7172
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
7273
| `stablecoin` | Tokens pegged to a stable value (typically fiat currencies like USD), backed by reserves such as cash, treasuries, or crypto collateral |
7374
| `commodity` | Tokens representing physical commodities like gold, silver, or oil, often redeemable or legally linked to off-chain reserves |
@@ -79,40 +80,57 @@ MPTs include a 1024-byte field for arbitrary metadata. The metadata field is par
7980

8081
---
8182

82-
### 2.3 urls
83+
### 2.3 uris
8384

84-
| Field | Description | Example | Allowed Values | Required |
85-
| ------- | ------------------------------------- | ----------------------------- | -------------------------------- | -------- |
86-
| `url` | The full link to the related resource | https://exampleyield.co/tbill | A valid HTTPS URL | ✔️ |
87-
| `type` | The category of the link | website | website, social, document, other | ✔️ |
88-
| `title` | A human-readable label for the link | Product Page | Any UTF-8 string | ✔️ |
85+
| Field | Key | Description | Example | Allowed Values | Required |
86+
| ---------- | --- | ----------------------------------- | ---------------------------------------- | --------------------------------------------------------------- | -------- |
87+
| `uri` | `u` | URI to the related resource | exampleyield.com/tbill, ipfs://abc123... | `hostname/path` (HTTPS assumed) or full URI for other protocols | ✔️ |
88+
| `category` | `c` | The category of the link | website | website, social, docs, other | ✔️ |
89+
| `title` | `t` | A human-readable label for the link | Product Page | Any UTF-8 string | ✔️ |
8990

9091
---
9192

92-
### JSON Metadata example
93+
## 3. Field Name Format
94+
95+
The metadata schema supports JSON objects with both long field names (e.g., `ticker`, `name`, `desc`) and short key names (e.g., `t`, `n`, `d`). However, it is recommended to use short key names to reduce storage requirements of the ledger. The MPT metadata field has a 1024-byte limit, and using compact keys can reduce the metadata size and allow more information to be stored within the available space.
96+
97+
### 3.1 Client Library Support
98+
99+
XRPL client libraries will provide utility functions to facilitate working with metadata in both formats:
100+
101+
- **Encoding utility**: Converts JSON metadata to hexadecimal format for on-ledger storage. If long field names are provided, the utility will automatically shorten them to their compact key equivalents before encoding.
102+
- **Decoding utility**: Converts hexadecimal metadata from the ledger back to JSON format. The utility will expand short keys back to their full field names for improved readability.
103+
104+
This approach provides flexibility for developers while ensuring efficient on-ledger storage. Developers can work with human-readable long field names in their applications, and the client libraries will handle the conversion to compact format automatically.
105+
106+
---
107+
108+
### 3.2 JSON Metadata Example
109+
110+
The example below demonstrates the recommended format using short key names. Note that the **Key** values from the tables in Section 2 are used as the property names in the JSON metadata object.
93111

94112
```json
95113
{
96-
"ticker": "TBILL",
97-
"name": "T-Bill Yield Token",
98-
"desc": "A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.",
99-
"icon": "https://example.org/tbill-icon.png",
100-
"asset_class": "rwa",
101-
"asset_subclass": "treasury",
102-
"issuer_name": "Example Yield Co.",
103-
"urls": [
114+
"t": "TBILL",
115+
"n": "T-Bill Yield Token",
116+
"d": "A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.",
117+
"i": "example.org/tbill-icon.png",
118+
"ac": "rwa",
119+
"as": "treasury",
120+
"in": "Example Yield Co.",
121+
"us": [
104122
{
105-
"url": "https://exampleyield.co/tbill",
106-
"type": "website",
107-
"title": "Product Page"
123+
"u": "exampleyield.co/tbill",
124+
"c": "website",
125+
"t": "Product Page"
108126
},
109127
{
110-
"url": "https://exampleyield.co/docs",
111-
"type": "docs",
112-
"title": "Yield Token Docs"
128+
"u": "exampleyield.co/docs",
129+
"c": "docs",
130+
"t": "Yield Token Docs"
113131
}
114132
],
115-
"additional_info": {
133+
"ai": {
116134
"interest_rate": "5.00%",
117135
"interest_type": "variable",
118136
"yield_source": "U.S. Treasury Bills",

0 commit comments

Comments
 (0)