Document
A Document is the primary data structure for knowledge in the Hypermedia ecosystem. Every Document is a Untitled Document, so it is modeled with Refs and Change blobs.
The main building block for knowledge in the Hypermedia network is the Document.
Each Document is identified by the Site Id + Path
Content
The content of the document is a hierarchy of Blocks. Each Block Node contains one block and any number of children blocks.
Block Types
Paragraph
Heading
Code
Math
Image
Video
File
Button
Embed
WebEmbed
Query
Experimental Block Types
Nostr
Note: Some Block types do not properly support children. TODO: research and explain this better
Metadata
A document has the following metadata fields to describe it. They are all optional but it is recommended to always have a name
name
The title of the Document. For Home Documents, this is the title of the Site
icon
The IPFS url for the icon associated with this Document. For Home Documents, this is the icon (or favicon) for the Site.
cover
The IPFS url for the cover image. When present, displayed full-width at the top of the document.
siteUrl
For Home Documents, contains the https URL where the Site is published on the web
displayPublishTime
TODO
showOutline
TODO
showActivity
TODO
contentWidth
TODO
theme
TODO
Experimental Metadata
seedExperimentalLogo
For Home Documents, contains the IPFS url for the logo to be used in the header, instead of the name+logo
Deprecated Metadata
Some fields are no longer in use but they may appear in older Documents. They can be safely ignored.
layout
seedExperimentalHomeOrder
Capability
The Capability is a signed blob used to delegate new permissions to read, write, or author as another identity.
It is used to grant signing permissions to other devices or people.
Each capability is a Untitled Document.
Shape
Contains the following fields
Signer
Delegate – The Account ID of the identity receiving new capabilities
Role
Label
Revoked – Boolean, true if the capability is being revoked
Path
Recursive
Deps – The CIDs of capabilities to depend on. Used to form a chain of capabilities
Signature – Cryptographic proof of this shape from the signer
Chaining
A capability might be granting permissions to another account, which might require a chain of capabilities.
ChangeResource
This Resource is created by forming a graph of Changes and then using Refs to point to the latest heads of the change graph.
Currently, the protocol's only ChangeResource is the Untitled Document
The Change blobs describe the operations to add/remove data from the resource. They depend on other Changes, and you can walk through all changes, applying operations, until you reach the current state of the Resource.
Changes are the raw data with version history, and a Ref specifies the actual location.
Unlike basic Resources, the ChagneResource allows easy branching, redirecting, and re-publishing.
Branching
If you want to create your own branch of an existing ChangeResource, you can simply create a Ref that points to the desired set of Changes.
Deleting
To delete the resource, create a new "tombstone" ref which marks the resource as deleted.
Redirecting
You can create a special Redirect Ref, so that you will be moved to another location when attempting to open this Resource.
Republishing
In cases where you want to redirect but keep showing the current URL, we allow a republish flag to be set on a redirect.
Move
To move a ChangeResource, you should create a new Ref at the new location.
With the old location, you should probably set a redirect to the new location, so links won't be broken. But if you want to break links, you can delete the old Ref.
Note: For users who have already downloaded the content and who want to refer to exact versions, links will not break.
Generations
Generations are numbers used to manage the lifecycle of ChangeResource Refs. This number must be incremented when deleting or undeleting the Resource. It can also be incremented if your ref shifts to an entirely unrelated change history.
Ref
A Ref is a Untitled Document that points to the latest state of a Untitled Document according to the signer.
Version
A set of change heads, identified by their CID
Location
The "space" and "path" which identifies the location of this ref
Generation
The number which identifies which generation of Ref is changing. Useful for handling concurrent updates to the ChangeResource, like if the resource is deleted by one author while it is updated by another.
Tombstone/Deletes
...
Redirect
Points to another ref. Optional Republishing flag which specifies that the content is being redirected but the location should remain
Change
A Change is a Untitled Document that specifies some set of operations against a Untitled Document
Deps
Change dependencies
Ops
The operations that are happening in this change
Signed Data Blob
A Signed Data Blob is a Untitled Document which has the "sig" and "signer" fields
Data Blob
A generic data blob is any IPFS file which is encoded using DAG-CBOR and has a "type" field that references this documentation.
Contact
A Contact is metadata that an Account uses to describe itself or another Account. Each Contact is a Untitled Document .