Skip to main content

Adding Metadata

The metadata section of ws-resources.json lets you add human-readable information to your Walrus Site object. This data lives onchain, and portals, explorers, wallets, and other tools use it to display information about your site.

{
  "metadata": {
    "link": "https://myproject.wal.app",
    "image_url": "https://myproject.wal.app/preview.png",
    "description": "A decentralized app built on Sui and Walrus.",
    "project_url": "https://github.com/myorg/myproject",
    "creator": "MyOrg"
  }
}

The five fields correspond to the basic set of properties suggested by the Sui Object Display standard.

All fields are optional. You might include any combination of them, or omit the metadata block entirely.

What metadata fields can you set?​

Type: string (URL)
Purpose: The canonical public URL of your Walrus Site.

This is the URL through which users access your site. Portals and social preview tools use it as the primary link to represent the site.

Example: SuiNS subdomain

{
  "metadata": {
    "link": "https://myapp.wal.app"
  }
}

Example: Custom domain

{
  "metadata": {
    "link": "https://www.myproject.xyz"
  }
}

Example: Testnet portal

{
  "metadata": {
    "link": "https://2ffmxm7jmglccr79htmpdbaeqezp2krgftue5pfq9f83tdqjsc.localhost:3000"
  }
}

image_url​

Type: string (URL)
Purpose: A URL pointing to a preview image for the site.

This image serves as the thumbnail when someone shares your site or when explorers and marketplaces list it. It should be a publicly accessible image hosted on a stable URL.

Example: Image hosted on the same Walrus site

{
  "metadata": {
    "image_url": "https://myapp.wal.app/og-image.png"
  }
}

Example: Image hosted on an external CDN

{
  "metadata": {
    "image_url": "https://cdn.myproject.xyz/preview/walrus-site-banner.jpg"
  }
}

Example: Image hosted on Walrus directly

{
  "metadata": {
    "image_url": "https://aggregator.walrus-testnet.walrus.space/v1/blobs/abc123xyz"
  }
}

description​

Type: string
Purpose: A short human-readable description of the site.

This appears in Sui explorers, portal listings, and social sharing previews, similar to the <meta name="description"> HTML meta tag. You can use description to provide a one or two sentence summary of what your site is and does.

Example: A basic app

{
  "metadata": {
    "description": "A decentralized token swap interface built on Sui."
  }
}

Example: An NFT project

{
  "metadata": {
    "description": "Flatland NFTs — mint and collect unique generative art stored entirely on Walrus."
  }
}

Example: A developer tool

{
  "metadata": {
    "description": "An open-source block explorer for the Sui testnet with real-time transaction search."
  }
}

project_url​

Type: string (URL)
Purpose: A URL pointing to the project's source code, homepage, or documentation.

Use this field to provide a link to where users and developers can learn more about the project behind the site, such as a GitHub repository, a documentation site, or a marketing page. It is separate from link, which represents the site itself.

Example: A GitHub repository

{
  "metadata": {
    "project_url": "https://github.com/MystenLabs/walrus-sites"
  }
}

Example: A documentation site

{
  "metadata": {
    "project_url": "https://docs.myproject.xyz"
  }
}

Example: An external landing page

{
  "metadata": {
    "project_url": "https://www.myorg.io"
  }
}

creator​

Type: string
Purpose: Identifies the author or organization that created and deployed the site.

Explorers and directory listings show this string to indicate ownership or attribution. It can be an individual name, a team, an organization, or a handle.

Example: Individual

{
  "metadata": {
    "creator": "Alice"
  }
}

Example: Organization

{
  "metadata": {
    "creator": "MystenLabs"
  }
}

Example: Handle or alias

{
  "metadata": {
    "creator": "@walrus_builder"
  }
}

Aggregator URLs for images stored on Walrus​

When you host the preview image on Walrus directly, build the image_url from an aggregator URL. The aggregator serves a blob by its blob ID at the path /v1/blobs/{blob_id}. If you know the Sui object ID of the blob, you can use /v1/blobs/by-object-id/{blob_object_id} instead. The object ID path also returns response headers, such as content-disposition, that you configure through blob attributes.