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;
}

`BlockNode`

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.

`Block`

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;
}