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
`line` or `scatter`	`float` or `integer`	`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.
	`choice`	`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.
	`float` or `integer`	`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.)