Add documentation for embed entity

docs/_entities/embed.md

@@ -0,0 +1,69 @@
+---
+title: Embed
+---
+
+This entity represents the embed information about an URL that should be
+embedded, it is nested in a [StatusMessage][status_message]. To embed a URL
+means to keep an embedded representation or a preview of a third party
+resource referenced by the URL inside the status message.
+
+* If this entity is present, the receiving server should only embed the included
+`url` and not search for other URLs to embed.
+* If the included `url` is a
+trusted oEmbed provider, the server should query the oEmbed data.
+* If `title`, `description` or `image` are missing, the server should query the
+information from the URL (oEmbed or OpenGraph).
+* If `nothing` is `true` the server should not embed any URLs.
+
+A link to the embedded resource should also be included in the `text` of the
+[StatusMessage][status_message] for accessibility reasons, otherwise it could
+happen that some people don't see the link, for example when this entity isn't
+implemented or where no embeds are supported at all. However, it is possible
+that the link in the `text` and the `url` here are different, because some sites
+have different URLs in `og:url` as requested.
+
+## Optional Properties
+
+All properties are optional, but either `url` is required or `nothing` must be `true`.
+
+| Property      | Type (Length)            | Description                           |
+| ------------- | ------------------------ | ------------------------------------- |
+| `url`         | [URL][url] (65535)       | The URL that should be embedded.      |
+| `title`       | [String][string] (255)   | The title of the embedded URL.        |
+| `description` | [String][string] (65535) | The description of the embedded URL.  |
+| `image`       | [URL][url] (65535)       | The image of the embedded URL.        |
+| `nothing`     | [Boolean][boolean]       | `true` if nothing should be embedded. |
+
+## Example
+
+### Only `url`
+
+~~~xml
+<embed>
+  <url>https://example.org/</url>
+</embed>
+~~~
+
+### With metadata
+
+~~~xml
+<embed>
+  <url>https://example.org/</url>
+  <title>Example Website</title>
+  <description>This is an example!</description>
+  <image>https://example.org/example.png</image>
+</embed>
+~~~
+
+### With `nothing`
+
+~~~xml
+<embed>
+  <nothing>true</nothing>
+</embed>
+~~~
+
+[string]: {{ site.baseurl }}/federation/types.html#string
+[url]: {{ site.baseurl }}/federation/types.html#url
+[boolean]: {{ site.baseurl }}/federation/types.html#url
+[status_message]: {{ site.baseurl }}/entities/status_message.html

docs/_entities/status_message.md

@@ -24,6 +24,7 @@ This entity represents a reshare of a status message. It inherits from [Post][po
 | `photo`                 | [Photo][photo]s        |    ✔     | The attached Photos of the status message, the `status_message_guid` and the `author` need to match the status message. |
 | `poll`                  | [Poll][poll]           |    ✘     | The attached Poll of the status message.                                                                                |
 | `event`                 | [Event][event]         |    ✘     | The attached Event of the status message.                                                                               |
+| `embed`                 | [Embed][embed]         |    ✔     | The Embed information of an URL that should be embedded in the status message.                                          |
 
 ## Examples
 
@@ -47,12 +48,12 @@ This entity represents a reshare of a status message. It inherits from [Post][po
   <guid>c3893bf029e7013487753131731751e9</guid>
   <created_at>2016-07-11T22:50:18Z</created_at>
   <text>I am a very interesting status update</text>
+  <public>true</public>
   <location>
     <address>Vienna, Austria</address>
     <lat>48.208174</lat>
     <lng>16.373819</lng>
   </location>
-  <public>true</public>
 </status_message>
 ~~~
 
@@ -64,6 +65,7 @@ This entity represents a reshare of a status message. It inherits from [Post][po
   <guid>e05828d029e7013487753131731751e9</guid>
   <created_at>2016-07-11T22:52:56Z</created_at>
   <text>I am a very interesting status update</text>
+  <public>true</public>
   <photo>
     <guid>0788070029e8013487753131731751e9</guid>
     <author>alice@example.org</author>
@@ -86,7 +88,6 @@ This entity represents a reshare of a status message. It inherits from [Post][po
     <height>480</height>
     <width>800</width>
   </photo>
-  <public>true</public>
 </status_message>
 
 ~~~
@@ -99,6 +100,7 @@ This entity represents a reshare of a status message. It inherits from [Post][po
   <guid>378473f029e9013487753131731751e9</guid>
   <created_at>2016-07-11T23:00:42Z</created_at>
   <text>I am a very interesting status update</text>
+  <public>true</public>
   <poll>
     <guid>2a22d6c029e9013487753131731751e9</guid>
     <question>Select an answer</question>
@@ -115,7 +117,24 @@ This entity represents a reshare of a status message. It inherits from [Post][po
       <answer>Maybe</answer>
     </poll_answer>
   </poll>
+</status_message>
+~~~
+
+### With [Embed][embed]
+
+~~~xml
+<status_message>
+  <author>alice@example.org</author>
+  <guid>378473f029e9013487753131731751e9</guid>
+  <created_at>2016-07-11T23:00:42Z</created_at>
+  <text>I am a very interesting status update</text>
   <public>true</public>
+  <embed>
+    <url>https://example.org/</url>
+    <title>Example Website</title>
+    <description>This is an example!</description>
+    <image>https://example.org/example.png</image>
+  </embed>
 </status_message>
 ~~~
 
@@ -128,6 +147,7 @@ This entity represents a reshare of a status message. It inherits from [Post][po
   <created_at>2016-07-11T23:02:24Z</created_at>
   <provider_display_name>mobile</provider_display_name>
   <text>i am a very interesting status update</text>
+  <public>true</public>
   <photo>
     <guid>0788070029e8013487753131731751e9</guid>
     <author>alice@example.org</author>
@@ -171,7 +191,12 @@ This entity represents a reshare of a status message. It inherits from [Post][po
       <answer>Maybe</answer>
     </poll_answer>
   </poll>
-  <public>true</public>
+  <embed>
+    <url>https://example.org/</url>
+    <title>Example Website</title>
+    <description>This is an example!</description>
+    <image>https://example.org/example.png</image>
+  </embed>
 </status_message>
 ~~~
 
@@ -186,3 +211,4 @@ This entity represents a reshare of a status message. It inherits from [Post][po
 [photo]: {{ site.baseurl }}/entities/photo.html
 [poll]: {{ site.baseurl }}/entities/poll.html
 [event]: {{ site.baseurl }}/entities/event.html
+[embed]: {{ site.baseurl }}/entities/embed.html