Knowboard v0.1

While this blog has been pretty quiet since I first posted my thoughts on Markdown Linked Data I’ve been iterating on the tools I use for it as part of my daily workflow, and have finally packaged up an initial release of what I’m now calling Knowboard.

Knowboard adds editor support for working with Markdown Linked-Data files through the Language Server Protocol. The initial release includes a Knowboard VS Code extension, but support for other editors like Zed and NeoVim is in-progress.

What happened to the UI?

My earlier prototypes focused on Kanban-style planning boards, which while flashier I found that I kept wanting better features for navigating and editing the Markdown source files. I was using Markdown-Oxide to add editor support for navigating [[Wiki-Links]] syntax between documents, but I wanted similar features for the RDF frontmatter, so I ended up shifting my focus to that.

Knowboard now runs as an editor extension for adding a number of features for working with RDF in Markdown (as well as additional RDF data files). While the Knowboard tutorial goes into more detail, some of the highlights are:

• auto-complete RDF properties and references
• linking RDF subjects to navigate quickly between documents
• hover preview for subjects using RDF properties
• exposes a SPARQL endpoint for querying data
• schema & shape definitions used for validation, as well as completion and previews

Re-shaping planning boards

One of the other hurdles with the planning boards was some challenges with how to define the queries for building them. Initial versions used SPARQL SELECT queries which return a simple row/column result. They’re pretty straightforward, and fairly familiar to SQL users, but also lose some information about where the data originated from. In order to implement features like drag & drop or editing fields, I needed to know which property to modify. This was implemented by parsing the SPARQL query and trying to extract where the source would be. It worked for basic queries, but had some limitations.

Some of the issues related to preserving type information from the data to help deciding how to format things like a date, or displaying an image based on properties in the RDF. Others came up when there might be ambiguity about which property was used for a value. Like if you wanted to allow looking up alternative properties like allowing either schema:name or rdfs:label to be used for a title, depending on which one was defined. The SELECT query doesn’t return this kind of information.

I spent some time experimenting with SPARQL’s CONSTRUCT queries instead, which return the query result as RDF, allowing it to preserve additional structure. While CONSTRUCT still doesn’t implicitly address returning the source of a value, I had come up with some patterns for explicitly specifying queries that would provide it. This did help in some situations, though added a lot of verbosity, and left it to the query author to redundantly provide information about the source of a value.

This never quite felt right so I left it stagnate for a while while I focused on the editor extension. As I did, I started working more with SHACL as a format for specifying the properties a type is expected to have. This initially helped provide better type-aware auto-complete suggestions. (E.g. if an ActionItem should have a project: property specified, completing the property name, but also completing the IDs of projects for the value.)

The next big transitions was to start augmenting the SHACL shapes with DASH Property Roles to provide annotations on how to display properties. This is now used to provide the hover previews by specifying what properties to use as the label, description, or other key fields based on the type of the record.

Now, this association between the “shape” definition and what fields to display seems like an ideal mapping to how records should be presented in a planning board. I need to revisit this and work out some of the details, but conceptually for a planning board you may specify something like:

• type: ActionItem — selecting the type of items to include in the board
• subject: dash:LabelRole — what to show as the main label for the cards
• assignee: dash:KeyInfoRole — specify additional fields to show in the card details
• status: knowboard:GroupRole — custom roles specific to the planning board layout

For the Knowboard hover previews, I already implemented SHACL shape lookups to take a shape definition and find property values, which I should be able to build on for building a new board-view as well.

However, I’m also trying to decide on how to present UIs going forward. The early prototypes were implemented as a separate web app that would scan the local files. In VS Code, extensions can provide Markdown preview enhancements which could be a way to present board definitions in the Markdown. For other editors, Knowboard may still need to provide some kind of separate web UI for interacting with features like this that would require a more graphical output that doesn’t work within a text editor.

For the moment I’m still focusing on improving the Knowboard documentation, and providing more introductory materials about how to use Knowboard, but the shape definitions seem like a promising path to get back to building more interactive UIs in the future.