Specification
Background information
In order to implement libraries for new languages (e.g. blockstack.ts or blockstack.go) it would really help to have clear specifications of the different parts (auth tokens, profiles, zone files, key derivation, storage, etc), maybe also architecture diagrams.
Currently the specification is in an unclear state, mainly defined by code spread around the project. Also due to JavaScript’s lack of types it’s in many cases unclear whether a type is needed or not.
This is a really big and important topic, since it defines how all the different parts of the ecosystem are supposed to work together. This is certainly not a topic to discuss and resolve in a week or so, I just want to push this topic forward before it gets lost between other things.
It might make sense to split these things into smaller action items / decisions.
Previous work
- Various readmes in blockstack.js which are a good start, but currently really informal and not versioned (and also not linked anywhere I think)
- @larry opened a topic here some time ago about needs and suggestions for the auth specification.
- There are some points in the code which define a quasi-standard
- Auth requests and auth responses in blockstack.js
- The
schemaDefinitionvariables insrc/profiles/profileSchemas/in blockstack.js hold JSON schema specifications
- I wrote JSON schema specifications for some things (which might be a good start)
Desired outcome
- How should the specification look like?
- Which parts need specification?
- Who is responsible for which part?
- When should which part be completely specified?
Previously my take on this
I think it make sense to put this into an own repository (e.g. blockstack-specifications). This way we could add it as sub-module into other projects (to derive interfaces from it, etc). Developers also would have a clear location to go when searching for specifications.
This repository should define the parts of the ecosystem separately (own specifications for auth, profiles, etc), so libraries that don’t need a part can only take the ones needed. Libraries then would state things like
This library implements Blockstack Authentication in
v1.2.3and Blockstack Profiles inv4.5.6.
I think using JSON schema makes sense here. The current parts mostly exchange data using JSON objects, for what JSON schema is the quasi-standard to specify properties. It’s supported by many other languages and is also used for specifying profiles.
Changing these specifications should have a clear formal way of proposing new things, as these may affect multiple other parts. It should be clear what’s part of the specification and what’s not, and probably most important what’s part of which version.