move new elements to top-level of schema

finos · May 20, 2022 · aaad6d5 · aaad6d5
1 parent 58a0e7f
commit aaad6d5
Show file tree

Hide file tree

Showing 2 changed files with 164 additions and 122 deletions.
diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml
@@ -428,8 +428,14 @@ components:
             $ref: '#/components/schemas/Intent'
         hostManifests:
           $ref: '#/components/schemas/HostManifests'
-        interopUse:
-          $ref: '#/components/schemas/InteropUse'
+        raiseIntent:
+          $ref: '#/components/schemas/RaiseIntent'
+        raiseIntentForContext:
+          $ref: '#/components/schemas/RaiseIntentForContext'
+        userChannels:
+          $ref: '#/components/schemas/UserChannels'
+        appChannels:
+          $ref: '#/components/schemas/AppChannels'
     Application:
       description: >
         Defines an application retrieved from an FDC3 App Directory, which can
@@ -543,9 +549,13 @@ components:
             $ref: '#/components/schemas/NameValuePair'
         intents:
           type: array
-          description: >
-            The list of intents implemented by the Application as defined by
+          description: >-
+            The list of intents that the Application listens for and resolves as defined by
             https://github.com/FDC3/Intents/blob/master/src/Intent.yaml
+            Primarily used to implement intent resolution in a Desktop Agent, but may also be used, 
+            for example in an app catalog UI, to find apps that 'interoperate with' other apps.
+            An Application MUST use the Desktop Agent's `addIntentListener` API to add an intent listener
+            for each intent listed here as soon as possible after it starts up.
           items:
             $ref: '#/components/schemas/IntentV1'
     AllApplicationsResponse:
@@ -785,70 +795,81 @@ components:
       additionalProperties:
         x-additionalPropertiesName: Language tag
         $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers.
-    InteropUse:
+    RaiseIntent:
       type: object
       description: >-
-        Optional metadata that describes how the application uses FDC3 APIs (beyond intents it listens for, 
-        which are defined under the `intents` element). This metadata may be used, for example in an app catalog UI, 
-        to find apps that 'interoperate with' other apps or to advertise app channels or intents that the application
-        use to other app developers and desktop assemblers. 
-        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual FDC3 API 
-        use MAY vary from what is described.
+        Optional metadata that describes which Intents are raised by the application and context types they are 
+        raised with.
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise intents that the application uses. 
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
+      additionalProperties:
+        x-additionalPropertiesName: Intent name
+        type: array
+        description: Context types that the intent may be raised with
+        items:
+          type: string
+    RaiseIntentForContext:
+      type: array
+      description: >-
+        Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow the user to 
+        select an intent from those that are available via the Desktop Agent. 
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise intents that the application uses.
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
+      additionalProperties:
+      items:
+        type: string
+    UserChannels:
+      type: object
+      description: >-
+        Describes the application's use of context types on User Channels.  
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise contexts that the application uses. 
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
       properties:
-        raisesIntents:
-          type: object
-          description: Intents that are raised by the application and contexts they are raised with.
-          additionalProperties:
-            x-additionalPropertiesName: Intent name
-            type: array
-            description: Context types that the intent may be raised with
-            items:
-              type: string
-        raisesContexts:
+        broadcast:
           type: array
-          description: >-
-            Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow 
-            the user to select an intent from those that are available via the Desktop Agent.
+          description: Context types that are broadcast by the application
           items:
             type: string
-        userChannels:
-          type: object
-          description: Describes the application's use of context types on User Channels
-          properties:
-            broadcast:
-              type: array
-              description: Context types that are broadcast by the application
-              items:
-                type: string
-            listen:
-              type: array
-              description: Context types that the application listens for
-              items:
-                type: string
-        appChannels:
+        listen:
           type: array
-          description: Describes the application's use of App Channels
+          description: Context types that the application listens for
           items:
-            type: object
-            required:
-              - name
-            properties:
-              name:
-                type: string
-                description: The name of the App Channel
-              description:
-                type: string
-                description: A description of how the channel is used
-              broadcast:
-                type: array
-                description: Context types that are broadcast by the application on the channel
-                items:
-                  type: string
-              listen:
-                type: array
-                description: Context types that the application listens for on the channel
-                items:
-                  type: string
+            type: string
+    AppChannels:
+      type: array
+      description: >-
+        Describes the application's use of App Channels.
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise App channels and contexts that the application creates and uses. 
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
+      items:
+        type: object
+        required:
+          - name
+        properties:
+          name:
+            type: string
+            description: The name of the App Channel
+          description:
+            type: string
+            description: A description of how the channel is used
+          broadcast:
+            type: array
+            description: Context types that are broadcast by the application on the channel
+            items:
+              type: string
+          listen:
+            type: array
+            description: Context types that the application listens for on the channel
+            items:
+              type: string
   examples:
     FDC3WorkbenchAppDefinition:
       value:

diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml
@@ -428,8 +428,14 @@ components:
             $ref: '#/components/schemas/Intent'
         hostManifests:
           $ref: '#/components/schemas/HostManifests'
-        interopUse:
-          $ref: '#/components/schemas/InteropUse'
+        raiseIntent:
+          $ref: '#/components/schemas/RaiseIntent'
+        raiseIntentForContext:
+          $ref: '#/components/schemas/RaiseIntentForContext'
+        userChannels:
+          $ref: '#/components/schemas/UserChannels'
+        appChannels:
+          $ref: '#/components/schemas/AppChannels'
     Application:
       description: >
         Defines an application retrieved from an FDC3 App Directory, which can
@@ -543,9 +549,13 @@ components:
             $ref: '#/components/schemas/NameValuePair'
         intents:
           type: array
-          description: >
-            The list of intents implemented by the Application as defined by
+          description: >-
+            The list of intents that the Application listens for and resolves as defined by
             https://github.com/FDC3/Intents/blob/master/src/Intent.yaml
+            Primarily used to implement intent resolution in a Desktop Agent, but may also be used, 
+            for example in an app catalog UI, to find apps that 'interoperate with' other apps.
+            An Application MUST use the Desktop Agent's `addIntentListener` API to add an intent listener
+            for each intent listed here as soon as possible after it starts up.
           items:
             $ref: '#/components/schemas/IntentV1'
     AllApplicationsResponse:
@@ -643,7 +653,7 @@ components:
             type: string
           description: >-
             A comma separated list of the types of contexts the intent offered by the application can process,  
-            where the first part of the context type is the namespace e.g."fdc3.contact", "org.symphony.contact"
+            where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact"
         resultType:
           type: string
           description: >-
@@ -704,7 +714,7 @@ components:
     LaunchDetails:
       description: >-
         The type specific launch details of the application. These details are intended to be 
-        vendor-agnostic and _MAY_ be duplicated or overridden by details provided in the hostManifests 
+        vendor-agnostic and MAY be duplicated or overridden by details provided in the hostManifests 
         object for a specific host.
       oneOf:
         - $ref: '#/components/schemas/WebAppDetails'
@@ -785,70 +795,81 @@ components:
       additionalProperties:
         x-additionalPropertiesName: Language tag
         $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers.
-    InteropUse:
+    RaiseIntent:
       type: object
       description: >-
-        Optional metadata that describes how the application uses FDC3 APIs (beyond intents it listens for, 
-        which are defined under the `intents` element). This metadata may be used, for example in an app catalog UI, 
-        to find apps that 'interoperate with' other apps or to advertise app channels or intents that the application
-        use to other app developers and desktop assemblers. 
-        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual FDC3 API 
-        use MAY vary from what is described.
+        Optional metadata that describes which Intents are raised by the application and context types they are 
+        raised with.
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise intents that the application uses. 
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
+      additionalProperties:
+        x-additionalPropertiesName: Intent name
+        type: array
+        description: Context types that the intent may be raised with
+        items:
+          type: string
+    RaiseIntentForContext:
+      type: array
+      description: >-
+        Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow the user to 
+        select an intent from those that are available via the Desktop Agent. 
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise intents that the application uses.
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
+      additionalProperties:
+      items:
+        type: string
+    UserChannels:
+      type: object
+      description: >-
+        Describes the application's use of context types on User Channels.  
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise contexts that the application uses. 
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
       properties:
-        raisesIntents:
-          type: object
-          description: Intents that are raised by the application and contexts they are raised with.
-          additionalProperties:
-            x-additionalPropertiesName: Intent name
-            type: array
-            description: Context types that the intent may be raised with
-            items:
-              type: string
-        raisesContexts:
+        broadcast:
           type: array
-          description: >-
-            Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow 
-            the user to select an intent from those that are available via the Desktop Agent.
+          description: Context types that are broadcast by the application
           items:
             type: string
-        userChannels:
-          type: object
-          description: Describes the application's use of context types on User Channels
-          properties:
-            broadcast:
-              type: array
-              description: Context types that are broadcast by the application
-              items:
-                type: string
-            listen:
-              type: array
-              description: Context types that the application listens for
-              items:
-                type: string
-        appChannels:
+        listen:
           type: array
-          description: Describes the application's use of App Channels
+          description: Context types that the application listens for
           items:
-            type: object
-            required:
-              - name
-            properties:
-              name:
-                type: string
-                description: The name of the App Channel
-              description:
-                type: string
-                description: A description of how the channel is used
-              broadcast:
-                type: array
-                description: Context types that are broadcast by the application on the channel
-                items:
-                  type: string
-              listen:
-                type: array
-                description: Context types that the application listens for on the channel
-                items:
-                  type: string
+            type: string
+    AppChannels:
+      type: array
+      description: >-
+        Describes the application's use of App Channels.
+        This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other 
+        apps or to advertise App channels and contexts that the application creates and uses. 
+        The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage 
+        MAY vary from what is described.
+      items:
+        type: object
+        required:
+          - name
+        properties:
+          name:
+            type: string
+            description: The name of the App Channel
+          description:
+            type: string
+            description: A description of how the channel is used
+          broadcast:
+            type: array
+            description: Context types that are broadcast by the application on the channel
+            items:
+              type: string
+          listen:
+            type: array
+            description: Context types that the application listens for on the channel
+            items:
+              type: string
   examples:
     FDC3WorkbenchAppDefinition:
       value: