RTD JSON format

This document describes the JSON format available through the OpenAPI and through the WebHare TypeScript APIs.

Build format

WebHare has an 'in-memory' and a 'build' format for Rich documents. In TypeScript these correspond to RTDBlock[] and RTDSource in jssdk/services/src/richdocument.ts.

The 'in-memory' format is a stricter, unambiguous format that corresponds to the minimal HTML syntax used interaly. The 'build' format offers shorter notation of various structures and is designed for use as an input format when manually building RTDs (especially in YAML). The build format is converted to the in-memory format when storing RTDs.

Eg the build format in YAML would support:

- h1: My heading
- p: A simple paragraph
- p:
  - "Click "
  - text: this link
    link:
      externalLink: "https://beta.webhare.net/" 

Where the corresponding in-memory format would be

[
  {
    "tag": "h1",
    "items": [
      {
        "text": "My heading"
      }
    ]
  },
  {
    "tag": "p",
    "items": [
      {
        "text": "A simple paragraph"
      }
    ]
  },
  {
    "tag": "p",
    "items": [
      {
        "text": "Click "
      },
      {
        "text": "this link",
        "link": {
          "_internal": null,
          "_external": "https://beta.webhare.net/",
          "_append": null
        }
      }
    ]
  }

RTD structure:

A RTD consists of an array of blocks. Each block is either a:

• paragraph (a h1 is considered a paragraph too for purposes of the file format)
• list
• table
• block widget

Paragraphs

A paragraph consists of a tag (p, h1, h2...), an optional className and inline items:

  {
    "tag": "p",
    "className": "centered",
    "items": [
      {
        "text": "My heading"
      }
    ]
  }

Inline items themselves are an array consisting of either a

• text node (text propery)
• image (image property)
• inline widget (inlineWidget propery)

Each array element can have these textstyle properties. If present, they should be true. If not set, leave them out:

• b
• i
• u
• strike
• sub
• super

Each array element can additionaly have these link properties:

• link
• target

link should either be of the format:

• { internalLink: string; append?: string } - for internal links to WHFS objects
• { externalLink: string } - for external links

Lists

A list block starts with tag: ul or ol for unnumbered or outline (numbered) lists and has a single listItems property.

The listItems are an array of objects with only a li property containing an array of objects.

Each of these objects must have a single propery named 'items' containing an array of inline items.

  {
    "tag": "ul",
    "listItems": [
      { "li": [{ "items": ["item", { "text": "1", "bold": true }] }] },
      { "li": [{ "items": ["item 2"] }] }
    ]
  }

Do not use a tag inside the the array passed to li. Although the format supports it, the built-in RTD editor and rendering do not understand this format yet.