adding docs from soapdog's patchfox about common ssb message schemas

[rabble]

Soapdog wrote some really night documentation for commons ssb message schemas as part of patchfox. I keep searching for message schema examples and find them hard to find. So i'm adding them here to the handbook because i think a lot of people want to see what some optional de facto schemas are as used in scuttlebutt apps.

[arj03]

For of all thanks for taking your time on this.

This is just a personal opinion but I think the protocol guide should only include things related to the actual protocol not application specific message types. This kind of information would fit better in https://github.com/ssbc/dev.scuttlebutt.nz.

[arj03]

Looping in @soapdog

[boreq]

This is just a personal opinion but I think the protocol guide should only include things related to the actual protocol not application specific message types.

I think this is a good idea as this section has a potential of being quite large and listing very obscure content formats. That being said I think it would be useful to at least have a short section linking to a different document which lists various content formats in the main protocol guide under https://ssbc.github.io/scuttlebutt-protocol-guide/#message-format. It could be a side note with a link like it is in the case of other specs.

[rabble]

@arj03 What I was thinking was that the conventions around messages and their schema are pretty standard, widely implemented, and needed to understand how scuttlebutt works in practice. For example, this document referrers to contact messages, pubs, and posts but doesn't directly cover what the schema is. Having a link from where we reference those to the section of the document about them would be really helpful for people coming up to speed on ssb. I think it'd be useful to have a set of links to all the message formats on dev.scuttlebutt.nz site as well. But i think it's helpful to have a subset here. Perhaps remove blog post as it's the one not widely supported type in included.

I also think there should be some more documentation about how blobs are referenced from other messages as mentions. There's a lot on how they work, how to request them, but not how they're connected to other parts of the ecosystem.

[arj03]

Right, an example in blobs for how they are referenced would be good. Pub & contact messages already have examples as you say and I agree that linking from those section to a spec would be good. They are quite important for how the protocol works, so that makes sense. With that said http://scuttlebot.io/ should be deprecated imo, we already have documentation scattered too many places.

[mixmix]

For ahau i have been making a repo per spec. I think that's the level of space we should be making for each thing.

Eg

• follow schemas
• pub schemas (invite, pub announce)
• thread schemas (post, vote)

I til one detailed source for each, then maybe little samples elsewhere as needed but referencing repos

[soapdog]

Hey folks, glad people find my docs useful 😻

My suggestion would be to add them to https://dev.scuttlebutt.nz, and then add an aside link to them on the protocol guide.

Also Patchfox documentation is online for those who want to check it out without installing the add-on.