What Is IPLD? The Data Model Behind IPFS's Merkle DAG

IPLD (InterPlanetary Linked Data) is the data model underneath IPFS: it defines what hash-linked data can contain and how it turns into bytes. A file is one shape of IPLD data; a JSON record whose fields link to other CIDs is another, and both get the same verification.

TL;DR:

• IPLD splits linked data into three layers: the Data Model (what the data is), a codec (how it becomes bytes), and blocks addressed by CID (how those bytes are found and verified)
• The Data Model has nine kinds: null, boolean, integer, float, string, bytes, list, map, and link, where a link is a CID
• UnixFS files use the DAG-PB codec, which supports only a small part of the Data Model; DAG-CBOR and DAG-JSON support nearly all of it
• Every CID records its codec, so whoever fetches a block knows how to decode it before reading a single field
• Pinning a CID keeps its blocks no matter which codec produced them; decoding is the reader's job

Updated Oct 19, 2026: new definition-first opening, a DAG-JSON example we ran, a diagram, and an AIOZ Pin section; removed an ERC-8004 claim the AIOZ Pin docs don't support.

Why IPFS Needs a Data Model

IPFS stores everything as blocks that point at other blocks by hash, a structure called a Merkle DAG. That structure says nothing about what a block means, so something has to define it. IPLD is that definition: a shared model for content-addressed data, plus a set of codecs that write it to bytes.

UnixFS, the format IPFS uses for files and directories, is one schema built on IPLD. You can also put your own structured records into the same graph, and every node that speaks IPFS can store, move, and verify them. If you are new to the DAG itself, start with how IPFS builds a Merkle DAG.

The Three Layers: Data Model, Codec, and Blocks

The IPLD docs separate the problem into layers, and keeping them apart is what lets one CID system carry many data formats.

The Data Model lists the kinds of value you can store. According to the IPLD kinds reference, there are nine: null, boolean, integer, float, string, bytes, list, map, and link. Lists and maps hold other values, and a link is a CID that points at another block. The docs also advise you to avoid floats in content-addressed data, because different languages can encode the same number differently and change the hash.

A codec turns Data Model values into bytes and back. The codec you pick decides how compact the block is, how fast it parses, and which kinds it can hold. The last layer is the block itself: the codec's bytes are hashed into a CID, moved between peers by the DHT and Bitswap, and kept on disk by pinning.

DAG-PB vs DAG-CBOR vs DAG-JSON

Three codecs cover most IPLD data you will meet, and the IPLD codec docs describe each one plainly:

DAG-PB's limits fit its job, because a file node only needs data and a list of named children. For your own records, the IPLD team suggests a split: design the protocol in DAG-CBOR for speed and size, then use DAG-JSON while you develop and debug. DAG-JSON pays for its readability with slower parsing, and it inflates byte fields because it must base64-encode them.

What Does DAG-JSON Look Like?

DAG-JSON is ordinary JSON with one reserved shape: a map with a single "/" key holds a CID, and that map is a link. We encoded a small record with the @ipld/dag-json and multiformats JavaScript libraries, where the image field links to the raw block for a one-line text file:

import { CID } from 'multiformats/cid'
import { sha256 } from 'multiformats/hashes/sha2'
import * as dagJson from '@ipld/dag-json'

const image = CID.parse('bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4')
const bytes = dagJson.encode({ name: 'cat.png', size: 48213, image })
const cid = CID.create(1, dagJson.code, await sha256.digest(bytes))

Running it on Oct 19, 2026 with @ipld/dag-json 11.0.1 printed these bytes and this CID:

{"image":{"/":"bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4"},"name":"cat.png","size":48213}
baguqeerazpobtwq63ebkdz47aswze3fi5m2zmhrfasqqz33h2ur4xfjte27q

Notice that the encoder sorted the keys. Canonical ordering means the same data always produces the same bytes, so you get the same CID every time. The bagu prefix is the base32 form of a CIDv1 with the DAG-JSON codec, which tells any reader to decode the block as DAG-JSON.

Compare that with a typical NFT metadata file, where "image": "ipfs://bafy..." is a plain string. An IPLD tool sees a string there, not a link, so it cannot follow it or fetch the image as part of the same graph. Only the {"/": ...} form creates a real edge in the DAG.

How Does a CID Know Which Codec to Use?

A CIDv1 carries a multicodec code next to the hash, such as 0x70 for DAG-PB, 0x55 for raw, 0x71 for DAG-CBOR, or 0x0129 for DAG-JSON. IPLD is why that field has to exist. The same DAG can mix blocks from several codecs, so the address itself must say how to read each block before you can parse a byte of it. The anatomy of a CID walks through where that code sits in the identifier.

The codec is also part of what gets hashed into identity. The same JSON text stored as a UnixFS file and stored as DAG-JSON produces two different CIDs, because the codec and the bytes differ. That is one of the reasons the same file can get different CIDs.

Is UnixFS Part of IPLD?

Yes, as one schema on top of it. UnixFS describes files and directories with DAG-PB nodes for structure, and with CIDv1 the file data usually sits in raw leaf blocks. IPLD itself is broader. You can query part of any IPLD graph with IPLD selectors, or package a whole graph into one file as a CAR archive, whatever codecs its blocks use.

How AIOZ Pin Handles It

We document AIOZ Pin in terms of files, folders, and CIDs. You upload files or directories with POST https://api.aiozpin.network/api/pinning, and the response includes the cid and an is_dir flag. If you already have a CID, such as a DAG-JSON record your own node provides, the AIOZ Pin pinning API lists a pin-by-hash endpoint for it:

const res = await fetch('https://api.aiozpin.network/api/pinning/pinByHash', {
  method: 'POST',
  headers: {
    pinning_api_key: process.env.AIOZ_PIN_API_KEY,
    pinning_secret_key: process.env.AIOZ_PIN_SECRET_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ hash_to_pin: 'YOUR_CID', metadata: { name: 'my-record' } })
})

What the docs don't cover yet: which codecs pin-by-hash accepts, and whether an uploaded JSON file is stored as UnixFS or as DAG-JSON. Test with a small DAG-JSON CID before you rely on it. Once a CID is pinned, you can read it back through the public gateway at https://public.aiozpin.network/ipfs/{cid}.

Next step: the Pinning API reference lists every request and response field.

Frequently Asked Questions

What is IPLD in one sentence? IPLD is the data model and codec layer underneath IPFS that defines what hash-linked data can contain and how it is written to bytes.

What's the difference between DAG-PB and DAG-CBOR? DAG-PB supports only bytes and named links, which is enough for UnixFS files, while DAG-CBOR supports the complete Data Model in a compact binary form.

Is DAG-JSON the same as JSON? Almost: DAG-JSON is JSON with a reserved {"/": ...} shape for links and bytes, plus canonical key ordering so the same data always hashes the same way.

How does a reader know which codec to use for a block? The multicodec code inside the block's CID names the codec, so the reader picks the right decoder before it parses the bytes.

Does IPLD only work for files? No, because the Data Model covers maps, lists, strings, numbers, and links, so any structured record can live in an IPLD graph.

Can a pinning service pin non-file IPLD data? A pin keeps whatever blocks sit under a CID, but each service decides which codecs it accepts, so check its docs or test with a small CID first.

Related Reading

• Merkle DAGs, chunking, and routing in IPFS - the generic DAG structure IPLD formalizes
• UnixFS: how IPFS represents files and directories - the file schema built on DAG-PB
• Anatomy of a CID - where the multicodec field sits and how to decode it
• IPLD selectors - fetching part of a DAG instead of all of it
• CAR files - packaging a whole DAG into one file

References

• IPLD Documentation
• IPLD Docs: Data Model Kinds
• IPLD Docs: Codecs
• IPLD Codec Docs: DAG-JSON
• IPLD Codec Docs: DAG-PB
• AIOZ Pin Docs: Pinning API