"TypeSpec is an attempt to combine the design-first and code-first worlds into something that works across both methodologies and reduces cognitive load for designers. ... The TypeSpec approach also means a general decrease in complexity, which, for Microsoft, eases its use across the organization." -- #ChrisWood
#TechnicalWriting#APIs#APIDocumentation#AsynchronousAPIs#AsyncAPI#EventDrivenAPIs#ApacheAvro#JSON: "Luckily there's a specification similar to OpenAPI but directed at defining event-driven APIs. I'm talking about AsyncAPI. It's a specification that lets you define an API that's asynchronous in nature. By using AsyncAPI you can define, among other things, the different topics where events will be dropped, and the shape of the messages that represent each topic.
And this is where things get interesting. The shape of messages or, in other words, its payload, can adhere to specific standards. Without messages, there's no way to communicate events. And, following standards helps to guarantee the correct publishing, transport, and consumption of messages. If messages don't follow any standards, it's hard for developers to understand the shape of the messages. In addition, it's easy for consumers to stop working because, suddenly, messages are being shared in a slightly different format.
Among different message standards, there's one particularly interesting to me. Apache Avro isn't just a theoretical standard. It's also a serialization format. You can say it's a competitor to JSON but specialized in working with event-driven APIs. In the same way you can use JSON Schema to define the shape of JSON data you have Avro Schema to help you specify what Avro message payloads look like."
For #ActivityPub the question of "Why use #LinkedData?" has never been answered. There should be clear merits to wade through all the complexity that this choice brings, right?
Yes, its ultra flexible, and you can define your own semantic #ontologies, and theoretically it could provide a robust extension mechanism to AP protocol. Except that right now it doesn't.
What's the vision of a Linked Data #Fediverse? What great innovative #SocialNetworking#UX would it bring, that makes it worthwhile?
> I do not think that machine-readable specs are feasible.
Umm.. well, it depends how you interpret that. I posted in reply to @hrefna about #AsyncAPI and #EventCatalog, both ways to have more structured docs and tools for validation and codegen, etc.
"A #DataContract is a document that defines the structure, format, semantics, quality, and terms of use for exchanging data between a data provider and their consumers [..] It follows #OpenAPI and #AsyncAPI conventions".