Skip to content

docs(arfs): name the snapshot body field jsonMetadata, not dataJson #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vilenarios merged 2 commits into from
Aug 29, 2026
Merged

docs(arfs): name the snapshot body field jsonMetadata, not dataJson #137

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
71fd35a
docs(arfs): name the snapshot body field jsonMetadata, not dataJson
vilenarios Aug 19, 2026
90313c4
Merge branch 'main' into fix/arfs-snapshot-jsonmetadata
vilenarios Aug 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions content/build/advanced/arfs/entity-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,9 +183,13 @@ Unix-Time: "<seconds since unix epoch>"

A JSON data object must also be uploaded with every ArFS Snapshot entity. This data contains all ArFS Drive, Folder, and File metadata changes within the associated drive, as well as any previous Snapshots. The Snapshot Data contains an array `txSnapshots`. Each item includes both the GQL and ArFS metadata details of each transaction made for the associated drive, within the snapshot's start and end period.

A `tsSnapshot` contains a `gqlNode` object which uses the same GQL tags interface returned by the Arweave Gateway. It includes all of the important `block`, `owner`, `tags`, and `bundledIn` information needed by ArFS clients. It also contains a `dataJson` object which stores the correlated Data JSON for that ArFS entity.
Each `txSnapshot` has exactly two fields, `gqlNode` and `jsonMetadata`, as siblings.

For private drives, the `dataJson` object contains the JSON-string-escaped encrypted text of the associated file or folder. This encrypted text uses the file's existing `Cipher` and `Cipher-IV`. This ensures clients can decrypt this information quickly using the existing ArFS privacy protocols.
`gqlNode` uses the same GQL tags interface returned by the Arweave Gateway. It includes all of the important `block`, `owner`, `tags`, and `bundledIn` information needed by ArFS clients.

`jsonMetadata` is a **string**, not an object: the correlated Data JSON for that ArFS entity, serialized and escaped. It is `null` for an entry recorded for its GQL node alone, with no metadata body — a client must handle that rather than assume a string is always present.

For private drives, `jsonMetadata` contains the JSON-string-escaped encrypted text of the associated file or folder. This encrypted text uses the file's existing `Cipher` and `Cipher-IV`. This ensures clients can decrypt this information quickly using the existing ArFS privacy protocols.

```json
{
Expand Down Expand Up @@ -242,7 +246,7 @@ For private drives, the `dataJson` object contains the JSON-string-escaped encry
}
]
},
"dataJson": "{\"name\":\"november\",\"rootFolderId\":\"71dfc1cb-5368-4323-972a-e9dd0b1c63a0\", \"isHidden\":false}"
"jsonMetadata": "{\"name\":\"november\",\"rootFolderId\":\"71dfc1cb-5368-4323-972a-e9dd0b1c63a0\", \"isHidden\":false}"
}
]
}
Expand Down