Smos File

A Smos file is a YAML document, for example:

version: 2.0.0
value:
- entry:
    header: Use Smos
    timestamps:
      DEADLINE: 2018-10-30
      SCHEDULED: 2018-10-21
    state-history:
    - state: STARTED
      time: 2020-05-04 03:25:45
    tags:
    - online
  forest:
  - header: Don't mess it up
    state-history:
    - state: DONE
      time: 2020-05-04 03:25:48
    - state: NEXT
      time: 2020-05-04 03:25:47
  - header: Be smart about it
    state-history:
    - state: TODO
      time: 2020-05-04 03:25:50
    tags:
    - work

It consists of a versioned forest of entries.

Versioned forest

The top-level of a smos file consists of an object with two fields: A `version` value which refers to the data format version. This is used for forward and backward compatibility. The other field is the `value` field which contains a forest of entries.

version: 1.0.0
value: [...]

(Version 0.0.0 did not have this top-level object and instead only had the contents of `value`.)

Forest of trees

A forest is a list of trees. It is parsed as a yaml list.

A tree is parsed as an entry with a subforest:

entry: 
forest:

If a tree has no subforest, then it can be represented as just an entry.

Entry

An entry consists of

A header
Contents (optionally)
Timestamps (optionally)
Properties (optionally)
Its state and state history (optionally)
Tags (optionally)
A clock logbook (optionally)

Example

header: Fix issue 25
contents: https://github.com/NorfairKing/smos/issues/25
timestamps:
  SCHEDULED: 2020-05-09
properties:
  project: smos
state-history:
- state: NEXT
  time: 2020-05-09 01:31:40
- state: TODO
  time: 2020-05-09 00:00:50
tags:
- code
- online
logbook:
- start: 2020-05-09 01:31:40
- start: 2020-05-09 00:08:20
  end: 2020-05-09 00:09:10

Yaml Schema

An entry can either be only a header, in which case it can be represented as a string:

<header>

Or it can have more fields, in which case it is an object:

header: <header>
contents: <contents>
logbook: <logbook>
timestamps: <timestamps>
state-history: <state-history>
tags: <tags>
properties: <properties>

Header

A Smos entry's header consists of a single line of text.

Headers contain a title-like piece of information about an entry.

Yaml Schema

def: Contents
<string>

Example

'Go to the gym: HITT class'

A Smos entry's contents consist of an arbitrary piece of text.

Contents contain details about an entry.

Yaml Schema

def: Contents
<string>

Timestamps

A Smos entry's timestamps are a map of timestamp names to timestamps. Timestamps contain time-based information about an entry.

Timestamp names are arbitrary pieces of text without whitespace.

Standard timestamps are, for example:

BEGIN
END
SCHEDULED
DEADLINE

A timestamp has two possible granularities:

The day level
The moment level

Example

SCHEDULED: 2020-05-09

Yaml Schema

<key>: 
  def: Timestamp
  # any of
  [ def: Day
    # %F
    <string>
  , def: LocalTime
    # %F %T%Q
    <string>
  ]

Properties

A Smos entry's properties are a map of property names to property values. Properties contain named pieces of information about an entry. Property names are arbitrary pieces of text without whitespace. Property values are arbitrary pieces of text without newlines.

Properties can be used to filter entries by.

Standard properties are, for example:

timewindow
brainpower
client

Example

project: smos

Yaml Schema

<key>: 
  def: PropertyValue
  <string>

State and state history

A Smos entry can have a state. States contain information about the state of an entry. States are arbitrary pieces of text without whitespace.

The state history must appear in reverse chronological order.

Standard states are, for example:

WAITING
TODO
STARTED
READY
NEXT
FAILED
DONE
CANCELLED

A Smos entry also remembers its entire state history.

Example

- state: NEXT
  time: 2020-05-09 01:31:40
- state: TODO
  time: 2020-05-09 00:00:50

Yaml Schema

def: StateHistory
# In reverse chronological order
- def: StateHistoryEntry
  # any of
  [ # StateHistoryEntry
    state: # required
      # new state
      # or null
      def: TodoState
      <string>
    time: # required
      # time at which the state change happened
      def: UTCTime
      # %F %T%Q
      <string>
  , # StateHistoryEntry (legacy)
    new-state: # required
      # new state
      # or null
      ref: TodoState
    timestamp: # required
      # time at which the state change happened
      ref: UTCTime
  ]

Logbook

Each entry can contain information about when a clock was started on it. Clocks can either be closed (have a begin and end time) or open (only a begin time).

Logbooks are used to generate timetables.

Example

- start: 2020-05-09 01:31:40
- start: 2020-05-09 00:08:20
  end: 2020-05-09 00:09:10

Yaml Schema

def: Logbook
# Logbook entries, in reverse chronological order.
# Only the first element of this list has an optional 'end'.
- # LogbookEntry
  start: # required
    # start of the logbook entry
    def: UTCTime
    # %F %T%Q
    <string>
  end: # optional
    # end of the logbook entry
    ref: UTCTime

Full Smos file schema reference

def: SmosFile
def: Forest Entry
- def: Tree Entry
  # any of
  [ # Tree Entry
    entry: # required
      # root
      def: Entry
      # any of
      [ # only a header
        def: Header
        <string>
      , # Entry
        header: # required
          # header
          ref: Header
        contents: # optional
          # contents
          def: Contents
          <string>
        timestamps: # optional
          # default: {}
          # timestamps
          <key>: 
            def: Timestamp
            # any of
            [ def: Day
              # %F
              <string>
            , def: LocalTime
              # %F %T%Q
              <string>
            ]
        properties: # optional
          # default: {}
          # properties
          <key>: 
            def: PropertyValue
            <string>
        state-history: # optional
          # state history (legacy key)
          def: StateHistory
          # In reverse chronological order
          - def: StateHistoryEntry
            # any of
            [ # StateHistoryEntry
              state: # required
                # new state
                # or null
                def: TodoState
                <string>
              time: # required
                # time at which the state change happened
                def: UTCTime
                # %F %T%Q
                <string>
            , # StateHistoryEntry (legacy)
              new-state: # required
                # new state
                # or null
                ref: TodoState
              timestamp: # required
                # time at which the state change happened
                ref: UTCTime
            ]
        history: # optional
          # state history
          ref: StateHistory
        tags: # optional
          # default: []
          # tags
          - def: Tag
            <string>
        logbook: # optional
          # default: []
          # logbook
          def: Logbook
          # Logbook entries, in reverse chronological order.
          # Only the first element of this list has an optional 'end'.
          - # LogbookEntry
            start: # required
              # start of the logbook entry
              ref: UTCTime
            end: # optional
              # end of the logbook entry
              ref: UTCTime
      ]
    forest: # optional
      # default: []
      # subforest
      ref: Forest Entry
  , # Leaf entry
    ref: Entry
  ]

File Format Reference

Versioned forest

Forest of trees

Entry

Example

Yaml Schema

Header

Yaml Schema

Example

Contents

Yaml Schema

Timestamps

Example

Yaml Schema

Properties

Example

Yaml Schema

State and state history

Example

Yaml Schema

Tags

Example

Yaml Schema

Logbook

Example

Yaml Schema

Full Smos file schema reference