HomeTwitterDiscordBlogs

Instructions for Building Manifest

Understanding the Path Manifest Schema

Path Manifests are JSON objects and come with several key-value pairs. Each of these keys serves a specific purpose.

Mandatory Fields

  • manifest: Type is string. This identifies that what you're creating is a path manifest for Arweave. It must be set to arweave/paths.

  • version: Type is string. This tells us which version of the manifest specification you're using. As of now, it's 0.1.0. For future updates, just keep an eye on semver.

  • paths: Type is object. This is where the magic happens. It maps your subpaths to Arweave transaction IDs. Each subpath key has an associated id which is the transaction ID for that particular file or asset.

Optional Fields

  • index: Type is object. This specifies what should happen when someone tries to access the manifest directly. If you set it, it must contain a behavior to adopt, which currently is path.

  • index.path: Type is string. If set, this is the default path that will load when the manifest is accessed. It must reference a key in the paths object, not a transaction ID.

Pro-Tips

  • Your path manifest transaction must only contain this JSON object.

  • The Content-Type tag must be set to application/x.arweave-manifest+json.

Example

Here’s a sample manifest JSON code snippet to illustrate how it all comes together:

{
  "manifest": "arweave/paths",
  "version": "0.1.0",
  "index": {
    "path": "index.html"
  },
  "paths": {
    "index.html": {
      "id": "cG7Hdi_iTQPoEYgQJFqJ8NMpN4KoZ-vH_j7pG4iP7NI"
    },
    "js/app.js": {
      "id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ"
    },
    "css/style.css": {
      "id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ"
    },
    "css/mobile.css": {
      "id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ"
    },
    "assets/img/logo.png": {
      "id": "QYWh-QsozsYu2wor0ZygI5Zoa_fRYFc8_X1RkYmw_fU"
    },
    "assets/img/icon.png": {
      "id": "0543SMRGYuGKTaqLzmpOyK4AxAB96Fra2guHzYxjRGo"
    }
  }
}

In this example, if someone accesses the manifest directly, it will load index.html by default. All the subpaths and their corresponding transaction IDs are clearly outlined in the paths object.

And there you have it! You’ve now become proficient in crafting and understanding Path Manifests. In the next part of this tutorial, we will look at how to actually implement these Path Manifests into your Web3 projects. So, don’t go too far!

Understanding URL Resolution in Arweave Gateways

Applicability Scope

Note that the rules for URL resolution are specific to the /[:txid] endpoint in Arweave gateways. These rules don't apply to /tx/[:txid] endpoints.

URL Anatomy and Resolution

When a user requests a URL from an Arweave gateway, the gateway must first identify the manifest transaction ID (manifestId) and the specified subpath. A typical Arweave URL might look like this:

Gateway Resolution Steps

  1. Content-Type Verification: The gateway must first check the Content-Type of the page being requested. If the Content-Type is application/x.arweave-manifest+json, then further processing is needed; otherwise, the data is served as-is.

  2. Manifest Parsing and Validation: Next, the gateway parses the manifest transaction’s data and should verify its contents according to the schema described in the document.

  3. Subpath Matching: The gateway searches the manifest for a key that corresponds to the requested subpath. If a match is found, the gateway responds with the transaction ID content specified in manifest.paths[subpath].id.

  4. HTTP Codes and Redirects: A HTTP 200 status code should be returned if content is found. Redirects are not allowed; the user's URL must remain unchanged in the browser.

  5. Error Handling: If the manifest points to an invalid transaction ID or one that can’t be accessed, a HTTP 404 status should be returned.

  6. Index Mapping: If a manifest is accessed directly (no subpath specified), and it has an index.path value, that value should be mapped to the manifest paths and resolved accordingly. Redirects to index.path are not allowed.

  7. Listing Available Paths: If no index.path is defined, the gateway should display a list of all valid paths in a user-friendly HTML format.

  8. ETag for Caching: ETag headers are important for caching. The ETag should be set to the transaction ID of the actual content, not the manifest, unless the manifest is being accessed without a subpath and no index is defined.

Examples

Here are some example scenarios based on hypothetical manifest files:

  • No subpath specified: The gateway will resolve to the data in cG7Hdi_iTQPoEYgQJFqJ8NMpN4KoZ-vH_j7pG4iP7NI as index.html is defined as index.path.

  • Valid subpath specified: A request for /mmJhKOPp2o73LXze05mj5qPVlgu4MsDzqCwpWKqoc7U/assets/img/logo.png would return the content at QYWh-QsozsYu2wor0ZygI5Zoa_fRYFc8_X1RkYmw_fU.

  • Invalid subpath: A request for a non-existing path like /mmJhKOPp2o73LXze05mj5qPVlgu4MsDzqCwpWKqoc7U/path/does/not/exist.txt will return a HTTP 404.

  • No default index defined: If no index.path is present, the gateway will display an HTML page listing all valid paths available in the manifest.

By understanding these resolution rules, you’ll be better equipped to interact with the Arweave decentralized web, whether you’re a developer or an end user.

Last updated