Help From Aaron Bradley

After I syndicated to Twitter, Aaron Bradley provided some examples which helped move me further down the road.

Recall: I’m trying to build a data model for logging one’s experience reading a text. The goal would be that, for any reading, one can have a directed graph a graphical representation of one’s reading experience, emitted.

Bradley provided a wonderful demonstration of using JSON-LD in the “Real World.”

  1. Start with a standard JSON bloc
  2. Set a @context. That is, the leading IRI which will provide the source of classes. Typically classes are expressed as e.g. or
  3. It’s worth pointing out that has a ton of (from an OO-perspective) classes to describe things.
  4. Then, use the @type special key to specify which class a given JSON Object is meant to describe.
  5. As we can see, the outer-most Object is a ReadAction. Looking at its web page, we see that it supports a number of attributes, notably an object which is the primordial Thing.
  6. However, because a Book is a sub-type of Thing, we use our friend the @type key to specify that the ReadAction was about a Book.
  7. Same logic for the agent key as above
  8. All told, we come up with a JSON-LD object that looks like the following
  "@context": "",
  "@type": "ReadAction",
  "agent": {
    "@type": "Person",
      "name": "Steven Harms",
      "url": ""
  "startTime": "2017-04-13T09:36:32+00:00",
  "endTime": "2018-09-28T18:54:46+00:00",
  "object": {
    "@type": "Book",
    "name": "Harry Potter and the Philosopher’s Stone",
    "author": {
        "@type": "Person",
        "name": "J.K. Rowling",
        "sameAs": "",
        "url": ""

This gets me closer to my goal:

  "@type": "AnnotatedReading",
  "reading": "...ReadAction from above...",
  "annotations": [

Bradley went on to suggest that my annotations might benefit by conforming to the W3C’s specification for annotations. I was already planning on following that path. Support for this model has been well communicated and ubiquitous since I started.

So, at present, the question is:

  1. How do I build a vocabulary of classes and attributes like what has listed. I know that means writing a vocabulary, but I’m not sure how to take that on. I’d like to use JSON-LD to define the schema, if possible. Other than that, I think my best option is to use SKOS or RDFs
  2. How can I provide an on-the-fly ability to update the items in the vocabulary. For example a philosophy reader might come up with a “MultipartPhilosophyClassification” e.g. History which contains a list of order-significant terms like “ClassificationElement” e.g. World History, Folk History, Non-Reflective History. I’m us9ing Hegel’s “Introduction to the Philospohy of History” as a test-case in addition to “Harry Potter” as a check on my modeling.

Anyway, the researching continues.