File

The kind that gives a UnixFS tree or raw blob a stable identity, a name, an audience and provenance, so a file can be shared, listed and retained on its own rather than only through the blocks that embed it.

Claude (via Starlight)

8 October 2026

Claude (via Starlight)

8 October 2026

ContentPeople2CommentsCitationsAttributes0

Part of Stem. This page defines the file kind. Files themselves stay what they are: IPFS UnixFS data addressed by CID (Files). A file resource wraps one in a node, which is what lets it have readers, a place in a space and an owner. The formal schema of this kind's state is attached as the schemaDefinition of this page.

Descriptor

{
  "name": "File",
  "description": "A UnixFS tree or raw blob with identity, placement and an audience.",
  "state": "snapshot",
  "schema": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/file/value",
  "naming": "any",
  "children": false,
  "access": "inherit",
  "retention": "latest",
  "links": [
    { "path": "/root", "kind": "file" }
  ]
}

State

field	type	required	meaning
`root`	cid	yes	CID of the UnixFS root or raw blob. Emits a `file` link, so the whole tree is in the resource's dependency closure.
`mediaType`	string	no	IANA media type.
`size`	integer	no	Size in bytes.
`fileName`	string	no	Original file name.

Rules

Blocks keep embedding files directly by ipfs:// URL; nothing about documents changes. A file node is additional: it exists when someone wants to share a file by itself, list it in a folder, give it a pretty name, or make it available to an audience without a document around it.

A file's bytes are readable by anyone in the readers of any node whose state embeds them, whether that node is a file resource or a document. This is the file link flag "retained while the source is" applied to access: access follows owner-signed structure, never a bare CID mention from elsewhere.

Uploading raw bytes with no node that embeds them gives them no readers. A client that uploads a file before publishing the document that embeds it should publish the two in one Publish call, or create a file node first. This closes the anonymous-upload gap in today's system.

Replacing a file publishes a new Snapshot with a new root; retention is latest, so a following peer may drop the old tree once no state references it.

Today (HM24)

There was no file resource. A file was public once a public Ref, Change or Comment linked to it, through the visibility propagation rules, and private otherwise; POST /ipfs/file-upload stored bytes with no signed statement at all (Privacy). The inherited-visibility behaviour survives as the file link; the file node adds identity and provenance.

Example

{
  "type": "Snapshot",
  "signer": { "/": { "bytes": "7QHm…" } },
  "sig": { "/": { "bytes": "…" } },
  "ts": 1759903000000,
  "schema": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/file/value",
  "value": {
    "root": { "/": "bafybeigdyrzt…" },
    "mediaType": "application/pdf",
    "size": 1839201,
    "fileName": "stem-overview.pdf"
  }
}

{
  "type": "Node",
  "signer": { "/": { "bytes": "7QHm…" } },
  "sig": { "/": { "bytes": "…" } },
  "ts": 1759903000000,
  "kind": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/file",
  "parent": "bafyreiwyojfljooa7lqsaj2xuid5zzzzg6zdmen4khvdgajgxbenyjqwx6",
  "name": "stem-overview.pdf",
  "target": { "kind": "snapshot", "snapshot": { "/": "bafy2bzacek…" } }
}

Descriptor

State

Rules

Today (HM24)

Example

See also