Filesystem Standard

A decentralized file and folder structure. Store files anywhere -- local disk, IPFS, S3, a WorldAPI hub -- and describe them the same way.

File

{
	$type: 'filesystem',
	$version: 1,
	$kind: 'file',
	$name: 'project-brief.pdf',
	$mime: 'application/pdf',
	$size: 284160,
	$hash: 'sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
	$created: '2026-02-10 09:30:00',
	$modified: '2026-03-15 14:22:10',
	$owner: { $type: 'contact', $name: 'John' },
	$source: 'ipfs://QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG',
	$permissions: {
		$public: false,
		$read: ['team-alpha'],
		$write: ['markus']
	}
}

Folder

{
	$type: 'filesystem',
	$version: 1,
	$kind: 'folder',
	$name: 'Documents',
	$path: '/Documents',
	$created: '2026-01-01 00:00:00',
	$modified: '2026-03-28 18:45:00',
	$owner: { $type: 'contact', $name: 'John' },
	$children: [
		{
			$kind: 'folder',
			$name: 'Projects',
			$path: '/Documents/Projects',
			$count: 12
		},
		{
			$kind: 'file',
			$name: 'notes.txt',
			$mime: 'text/plain',
			$size: 4096,
			$hash: 'sha256:a1b2c3...'
		}
	],
	$permissions: {
		$public: false,
		$read: ['team-alpha'],
		$write: ['markus']
	}
}

A share link -- grants access to a file or folder without requiring authentication.

{
	$type: 'filesystem',
	$version: 1,
	$kind: 'share',
	$target: '/Documents/project-brief.pdf',
	$token: 'abc123xyz',
	$url: 'https://hub.example.com/s/abc123xyz',
	$expires: '2026-04-30 23:59:59',
	$permissions: {
		$read: true,
		$write: false
	},
	$created: '2026-03-29 10:00:00',
	$created_by: { $type: 'contact', $name: 'John' }
}

Object Kinds

$kind	Use case
`file`	A single file with content stored elsewhere
`folder`	A directory containing files and subfolders
`share`	A share link granting access to a file or folder

Standard Properties

Property	Type	Required	Description
`$type`	string	yes	Always `'filesystem'`
`$version`	number	yes	Standard version
`$kind`	string	yes	file, folder, or share
`$name`	string	yes	File or folder name
`$path`	string	no	Full path from root
`$mime`	string	yes*	MIME type (files only)
`$size`	number	no	Size in bytes
`$hash`	string	no	Content hash (algorithm:hex)
`$source`	string	no	Where the content lives (URL, IPFS CID, S3 URI)
`$created`	string	no	UTC datetime
`$modified`	string	no	UTC datetime of last modification
`$owner`	object	no	Owner (contact object)
`$children`	array	no	Contents of a folder
`$count`	number	no	Number of items in folder (when `$children` omitted)
`$permissions`	object	no	Access control
`$target`	string	yes*	Path the share points to (shares only)
`$token`	string	yes*	Share token (shares only)
`$expires`	string	no	UTC datetime when share expires

* Required depends on $kind.

Permissions