ERC: Token Metadata JSON Schema

ERCs
1

This proposal specifies the JSON document that tokenURI returns in ERC-721 and ERC-6909 and that uri returns in ERC-1155.

Most deployed tokens already use this format, but only part of it was ever specified. ERC-721 and ERC-1155 define name, description and image. Everything else wallets and marketplaces show (animation_url, attributes and its display_type values, external_url, background_color) comes from a page OpenSea published in 2018. Clients fill the gaps differently, so the same token renders differently from one app to the next.

Draft: erc-draft_token_metadata_json.md (ethereum/ERCs#2163)

The draft covers:

  • Every field and its type, every display_type value in use, and what clients do with values that don’t match, such as booleans, quoted numbers and dates in milliseconds.
  • The URI schemes clients must resolve (https, ipfs, ar, data), the ones they may resolve (ipns, and web3 from ERC-4804), and the ones they must never resolve.
  • Fetching rules: ipfs:// URIs instead of gateway URLs, sandboxing HTML in animation_url, and keeping server-side fetches away from private addresses.
  • How later proposals add fields without breaking older clients.

The Rationale cites an October 2026 survey of 708 Ethereum and Base contracts. 113 of the 204 IPFS gateway URLs in it failed when fetched as written, and more contracts use text as a display_type than string. The draft accepts both.

Questions we’d like input on:

  1. Data URIs. The draft recommends base64, because fetch drops everything after # in an unencoded data URL, which breaks JSON that contains a #. Clients must accept base64 and should accept unencoded JSON. Is that the right line?
  2. Dates. Clients may read a date value of 1000000000000 or more as milliseconds. A lower cutoff would misread 253402300800 (the year 10000), which some contracts use to mean “never expires”.
  3. Onchain values. The author of ERC-8048 has proposed an onchain: URI scheme that points a field at a value stored under ERC-8048 or ERC-8049, such as "image": "onchain:image/png". Once it has a number, this draft would list it as an optional scheme next to web3.

A companion extension adds a model_3d field that lists a token’s 3D files by format (glTF, USDZ, VRM, STL and others). We’ll post it separately once this proposal has a number.

Feedback from wallet, marketplace and indexer teams is the most useful: tell us anything your client does today that this draft would break.

Authors: Devin Finzer, Alex Atallah and Ryan Ghods