An Entity is a mutable value in the network, which can be created, modified, forked, and deleted by creating chunks of signed data.
The primary Entity in our network is the Document.
We have two types of data which work together to define the state of an Entity/Document. A Change describes a modification to the state of the Entity, and a Ref is an assertion of the Entity's current state.
Change Blob
Changes are blobs (data) which describe the creation or mutation of the Entity value. Each change has a few important ingredients:
Operations - A list of additions, modifications or removals of Entity state
Dependencies - What other Changes are necessary before this Change will make sense
Authorship information - The author ID, signature proof of authorship, and timestamp of the Change
Because your Change may link to other Changes as "dependencies", a Change generally represents a "Version" of an Entity. The changes form a graph (technically, a DAG because there are no cycles). As the Entity evolves, the graph gets larger. And because a Change may have multiple dependencies, you can merge in a branch of Changes to the state of the Entity.
Ref Blob
Changes don't tell the whole story, because its possible for a Change to exist without affecting the current state of the Entity. The Ref data blob is used to assert the current version of a document. It includes:
Location - What is the address of the Entity
Authorship information - Author ID, signature proof of authorship, and timestamp of the Ref
Active Version - The Change ID(s) of the current version
To understand the current version of an Entity, you can find the most recent Ref for a given location. Then you'd verify that the Author is allowed to modify this.
Snapshot Entities
These are lightweight mutable values which must be re-published when they are changed. They are optimal for smaller values, and values that don't change often. They are simpler than full Entities but cannot be branched and they do not store a history of operations. They support a version history but the deltas must be inferred.
A Snapshot Entity Blob contains:
The latest/current value
Location - What is the address of the Entity
Authorship information - Author ID, signature proof of authorship, and timestamp of the Ref
The following are Snapshot Entities:
Comments
Capabilities
Contacts
A snapshot entity may be addressed with hm://{ACCOUNT_ID}/{ENTITY_ID}, where the entity ID is constructed by combining the timestamp with the hash of the first version of the entity.