json-api · hhware · May 1, 2015
diff --git a/faq/index.md b/faq/index.md
@@ -39,7 +39,8 @@ interchange format itself.
 
 ### How to discover resource possible actions? <a href="#how-to-discover-resource-possible-actions" id="how-to-discover-resource-possible-actions" class="headerlink"></a>
 
-You should use the OPTIONS HTTP method to discover what can be done with a
+If resource-level member `"actions"` is not provided by the server,
+you should use the OPTIONS HTTP method to discover what can be done with a
 particular resource. The semantics of the methods returned by OPTIONS is defined
 by the JSON API standard.
 

diff --git a/format/index.md b/format/index.md
@@ -192,6 +192,8 @@ In addition, a resource object **MAY** contain any of these top-level members:
   relationships (described below).
 * `"meta"`: non-standard meta-information about a resource that can not be
   represented as an attribute or relationship.
+* `"actions"`: a list of actions, which the client can perform on 
+  the given resource.
 
 Here's how an article (i.e. a resource of type "articles") might appear in a document:
 
@@ -378,6 +380,51 @@ The `comments` relationship is simpler: it just provides a related resource URL
 to fetch the comments. The URL can therefore be specified directly as the
 attribute value.
 
+#### Actions <a href="#document-structure-resource-actions" id="document-structure-resource-actions" class="headerlink"></a>
+
+Member `"actions"` contains list of actions which the client can perform 
+on the given resource. If provided, it **MUST** account for authentication
+and authorization status of the current client and for other pertinent 
+circumstances in order to provide a list of actions which the given client 
+is actually allowed to perform on the given resource at the moment when 
+the response is being built by the server.
+
+Its value **MUST** be an array of action objects, each including at least 
+the following members:
+
+* `"label"`: a string, identifying the given action,
+* `"href"`: an endpoint for performing the given action.
+
+In addition, each action object **MAY** include the following members:
+
+* `"method"`: contains name of HTTP method corresponding to the given action.
+* `"meta"`: contains non-standard meta-information about the action.
+
+For example,
+
+```
+// ...
+{
+  "type": "articles",
+  "id": "1",
+  "title": "Rails is Omakase",
+  "actions": [{
+    "label": "FETCH",
+    "href": "http://example.com/articles/1",
+    "method": "GET"
+  },{
+    "label": "DISCARD",
+    "href": "http://example.com/articles/1",
+    "method": "DELETE"
+  },{
+    "label": "PUBLISH",
+    "href": "http://example.com/articles/1/publish",
+    "method": "POST"
+  }]
+}
+// ...
+```
+
 ### Compound Documents <a href="#document-structure-compound-documents" id="document-structure-compound-documents" class="headerlink"></a>
 
 To reduce the number of HTTP requests, servers **MAY** allow responses that