mercatr — Off-Chain Parcel Metadata Schema

Schema Version: v1.0.0 Protocol Version: v1.0.0 Status: Canonical Specification

1. Introduction

1.1 Purpose

This document specifies the canonical JSON schema for off-chain parcel metadata in the mercatr protocol. The schema defines the structure and constraints of the JSON object that a parcel owner may publish to a content-addressable storage network and reference from the on-chain cadastre via a URI string.

The schema is intentionally permissive: only the schema_version field is required. All other fields are optional. This design allows metadata to be incrementally enriched over time without invalidating existing records, and permits different hierarchy levels to carry different amounts of information without schema violations.

1.2 Relationship to On-Chain State

The on-chain mercatr::metadata module stores a single URI string (the cid field of MetadataState) per parcel. In the app, owners edit this through the Name & Visual Layer → Saving Changes interface. That URI points to a JSON document conforming to this schema. The on-chain layer performs no validation of the JSON content; it stores the URI as-given and records the Sui epoch at which it was last set.

On-chain enforcement

The protocol enforces exactly one constraint: the URI string must not exceed 128 bytes (MAX_CID_LENGTH in mercatr::metadata). Everything else in this document — URI schemes, JSON field names, field size limits, SVG safety rules — is an off-chain consumer convention. The chain does not validate, parse, or reject any of it.

Off-chain consumers are responsible for fetching the URI, parsing the JSON, and validating it against this schema. The on-chain record provides only a freshness signal (updated_epoch) and an ownership-gated write path.

The SVG field, when present, is itself a URI pointing to a separate blob. The SVG content is not embedded in the metadata JSON.

1.3 Notation

Throughout this document:

Required denotes a field that must be present for the document to be considered valid.
Optional denotes a field whose absence does not constitute a schema violation.
Constraints are expressed as mathematical inequalities where applicable. For a string field of length $n$ : $n \leq N_{\max}$ means the UTF-8 character count must not exceed $N_{\max}$ .
JSON types follow RFC 8259: string, number, boolean, array, object, null.

2. Schema Definition

2.1 Top-Level Fields

A conforming metadata document is a JSON object with the following top-level fields:

Field	Type	Required	Constraint
`schema_version`	`string`	Yes	Semantic version string
`name`	`string`	No	$n \leq 256$ characters
`description`	`string`	No	$n \leq 10{,}000$ characters
`svg`	`string`	No	URI; see §3.2
`properties`	`object`	No	Arbitrary key-value pairs

All constraints in this table are off-chain consumer conventions. The protocol does not enforce field presence, field types, or character limits on the JSON content.

2.2 Field Reference

schema_version (string, required) — The version of this schema specification that the document conforms to. Consumers use this field to select the appropriate parsing and validation logic. The current value for documents conforming to this specification is "1.0.0". The value must be a valid semantic version string of the form MAJOR.MINOR.PATCH.

name (string, optional) — A human-readable display name for the parcel. Intended for use in map labels, search results, and UI tooltips. The value must not exceed 256 UTF-8 characters. No markup is interpreted; the value is treated as plain text.

description (string, optional) — A longer textual description of the parcel. CommonMark Markdown is accepted; raw HTML is not permitted. The value must not exceed 10,000 UTF-8 characters. Consumers may render the Markdown or display it as plain text at their discretion.

svg (string, optional) — A URI referencing an SVG image that visually represents the parcel. The SVG content is stored as a separate blob; this field contains only the URI. Accepted URI schemes are walrus://, ipfs://, and https://. See §3.1 for URI format rules and §3.2 for SVG safety requirements that apply to the referenced content.

properties (object, optional) — An extensible map of arbitrary key-value pairs for application-specific or future protocol data. Keys are strings; values may be any JSON type. This field is the designated extension point for data that does not fit the standard fields above. Consumers must ignore unknown keys within properties rather than rejecting the document.

3. Validation Rules

3.1 URI Formats

Off-chain consumer convention. The protocol stores the URI as an opaque string and does not validate its scheme or structure.

The svg field, when present, must be a URI conforming to one of the following schemes:

walrus://<blobId> — A Walrus decentralized storage blob. The blobId is the base64url-encoded blob identifier assigned by the Walrus network at upload time.
ipfs://<cid> — An IPFS content identifier. The CID may be v0 (base58 Qm...) or v1 (multibase-encoded).
https://<host>/<path> — A standard HTTPS URL. HTTP (non-TLS) URLs are not accepted.

URIs that do not match one of these three schemes must be rejected by conforming consumers. Relative URIs are not permitted.

3.2 SVG Safety

The SVG content referenced by the svg URI is subject to the following safety requirements. These constraints apply to the SVG document itself, not to the metadata JSON. Consumers that render SVG content must enforce these rules before display:

No script execution. The SVG must not contain <script> elements. Any <script> element, regardless of its type attribute, renders the SVG non-conforming.
No event handlers. Attributes whose names begin with on (case-insensitive) are prohibited. This includes onclick, onload, onerror, and all other DOM event handler attributes.
No external resource loading. The SVG must not reference external resources via href, xlink:href, src, or CSS url() expressions that resolve to non-data URIs. Inline data URIs for embedded images are permitted.
No <foreignObject> elements. This element can embed arbitrary HTML and is prohibited.

SVG documents that violate any of these rules must not be rendered by conforming consumers.

3.3 Size Limits

The protocol enforces one size limit on-chain: the metadata URI string must not exceed 128 bytes (ECidTooLong, error 6002). This is the only hard constraint the chain applies.

All other limits below are off-chain consumer conventions — the chain does not check them:

Field	Limit	Enforced by
Metadata URI string	128 bytes	On-chain protocol (`mercatr::metadata`)
`name`	256 UTF-8 characters	Off-chain consumers
`description`	10,000 UTF-8 characters	Off-chain consumers
SVG blob (referenced content)	1 MiB	Off-chain consumers

The total size of the metadata JSON document itself is not constrained by this schema, but storage networks may impose their own limits. Consumers should treat documents larger than 64 KiB with caution.

4. Level Conventions

4.1 Hierarchy Overview

The mercatr protocol organizes parcels into six hierarchy levels, identified by a rank integer. Rank 0 is the finest granularity (individual blocks and parcels); rank 5 is the coarsest (continental regions). The mapping is:

Rank	Level Name	Typical Map Zoom
5	Continent	1 – 2
4	Country	3 – 5
3	Region	6 – 8
2	City	9 – 11
1	District	12 – 14
0	Block	15 – 22

The rank is stored on-chain in the market's level registry. It is not part of the metadata JSON; consumers derive the level from the on-chain parcel record.

4.2 Typical Field Usage by Level

The following table describes the fields that are conventionally populated at each level. These are recommendations, not requirements. Owners may omit any optional field at any level.

Level	`name`	`description`	`svg`	`properties`
Continent (5)	Typical	Rare	Typical	Rare
Country (4)	Typical	Optional	Typical	Optional
Region (3)	Typical	Optional	Optional	Optional
City (2)	Typical	Typical	Optional	Optional
District (1)	Typical	Typical	Rare	Optional
Block (0)	Optional	Typical	Rare	Typical

Continent and Country parcels typically carry a name and an svg (a flag or territorial outline). Detailed descriptions are uncommon at these scales.

Region and City parcels typically carry a name and often a description summarising the area.

District and Block parcels are the most information-dense. Block-level parcels often omit name (the address or parcel ID serves as identifier) but carry detailed description text and structured properties data such as zoning classification, floor area, or permitted use codes.

5. Examples

The following examples are complete, conforming metadata documents. All field values are illustrative.

5.1 Country (rank 4)

A country-level parcel for a fictional nation. The document carries a name and an SVG flag reference on Walrus.

{
  "schema_version": "1.0.0",
  "name": "Republic of Zephyria",
  "svg": "walrus://bafkreibm6jg3ux5qumhcn2b3flc3ppihy6atznsk456tvkfaphbx4cgjoe"
}

5.2 City (rank 2)

A city-level parcel for the capital of the fictional nation. The document includes a description in CommonMark Markdown and an SVG city seal.

{
  "schema_version": "1.0.0",
  "name": "Port Zephyria",
  "description": "The capital and largest city of the Republic of Zephyria, situated at the confluence of the Zeph River and the Adriatic coast.\n\nFounded in the 12th century, Port Zephyria serves as the nation's primary commercial and administrative centre. The historic old town is a UNESCO-recognised heritage site.",
  "svg": "walrus://bafkreihdwdcefgh4dqkjv67uzcmw37nvexzhp5k6topapi5en57bfc7d62"
}

5.3 Block / Parcel (rank 0)

A block-level parcel representing a commercial property. The document omits name (the parcel is identified by its on-chain ID and address), carries a detailed Markdown description, and includes structured properties data for downstream applications.

{
  "schema_version": "1.0.0",
  "description": "## 14 Harbour Crescent — Commercial Block\n\nA four-storey mixed-use commercial building occupying the full block between Harbour Crescent and Quay Lane. Ground floor is retail; floors 2–4 are open-plan office space.\n\n**Zoning:** Commercial C-2 (retail and office permitted; residential prohibited)\n\n**Access:** Primary entrance on Harbour Crescent. Loading bay on Quay Lane (restricted 06:00–22:00). Disabled access via ramp at north-east corner.",
  "properties": {
    "zoning": "commercial-c2",
    "floor_area_m2": 4500,
    "floors": 4,
    "year_built": 1998,
    "permitted_use": ["retail", "office"],
    "energy_rating": "B"
  }
}

This document is part of the mercatr protocol specification. For the on-chain implementation of metadata storage, see §4.8 of the Yellowpaper and the mercatr::metadata module source.

1. Introduction​

1.1 Purpose​

1.2 Relationship to On-Chain State​

1.3 Notation​

2. Schema Definition​

2.1 Top-Level Fields​

2.2 Field Reference​

3. Validation Rules​

3.1 URI Formats​

3.2 SVG Safety​

3.3 Size Limits​

4. Level Conventions​

4.1 Hierarchy Overview​

4.2 Typical Field Usage by Level​

5. Examples​

5.1 Country (rank 4)​

5.2 City (rank 2)​

5.3 Block / Parcel (rank 0)​