mercatr — Off-Chain Parcel Metadata Schema

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

 Introduction
1  Purpose
2  Relationship to On-Chain State
3  Notation
 Schema Definition
1  Top-Level Fields
2  Field Reference
 Validation Rules
1  Coordinate Ranges
2  URI Formats
3  SVG Safety
4  Size Limits
 Level Conventions
1  Hierarchy Overview
2  Typical Field Usage by Level
 Examples
1  Country (rank 4)
2  City (rank 2)
3  Block / Parcel (rank 0)

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

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.
The coordinate object { "lat": number, "lng": number } uses geographic convention: latitude first, longitude second. This differs from GeoJSON, which uses [longitude, latitude] order.

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
`label`	`object`	No	`{ "lat": number, "lng": number }`
`pois`	`array`	No	At most 50 items
`properties`	`object`	No	Arbitrary key-value pairs

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.2 for URI format rules and §3.3 for SVG safety requirements that apply to the referenced content.

label (object, optional) — A geographic coordinate indicating the preferred placement point for a map label or marker associated with this parcel. The object must contain exactly two numeric fields:

lat (number) — Latitude in decimal degrees. Must satisfy $-90 \leq \text{lat} \leq 90$ .
lng (number) — Longitude in decimal degrees. Must satisfy $-180 \leq \text{lng} \leq 180$ .

The label coordinate need not lie within the parcel polygon. For concave or multi-part parcels, owners may choose a centroid or a visually prominent interior point.

pois (array, optional) — An ordered array of Points of Interest (POIs) within or associated with the parcel. Each element is an object with the following fields:

Field	Type	Required	Description
`id`	`string`	Yes	Stable identifier, unique within the array
`name`	`string`	Yes	Display name for the POI
`coord`	`object`	Yes	`{ "lat": number, "lng": number }`
`icon`	`string`	No	Icon identifier (e.g., `"entrance"`, `"parking"`, `"landmark"`)
`description`	`string`	No	Short description; $n \leq 512$ characters

The array must contain at most 50 items. POI coordinates follow the same range constraints as the label field (§3.1). The icon field is a free-form string; consumers interpret it according to their own icon sets.

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 Coordinate Ranges

All geographic coordinates in this schema follow the same constraints:

$\text{lat} \in [-90,\ 90]$ $\text{lng} \in [-180,\ 180]$

This applies to the label field and to every coord object within the pois array. Values outside these ranges are invalid. Consumers should reject documents containing out-of-range coordinates rather than silently clamping them.

3.2 URI Formats

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. Relative URIs are not permitted.

3.3 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.4 Size Limits

Field	Limit
`name`	256 UTF-8 characters
`description`	10,000 UTF-8 characters
`pois` array length	50 items
POI `description`	512 UTF-8 characters
SVG blob (referenced content)	1 MiB

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`	`label`	`pois`	`properties`
Continent (5)	Typical	Rare	Typical	Typical	Rare	Rare
Country (4)	Typical	Optional	Typical	Typical	Rare	Optional
Region (3)	Typical	Optional	Optional	Typical	Rare	Optional
City (2)	Typical	Typical	Optional	Typical	Typical	Optional
District (1)	Typical	Typical	Rare	Typical	Typical	Optional
Block (0)	Optional	Typical	Rare	Optional	Typical	Typical

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

Region and City parcels typically carry a name, a label, and often a description summarising the area. Cities frequently include POIs marking notable locations such as city halls, transit hubs, or landmarks.

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, multiple POIs (entrances, parking, amenities), 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, an SVG flag reference on Walrus, and a label coordinate for the capital region.

{
  "schema_version": "1.0.0",
  "name": "Republic of Zephyria",
  "svg": "walrus://bafkreibm6jg3ux5qumhcn2b3flc3ppihy6atznsk456tvkfaphbx4cgjoe",
  "label": {
    "lat": 41.3275,
    "lng": 19.8187
  }
}

5.2 City (rank 2)

A city-level parcel for the capital of the fictional nation. The document includes a description in CommonMark Markdown, an SVG city seal, a label coordinate, and three POIs marking key civic locations.

{
  "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",
  "label": {
    "lat": 41.3275,
    "lng": 19.8187
  },
  "pois": [
    {
      "id": "poi-city-hall",
      "name": "City Hall",
      "coord": { "lat": 41.3301, "lng": 19.8210 },
      "icon": "landmark",
      "description": "Seat of the Port Zephyria municipal government, built 1887."
    },
    {
      "id": "poi-central-station",
      "name": "Central Railway Station",
      "coord": { "lat": 41.3248, "lng": 19.8155 },
      "icon": "transit",
      "description": "Main intercity rail terminus. Connections to all regional lines."
    },
    {
      "id": "poi-harbour-gate",
      "name": "Harbour Gate",
      "coord": { "lat": 41.3190, "lng": 19.8090 },
      "icon": "entrance",
      "description": "Primary public access point to the commercial port district."
    }
  ]
}

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, lists five POIs covering access and amenities, 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.",
  "pois": [
    {
      "id": "poi-main-entrance",
      "name": "Main Entrance",
      "coord": { "lat": 41.3195, "lng": 19.8102 },
      "icon": "entrance"
    },
    {
      "id": "poi-loading-bay",
      "name": "Loading Bay",
      "coord": { "lat": 41.3188, "lng": 19.8115 },
      "icon": "delivery",
      "description": "Restricted access 06:00–22:00. Max vehicle height 4.2 m."
    },
    {
      "id": "poi-disabled-access",
      "name": "Accessible Entrance",
      "coord": { "lat": 41.3198, "lng": 19.8108 },
      "icon": "accessibility"
    },
    {
      "id": "poi-parking",
      "name": "Underground Car Park",
      "coord": { "lat": 41.3192, "lng": 19.8110 },
      "icon": "parking",
      "description": "48 spaces. Access via Quay Lane ramp. Clearance 2.1 m."
    },
    {
      "id": "poi-fire-assembly",
      "name": "Fire Assembly Point",
      "coord": { "lat": 41.3202, "lng": 19.8095 },
      "icon": "safety"
    }
  ],
  "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 Yellow Paper and the mercatr::metadata module source.

Table of Contents​

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 Coordinate Ranges​

3.2 URI Formats​

3.3 SVG Safety​

3.4 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)​

Table of Contents