Follow

For techies who want to read the ActivityPub specs 

Years ago I tried to learn ActivityPub. I succeeded, but it was difficult. I wrote this blog post which is a "what I wish I knew before trying to learn ActivityPub" guide. It is basically "how to read the specs in a way that will make them make more sense".

tinysubversions.com/notes/read

For techies who want to read the ActivityPub specs 

Was re-reading and this paragraph made me laugh.

> Is this technically 100% correct? No. But if you were the kind of person who cared about the difference between JSON-LD and JSON, you'd probably be writing your own spec right now instead of reading this article.

re: For techies who want to read the ActivityPub specs 

@darius

Do you feel like it's gotten more accessible since then (or I should say, accessible *enough*)?

re: For techies who want to read the ActivityPub specs 

@enkiv2 It has gotten better but I haven't dug in enough to say for sure exactly how much better

For techies who want to read the ActivityPub specs 

@darius Thanks! I was just sitting down to learn more about ActivityPub and fedi tech. :)

For techies who want to read the ActivityPub specs 

@darius So great, I've been looking for something like this. Thank you!

re: For techies who want to read the ActivityPub specs 

@darius thank you for sharing your notes
it's a few days since I'm diving in, and it's a little overwhelming
but I start finding my way step after step

For techies who want to read the ActivityPub specs 

@darius you are the best

For techies who want to read the ActivityPub specs 

@thisisaaronland thank you Aaron that means a lot coming from you!!

For techies who want to read the ActivityPub specs 

@darius yeah I cannot for the life of me make heads or tails of the difference between JSON and JSON-LD...

@nasser yeah as far as I can tell it is just a series of conventions that when you encounter a property named X, you should do Y with it

@darius it feels vaguely like XML schemas? which are also URLs and I guess namespaces are nice but, fundamentally this stuff is all just conventions no?

@nasser @darius the context stuff embeds typing information about what the properties refer to, so the processor can tell what's an IRI or a string literal or some other typed object etc. and it's exactly like XML schemas except we can mostly pretend that RDF never had anything to do with XML and it was all just a bad dream.

i do kind of wonder if fedi clients will handle fully baroque json-ld or are only pretending though.

@jleedev yeah I guess I'm curious as to what the "processor" is here. the implementations I've seen have all been just throwing JSON together as you would normally or parsing it normally with hard-coded rules. I haven't seen an implementation where the context gets consulted, but I'm also not well versed in this technology.

@darius if this is annoying LMK and I will take you off these mentions

@nasser You're not wrong. Approximately 0% of people care about the LD in JSON-LD other than the creators of LD

@nasser @jleedev @darius right; I'm actually kinda curious about the difference between "all the stuff JSON-LD is capable of as a standard" vs "the way JSON-LD gets used by ActivityPub and its implementations"

I get the feeling that the latter is a lot more just "a document with hyperlinks" and the ontology stuff doesn't really come into play in a serious way, but maybe I've just been looking in the wrong places

@technomancy @nasser @jleedev I've never encountered it as anything but "json with hyperlinks" in an AP context

@darius @technomancy @jleedev and, crucially, the differentiation between strings that are hyperlinks to be followed and strings that are just strings is captured directly in the software, as opposed to consulting some kind of schema in a meaningful way

@nasser @darius @technomancy @jleedev so are we saying that AP could have just used straight JSON and lost essentially nothing?

@teleclimber @nasser @darius @technomancy

JSON-LD is extensible, so if you see an unfamiliar property it *does* have a URI so you can know who/what dreamed it up, you don't have to wonder if it's eXtendedAP or APmarkII just by guessing etc.

the AP spec doesn't seem to mention JSON-LD Framing, but that is basically a way to output JSON in a predictable way for the benefit of anyone who "just wants to consume JSON"

@teleclimber @nasser @darius @technomancy nobody is going to write a fedi server that consumes the json-ld in a totally generic way, like of course you already know which fields contain hyperlinks.

but schemas *do* evolve; any time at work someone says "oh no, entity A and entity B now must be related by property P" i quietly cough 'rdf'.

we somewhat left XML in the 1990s but i think that it informs the design of specifications such as this, in a positive way.

@jleedev @teleclimber @darius @technomancy I have a background in compilers and program language theory so the schema URLs in XML and JSON-LD always felt like type annotations on unstructured data to me. what throws me is that there's no "type checker" though. I guess the URLs exist for the benefit of human beings to physically look at if they so choose?

@nasser @teleclimber @darius @technomancy

Well, there is, an @-context actually points to a jsonld resource, for instance w3.org/ns/activitystreams.json gives some types. Mostly "typed literal" (date, number) or "thing" though. Nothing about "what type of thing".

I can use the schema.org context to interpret values somewhat (having hacked up rdflib to print out what it's fetching) but it leaves a little to be desired, lat/lon are not strings with languages.

@nasser @teleclimber @darius @technomancy The statement ‘as:Announce “extends” as:Activity’ is written in prose, only. schema.org uses its own types; there's owl and rdfs and whatnot for defining those sorts of classes.

perhaps i want to say `SELECT * WHERE { ?x a/rdfs:subClassOf* schema:LocalBusiness }`, and i think i probably could.

if i say `my_social:Superfollow rdfs:subClassOf as:Follow` then maybe nobody will understand me. i don't think that's a problem anybody wants to solve.

@darius @nasser that tracks with my understanding; it's like ... a way of splitting up data into separate documents using hyperlink references?

@technomancy @darius that's neat. I suppose it provides some mechanism to differentiate between hyperlink references to be followed and random strings?

@technomancy @darius @nasser a way of creating and reusing schema and then applying them in a way that reduces to triplet subject predicate object links. so instead of just having an autonomous JSON object it can reference terms from controlled vocabularies and ideally be made interoperable. v powerful way of describing things but also of making compound concepts, actions, etc. some examples and info here: json-ld.org/

kibitzing, being a linked data nerd 

@technomancy @darius @nasser not necessarily separate - it’s more that JSON-LD can represent a graph of things linked by relations (which can be internal to a document or point outside the document) and also associate the relations with an ontology somewhere

@technomancy @nasser @darius think of being able to build composable graphs. there's 1:1 transformation with specs like RDF

@technomancy @darius @nasser JSON-LD is RDF encoded using JSON, but without mentioning the R-word since it may trigger an irrational outburst against XML for some. I think this is where the confusion arises.

For techies who want to read the ActivityPub specs 

@darius as a technical writer, I felt called out by that paragraph 😅

For techies who want to read the ActivityPub specs 

@darius ha!!

For techies who want to read the ActivityPub specs 

@darius BEAUTIFUL timing, I was literally thinking “I should go read the ActivityPub spec” a few minutes ago, and you have saved me so much pain

For techies who want to read the ActivityPub specs 

@darius using this to learn it - it's immensely helpful. thanks!

For techies who want to read the ActivityPub specs 

@darius this is super useful, thank you!!

For techies who want to read the ActivityPub specs 

@darius I just wanted to say that your express AP project has been a massive boon with trying to write a node lambda version. Thank you for that!

For techies who want to read the ActivityPub specs 

@twipped oh I'm glad to hear it!

For techies who want to read the ActivityPub specs 

@darius You don't see this kind of document very often but they're darned useful.

If nothing else there are lot of APIs out there that could use something like this to bridge the gaps between "here's all the things you can do" and "here's how to USE the API".

For techies who want to read the ActivityPub specs 

@darius Couple years ago I wanted to build an ActivityPub application

I hate to admit that I still don't really get the secret sauce of it, but it eats away at me to try looking at it again

For techies who want to read the ActivityPub specs 

@darius Ooh, neat -- I'm starting to noodle with a new library and have the spec on my To Do list, so this is super-useful. Thanks!

Sign in to participate in the conversation
Friend Camp

Hometown is adapted from Mastodon, a decentralized social network with no ads, no corporate surveillance, and ethical design.