Diary Schema Format

A diary schema describes a diary entry.

The schema from a diary entry is exported via the API using JSON.

The schema JSON object has the following attributes:

Description of schema attributes

Name

Value

Required

@id

Unique identifier for the schema

Yes

title

Human readable title for the user

Yes

fields

List of fields JSON objects defining the schema

Yes

timeline

List of fields to show on the timeline

No

resources

List of external resources used in this schema

No

charts

List of chart definitions

No

The @id value of a schema will be used as unique resource identifier @type of a diary entry using this schema in the scope of the Minddistrict API.

When retrieving one of multiple entries an extra meta information @schemas will be included. It will be the list of the schema used by entries contained in the response. You can identify which schema is related to which entry by mapping the @id value of a schema to a @type value of an entry.

Fields JSON object

All field JSON objects have at least the following attributes:

Description of field attributes

Name

Value

Required

type

Type of the field

Yes

name

Unique name of the attribute to use to transfer the value of the field inside a call to the API

Yes

title

Human readable title for the user

Yes

description

Human readable description for the user

No

required

Boolean indicating if the field is required

No

readonly

Boolean indicating if the field is a readonly (or computed) field. Default if omitted is false.

No

Some field, depending on their type, will have extra attributes which are described below.

In addition to the fields listed in the schema, the dt field is always present inside an entry and contains the date and time information at which the entry was posted.

It is possible that none of the fields in a schema are required. In that case, at least one of the fields should be filled in, as an empty entry doesn’t make much sense. This rule is applied both when creating and editing an entry.

text field

A text field accepts text input. Newlines are accepted in that field. None of the extra attributes are applicable to this field.

{
    "name": "location",
    "title": "Locatie",
    "type": "text"
}

textline field

A textline field accepts text input without newlines. None of the extra attributes are applicable to this field.

{
    "name": "situation",
    "title": "Situatie",
    "type": "textline"
}

boolean field

A boolean field accepts a true or false value as input and can have a default attribute.

{
    "name": "hungry",
    "title": "Hunger",
    "type": "boolean",
    "default": true
}

integer field

An integer field accepts whole numbers as input. If the min and max attributes have been set, only entry field values inside the range are valid. This field (optionally) may have a slider widget. This field can have a default value, which is the default value for the field.

{
    "name": "intensity",
    "title": "Intensiteit",
    "type": "integer",
    "min": 1,
    "max": 10,
    "widget": "slider"
}

float field

A float field accepts floating point numbers as input. If the min and max attributes have been set, only entry field values inside the range are valid. This field (optionally) may have slider or hours widgets. This field can have a default value, which is the default value for the field.

{
    "name": "spam",
    "title": "Spam",
    "type": "float",
    "min": 5.1,
    "max": 10.4,
    "default": 9.8
}

image field

An image field accepts an image as input. There are no additional attributes. The image is transferred as a regular image.

{
    "name": "picture",
    "title": "Afbeelding",
    "type": "image"
}

choice field

A choice field presents a list of items for the user to choose from. The list of options is a list of value, name attributes. The values are strings.

Warning

Diary fields use name for the machine-readable field name, and title for the human-readable version. Choices, regrettably, use name for the human-readable choice name and value for the machine-readable variant.

The field has an optional default attribute, which is the default value for the field. It is safe to assume that the default value is found as a value in the vocabulary.

{
    "name": "breakfast",
    "title": "Ontbijt",
    "type": "choice",
    "choices": [
        {
            "value": "bacon",
            "name": "Bacon"
        },
        {
            "value": "eggs",
            "name": "Eieren"
        },
        {
            "value": "spam",
            "name": "Spam"
        }
    ]
}

The items in the choice vocabulary have optional icon, referring a resource inside the resources JSON object. These icons can be shown to the end-user when presenting the field. An icon must be a 600x600 PNG file.

{
    "name": "breakfast",
    "title": "Ontbijt",
    "type": "choice",
    "choices": [
        {
            "value": "bacon",
            "name": "Bacon",
            "icon": "resources/pork.png"
        },
        {
            "value": "eggs",
            "name": "Eieren",
            "icon": "resources/egg.png"
        },
        {
            "value": "spam",
            "name": "Spam",
            "icon": "resources/spam.png"
        }
    ]
}

Widgets

Some fields can (optionally) be given a widget key. In the minddistrict platform this changes the way the field is displayed and entered. It’s not absolutely required that API integrations understand the widget settings, but it is strongly recommended: these settings typically describe how to interpret a number which is otherwise not meaningful to the end user.

Currently the following widget types are supported:

  • slider (for integer and float fields): Displays a slider tool ranging between the min and max settings.

  • hours (for float fields): The floating point number is interpreted as a time duration measured in hours, and displayed in hours and minutes. E.g. the float value 3.5 displays 3 hours and 30 minutes, the float value 3.75 displays 3 hours and 45 minutes, etc.

Computations and computed fields

A field marked readonly is a computed field: instead of having its value specified when creating an entry, it is computed by the server based on the values of the other fields in the entry.

Computed fields let a diary schema specify field values that depend on the values of other fields. For instance, one could use a computed field to calculate a general “happiness index” from a number of fields rating different aspects of the user’s mood, or a “sleep efficiency” calculated from fields recording the number of hours spent in bed and the number of wakings during the night.

The calculation is performed with Javascript code. (The code is not visible in the diary schema, but is part of the content written in the Minddistrict platform content management system.) The calculation is performed by the server whenever an entry is added or edited.

A field cannot be both readonly and required.

Timeline

The optional timeline attribute defines an ordered list of field names that should appears on the timeline of the diary.

Resources

An external resource is describe with a JSON object with the following attributes:

Description of resources attributes

Name

Value

name

Identifier for the resource

url

URL of the resources

For example:

{
    "name": "happy",
    "url": "https://cs.minddistrict.com/emotion/3/resources/happy.png"
}

Examples

The moment entry

For example, the moment entry from the version 2 for the API is described like this:

{
    "@id": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
    "fields": [
        {
            "name": "text",
            "title": "Tekst",
            "type": "text"
        },
        {
            "name": "picture",
            "title": "Afbeelding",
            "type": "image"
        }
    ],
    "resources": [],
    "title": "Moment"
}

With this schema, the following fields will be usable on the entry as a json object:

Name

Value

Explanation

Value type

Notes

dt

Date and time

Date and time for this entry

Date with time

Required
text

Tekst

-

String

picture

Afbeelding

Max file size: 10 MB

File

The @type meta information for this object is: http://ns.minddistrict.com/diary/schema/entry#moment:1.

The emotion entry

For example, the emotion entry from the version 2 for the API is described like this:

{
    "@id": "http://ns.minddistrict.com/diary/schema/entry#emotion:3",
    "fields": [
        {
            "choices": [
                {
                    "icon": "resources/happy.png",
                    "name": "Blij",
                    "value": "happy"
                },
                {
                    "icon": "resources/angry.png",
                    "name": "Boos",
                    "value": "angry"
                },
                {
                    "icon": "resources/sad.png",
                    "name": "Verdrietig",
                    "value": "sad"
                },
                {
                    "icon": "resources/scared.png",
                    "name": "Angstig",
                    "value": "scared"
                }
            ],
            "name": "emotion",
            "required": true,
            "title": "Hoe voel jij je?",
            "type": "choice"
        },
        {
            "default": 1,
            "max": 5,
            "min": 1,
            "name": "intensity",
            "required": true,
            "title": "Hoe sterk is deze emotie?",
            "type": "integer",
            "widget": "slider"
        },
        {
            "description": "In welke situatie bevind jij je?",
            "name": "situation",
            "title": "Situatie",
            "type": "text"
        },
        {
            "name": "picture",
            "title": "Afbeelding",
            "type": "image"
        }
    ],
    "resources": [
        {
            "name": "resources/angry.png",
            "url": "https://cs.minddistrict.com/emotion/3/resources/angry.png"
        },
        {
            "name": "resources/happy.png",
            "url": "https://cs.minddistrict.com/emotion/3/resources/happy.png"
        },
        {
            "name": "resources/sad.png",
            "url": "https://cs.minddistrict.com/emotion/3/resources/sad.png"
        },
        {
            "name": "resources/scared.png",
            "url": "https://cs.minddistrict.com/emotion/3/resources/scared.png"
        }
    ],
    "title": "Emotie"
}

With this schema, the following fields will be usable on the entry as a json object:

Name

Value

Explanation

Value type

Notes

dt

Date and time

Date and time for this entry

Date with time

Required
emotion

Hoe voel jij je?

-

Choice: happy, angry, sad or scared

Required
intensity

Hoe sterk is deze emotie?

-

Integer

Required
situation

Situatie

In welke situatie bevind jij je?

String

picture

Afbeelding

Max file size: 10 MB

File

The @type meta information for this object is: http://ns.minddistrict.com/diary/schema/entry#emotion:6.

Charts

The optional charts attribute defines an ordered list of chart definitions. Each one is a JSON object defining a single chart. A chart can only be defined for fields of type integer, float, and choice. Here is an example:

{
  "charts": [
    { "type": "line",
      "title": "Mood indicators",
      "series": [
        { "field": "self_reported_mood" },
        { "field": "sleep_quality" },
        { "field": "appetite" }
      ]
    },
    { "type": "bar",
      "title": "Sleep hours",
      "buckets": "day",
      "series": [
        { "field": "sleep_hours" }
      ]
    }
  ]
}

A chart definition JSON object has the following attributes:

Description of chart attributes

Name

Value

Required

type

Chart type (one of "bar", "line", "scatter")

Yes

title

Human readable chart title. This will be displayed above the chart.

Yes

series

List of definitions for individual data series in the chart. This defines which field to take data from, plus some chart-type-specific options.

Yes

buckets

Whether, and how, to collect time-series data from multiple entries into a single value display on the chart. See below for details.

No

Chart types

A line chart joins the points in the data series with straight lines. This chart type is a good choice if the value being plotted is a measurement of some quantity that varies smoothly over time (e.g., weight, blood pressure): the line suggests that the values moved smoothly from one data point to the other, and makes long-term trends more visible.

If the field is counting how often something happened (e.g., how much alcohol the client drank or cigarettes they smoked), a bar chart is typically a better visualisation. This makes explicit the fact that these measurements are made over a period of time (the buckets attribute), and that counting over a longer period will typically give a larger result. (Rule of thumb: a bar chart implies that adding together the values from two entries “makes sense”.)

A scatter chart plots individual data points just as a line chart does, but does not draw a line between them. This is useful for numeric data when measuring a quantity at a moment in time (rather than counting events over some period) but when the quantity cannot be expected to vary smoothly over time: examples include the intensity of an emotional response to a situation, or quality of sleep.

Series

Each JSON object in the series list defines a single data series in the chart. A series object must specify a field to take the data from (the field type must be integer, float, or choice), and may optionally specify a bucket-function.

There are some restrictions on series combinations:

  • A bar chart can only show a single series (a line or scatter chart may show more).

  • If a scatter chart shows more than one series, they must be on numeric fields; it can also show a choice field, but not more than one.

  • If a line or scatter chart includes more than one series, all series fields must be numeric and they must either all have the same min/max values configured, or have no min/max values configured.

  • To use a numeric field (integer or float) in a bar chart, the field must have a min of at least 0. This prevents the bar chart from going below the x axis, which is currently not supported.

Buckets and bucketing

The buckets attribute on a chart lets you collect multiple entries into a single data value in the chart; for example "day" (which collects all values on the same day into a single data point) or "night-morning-afternoon-evening" (which shows four data points, collecting entries from multiple days for each one).

The default buckets for a line chart or scatter chart on numeric fields is to not do bucketing (i.e., each entry is a separate data point). For a bar chart, the default is the same as specifying "day". A scatter chart on a choice field does not support bucketing at all.

The bucket-function on a series defines how a single data point is constructed from multiple entries. For example, for a field describing the amount of alcohol consumed in a single sitting, and with per-day buckets, the bucket-function "sum" is the most appropriate: it will show the total alcohol consumption per day. On the other hand for a field recording the intensity of an emotion the bucket-function "average" would be more appropriate. For choice fields the "tally" bucket-function counts how many times each option was selected, for display in a stacked bar chart.

Not all combinations of chart types, field types, buckets, and bucket functions make sense; of those that make sense, not all are supported at present. The following combinations are currently supported:

Chart type / field type / bucketing combinations

Chart type

Field type

buckets

bucket-function

Used for

line or scatter

float or integer

(none)

(none)

Each entry is a data point

day

sum or average

Each day is the average or sum of all entries on that day.

scatter

choice

(none)

(none)

Each entry is a single data point, with the Y position showing the choice option selected.

bar

choice

(none) or day

tally

Each day is a stacked bar; each section of the stack counts a choice option.

night-morning-afternoon-evening

tally

Four bars show the hours 0-6, 6-12, 12-18, 18-24. This is a stacked bar, as for the day bucket.

float or integer

(none) or day

sum or average

Each day is the average or sum of all entries on that day.

night-morning-afternoon-evening

sum or average

Four bars show the hours 0-6, 6-12, 12-18, 18-24.

Rendering tweaks based on chart config details

Getting charts that look good regardless of the data they contain is harder than you might expect. Here we collect the adjustments we make to details of chart rendering on the Minddistrict platform, based on the details of the chart config. If you’re implementing your own charting engine using configuration and data from our API, you may want to make the same adjustments so that your charts render consistently with ours.

  • In a line chart, if a series defines a maximum and minimum value, make sure that the Y axis range includes these values.

  • In a line chart, if the bucket function is sum and no series defines a maximum or minimum value, make sure that the Y axis range includes 0. (It is likely to be the minimum Y value, but need not be if the data includes negative numbers.)