I’d like to get a discussion going about what kind of specification we need and how to get it all started. This topic was recently in the engineering meeting where we started discussing this and potential ways to do it.
I feel that this topic still needs to be discussed, also raising it here to keep track of it all.
See also here, here and here for previous discussion on this.
This topic might overlap the existing posts, but to keep this all together I think this will still be helpful.
Motivation
So to start with, I recently got back to this issue because I started to implement/port a TypeScript version of blockstack.js. I decided to fork (and not to re-implement it) to stay conform with the current ecosystem. Since TypeScript and JavaScript are similar, this isn’t a big deal. But when it comes to other languages things get tricky.
Currently the relevant parts of the existing specification live scattered around in various repositories (see the other posts for examples 
). So for a developer it’s currently not very clear how a library is supposed to interact with the ecosystem.
Goals
- Create a coherent and clear specification.
- Enable developers to easily implement libraries in new languages.
- Make sure that the parts implement the specification correctly (make sure that all are on the same page).
- Define a process for changes to the specification, so that future libraries can easily see and react accordingly to these.
Proposal
My take on this is that there are two different types of specification that we need.
First, specification that defines an interface of a component (“one way”). For example the endpoints Blockstack Core provides. This specification depends heavily on the code of Core and I agree with @aaron that the specification should live next to the code (at least in this case 
). The external developer interface of blockstack.js might be also in this category, although I’m not sure whether this needs a full-fledged specification.
Second, specification that defines how multiple parts interact with eachother (“two-way”). For example profiles, which are used by blockstack.js, Core, the explorer, etc. In this case there isn’t a clear owner (in terms of repositories) which should hold the specification. For this I’d like to propose a new repository (probably blockstack-specifications).
If we decide on this, we should make this repository to an entry point for developers who like to implement a new library. So we should explain that there are two kinds of specification, and link all other specifications (e.g. Core endpoints).
Caveats
During the engineering meeting several caveats came up that are important enough to repeat them here.
Unfortunately I only remember the one that a specification could take away the agility the team currently has.
I think that we might be still in a phase where the ecosystem changes quickly, so changing things in the specification should (for now) be really easy. We probably should mark it as draft or unstable I guess.
Though I really think that we already benefit from this, as there are now several libraries (JavaScript, TypeScript and Go). Having a place for managing changes that affect not only one library would be a big step forward. E.g. currently multiple parts define what’s a profile (Core returns these at an endpoint, blockstack.js is able to parse/generate profiles, etc). If now some of these “specifications” are contrary, there’s no way to find out who’s right.
Potential steps
For now I’d like to only target the “two-way” specifications (e.g. auth, profiles, zone files, etc).
- Find out where parts are that define these interfaces
- Compare these against eachother to compile one specification from these
- Enforce specification-conformity in the necessary projects
- Create a repository for gathering these
- Add links to other specifications (e.g. the JSON schema specifications for Core endpoints)
- Develop a process for changing the specifications
- Make it easy and fun to develop with these specifications
- Make sure that changes, which affect multiple parts, are made in this specification repository (instead of adding exceptions to multiple repositories)