Okay/Spec: Difference between revisions

Line 11:

* Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. Other benefits include allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.

* Authentication works by just signing every request with a key that gets generated by the client on first use.

== the warning (Hot Chip album) ==

This standard is '''deeply unserious'''. It is also '''deeply in progress'''. Implement at your own peril.

== conventions ==

Line 24:

Line 27:

Connections in Okay <span class="should">should</span> happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).

A typical connection to an never before seen space usually goes like this:

A typical connection to a never before seen space usually goes like this:

* The user hands the client a URI to examine;

Line 30:

Line 33:

* If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new key pair and registers itself with the space’s registration endpoint;

* Once everyone’s happy, the client can begin posting messages to rooms.

== processing documents ==

Much of the Okay protocol involves retrieving documents and scanning them for special markup.

=== michaelformats ===

The Okay Standard introduces a number of HTML patterns known as '''michaelformats'''. These are identical in concept to (and heavily plagiarise from) [https://microformats.org/wiki/Main_Page microformats].

=== looking for stuff ===

=== linking to stuff ===

Links in Okay follow the same rules as in standard HTML.

When a client encounters a URI with a fragment, it must search for an element with a matching <code>id</code> in the linked document. If the specified element is present, the client must not scan the document for the desired markup, and instead consider the linked element to be the desired markup. If multiple instances of the same <code>id</code> exist in the document, the client must ignore all but the first instance. todo: make this make sense

== spaces ==

Line 49:

Line 65:

==== ok-space ====

Spaces are declared using the '''ok-space''' ~~micro-format~~. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:

Spaces are declared using the '''ok-space''' [[Okay#michaelformats|michaelformat]]. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:

Line 111:

Line 127:

The '''Room Directory''' is a list of every room contained within the space. This list <span class="may">may</span> be [[Okay#pagination|paginated]].

The ~~path to~~ the space's room directory <span class="must">must</span> be ~~defined~~ in its [[Okay#~~the element thereof~~|~~discovery element~~]] ~~with~~ the <code>ok-rooms</code> rel value.

The URI of the space's room directory <span class="must">must</span> be linked in its [[Okay#ok-space|ok-space]] element using the <code>ok-rooms</code> rel value.

Here's an example of what a room directory might look like:

Line 120:

Line 136:

<li><a href="/rooms/evil" class="ok-room">Evildoing Room (evil)</a></li>

</ul>

</main></syntaxhighlight>

</main></syntaxhighlight>A room directory is just a

=== sections ===

@@ Line 11: / Line 11: @@
 * Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. Other benefits include allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.
 * Authentication works by just signing every request with a key that gets generated by the client on first use.
+== the warning (Hot Chip album) ==
+This standard is '''deeply unserious'''. It is also '''deeply in progress'''. Implement at your own peril.
 == conventions ==
@@ Line 24: / Line 27: @@
 Connections in Okay <span class="should">should</span> happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).
-A typical connection to an never before seen space usually goes like this:
+A typical connection to a never before seen space usually goes like this:
 * The user hands the client a URI to examine;
@@ Line 30: / Line 33: @@
 * If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new key pair and registers itself with the space’s registration endpoint;
 * Once everyone’s happy, the client can begin posting messages to rooms.
+== processing documents ==
+Much of the Okay protocol involves retrieving documents and scanning them for special markup.
+=== michaelformats ===
+The Okay Standard introduces a number of HTML patterns known as '''michaelformats'''. These are identical in concept to (and heavily plagiarise from) [https://microformats.org/wiki/Main_Page microformats].
+=== looking for stuff ===
+=== linking to stuff ===
+Links in Okay follow the same rules as in standard HTML.
+When a client encounters a URI with a fragment, it must search for an element with a matching <code>id</code> in the linked document. If the specified element is present, the client must not scan the document for the desired markup, and instead consider the linked element to be the desired markup. If multiple instances of the same <code>id</code> exist in the document, the client must ignore all but the first instance. todo: make this make sense
 == spaces ==
@@ Line 49: / Line 65: @@
 ==== ok-space ====
-Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:
+Spaces are declared using the '''ok-space''' [[Okay#michaelformats|michaelformat]]. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:
 <syntaxhighlight lang="html"><nav class=“ok-space”>
@@ Line 111: / Line 127: @@
 The '''Room Directory''' is a list of every room contained within the space. This list <span class="may">may</span> be [[Okay#pagination|paginated]].
-The path to the space's room directory <span class="must">must</span> be defined in its [[Okay#the element thereof|discovery element]] with the <code>ok-rooms</code> rel value.
+The URI of the space's room directory <span class="must">must</span> be linked in its [[Okay#ok-space|ok-space]] element using the <code>ok-rooms</code> rel value.
 Here's an example of what a room directory might look like:
@@ Line 120: / Line 136: @@
      <li><a href="/rooms/evil" class="ok-room">Evildoing Room (evil)</a></li>
    </ul>
-</main></syntaxhighlight>
+</main></syntaxhighlight>A room directory is just a
 === sections ===