Subject: [apps-discuss] Automated specification generation tools

From: Phillip Hallam-Baker <[email-masked]>
Date: Tue, 22 Mar 2016 15:48:15 -0400

A while back I described a tool that I have been using as a code
generator for JSON based applications. I have extended the tool since
to the point where it almost (but not quite) writes the specification
for you.

The tool bundle itself is open source (MIT license, GitHub) and
available from here:

http://www.prismproof.org/downloads.html

I am now working on some documentation and an example of a spec
produced using the tool chain. This is one of the specs I have
produced:

https://tools.ietf.org/html/draft-hallambaker-lurk-01

Normally when you write a specification, there is a huge amount of
back and forth as changes to the spec cause examples to be out of
sync. Or you change the text in one place but not another. And of
course it all gets worse if someone else writes stuff that has to be
merged in.

So what tends to happen is that the editor spends a lot of time
checking the spec for consistency after each change and then reviewers
do the same and then the spec goes out with some last minute change
and you end up with errata.

Alternatively, the spec is 100% right but someone's implementation is
wrong. And because that is the implementation everyone has to interop
with you end up with two specs, the one that was written and the
defacto one you have to implement.

The Protogen toolset is a suite of code building tools. They allow you
to build specifications, examples and reference code from a single
source. So any changes to that source automatically ripple through the
spec. And anyone who does interop testing against the reference
implementation can be fairly sure that they have done it right.

Right now the tool set is (mostly) targeted at writing JSON specs but
I have developed tools that I use with RFC 821 and RFC 822 style
encodings, TLS schema and ASN.1 as well. These are only intended to
support existing IETF specs though rather than develop more of the
same.

So the way I developed the LURK spec above in three days (i.e 24 man
hours, not pulling three all nighters in a row) was that I started off
describing the protocol in Word, then I roughed out the set of
examples I wanted to produce to describe the spec, then I developed
the schema from those. The second day, I worked on the Word
documentation again, got the examples running with only request
messages being generated. The third day I implemented the server
dispatch function to give me the responses.

If you prefer, you can use Markdown instead of Word. I am just in the
middle of converting to Carsten's particular variant of the markup.

This isn't just a quicker and less error prone way to write specs. The
same tools generate C so you can integrate with existing
implementations.

The resulting specifications are a lot better than those you get
writing by hand as well. Instead of different parts of the spec being
written in a variety of styles, there is one consistent style applied
throughout.

The question now is what should that style be?