A Document is the primary data structure for knowledge in the Hypermedia ecosystem. Every Document is a

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/change-resource, 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

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

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/resource.

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.

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

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/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.

A Ref is a

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/signed-data-blob that points to the latest state of a hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/change-resource 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

A Change is a

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/signed-data-blob that specifies some set of operations against a hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/change-resource

Deps

Change dependencies

Ops

The operations that are happening in this change

A Signed Data Blob is a

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/data-blob which has the "sig" and "signer" fields

A generic data blob is any IPFS file which is encoded using DAG-CBOR and has a "type" field that references this documentation.

A Contact is metadata that an Account uses to describe itself or another Account. Each Contact is a

hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/data/resource .