Interoperability

[NoelDeMartin]

I've been looking at the data generated by Understory Garden, and I think the structure could be improved to favor interoperability with other apps.

Here's the data within a turtle file for a test note I created:

<#concept> <https://understory.coop/vocab/garden#noteBody> "[{\"children\":[{\"text\":\"Ok, let's see what this is all about...\"}]},{\"children\":[{\"text\":\"\"}]},{\"children\":[{\"text\":\"Ain't that nice!!\"}]}]".

Looking at this, I realize that his is actually a json-encoded of some data structure created by Understory, but I have no way of knowing what this format is because the page at https://understory.coop/vocab/garden#noteBody doesn't exist. I'm also not sure where the rest of the data is, for example the title of the note.

The <#concept> doesn't have a rdfs:type definition either, so that means it cannot be declared in the type index for other apps to discover. They have to know that the data is under /private/apps/understory/garden. And I pressume if I changed to location of these files in my POD, the application wouldn't work anymore.

I wasn't sure if this should be classified as a "bug" or a "feature request", so feel free to change the label. But personally I think Interoperability is super important in the Solid ecosystem and it should be one of the main design goals, not an afterthought. Of course, it cannot be perfect and there'll always be things that can be improved. But I think that at least the type index and working vocabs are a minimum.

[ianconsolata]

Lets keep this as a bug, cause I agree it"s pretty high priority. Travis just went on paternity leave, so I'm still getting up to speed on our backlog but can take a look when I have time.

Right now, we use SlateJS, and just store the SlateJS JSON in the #noteBody predicate field. We are only now starting to think about interoperability, and I think that means we will likely start serializing the data in a more widely used format (lots of other tools seems to really like Markdown for this).

What the recommended way to deploy vocab? I want to setup a config-as-code repo to CD out vocab definitions somewhere, but I know the URLs should be permanent so can't think of a good, open place to host them. We're in the middle of another name change, so hosting them on our site is waiting on us finding a more permanent home.

We haven't used the type index stuff yet, but if you have the time to sit down for a bit and explain to me how it works I'd be happy to make sure we're compatible with it.

[NoelDeMartin]

Thanks @ianconsolata!

Markdown seems a good choice, although I'm not sure how you could achieve some advanced features that are not supported by markdown. But yes, I also think markdown is great :).

What the recommended way to deploy vocab? I want to setup a config-as-code repo to CD out vocab definitions somewhere, but I know the URLs should be permanent so can't think of a good, open place to host them. We're in the middle of another name change, so hosting them on our site is waiting on us finding a more permanent home.

I'm probably not the most suitable person to answer this, because I don't have any experience making vocabs. But as far as I know, the only requirement is that the urls don't change (or if they change, you should properly implement redirects from the old ones). That way, people browsing data created with your app can understand it by following the links. And if your app becomes popular an indie developer will be able to implement their own interoperable app. I'm not sure how important it is that machines can also understand it.

I have been thinking about doing my own vocab, and the idea I have so far is that I'll have the files in a github repo and host it using Github Pages. You can use a custom subdomain for this, so you could for example serve it at vocab.understory.garden. That way you can also change the hosting if you don't want to use Github Pages in the future.

As per the actual implementation, I still haven't done it, but I'll be happy to share my solution once I do it :). In the meanwhile, you can see how schema.org does it. It looks too complicated in my opinion, so I'll probably do something simpler (they also have very different requirements, of course).

We haven't used the type index stuff yet, but if you have the time to sit down for a bit and explain to me how it works I'd be happy to make sure we're compatible with it.

I'm also no expert in this area, but I've used it in my apps and seems like it's working (I haven't heard any complaints from real experts :D).

The gist of it is that when a user logs in, you'll read their profile and find existing containers with the type of data that your application is interested in. You can find those in the documents listed in solid:privateTypeIndex and solid:publicTypeIndex (in the same way that you should read pim:storage to know where to store data, I don't know if you're already doing that). If they exist, you should use those containers. If they don't, you should register the ones you create in those files. And personally I think you should also ask for confirmation before creating any containers, even better, ask them where they want the container to be created. But the UX can be challenging for users who are not familiar with Solid. That's why I'm not doing this in all my apps yet.

Let me know if you have any other doubts, or you can also bring this up in the gitter or forum. In case you're interested, this is how I did it in one app.