Widgets, the spec

api/widgets/definitions/api_error.yaml

@@ -0,0 +1,41 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: WidgetApiErrorResponse
+description: |-
+  Schema definition for an error response in the Widget API. This is a regular ``WidgetApiResponse``
+  object with the ``response`` specified as follows.
+allOf:
+  - $ref: "./api_response.yaml"
+properties:
+  response:
+    type: object
+    title: WidgetErrorResponseData
+    description: |-
+      The response data.
+    properties:
+      error:
+        type: object
+        title: WidgetApiError
+        description: |-
+          Information about the error that happened.
+        properties:
+          message:
+            type: string
+            description: |-
+              Human-readable string for the cause of the error.
+            example: "Failed to process request: Server returned 500 error"
+        required: ['message']
+    required: ['error']

api/widgets/definitions/api_request.yaml

@@ -0,0 +1,55 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: WidgetApiRequest
+description: |-
+  Schema definition for a widget request object over the Widget API.
+properties:
+  api:
+    type: string
+    enum: [fromWidget, toWidget]
+    description: |-
+      The API for which the request is to be sent over.
+    example: "fromWidget"
+  requestId:
+    type: string
+    description: |-
+      An opaque string which uniquely identifies the request in the context of the session.
+    example: "generated-id-1234"
+  action:
+    type: string
+    description: |-
+      The action to send to the other party. Custom actions can be sent using the Java package
+      naming convention as a namespace.
+    example: "com.example.say_hello"
+  widgetId:
+    type: string
+    description: |-
+      The widget's ID.
+    example: "20200827_WidgetExample"
+  data:
+    type: object
+    description: |-
+      The request data.
+    additionalProperties: true
+    example: {
+      "request-param": "value"
+    }
+required:
+  - api
+  - requestId
+  - action
+  - widgetId
+  - data

api/widgets/definitions/api_response.yaml

@@ -0,0 +1,51 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: WidgetApiResponse
+description: |-
+  Schema definition for a widget response object over the Widget API.
+
+  .. Note::
+     This is intentionally designed to allow API users to copy the request object
+     verbatim and simply append their ``response``.
+
+allOf:
+  - $ref: "./api_request.yaml"
+properties:
+  response:
+    type: object
+    description: |-
+      The response data.
+    additionalProperties: true
+    example: {
+      "response-param": "value"
+    }
+  # We define other properties from the api_request.yaml schema to override their descriptions
+  # for context purposes
+  api:
+    type: string
+    enum: [fromWidget, toWidget]
+    description: The API the request was sent over.
+    example: "fromWidget"
+  requestId:
+    type: string
+    description: The request ID supplied in the original request.
+    example: "generated-id-1234"
+  action:
+    type: string
+    description: The action which was invoked.
+    example: "com.example.say_hello"
+required:
+  - response

api/widgets/definitions/capabilities_action.yaml

@@ -0,0 +1,32 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: CapabilitiesActionBase
+properties:
+  api:
+    type: string
+    enum: ["toWidget"]
+    description: "" # The enum will result in this being "Must be $0"
+    example: "toWidget"
+  action:
+    type: string
+    enum: ["capabilities"]
+    description: "" # The enum will result in this being "Must be $0"
+    example: "capabilities"
+  data:
+    type: object
+    description: |-
+      An empty data object (no request parameters).
+    example: {}

api/widgets/definitions/capabilities_action_request.yaml

@@ -0,0 +1,22 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: CapabilitiesActionRequest
+description: |-
+  Schema definition for a ``toWidget`` API request with action of ``capabilities``.
+allOf:
+  - $ref: "./api_request.yaml"
+  - $ref: "./capabilities_action.yaml"
+properties: {}

api/widgets/definitions/capabilities_action_response.yaml

@@ -0,0 +1,37 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: CapabilitiesActionResponse
+description: |-
+  Schema definition for a response to a ``CapabilitiesActionRequest``.
+allOf:
+  - $ref: "./api_response.yaml"
+  - $ref: "./capabilities_action_request.yaml"
+properties:
+  response:
+    type: object
+    description: |-
+      The response data.
+    title: CapabilitiesActionResponseData
+    properties:
+      capabilities:
+        type: array
+        items:
+          type: string
+        description: |-
+          The list of requested capabilities. An empty array indicates that no capabilities are
+          requested.
+        example: ["m.capabilitity.screenshot", "m.sticker"]
+    required: ['capabilities']

api/widgets/definitions/content_loaded_action.yaml

@@ -0,0 +1,32 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: ContentLoadedActionBase
+properties:
+  api:
+    type: string
+    enum: ["fromWidget"]
+    description: "" # The enum will result in this being "Must be $0"
+    example: "fromWidget"
+  action:
+    type: string
+    enum: ["content_loaded"]
+    description: "" # The enum will result in this being "Must be $0"
+    example: "content_loaded"
+  data:
+    type: object
+    description: |-
+      An empty data object (no request parameters).
+    example: {}

api/widgets/definitions/content_loaded_action_request.yaml

@@ -0,0 +1,22 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: ContentLoadedActionRequest
+description: |-
+  Schema definition for a ``fromWidget`` API request with action of ``content_loaded``.
+allOf:
+  - $ref: "./api_request.yaml"
+  - $ref: "./content_loaded_action.yaml"
+properties: {}

api/widgets/definitions/content_loaded_action_response.yaml

@@ -0,0 +1,27 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: ContentLoadedActionResponse
+description: |-
+  Schema definition for a response to a ``ContentLoadedActionRequest``.
+allOf:
+  - $ref: "./api_response.yaml"
+  - $ref: "./content_loaded_action_request.yaml"
+properties:
+  response:
+    type: object
+    description: |-
+      An empty response body to acknowledge the request.
+    example: {}

api/widgets/definitions/custom_data.yaml

@@ -0,0 +1,31 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: CustomWidgetData
+description: |-
+  Definition for a widget's ``data`` when using a ``type`` of ``m.custom`` or using an
+  unknown/unsupported ``type``. Currently no requirements are specified.
+properties:
+  url:
+    type: string
+    description: |-
+      The URL for the embedded content. Required only if the widget's URL does not match
+      the embedded content, before templating ocurrs.
+
+      Clients should note that not all widgets which get interpretted as custom widgets
+      will have this property, though all widgets are required to have a higher level ``url``
+      which can be used to display them. As such, requirements for this field being present
+      SHOULD only be enforced upon widgets with an explicit ``type`` of ``m.custom``.
+    example: "https://matrix.org"