Hypermedia Schema

Hypermedia is all about collaboration. For a group of humans to collaborate they need to share the same medium, a structured data type.
The way we are empowering people to collaborate is with Documents. A Document simply is a set of hierarchical blocks that follow a set of simple rules. This set of rules makes it possible to have a open and asynchronous collaboration.

Document Definition

// Document represents metadata and content of a draft or publication.
message Document {
  // Permanent ID of the document.
  string id = 1;

  // Title of the document.
  string title = 2;

  // Output only. Author ID of the document.
  string author = 4;

  // Output only. Account IDs of all the editors of the document.
  // Includes the original author as well.
  repeated string editors = 11;

  // Content of a Document structured in blocks and hierarchy
  repeated BlockNode children = 9;

  // Output only. Time when document was created.
  google.protobuf.Timestamp create_time = 6;

  // Output only. Time when document was updated.
  google.protobuf.Timestamp update_time = 7;

  // Output only. Time when this version was published. Not present in drafts.
  google.protobuf.Timestamp publish_time = 8;

  // Output only. Current version of the document.
  string version = 12;

  // Output only. Previous version of the document,
  // unless this is the first version.
  string previous_version = 13;


a Blocknode is a struct that its main purpose is to hold the relationship between a block parent and its children. As you can see, the Document defines a list of BlockNodes.
block - (Block): defines the content of the block and its type
children - Array<BlockNode>: (optional) a set of children blockNodes.


This is the smallest structure with a unique identifier in Hypermedia. Some of the attributes of a block are completely arbitrary and irrelevant to the system, but important for the renderer and the have a better user experience so writers can express better their intentions.
The minimal representation of a block includes an id and text or ref. The other properties are irrelevant to the system (the exception is the annotations).
// Content block.
message Block {
  // Block ID. Must be unique within the document.
  string id = 1;

  // Type of the block. Specific to the renderer.
  string type = 2;

  // Text of the content block.
  string text = 3;

  // Optional. The hyperlink to an external resource.
  // Must be a valid URL.
  string ref = 7;

  // Arbitrary attributes of the block.
  map<string, string> attributes = 4;

  // Annotation "layers" of the block.
  repeated Annotation annotations = 5;

  // Output only. Current revision of the block. It's the ID of the last Change that modified this block.
  // Additional information about the Change can be obtained using the Changes service.
  string revision = 6;
a Document is composed by a list of blocks
each block can have blocks as children
a document has a list of blocks
Blocks is the minimal referenced object in a document
blocks can have optional content and also a list of Blocks as children
a block parent define the list type, not each block
a heading is a block, and the heading level is defined by its hierarchy, the heading level is not arbitrary
why not markdown?
why the parent defines the children type?
standoff properties
why is important
usecase where is relevant:
merge conflicts
detect format changes vs content changes
better detection of the actual change of a standoff property (add/remove property versus create all the time the property)
extending blocktypes