Created: 2011-07-15 15:33
Updated: 2013-10-06 17:58

doctorj: JSON messaging doc generator


I like building systems made up of loosely coupled components that send messages to each other. There's a bunch of ways to serialize messages these days.

I like using JSON for message serialization. It's cross-language, it expresses lists and maps in a human readable manner. Javascript likes it. There's no tooling to setup.

The downside is that it's hard to document your JSON APIs once you have something you like. Validating incoming messages is also a pain. Lots of boilerplate.

JSON schema can help with the validation problem. But writing JSON schema files by hand is a drag.

Orderly simplifies writing JSON schema, but you have to write individual files for each message. My APIs may have 20-30 operations. That's a lot of files!

I wanted to write one Markdown file to document my API and have it generate a human readable HTML doc and JSON schema files I can use to validate messages in my app.

That's what doctorj does.


  • Write one Markdown file to document your JSON API.
  • Inline Orderly blocks per-message you wish to document
  • Run doctorj
  • Get a human readable API doc in HTML format
  • Get a JSON schema file for each Orderly block


Say you have this Markdown file:

foo api


## overview ##

The foo system lets you do great things.

## messages ##

### message: foo_request ###

object {
  string name;
  string description?;
  string homepage /^http:/;
  integer {1500,3000} invented;

### message: foo_response ###

object {
  string status;
  string description?;

And you run doctorj:

src/ \
     --outdir=out \
     --orderly=/Users/james/bitmechanic/orderly.js/bin/node-orderly2jsonschema \

Then in the out dir you'll find:



You need to install some stuff:

pip install markdown
git clone
install a recent version of node (tested with 0.4.8 on macos)

Sorry, the node/orderly.js dependency is a drag. The C version of orderly wasn't working for me.

JSON Schema Implementations


syntax in markdown file

  • In your Markdown file use ~~~~{.orderly} to start an orderly block
  • Each block must be preceeded by: message: [name]
  • [name] is used to name the generated .json files
  • In the above example, message: foo_response becomes out/foo_response.json

html templates

  • Use the --template switch to tell doctorj to use your HTML template file when merging in the Markdown output
  • If you omit this switch, a hardcoded template will be used (see to view it)
  • Currently templates can contain two tokens:
  • {{ CONTENT }} - Will be replaced with the output from your .md file
  • {{ DATE }} - Will be replaced with the current date/time


  • Use the --clean switch to tell doctorj to remove all files in your --outdir directory before generating new output
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more