microforms is a file type (application/microforms) designed to expose REST endpoints.

The syntax, inspired by kotlin, is designed to intermingle data (text) with control (hypertext) more ergonomically (compared to HTML or JSON).

Like HTML, it defines a set of affordances (e.g. links, forms, imports, etc, designed to be isomorphic to HTML) and is typically used with a client side library that follows instructions sent by the server.

  // Ah, interesting, kindaof looks like JSON ...
  foo: "foo",
  hello: "world",
  // This is where things get interesting: introducing, form {}.
  action: form {
    method: "POST",
    input { name: "content", required: true }


Microforms are designed to describe REST APIs. Here is a longer example:

  type: "Blog",
  blogPost: [{
    type: "BlogPosting",
    id: 1,
    title: "hello world",
    get: a { href: "/posts/1"}
  }, {
    type: "BlogPosting",
    id: 2,
    title: "foo bar",
    get: a { href: "/posts/2"}
  create: form {
    method: "POST",
    action: "/create",
    input { name: "title", type: "text", required: true }
    input { name: "content", type: "text", required: true }
    input { name: "author", type: "text", required: true }

And here is how a client (in this specific example, a javascript client) would interact:

// No out-of-band information needed to construct a request to create a post.
// Everything is embedded into the message.
// The client knowns how to follow links (a) and submit forms (form).
let post = await fetch("/blog.micro").then(posts => posts.create({
  title: "hello",
  content: "world",
  author: ""

Which returns:

  type: "BlogPosting",
  id: 4,
  title: "hello",
  content: "world",
  author: "",
  delete: form {
    action: "/posts/4"
    method: "DELETE",
  update: form {
    method: "POST",
    input { name: "content", type: "text", required: true }

With the magic of HATEOAS, submitting a microform gets you another microform, with new exciting data and affordances!

// For example, say you disliked it, you can update it ...
  content: "Actually, nevermind."

// ... or delete it ...
// ...

Shared Semantics

Like HTML, microforms isn’t opinionated about JSON conventions nor schemas / ontologies. As a layered data format, it is designed to enable innovation to happen in that space without recompilation of the parsers / binaries. Here is an example of what it could look like if you are into JSON-LD and

  @context: "",
  @type: "Blog",
  @id: "/",
  title: "Sam's blog",
  blogPost: [{
    @type: "BlogPosting",
    title: "Welcome",
    content: "This is my first post!"
  potentialAction: form {
    @type: "CreateAction",
    input { name: "title", required: true }
    input { name: "content", required: true }


It comes with some common control structures, borrowed from HTML for ease of use. For example:

  • a
  • link
  • form
  • input
  • select
  • option
  • meta
  • fieldset

As well as some additional ones to enable contemporary APIs to be written:

  • group
  • data loading
  • validation

A lot of control structures are also available outside of the context of the file format, which gives clients of microforms more instructions on how to proceed. These are:

  • Accepts-Vocab: for vocabulary negotiation
  • Bearer tokens: for key management
  • Throttling: for quota management

Extension mechanism

We are still exploring some options, but it is clear that we need to support some sort of extension mechanism. Something along the lines of:

  namespace { id: "oauth", url: "" }
  type: "Error",
  messsage: "Oops, you have to be signed-in to access this resource",
  retry: [oauth:signin] {
    [oauth:authorization]: "",
    [oauth:scopes]: {
      "write.calendar": "modify your calendar events",
      "write.calendar": "access your calendar events",


TODO(goto): write this down. Looks something like JSON + {} nodes + comments.

Related Work

  • hydra
  • atom
  • swagger
  • alps
  • siren
  • swagger
  • json-home
  • rsdl
  • wadl
  • blueprint
  • restdesc
  • wsdl
  • hal


  • TODO(goto): fill this up

HTML Comment Box is loading comments...