Sandpiper Framework API documentation and schemas
These are the core specs for the Sandpiper Framework. More documentation and information will be added as we move this from being a behind-the-scenes effort to a fully integrated one.
Please feel free to visit us at https://sandpiperframework.net
Four eventual specifications will live here.
Currently we have the API spec, plan document schema, and database schema relatively stable and present in the repository. An out-of-date version of the documentation can be found on the Sandpiper Framework website, and will be merged here with caveats in a separate branch while we update it.
The full Sandpiper API specification is provided as an OpenAPI 3 YAML schema. It is entirely contained in sandpiper_api.yaml.
We do our proving and much of the editing in the Swagger Editor. For an offline copy, you can just download the source code of the latest release, unzip it to a local folder somewhere, and use a web browser to open the index.html file that sits in the root directory. You can also use the editor online at editor.swagger.io.
The Plan Document is an XML file that codifies the agreement between two partners, and cannot be modified without both partners approving the change. The structure of this file is governed by an XML Schema Definition (XSD), found in sandpiper_plan.xsd.
There are a handful good graphical XSD editors like Eclipse (Open Source; look for the Java and DSL Developer package), oXygen XML (proprietary), and XMLSpy (proprietary). We do all the editing at a text/source code level, to avoid artifacts, so if no graphical tool works for you, most good editors include an XSD plugin or mode.
The Database Schema is a single SQL file that contains all the data and tables for a reference database implementation in SQLite 3. To use it, you can run this file inside an SQLite .db file, and it will drop/create tables and their relationships, as well as insert valid values for things like plan status and grain type.
Many tools exist to interact with SQLite, from raw Python (natively supported) to database clients like dBeaver (open source) and the dedicated SQLite Browser (open source).
The Framework Documentation is a markdown file containing a Sandpiper technical overview, reasoning, concepts, and implementation details. A PDF copy of the last version is available here. We created this before our API work had completed, so it is missing some critical details, but the overview, reasoning, and model are all still correct.