Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Things JSON Coder

This repo contains a Swift file that allows the creation of the JSON required to be passed to the json command of Things’ URL scheme.


To install, download the ThingsJSON.swift file and add it as a source file to your own project. Alternatively, this repo can be cloned as either a real or fake submodule inside your project.


This code is written with Swift 4.

Getting Started

The Things JSON Container

The top level object that will be encoded into the JSON array is the TJSContainer. This object contains an array of the items to be included in the JSON.

Model Classes

The following Things model classes can be encoded into JSON:

  • Todo
  • Project
  • Heading
  • ChecklistItem

Container Enums

There are two wrapper enums used to package objects into arrays. Associated values are used to hold the above model objects inside. These enums exist to allow more than one type of object inside an array while retaining type safety. They also handle the encoding and decoding of heterogeneous types within an array to and from JSON.

  • TJSContainer.Item – This enum has cases for todo and project objects. Only todo and project items can exist at the top level array in the JSON.

  • TJSProject.Item – This enum has cases for todo and heading objects. Only todo and heading objects can be items inside a project.


Dates should be formatted according to ISO8601. Setting the JSON encoder’s dateEncodingStrategy to ThingsJSONDateEncodingStrategy() is the easiest way to do this (see example below).


Create two todos and a project, encode them into JSON and send to Things’ add command.

let todo1 = TJSTodo(title: "Pick up dry cleaning", when: "today")
let todo2 = TJSTodo(title: "Pack for vacation",
                    checklistItems: [TJSChecklistItem(title: "Camera"),
                                     TJSChecklistItem(title: "Passport")])

let project = TJSProject(title: "Go Shopping",
                         items: [.heading(TJSHeading(title: "Dairy")),
                                 .todo(TJSTodo(title: "Milk"))])

let container = TJSContainer(items: [.todo(todo1),
do {
    let encoder = JSONEncoder()
    encoder.dateEncodingStrategy = ThingsJSONDateEncodingStrategy()
    let data = try encoder.encode(container)
    let json = String(data: data, encoding: .utf8)!
    var components = URLComponents(string: "things:///add-json")!
    let queryItem = URLQueryItem(name: "data", value: json)
    components.queryItems = [queryItem]
    let url = components.url!, options: [:], completionHandler: nil)
catch {
    // Handle error


This code is released under the MIT license. See LICENSE for details.


Helper classes to create the JSON required for the Things URL scheme




No releases published


No packages published


You can’t perform that action at this time.