Support multiple app names/media types in a webapp share

Author: glpatcern

IETF-OCM.md

@@ -1235,23 +1235,57 @@ described in [OCM-IP].
     token in a form field named `access_token` (see
     [Resource Access](#resource-access)).  The shared secret MUST NOT
     be exposed to the browser and MUST NOT appear in any URI.
-  - OPTIONAL appName (string)
-    A human-friendly name of the web application, to be used in user
-    interfaces when referring to this Share.
+  - OPTIONAL apps (array of objects)
+    The web applications available at the Sending Server to access
+    the Shared Resource.  This is useful in particular when the
+    Resource is a folder, whose files can be opened by different web
+    applications depending on their format.  If present, the array
+    MUST NOT be empty and MUST NOT contain more than one entry per
+    given `name`.  Each entry contains:
+    - REQUIRED name (string) - A human-friendly name of the web
+      application, to be used in user interfaces when referring to
+      this Share.
+    - REQUIRED mediaTypes (array of strings) - The media types (MIME
+      types) that this web application can handle.  The array MUST
+      NOT be empty.  This can be any media type entries from the IANA
+      Media Type registry.  The receiver MAY use this as a hint for UI
+      or routing decisions, e.g. to show which web application opens
+      a given file, and MAY ignore values it does not understand.
+      Unlike `appIconHint`, this describes formats the web
+      application can open rather than the share-level icon hint.
+      [RFC6838]
+
+    The order of the entries MAY be used by the Sending Server to
+    express a preference: when multiple web applications can handle
+    the same media type, the receiver SHOULD consider the first
+    matching entry as the default one.  All web applications listed
+    are accessed through the same `uri`, `sharedSecret`, `targets`,
+    `permissions` and `requirements`.  Example:
+
+    ~~~
+            "apps": [
+              {
+                "name": "HedgeDoc",
+                "mediaTypes": ["text/markdown", "text/html"]
+              },
+              {
+                "name": "Collabora",
+                "mediaTypes": [
+                  "application/vnd.oasis.opendocument.text",
+                  "application/vnd.oasis.opendocument.spreadsheet"
+                ]
+              }
+            ]
+    ~~~
+    {: type="json"}
   - OPTIONAL appIconHint (string)
     A string in the form of a media type (MIME type) that describes the
     share as a whole, primarily intended as a way for the receiving
     server to select an appropriate local icon for the share.  This is
     display metadata and MUST NOT be interpreted as fetchable or
-    executable content.  It does not need to appear in `mediaTypes`, but
-    SHOULD describe the primary shared resource. [RFC6838]
-  - OPTIONAL mediaTypes (array of strings)
-    An array of media types (MIME types) the webapp server can handle.
-    This can be any media type entries from the IANA Media Type
-    registry.  The receiver MAY use this as a hint for UI or routing
-    decisions, and MAY ignore values it does not understand.  Unlike
-    `appIconHint`, this describes formats the webapp can open rather
-    than the share-level icon hint. [RFC6838]
+    executable content.  It does not need to appear in any of the
+    `apps` media types, but SHOULD describe the primary shared
+    resource. [RFC6838]
 * Protocol details for `ssh` MAY contain:
   - OPTIONAL accessTypes (array of strings) - The type of access
     being granted to the remote resource.  If omitted, it defaults to
@@ -2868,6 +2902,11 @@ version in the IETF datatracker.  It is meant to ease the review
 process and it shall be removed when going to RFC last call.
 The complete changelog is updated in the OCM-API GitHub repository.
 
+## Version 08
+* Introduced an `apps` array in the `webapp` protocol payload, listing
+  the available web applications each with the media types it can
+  handle.  It replaces the `appName` and `mediaTypes` properties.
+
 ## Version 07
 * Required the `keyid` signature parameter and that it matches the
   `kid` of the verification key in the signer's JWK Set.

spec.yaml

@@ -848,25 +848,45 @@ components:
                     describes the share as a whole, primarily intended as a way for
                     the receiving server to select an appropriate local icon for the
                     share. This is display metadata and MUST NOT be interpreted as
-                    fetchable or executable content. It does not need to appear in
-                    `mediaTypes`, but SHOULD describe the primary shared resource.
-                appName:
-                  type: string
-                  description: >
-                    An optional human-friendly name of the web application to be used
-                    in user interfaces when referring to this share.
-                mediaTypes:
+                    fetchable or executable content. It does not need to appear in any
+                    of the `apps` media types, but SHOULD describe the primary shared
+                    resource.
+                apps:
                   type: array
-                  description: >
-                    An optional array that describes the media (MIME) types that the
-                    webapp server can handle. This is a hint for receiver UI and
-                    routing decisions, and receivers MAY ignore values they do not
-                    understand. Unlike `appIconHint`, this describes formats the
-                    webapp can open rather than the share-level icon hint.
                   minItems: 1
-                  uniqueItems: true
+                  description: >
+                    An optional array of the web applications available at the
+                    Sending Server to access the shared resource, useful in particular
+                    when the resource is a folder whose files can be opened by different
+                    web applications. The array MUST NOT contain more than one entry per
+                    given `name`. The order of the entries MAY express a preference:
+                    when multiple web applications can handle the same media type, the
+                    receiver SHOULD consider the first matching entry as the default one.
+                    All listed web applications are accessed through the same `uri`,
+                    `sharedSecret`, `targets`, `permissions` and `requirements`.
                   items:
-                    type: string
+                    type: object
+                    required:
+                      - name
+                      - mediaTypes
+                    properties:
+                      name:
+                        type: string
+                        description: >
+                          A human-friendly name of the web application to be used
+                          in user interfaces when referring to this share.
+                      mediaTypes:
+                        type: array
+                        minItems: 1
+                        uniqueItems: true
+                        description: >
+                          The media (MIME) types that this web application can handle.
+                          This is a hint for receiver UI and routing decisions, and
+                          receivers MAY ignore values they do not understand.
+                          Unlike `appIconHint`, this describes formats the web
+                          application can open rather than the share-level icon hint.
+                        items:
+                          type: string
             ssh:
               type: object
               properties:
@@ -933,11 +953,16 @@ components:
                 requirements:
                   - must-use-mfa
                   - must-exchange-token
-                appName: HedgeDoc
                 appIconHint: text/markdown
-                mediaTypes:
-                  - text/markdown
-                  - text/html
+                apps:
+                  - name: HedgeDoc
+                    mediaTypes:
+                      - text/markdown
+                      - text/html
+                  - name: Collabora
+                    mediaTypes:
+                      - application/vnd.oasis.opendocument.text
+                      - application/vnd.oasis.opendocument.spreadsheet
               ssh:
                 accessTypes: ["datatx"]
                 uri: extuser@cloud.example.org:/7c084226-d9a1-11e6-bf26-cec0c932ce01