Why did we write a KeepRight spec, part 1
Or rather, how to build the thing so other people can also build the thing.
If you’ve not had a chance to run through creating a Keep Right Declaration, I suggest you give it a quick try. Think of some thing, collection or archive you’d want preserved, either real or made up, and make a declaration for it.
This will then make a lot more sense, but you don’t have to, hopefully this is clear enough to get by without doing any homework.
At first glance it’s just a form, and if all we wanted to do was ask questions and create a declaration at the end, a html form would be the perfect thing to do, easy, job done.
However, we want other people to make be able to create Keep Right Declaration makers. Or another way around, we don’t want to be the only people who can make them, where’s the fun in that?!
Also, our maker is great for people making personal declarations but what if you’re an institution that wants to create thousands that integrate with your local DAM or CMS (Digital Asset Management & Contend Management System), where it’d be much better to build your own?
Then just an html form won’t cut it.
What you need is something that describes what the questions that make up a declaration are, and how they’re structured.
Enter; the spec: https://github.com/Deep-Keep-Group/keepright-spec
🔎 🔎 🔎
The spec is the single source of truth. The spec is a .json file so computers can pass it around and understand it. The spec is essentially a collection of items, each of which is either a thing or another collection items. This is what it looks like at the very top level.
So far the KR spec has five items in it, each one a section, and each has an id and title. If we open the first one up we see this…
…various ids, titles and descriptions, but then a whole bunch more items, only this time the items are questions.
The items could also be another section, a group, or a note, which helps divide everything up and group questions together better.
From a code point of view, it walks all the items, sees what each one is, decides what to do with it, and open it up to see if there are more items inside.
We made some demo code that does exactly that by pulling the spec directly from github; the source code lives here: https://github.com/Deep-Keep-Group/keepright-declaration-maker-demo
Runs here: https://keepright.info/demos/keepright-declaration-maker-01/
And looks like this…
…because I grew up in the 80s and have exceptional taste.
Ahem. The point being there’s enough information in the spec that you can roll your own front-end, be that in html, or direct into your DAM or CMS.
Specs made up of .json aren’t the easiest to read, so we also built the Declaration Spec Viewer which allows you to view it parsed into plain text or markdown.
The Spec is what questions need to be asked, it’s the content; I’ve written more about what happens to the spec if we change questions over here: https://keepright.info/building so it can evolve in the future, and in ways that won’t break any tools already written, more on that in a moment.
Another reason for making a spec this way, is that people can not only use it as is, but fork it, patch it, expand on it, adjust it to their own needs and make pull requests against it, while also maintaining stability with verifiable version numbers.
💻 💻 💻
To get even more technical, just for a moment.
As The Spec is the content, we also have the Schema; the latest version of which is keepright-spec.schema.json over on GitHub here: https://github.com/Deep-Keep-Group/keepright-spec/tree/main/schemas
The Schema describes the scaffolding: the framework the spec’s content lives in. It explains to code what a question, or a section, or a group is.
You can roll your own declaration maker with just the spec, the schema is the safety net if you want to double check your workings.
The idea goes something like this;
The spec may change over time, if there’s a fix to a typo or clarification it gets a patch version number bump x.x.1 👉 x.x.2. If we add, remove or change the order questions, then there’s a minor version bump x.1.x 👉 x.2.0
Major versions are a whole different kettle of fish, and probably the first time that’ll happen is when we’ve taken all the feedback and finally settled on a bump to version 1.0.0 (at time of writing we’re 0.0.5).
But!
The schema describes what can exist in the spec, so if your code is written to schema and understands; sections, groups, notes, questions and items, then it’ll keep working no matter how much the spec changes.
Until we update the schema, which’ll happen far less often than changes to the spec.
🐟 🐙 🐡
To come back to the title of this post; “Why did we write a Keep Right spec, pt1?”
The answer is ‘cause we didn’t want to keep it to ourselves, we wanted to make it as open as possible for other people to not only use the version we’d made, but go off and make their own,. To be able to easily keep up to date by tracking (or not) version numbers, or extend it themselves.
Also, to make declaration makers look however they want.
Like this underwater side scrolling version.
https://keepright.info/demos/keepright-declaration-maker-02/
📜 📜 📜
The end result of someone or a system running through making a declaration, is, well, a declaration, but in .json form.
In the same way as the spec is written to make it easy to move around systems, the declaration itself is the same. On our own website we allow people to download a declaration in a number of different formats, for both humans and robots.
But also in the same way as the spec, we do it to make things lovingly interoperable, the declaration has it’s own scheme, which I’ll cover in part two.
In the mean time, please do have a play. Suggestions, forks, implementations, let us know 😁 (especially if it’s cooler than a deep sea diver, or certainly more practical).
Dan.