This ERC defines standard formats for parameterized string keys used in EVM key-value storage. It supports two encodings: a slash/colon form for a single parameter (<key-label>/<key-parameter> or <key-label>:<key-parameter>) and a bracket form for one or more parameters (<key-label>[<key-parameter-1>][<key-parameter-2>]...).
Many EVM-based smart contracts use key-value storage to store metadata where string keys may need to represent multiple instances or variations of the same metadata type. Without a standardized format for parameterized keys, different implementations use inconsistent formats, leading to interoperability issues and parsing difficulties.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
String keys used in EVM key-value storage MAY include parameters to represent variations or instances of a metadata type. When keys include parameters, they MUST follow the format:
or:
Where:
<key-label>: MUST contain only printable ASCII characters except space, the forward slash character (/), the colon character (:), and the left bracket character ([). Concretely, allowed code points are 0x21-0x2E, 0x30-0x39, 0x3B-0x5A, and 0x5C-0x7E (letters, digits, and common punctuation), explicitly excluding control characters (0x00-0x1F), space (0x20), the slash character (0x2F), the colon character (0x3A), the left bracket (0x5B), and DEL (0x7F). The key-label identifies the type or category of metadata.<key-parameter> in slash/colon form: MAY be any UTF-8 encoded string except one that begins with a space. The character immediately after / or : MUST NOT be space; parameters may contain spaces elsewhere (e.g., key/hello world). For parameter data that must start with a space, use a quoted encoding where the space is the first character inside the quote (e.g., quote/' space is the first character in the quote'). Parsing uses the first occurrence of / or : as the separator; all subsequent characters belong to the single parameter.<key-parameter-n> in bracket form: each parameter MAY be any UTF-8 encoded string except ] (which is reserved as the closing delimiter).Examples:
"registration/1" - ASCII key-label with numeric parameter"registration:1" - Same as above, using colon separator"user/alice" - ASCII key-label with ASCII parameter"website/http://website.com" - Slash/colon form where parameter includes additional /"name/María" - ASCII key-label with UTF-8 parameter (Spanish)"description/说明" - ASCII key-label with UTF-8 parameter (Chinese)"title/タイトル" - ASCII key-label with UTF-8 parameter (Japanese)"label/Étiquette" - ASCII key-label with UTF-8 parameter (French with accent)"user[alice]" - Bracket form with one parameter"resource[chain][1][token][42]" - Bracket form with multiple parameters"%gain/50" - Key-label with special character (percent)"$price/100" - Key-label with special character (dollar sign)"#tag/featured" - Key-label with special character (hash)"quote/' space is the first character in the quote'" - Parameter data starting with space: use quotes; space is first character insideInvalid formats:
"registration-1" (hyphen separator)"registration1" (no separator)"key/ value" (space immediately after separator)"key label/value" (space in key-label)"key[label" (missing closing bracket)"key[]tail" (trailing text after bracket form parameter list)These formats provide a clean, consistent way to represent parameterized keys while maintaining readability and compatibility with parsers.
For string keys used in EVM key-value storage (e.g., mapping(string => bytes) in Solidity, hash maps in Vyper, or equivalent structures in other EVM-compatible languages):
<key-label> MUST contain only printable ASCII characters (0x21-0x7E), excluding spaces, /, :, and [. This excludes control characters, space, /, :, [, and DEL.<key-label>/<key-parameter> or <key-label>:<key-parameter> (exactly one parameter)<key-label>[<key-parameter-1>][<key-parameter-2>]... (one or more parameters)/ or : as the separator; all remaining characters belong to the single parameter. The character immediately after the separator MUST NOT be space.[, then reads one or more bracketed parameters in order. No trailing characters are allowed after the final ].The slash (/) and colon (:) separators were chosen for the single-parameter form because:
].key/hello world) remain valid.The bracket form was added because:
Reserving /, :, and [ from <key-label> keeps both encodings unambiguous.
This ERC is fully backwards compatible. Existing implementations that do not use parameterized keys are unaffected. Implementations using non-standard parameter formats may continue to work but are encouraged to migrate to this standard format for better interoperability.
"name" - Simple key without parameters"registration/1" - Key with numeric parameter (slash)"registration:1" - Key with numeric parameter (colon)"registration/2" - Key with numeric parameter"user/alice" - Key with ASCII string parameter (slash)"user:alice" - Key with ASCII string parameter (colon)"session/abc123" - Key with alphanumeric parameter"website/http://website.com" - Slash/colon form parameter containing //"name/María" - Key with UTF-8 parameter (Spanish)"description/说明" - Key with UTF-8 parameter (Chinese)"title/タイトル" - Key with UTF-8 parameter (Japanese)"label/Étiquette" - Key with UTF-8 parameter (French with accent)"key/value:with:colons" - Key with parameter containing colons"key/one1 two2 three3" - Key whose single slash/colon-form parameter can be interpreted by an application as a list"key/value/with/slashes" - Key with parameter containing additional / (parsed at first /)"excerpt/Dan said \"hi: how are you?\"" - Key with quoted speech containing : "quote/' space is the first character in the quote'" - Parameter starting with space: use quotes; space is first character inside"user[alice]" - Bracket form with one parameter"resource[chain][1][token][42]" - Bracket form with multiple parameters"title[说明][日本語]" - Bracket form with UTF-8 parameters"registration-1" - Uses hyphen instead of slash/colon"registration1" - No separator"key/ value" - Space immediately after separator (parameter must not start with space)"key label/value" - Space in key-label (key-label must be ASCII with no spaces)"key[label" - Unclosed bracket parameter"key[]tail" - Trailing non-bracket content in bracket form"key/param[extra]" - Mixed slash and bracket formatsThe following is a Solidity reference implementation. This standard applies to all EVM-compatible languages (Solidity, Vyper, etc.) that support string-keyed storage.
<key-label> against the allowed ASCII range and reject labels containing spaces, /, :, or [ to avoid ambiguous or non-standard keys. For slash/colon form, clients SHOULD reject keys where the character immediately after the separator is space.], or mixed slash and bracket delimiters) to prevent parser divergence.Copyright and related rights waived via CC0.