Sleep Resources

A collection of files to help study and improve sleep

Project maintained by sleepdiary Hosted on GitHub Pages — Theme by mattgraham

entities.json specification

entities.json is a JSON file containing information about sleep-related entities. This document explains the format of that file.

The project itself builds entities.json from files hosted in the same directory as this specification. Their format is typically similar enough that an interested developer can learn a lot from the specification, but no guarantees are made about them - even that they will continue to exist in future. Production systems should avoid them in favour of entities.json itself.

Common features

All versions of entities.json contain a single root object with a format key that uniquely identifies the file format. The associated value MUST begin with https://sleepdiary.github.io/resources/entities#, followed by an arbitrary string. All versions of the format so far use semantic versioning, but implementations should not depend on this behaviour. Instead, implementations that handle more than one version should check the format string against a list of known values.

Version 0.0.2

Format string: https://sleepdiary.github.io/resources/entities#version-002

Contains the following top-level sections:

valid_values

This object contains a set of key/value pairs, where each key indicates the name of a key that can exist elsewhere in the document, and each value is an object describing valid values for that key. Depending on the key, valid values might be either a single string or an array of strings from the list.

The following example says that all specialist_type keys outside of valid_values must have a string value matching either physician or researcher. It further includes a non-normative English description for what those keys mean.

{
 ...
 "specialist_type": {
   "physician": "a medical doctor who treats sleep disorders",
   "researcher": "an academic who studies sleep disorders"
 }
 ...
}

specialist

This object contains a single records key, the value of which is a list of known specialists. Each entry in the list is an object with the following keys:

software

locations

Each entry in the locations array contains the following values:

forms and reports

Each entry in the forms and reports arrays contain the following values:

The following entries are only relevant for entries in specialist:

The following entries are only relevant for entries with a layout of calendar:

Each entry in the gallery array contains an image of the document, contaning the following values:

events

Each entry in the events array contains an event that should be marked in a calendar. For example, marking caffeine consumption. Each entry is an object containing the following values:

modifiers

Each entry in the modifiers array contains a way that a component can be modified. Each entry is an object containing the following values:

sort keys

Some values are hard to sort correctly. For example, most algorithms will not sort the list [ "6am", "noon", "10pm" ] in a useful order. Sort keys are objects that resemble the following:

{
  "key": "012345",
  "value": "hard-to-sort-string"
}

key is a string to sort on. Some sort keys only contains digits, but should not be converted to integers because the leading 0s are significant.

value is a value to display.

Version 0.0.1

This version is the same as 0.0.2, except for the following: