Introduction

Document Purpose

This document describes the files used and data transmitted by the application, detailing the controls that make it secure and ensure reliability.

Application Summary

Openbook is a web application that allows users to access ‘open textbooks’ and complete interactive questions. Openbook itself is comprised of two systems - the site, and the textbook engine. The site is the system most users interact with. It operates in the browser and is used to actually read the textbooks. Some functionality of the site requires an internet connection, even when ran from your own device. The textbook engine (OTE) is a CLI toolkit for any users authoring textbooks for Openbook. It is used as a command in the shell to generate textbook files and export the raw markdown content to useable rendered HTML to be uploaded to a GitHub repository linked to the site.

File Summary - textbook options file

Used by authors to store important textbook metadata. This is a user-modified file processed by the server when adding a textbook to the database.

Organisation/Structure

Naming	options.[json, xml]
Filetype	JSON or XML
Required fields	metadata/title (string)
metadata/authors (array)
metadata/description (string)
book/cover/colour (string)
page_numbers/pre-content.md (string)
Maximum size	100 MiB
Other restrictions	For XML files:

Certain characters like the ampersand (&) must be avoided. | | Notes | XML options files are discouraged |

Samples

options.json

{
  "metadata": {
    "title": "Sample Subject Units 1 & 2",
    "authors": ["William Herring", "John Doe"],
    "description": "A sample textbook designed for those undertaking Sample Subject Units 1 & 2."
  },
  "book": {
    "cover": {
      "colour": "default"
    },
    "page_numbers": {
      "book/pre-content.md": "roman"
    }
  }
}

options.xml

<?xml version="1.0" encoding="UTF-8" ?>
 <root>
     <metadata>
         <title>Sample Subject Units 1 and 2</title>
         <authors>William Herring</authors>
         <authors>John Doe</authors>
         <description>A sample textbook designed for those undertaking Sample Subject Units 1 and 2.</description>
     </metadata>
     <book>
         <cover>
             <colour>default</colour>
         </cover>
         <page_numbers>
             <pre-content.md>roman</pre-content.md>
         </page_numbers>
     </book>
 </root>

Storage

The options file is stored in a textbook directory on the user’s device. It is also stored remotely in a GitHub repository if the textbook is published.

Backup plan

The options file is backed up remotely in a textbook’s GitHub repository. Users should use Git and frequently make commits when working with textbooks for version control. This, combined with a remote repository, would provide two layers of file backup including one off-device. The impact of losing an options file is insignificant if it is lost on a user’s device, however it would impact the textbook upload process if it is missing from the remote repository.