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:
Name |
Value |
Required |
---|---|---|
|
Unique identifier for the schema |
Yes |
|
Human readable title for the user |
Yes |
|
List of fields JSON objects defining the schema |
Yes |
|
List of fields to show on the timeline |
No |
|
List of external resources used in this schema |
No |
|
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:
Name |
Value |
Required |
---|---|---|
|
Type of the field |
Yes |
|
Unique name of the attribute to use to transfer the value of the field inside a call to the API |
Yes |
|
Human readable title for the user |
Yes |
|
Human readable description for the user |
No |
|
Boolean indicating if the field is required |
No |
|
Boolean indicating if the field is a readonly
(or computed) field.
Default if omitted is |
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
(forinteger
andfloat
fields): Displays a slider tool ranging between themin
andmax
settings.hours
(forfloat
fields): The floating point number is interpreted as a time duration measured in hours, and displayed in hours and minutes. E.g. the float value3.5
displays 3 hours and 30 minutes, the float value3.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:
Name |
Value |
---|---|
|
Identifier for the resource |
|
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 |
Required | |
text |
Tekst |
- |
String |
|
picture |
Afbeelding |
Max file size: 10 MB |
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 |
Required | |
emotion |
Hoe voel jij je? |
- |
Choice: |
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 |
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:
Name |
Value |
Required |
---|---|---|
|
Chart type (one of |
Yes |
|
Human readable chart title. This will be displayed above the chart. |
Yes |
|
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 |
|
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
orfloat
) in a bar chart, the field must have amin
of at least 0. This prevents the bar chart from going below thex
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 |
|
|
Used for |
---|---|---|---|---|
|
|
(none) |
(none) |
Each entry is a data point |
|
|
Each day is the average or sum of all entries on that day. |
||
|
|
(none) |
(none) |
Each entry is a single data point, with the Y position showing the choice option selected. |
|
|
(none) or |
|
Each day is a stacked bar; each section of the stack counts a choice option. |
|
|
Four bars show the hours
0-6, 6-12, 12-18, 18-24.
This is a stacked bar, as
for the |
||
|
(none) or |
|
Each day is the average or sum of all entries on that day. |
|
|
|
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.)