About the Docs

Tutorial

In these docs, we implement Diátaxis style documentation. This means all documentation pages can be classified into one of

Tutorial - Quick hands on learning material
How-to - Practical guides for achieving certain aims
Reference - Technical reference documentation
Explanation - Discussions of best practices and tradeoffs

Next to each page in the sidebar, you’ll see one of those tags which tells you what kind of documentation to expect there.

JSON Specification

In these docs we make extensive use of JSON schemas to define the API interface. We use the following types:

String = text i.e. ”value”
Integer = Integer number
Float = Floating Point number
Bool = Boolean i.e. true
List<T> = list of type T
Object<T> = JSON object named T, which is defined elsewhere
Optional<T> = T may or may not be present
Nullable<T> = can be T or null
Enum<T> = an enumeration named T
Uuid = A valid UUID. See the spec (this will be a String in the JSON)

An example might be

{
  "a_string": String,
  "a_number": Float,
  "a_bool": Bool,
  "a_list": List<Integer>,
  "an_object": Object<SomeObject>,
  "an_option": Option<String>,
  "nullable": Null<String>
}

Where SomeObject is

{
  "key": String
}

An instance of this object could be

{
  "a_string": "Hello!",
  "a_number": 654.3,
  "a_bool": true,
  "a_list": [12,11],
  "an_object": {
    "key": "I'm some text!"
  },
  "nullable": null
}

Enum<T> will appear as String, but Naurt makes a guaranteed that only certain strings will ever appear in that field. For example, we might define Enum<Pet> as

cat
dog
goldfish

This means that a JSON with this field

{
  "pet": Enum<Pet>
}

an example would be

{
  "pet": "cat" // or "dog" or "goldfish" but NEVER "shark"
}