After I wrote about federated bookshelves again two weeks ago, I decided to build a proof of concept. A proof of concept for providing an OPML file that contains a list of books, in a way that can be parsed by others. I roughly follow Tom Critchlow’s “spec”.
Because I am making up my own data attributes (although I follow where possible), I decided to not just create an OPML list, but also to add an XSL template so that OPML is not just machine readable but also human readable in a browser.

The general idea is I have a list that contains lists of books. A list of books can contain books directly, or only be a link to that list of books. A list of books can be one of my own lists on my own domain, or it can be a list published by someone else on a different web address. This allows me to point to other people’s lists when it is somehow relevant to me.

A book in a list I provided with data attributes like title, author and urls for the book and author, and again fields pointing to other people, like the url for the list I may have found the book, or the url for the person / review which was my recommendation.

This allows discovery for both you and me. It makes it work like social software: in triangles, where you can navigate from a person, to a piece of content (a book or list), and to a piece of metadata which is itself the url of another list, or the url of another person, that then have their own metadata pointing to others etc.

Because my lists are structured opml, I should be able to automatically create list files from my own book notes.

Let’s have a look at the proof of concept:
I have an OPML file, called ‘books.opml

At the top of that screenshot you can see the opml file calls a XSL stylesheet, named test. I created it by adapting the similar set-up I have for my OPML blogroll. Because of that stylesheet the book list is human readable in a browser and looks like this:

What you see is first some info about me as the creator of the list. It has a link to this list, which is my main list, and a link to my site.
Below it is a list of book lists.

  • The first of those book lists, called ‘Fiction I read in 2021’ doesn’t have its own url, and the books are shown directly. Those books may have a link to the book, to the author, some notes, or a link to who recommended it to me, or in which list I found it. It also has a short list description at the top.
  • Underneath it is another list by me, called ‘Current non-fiction anti-library’, that is just linked.
  • Underneath that are two lists, created by Tom Critchlow and Tom Macwright, both of which are just links. The list item in the outline has an author attribute, and if it’s not my name it gets shown as a ‘followed’ book list. Theoretically if an external link is an OPML file itself, I could include it and show it right here.

Now if you click my other book list, the anti-library list (read here what an anti-library is), that is another opml file.

It calls the same XSL stylesheet as the other list, and renders in the browser as

What you can see in this second list is that it starts with the same link to the main list and info about me, and then shows how the list itself has both a URL and a description. It contains books, and see how one of those books has a link to the book itself. (I don’t link to Amazon or Goodreads, so won’t have links for most books, only if there’s a link to the publisher’s or author’s page on that book)
In the description of the last book you also see how it has a link to the list (Tom Macwright’s) in which I found it, as well as a link to a posting that served as recommendation for me.

For now what I like is that these lists bring their own viewer with it (your browser using my stylesheet), and can point to other people’s lists both directly as a list in my own collection, or as a reference for one of the books. Without having to make assumptions about other people’s lists or parse them somehow, it still allows connecting to them (federating), and discovery. My own lists use terms for book lists (collection) and books (book). Three attributes I cannot place within terms, at least not without adding additional subnodes in the outline: author url, reference list (url of the list I found a book in), and reference url (the person or posting that recommended the book to me).

UPDATE: I described the data structure for booklists I used.

1 annotations of "Federated Bookshelf Proof of Concept"

This blogpost has 1 annotations in! See annotations

33 reactions on “Federated Bookshelf Proof of Concept

  1. @x28de yes, it is. Thanks, I realise I had postponed the decision on what to put in ‘text’, title, author or both. In a next step I probably should also move some of the other attributes in underlying outline nodes. And a question is what of the things I’d want to use are and aren’t defined in other w3 namespaces. Now the choices are mine, so not to spec as such.

  2. This is great!

    Can you subscribe to an OPML list directly in an RSS reader? Feedly doesn’t seem to subscribe to this list…

    My limited understanding of OPML was that it contained lists of RSS feeds – but I may well be missing something.

    Either way – this is great exploration and thanks for going down this rabbit hole!

    • OPML is for outlines, basically building tree structures of any type of content and data, viewed/manipulated in an outliner. I also use outlines e.g. to create and structure talks. They could be anything though, in the 1968 mother of all demo’s Douglas Engelbart uses an outliner to create and organise a shopping list. Using it as a list of RSS feeds is one specific use case, which allows import/exporting lists in rss readers. Because an opml file is an outline, you can group elements together e.g. the folders I separate my RSS feeds in.

      The OPML spec doesn’t itself describe subscription. It does allow for inclusion: if an outline element points to an opml file, that opml file’s outline should be included from that node. This makes it possible to adopt someone else’s opml outline of books, or another one of my own, as a branch on my own tree structured opml outline. If you do that not just statically, replicating it once, but would do it dynamically, pulling in a branch whenever it is getting viewed, or by comparing your version to the current external one, you are de facto subscribed.

      Inoreader some years ago implemented subscribing to opml outlines : The functionality for it was created by Marjolein Hoekstra and she blogged a lengthy description of opml ‘subscriptions’ and lots of other opml facets at

  3. @ton Hi Tom. This is very cool! I’m curious though about your thoughts on the terms machine readable and federated.I’ve always interpreted machine readable as requiring semantic encoding, but I don’t see that in your data.Is there something I’m missing, or do you have a different view of machine readability? Something else?

Comments are closed.