diff --git a/docs/api/oas/openapi.yaml b/docs/api/oas/openapi.yaml
index f59350ebe9..b6a0a2843e 100644
--- a/docs/api/oas/openapi.yaml
+++ b/docs/api/oas/openapi.yaml
@@ -1,8 +1,10 @@
-# simpleStrategySchema works (and may be correct for some responses)
-# strategySchema can't render in Swagger UI. use simple for now
 # Add questions list
-# Check for $ref substitutions - see the 'required' items
-# Need to define variants schema
+# Add style guide MD. UK/US, Newspaper/Movie, JS/OAS. Nouns: UBleash, Feature Toggle. Strategy. Plurals. &. Glossary
+# Only use backticks for code samples and API paths. Use bold for schema items and italic for schema item settings
+# Move responses to root responses section in components (from schema section)
+# Issues with rendering as nested externaldocs from Swagger UI. See GET /admin​/feature-types
+# Make sure everthing from the Unleash admin documentation is incorporated or referenced
+# List questions
 openapi: 3.0.0
 servers:
   - description: Local host.
@@ -11,7 +13,7 @@ tags:
   - name: Archive
     description: Handling Feature Toggle archiving and un-archiving
   - name: Events
-    description: Idientifying events on the Unleash server
+    description: Identifying events on the Unleash server
   - name: Feature toggles
     description: Accessing feature toggles
   - name: Feature types
@@ -24,7 +26,7 @@ tags:
     description: Accessing and updating strategies
 info:
   title: Unleash API
-  description: Unleash is a open source feature flag and toggle system for all your applications and services.
+  description: Unleash is an open source feature flag and toggle system for all your applications and services.
   version: 3.5.6
   contact:
     name: The Unleash team
@@ -62,7 +64,9 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/401'
+
     post:
+      summary: Create a Feature Toggle
       description: Create a new Feature Toggle
       tags:
         - Feature toggles
@@ -72,21 +76,19 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/newFeatureToggle'
+              $ref: '#/components/schemas/featureToggleSchema'
       responses:
-        '200':
-          description: Successful response
+        '201':
+          description: Feature Toggle successfully created
+        '400':
+          description: Bad body request (for example, Feature Toggle name is not unique)
+        '401':
+          description: Not authorised
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/200'
-        '409':
-          description: Feature Toggle name is not unique
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/409'
-      summary: Create a Feature Toggle
+                $ref: '#/components/schemas/401'
+
   '/admin/features/{featureName}':
     put:
       summary: Update a Feature Toggle
@@ -101,14 +103,25 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/updateFeatureToggle'
+              $ref: '#/components/schemas/featureToggleSchema'
       responses:
         '200':
-          description: Successful response
+          description: Feature Toggle successfully updated
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
+        '400':
+          description: Bad body request (for example 'strategies' is not an array)
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
     delete:
       summary: Archive a Feature Toggle.
       description: |
@@ -118,6 +131,7 @@ paths:
       operationId: archiveFeatureToggle
       tags:
         - Feature toggles
+        - Archive
       parameters:
         - $ref: '#/components/parameters/featureNamePath'
       responses:
@@ -127,10 +141,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
   '/admin/features/{featureName}/toggle/on':
     post:
       summary: Enable a Feature Toggle.
-      description: '*featureName* must match an existing Feature Toggle.'
+      description: '**featureName** must match an existing Feature Toggle.'
       operationId: enableFeatureToggle
       tags:
         - Feature toggles
@@ -143,10 +166,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
   '/admin/features/{featureName}/toggle/off':
     post:
       summary: Disable a Feature Toggle.
-      description: '*featureName* must match an existing Feature Toggle.'
+      description: '**featureName** must match an existing Feature Toggle.'
       operationId: disableFeatureToggle
       tags:
         - Feature toggles
@@ -159,10 +191,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
   '/admin/features/{featureName}/stale/on':
     post:
       summary: Mark a Feature Toggle as 'stale' (deprecated).
-      description: '*featureName* must match an existing Feature Toggle.'
+      description: '**featureName** must match an existing Feature Toggle.'
       externalDocs:
         description: Feature Toggle types
         url: 'https://unleash.github.io/docs/feature_toggle_types'
@@ -178,10 +219,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
   '/admin/features/{featureName}/stale/off':
     post:
       summary: Mark a Feature Toggle as active.
-      description: '*featureName* must match an existing Feature Toggle.'
+      description: '**featureName** must match an existing Feature Toggle.'
       externalDocs:
         description: Feature Toggle types
         url: 'https://unleash.github.io/docs/feature_toggle_types'
@@ -197,13 +247,16 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
-        '409':
-          description: Feature Toggle name is not unique.
+        '401':
+          description: Not authorised
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/409'
-  /admin/archive/features:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
+  '/admin/archive/features':
     get:
       summary: List all the archived feature toggles on the Unleash server
       description: Archived feature toggles are those that have been previously deleted
@@ -217,6 +270,15 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Feature Toggle not found
+
   '/admin/archive/revive/{featureName}':
     post:
       summary: Un-archive a Feature Toggle
@@ -233,7 +295,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200'
-  /admin/strategies:
+        '404':
+          description: Feature Toggle not found
+
+  '/admin/strategies':
     get:
       summary: Fetch all strategies and their parameters.
       description: Fetch all strategies and their parameters.
@@ -247,6 +312,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200strategy'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+
     post:
       summary: Create Strategy
       description: Create Strategy
@@ -262,15 +334,24 @@ paths:
       responses:
         '201':
           description: Strategy successfully added
+        '400':
+          description: Bad body request (for example 'strategies' is not an array)
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+
   '/admin/strategies/{strategyName}':
     put:
       summary: Update Strategy
       description: |
         Use to update a Strategy definition.
 
-        *name* and *strategyName* must match and must also match an existing Strategy name.
+        **name** and **strategyName** must match and must also match an existing Strategy name.
 
-        **Caution:** It can be dangerous to change a Strategy (as the implementation also might need to be changed).
+        **Caution: It can be dangerous to change a Strategy (as the implementation also might need to be changed).**
       operationId: updateStrategy
       tags:
         - Strategies
@@ -285,6 +366,15 @@ paths:
       responses:
         '200':
           description: Strategy successfully updated.
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: Strategy not updated due to errors in query and/or request body (such as **name** and **strategyName** not matching).
+
   /admin/metrics/seen-toggles:
     get:
       summary: Returns a list of applications and the feature toggles that Unleash has 'seen' for each application.
@@ -299,11 +389,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200seen'
+
   /admin/metrics/feature-toggles:
     get:
       summary: Gives 'last minute' and 'last hour' metrics for all active toggles (based on what was reported by the client applications).
-      description: |
-        - **Yes** is the number of times a given feature toggle was enabled in a client applcation
+      description: |-
+        - **Yes** is the number of times a given feature toggle was enabled in a client applucation
         - **No** is the number of times it was disabled.
       operationId: featureToggles
       tags:
@@ -315,6 +406,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200feature'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+
   /admin/metrics/applications:
     get:
       summary: A list of known applications ('seen' by Unleash in the last two days)
@@ -330,7 +428,16 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/200application'
+                $ref: '#/components/schemas/applicationArray'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '500':
+          description: Strategy name not found
+
   '/admin/metrics/applications/{appName}':
     get:
       summary: Details about a client application.
@@ -347,10 +454,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200appdetails'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '500':
+          description: Application name not found
+
   /admin/metrics/seen-apps:
     get:
-      summary: Details about application seen per Feature Toggle.
-      description: Details about application seen per Feature Toggle.
+      summary: Details about applications seen
+      description: (per Feature Toggle)
       operationId: seenApps
       tags:
         - Metrics
@@ -360,10 +476,26 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/200seenapps'
+                $ref: '#/components/schemas/applicationArray'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+
   /admin/events:
     get:
+      operationId: get-admin-events
       summary: Fetch all changes in the Unleash system
+      description: |-
+        Returns one of the five event types:
+        - feature-created
+        - feature-updated
+        - feature-archived
+        - feature-revived
+        - strategy-created
+        - strategy-deleted
       tags:
         - Events
       responses:
@@ -373,20 +505,49 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200-events'
-      operationId: get-admin-events
-      description: |-
-        Returns one of the five event types:
-        - feature-created
-        - feature-updated
-        - feature-archived
-        - feature-revived
-        - strategy-created
-        - strategy-deleted
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+
   /admin/state/export:
     get:
+      operationId: get-admin-state-export
       summary: Export feature toggles and strategies
+      description: Exports a list of feature toggles and/or strategies in either JSON or YAML format.
       tags:
         - Import and export
+      parameters:
+        - schema:
+            type: string
+            enum:
+              - json
+              - yaml
+          in: query
+          name: format
+          description: |
+            Choose export format, either json or yaml. json is the default
+          example: json
+        - schema:
+            type: boolean
+          in: query
+          name: download
+          example: false
+          description: Do you want to export the data as a file? Default is false
+        - schema:
+            type: boolean
+          in: query
+          name: featureToggles
+          description: Do you want to include feature toggles in the export? Default is true
+          example: true
+        - schema:
+            type: boolean
+          in: query
+          name: strategies
+          description: Do you want to include strategies in the export? Default is true
+          example: true
       responses:
         '200':
           description: OK
@@ -394,53 +555,40 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200export'
-      operationId: get-admin-state-export
-      parameters:
-        - schema:
-            type: string
-          in: query
-          name: format
-          description: |
-            Choose export format, either json or yaml. json is the default
-        - schema:
-            type: boolean
-          in: query
-          name: download
-          description: Export the data as a file? Default is false
-        - schema:
-            type: boolean
-          in: query
-          name: featureToggles
-          description: Include feature toggles in the export? Default is true
-        - schema:
-            type: boolean
-          in: query
-          name: strategies
-          description: Include strategies in the export? Default is true
-      description: Exports a list of feature toggles and/or strategies in either JSON or YAML format.
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+
   /admin/state/import:
     post:
       summary: Import feature toggles and strategies
       operationId: post-admin-state-import
       tags:
         - Import and export
-      responses:
-        '200':
-          description: Successful import.
-      description: Upload the data, in JSON or YAML format, in the POST body. What schema must the import file adopt? Same as the export 200 response?
+      description: |-
+        Upload the data, in JSON or YAML format.
+        You can add in the POST body or upload a file
+        - **POST body** (JSON format only) - next to **Request body**, choose the *application/json* dropdown option.
+        - **File upload** (JOSN or YAML format) - next to **Request body**, choose the *multipart/form-data* dropdown option. This adopts the same schema as `GET /admin/state/export`
       parameters:
         - schema:
             type: boolean
             default: 'false'
+            example: false
           in: query
           name: drop
           description: Be careful using this in production environments. Set to true if you want the to remove all strategies and feature toggles from the datebase before import. Default is false.
         - schema:
             type: boolean
-            default: 'true'
+            default: 'false'
+            example: false
           in: query
           name: keep
-          description: Set to true if you want keep all existing feature toggles and strategies as is; only the missing feature toggles and strategies will be inserted from the import data. Default is true.
+          description: Set to *true* if you want keep all existing feature toggles and strategies as is; only the missing feature toggles and strategies will be inserted from the import data. Default is true.
+          example: true
       requestBody:
         content:
           multipart/form-data:
@@ -450,6 +598,21 @@ paths:
                 fileName:
                   type: string
                   format: binary
+          application/json:
+            schema:
+              $ref: '#/components/schemas/200export'
+      responses:
+        '200':
+          description: Successful import.
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '404':
+          description: No import data provided.
+  
   /admin/feature-types:
     get:
       summary: Fetch the list of Unleash feature types
@@ -469,20 +632,28 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/200featuretype'
+        '401':
+          description: Not authorised
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
 
 components:
   parameters:
     strategyQuery:
       name: strategyName
-      in: query
       description: (Optional). Return all applications implementing the specified Strategy. Must match an existing Strategy name.
+      example: remoteAddress
+      in: query
       schema:
         type: string
     featureNamePath:
       name: featureName
+      description: Must match an existing Feature Toggle name.
+      example: featureX
       required: true
       in: path
-      description: Must match an existing Feature Toggle.
       schema:
         type: string
     strategyNamePath:
@@ -490,6 +661,7 @@ components:
       required: true
       in: path
       description: Must match an existing Strategy name.
+      example: flexibleRollout
       schema:
         type: string
     appNamePath:
@@ -497,60 +669,20 @@ components:
       required: true
       in: path
       description: Must match an existing application name.
+      example: my-application
       schema:
         type: string
+
   schemas:
     '200':
       title: Successful response
       type: object
       properties:
         version:
-          type: number
+          $ref: '#/components/schemas/versionSchema'
         features:
-          type: array
-          uniqueItems: true
-          minItems: 1
-          items:
-            properties:
-              name:
-                description: Feature Toggle name
-                type: string
-                minLength: 1
-                example: featureX
-              description:
-                description: What the Feature Toggle does
-                type: string
-                minLength: 1
-              type:
-                description: One of the five types of Feature Toggle
-                externalDocs:
-                  description: Feature Toggle types
-                  url: 'https://unleash.github.io/docs/feature_toggle_types'
-                type: string
-                minLength: 1
-                example: release
-              enabled:
-                description: Is the Feature Toggle enabled?
-                type: boolean
-              stale:
-                description: Is the Feature Toggle 'stale' (deprecated)?
-                type: boolean
-              strategies:
-                $ref: '#/components/schemas/simpleStrategySchema'
-              variants:
-                type: array
-                uniqueItems: true
-                minItems: 1
-                items:
-                  required:
-                    - name
-                    - weight
-                  properties:
-                    name:
-                      type: string
-                      minLength: 1
-                    weight:
-                      type: number
+          $ref: '#/components/schemas/featureToggleSchema'
+
     '401':
       description: Not authorised
       type: object
@@ -568,114 +700,18 @@ components:
         - type
         - path
         - message
-    '409':
-      type: object
-      properties:
-        isJoi:
-          type: boolean
-        name:
-          type: string
-          minLength: 1
-        details:
-          type: array
-          uniqueItems: true
-          minItems: 1
-          items:
-            required:
-              - message
-            properties:
-              message:
-                type: string
-                minLength: 1
-      required:
-        - isJoi
-        - name
-        - details
+
     200strategy:
-      description: Successful.
       type: object
       required:
         - version
         - strategies
       properties:
         version:
-          type: number
-          example: 1
+          $ref: '#/components/schemas/versionSchema'
         strategies:
-          $ref: '#/components/schemas/simpleStrategySchema'
-    newFeatureToggle:
-      type: object
-      required:
-        - name
-        - description
-        - enabled
-        - stale
-        - strategies
-      properties:
-        name:
-          description: Feature Toggle name must be unique.
-          type: string
-          minLength: 1
-          example: FeatureA
-        description:
-          description: What the Feature Toggle does
-          type: string
-          minLength: 1
-          example: Toggles FeatureA on and off
-        type:
-          type: string
-          description: '*type* is optional. If not defined, it defaults to `release`'
-          externalDocs:
-            description: Feature Toggle types
-            url: 'https://unleash.github.io/docs/feature_toggle_types'
-          enum:
-            - release
-            - experiment
-            - ops
-            - killswitch
-            - permission
-          minLength: 1
-          example: release
-        enabled:
-          type: boolean
-          example: false
-        stale:
-          description: Is the Feature Toggle deprecated (stale)?
-          type: boolean
-          example: false
-        strategies:
-          $ref: '#/components/schemas/simpleStrategySchema'
-    updateFeatureToggle:
-      type: object
-      properties:
-        description:
-          type: string
-          minLength: 1
-          example: Toggles FeatureB on and off
-        type:
-          type: string
-          minLength: 1
-          description: '*type* is optional. If not defined, it defaults to `release`'
-          example: release
-        enabled:
-          type: boolean
-          example: false
-        stale:
-          type: boolean
-          example: false
-        strategies:
-          $ref: '#/components/schemas/simpleStrategySchema'
-        variants: {}
-        createdAt:
-          type: string
-          minLength: 1
-      required:
-        - name
-        - description
-        - enabled
-        - stale
-        - strategies
-        - variants
+          $ref: '#/components/schemas/strategySchema'
+
     createStrategy:
       type: object
       properties:
@@ -712,13 +748,14 @@ components:
                 example: What percent of users should the new Feature Toggle be active for?
               required:
                 type: boolean
+                example: true
       required:
         - name
         - description
         - parameters
+
     200seen:
       type: array
-      description: ''
       minItems: 1
       uniqueItems: true
       items:
@@ -737,8 +774,9 @@ components:
               properties: {}
           metricsCount:
             type: number
+
     200feature:
-      description: |
+      description: |-
         - **lastHour** - how many times a Feature Toggle was accessed in the last hour.
         - **lastMinute** - how many times a Feature Toggle was accessed in the last minute.
       type: array
@@ -770,7 +808,13 @@ components:
                   - 'no'
               metricsCount:
                 type: number
-    200application:
+                
+    applicationArray:
+      type: array
+      items:
+        $ref: '#/components/schemas/application'
+
+    application:
       type: object
       required:
         - applications
@@ -805,48 +849,28 @@ components:
                 description: A description of what the application does
                 type: string
               url:
-                description: Link to more information about the application? Relative only?
+                description: Link to more information about the application? Relative only? # Question?
                 type: string
                 example: 'https://medium.com/keptn'
               color:
-                description: The colour (American English?) of something. Hex code?
+                description: The colour (American English?) of something. Hex code? # Question?
                 type: string
               icon:
-                description: The icon to use for something. Link?
+                description: The icon to use for something. Link? # Question?
                 type: string
 
     200appdetails:
       type: object
       required:
-        - appName
+        - application
         - instances
         - strategies
         - seenToggles
       properties:
-        appName:
-          description: Application name
-          type: string
-          minLength: 1
-          example: my-application
-        createdAt:
-          description: Date and time when the application was initially created
-          type: string
-          example: '2016-12-09T14:56:36.730Z'
-        description:
-          description: A description of what the application does
-          type: string
-        url:
-          description: Link to more information about the application? Relative only?
-          type: string
-          example: 'https://medium.com/keptn'
-        color:
-          description: The colour (American English?) of something. Hex code?
-          type: string
-        icon:
-          description: The icon to use for something. Link?
-          type: string
+        application:
+          $ref: '#/components/schemas/application'
         strategies:
-          $ref: '#/components/schemas/simpleStrategySchema'
+          $ref: '#/components/schemas/strategySchema'
         instances:
           type: object
           required:
@@ -873,139 +897,114 @@ components:
               minLength: 1
               example: 'unleash-client-node:3.4.0'
             clientIp:
-              description: The IP address of the system running this instance of the application. What is the prefix on the string?
+              description: The IP address of the system running this instance of the application. What is the prefix on the string? # Question?
               type: string
               minLength: 1
               example: '::ffff:127.0.0.1'
             lastSeen:
-              description: The last time the application accessed Unleash?
+              description: The last time the application accessed Unleash? # Question?
               type: string
               minLength: 1
               example: '2020-11-14T11:17:24.482Z'
             createdAt:
-              description: When the application was created?
+              description: When the application was created? # Question?
               type: string
               minLength: 1
               example: '2020-11-13T16:56:29.279Z'
         seenToggles:
-          type: array
-          uniqueItems: true
-          minItems: 1
-          items:
-            required:
-              - name
-              - type
-              - enabled
-              - stale
-              - createdAt
-            properties:
-              name:
-                description: Name of the Feature Toggle
-                type: string
-                minLength: 1
-                example: FeatureX
-              description:
-                description: What the Feature Toggle does
-                type: string
-              type:
-                description: One of the five types of Feature Toggle
-                type: string
-                externalDocs:
-                  description: Feature Toggle types
-                  url: 'https://unleash.github.io/docs/feature_toggle_types'
-                minLength: 1
-                example: release
-              enabled:
-                description: Is the Feature Toggle enabled?
-                type: boolean
-              stale:
-                description: Is the Feature Toggle
-                type: boolean
-              strategies:
-                $ref: '#/components/schemas/strategySchema'
-              variants:
-                description: What is this?
-                type: string
-              createdAt:
-                description: Date and time when the application was initially created
-                type: string
-                minLength: 1
-                example: '2020-11-09T15:25:59.517Z'
+          $ref: '#/components/schemas/featureToggleSchema'
         links:
           type: object
           properties:
             self:
-              description: What is this?
+              description: What is this? # Question?
               type: string
               minLength: 1
           required:
             - self
-    200seenapps:
-      type: object
-      properties:
-        my-toggle:
-          type: array
-          items:
-            required:
-              - appName
-              - createdAt
-              - updatedAt
-              - description
-              - url
-              - icon
-            properties:
-              appName:
-                description: Appplication name
-                type: string
-                minLength: 1
-                example: my-application
-              createdAt:
-                description: Date and time when the application was initially created
-                type: string
-                minLength: 1
-                example: '2016-12-09T14:56:36.730Z'
-              updatedAt:
-                description: Date and time when the application was last updated
-                type: string
-                minLength: 1
-                example: '2020-11-14T09:55:23.653Z'
-              description:
-                description: A description of what the application does
-                type: string
-                minLength: 1
-              strategies:
-                $ref: '#/components/schemas/simpleStrategySchema'
-              url:
-                description: Link to more information about the application? Relative only?
-                type: string
-                minLength: 1
-                example: 'https://medium.com/keptn'
-              color:
-                description: The colour (American English?) of something. Hex code?
-                type: string
-              icon:
-                description: The icon to use for something. Link?
-                type: string
-                minLength: 1
+
+    featureToggleTypeSchema:
+      type: string
+      enum:
+        - release
+        - experiment
+        - ops
+        - killswitch
+        - permission
+      description: |-
+        'One of the five Unleash Feature Toggle types.
+        
+        **type** is optional. If not defined, it defaults to *release*'
+      default: 'release'
+      externalDocs:
+        description: Feature Toggle types
+        url: 'https://unleash.github.io/docs/feature_toggle_types'
+      minLength: 1
+      example: release
+    
+    versionSchema:
+      type: number
+      description: What is this? # Question?
+      example: 1
+
+    featureToggleSchema:
+      type: array
+      items:
+        type: object
+        required:
+        - name
+        - description
+        - type
+        - enabled
+        - stale
+        - strategies
+        properties:
+          name:
+            description: Feature Toggle name must be unique.
+            type: string
+            minLength: 1
+            example: featureX
+          description:
+            type: string
+            minLength: 1
+            example: Toggles featureX on and off
+          type:
+            $ref: '#/components/schemas/featureToggleTypeSchema'
+          enabled:
+            description: Is the Feature Toggle enabled?
+            type: boolean
+            example: true
+          stale:
+            description: Is the Feature Toggle 'stale' (deprecated)?
+            type: boolean
+            example: false
+          strategies:
+            $ref: '#/components/schemas/strategySchema'
+          variants:
+            $ref: '#/components/schemas/variantsSchema'
+          createdAt:
+            type: string
+            minLength: 1
+
     strategySchema:
       type: array
-      properties:
-        name:
-          description: Name of the Strategy
-          type: string
-          minLength: 1
-          example: default
-        editable:
-          type: boolean
-        description:
-          description: What the Strategy is
-          type: string
-          example: Default on/off strategy.
-        parameters:
-          type: array
-          items:
-            required:
-              - parameter
+      items:
+        type: object
+        properties:
+          name:
+            description: Name of the Strategy
+            type: string
+            minLength: 1
+            example: default
+          editable:
+            type: boolean
+            example: true
+          description:
+            description: What the Strategy is
+            type: string
+            example: Default on/off strategy.
+          parameters:
+            type: object
             properties:
               parameter:
                 type: object
@@ -1028,34 +1027,33 @@ components:
                   required:
                     description: Is this a required parameter?
                     type: boolean
-    simpleStrategySchema:
-      type: object
-      required:
-        - appName
-        - parameterName
-      properties:
-        appName:
-          description: Application name
-          type: string
-          minLength: 1
-          example: demo-app
-        strategies:
-          type: array
-          items:
-            required:
-              - strategyName
-            properties:
-              parameterName:
-                description: Name of Strategy's parameter
-                type: string
-                example: extra
+                    example: false
+
+    variantsSchema:
+      externalDocs:
+        description: How to use Feature Toggle variants
+        url: https://unleash.github.io/docs/toggle_variants
+      type: array
+      items:
+        required:
+          - name
+          - weight
+        properties:
+          name:
+            description: The name of the Feature Toggle variant
+            type: string
+            minLength: 1
+            example: yellow
+          weight:
+            description: The 'weighting' for the variant. How does Unleash use weighting to determine which variant to use? What is the range? # Question?
+            type: number
+            example: 20
+
     200-events:
       type: object
       properties:
         version:
-          description: Version number of what?
-          type: number
-          example: 1
+          $ref: '#/components/schemas/versionSchema'
         events:
           type: array
           required:
@@ -1068,11 +1066,11 @@ components:
           items:
             properties:
               id:
-                description: The event number. Starts at 1? On first run of application version?
+                description: The event number. Starts at 1? On first run of application version? # Question?
                 type: number
                 example: 55
               type:
-                description: One of the five event types
+                description: One of the six event types
                 type: string
                 enum:
                   - feature-created
@@ -1084,7 +1082,7 @@ components:
                 minLength: 1
                 example: feature-updated
               createdBy:
-                description: Creator of the application? Where is this taken from?
+                description: Creator of the application? Where is this taken from? # Question?
                 type: string
                 minLength: 1
               createdAt:
@@ -1092,57 +1090,9 @@ components:
                 type: string
                 example: '2016-12-09T14:56:36.730Z'
               data:
-                type: object
-                required:
-                  - name
-                  - description
-                  - type
-                  - enabled
-                  - stale
-                  - strategies
-                  - createdAt
-                properties:
-                  name:
-                    description: Feature Toggle name .
-                    type: string
-                    minLength: 1
-                    example: FeatureA
-                  description:
-                    description: What the Feature Toggle does
-                    type: string
-                    minLength: 1
-                    example: Toggles FeatureA on and off
-                  type:
-                    type: string
-                    description: '*type* is optional. If not defined, it defaults to `release`'
-                    externalDocs:
-                      description: Feature Toggle types
-                      url: 'https://unleash.github.io/docs/feature_toggle_types'
-                    enum:
-                      - release
-                      - experiment
-                      - ops
-                      - killswitch
-                      - permission
-                    minLength: 1
-                    example: release
-                  enabled:
-                    type: boolean
-                    example: false
-                  stale:
-                    description: Is the Feature Toggle deprecated (stale)?
-                    type: boolean
-                    example: false
-                  strategies:
-                    $ref: '#/components/schemas/simpleStrategySchema'
-                  variants: {}
-                  createdAt:
-                    description: Date and time when the Feature Toggle was created?
-                    type: string
-                    minLength: 1
-                    example: '2020-11-09T13:51:08.949Z'
+                $ref: '#/components/schemas/featureToggleSchema'
               diffs:
-                description: What are diffs? I don't think this part of the schema is correct
+                description: What are diffs?  # Question?
                 type: array
                 items:
                   required:
@@ -1151,6 +1101,7 @@ components:
                     - rhs
                   properties:
                     kind:
+                      description: What do these letters signify? What's the full list? # Question? 
                       type: string
                       example: E
                     path:
@@ -1160,15 +1111,18 @@ components:
                           - pathItem
                       properties:
                         pathItem:
-                          description: What's this?
+                          description: What's this? # Question?
                           type: string
                           example: enabled
                     lhs:
-                      description: Left-hand side of something?
+                      description: Left-hand side of something? Sometimes boolean, sometimes an object, sometimes null. What is it? # Question?
                       type: boolean
+                      example: true
                     rhs:
-                      description: Left-hand side of something?
+                      description: Left-hand side of something? Sometimes boolean, sometimes an object, sometimes null. What is it? # Question?
                       type: boolean
+                      example: false
+
     200export:
       type: object
       required:
@@ -1177,68 +1131,20 @@ components:
         - strategies
       properties:
         version:
-          description: Version number of what?
-          type: number
-          example: 1
+          $ref: '#/components/schemas/versionSchema'
         features:
-          type: array
-          uniqueItems: true
-          minItems: 1
-          items:
-            required:
-              - name
-              - description
-              - type
-              - enabled
-              - stale
-              - createdAt
-            properties:
-              name:
-                description: Feature Toggle name .
-                type: string
-                minLength: 1
-                example: FeatureA
-              description:
-                description: What the Feature Toggle does
-                type: string
-                minLength: 1
-                example: Toggles FeatureA on and off
-              type:
-                type: string
-                description: '*type* is optional. If not defined, it defaults to `release`'
-                externalDocs:
-                  description: Feature Toggle types
-                  url: 'https://unleash.github.io/docs/feature_toggle_types'
-                enum:
-                  - release
-                  - experiment
-                  - ops
-                  - killswitch
-                  - permission
-                minLength: 1
-                example: release
-              enabled:
-                type: boolean
-                example: false
-              stale:
-                description: Is the Feature Toggle deprecated (stale)?
-                type: boolean
-                example: false
-              strategies:
-                $ref: '#/components/schemas/simpleStrategySchema'
-              variants: {}
-              createdAt:
-                type: string
-                minLength: 1
+          $ref: '#/components/schemas/featureToggleSchema'
         strategies:
-          $ref: '#/components/schemas/simpleStrategySchema'
+          $ref: '#/components/schemas/strategySchema' # Difference between this and the strategies in the Feature Toggle schema?
+
     200featuretype:
       type: object
+      required:
+        - version
+        - types
       properties:
         version:
-          description: A version number of something?
-          type: number
-          example: 1
+          $ref: '#/components/schemas/versionSchema'
         types:
           type: array
           uniqueItems: true
@@ -1251,13 +1157,7 @@ components:
               - lifetimeDays
             properties:
               id:
-                description: The *id* string for the Feature Toggle type
-                externalDocs:
-                  description: Feature Toggle types
-                  url: 'https://unleash.github.io/docs/feature_toggle_types'
-                type: string
-                minLength: 1
-                example: release
+                $ref: '#/components/schemas/featureToggleTypeSchema'
               name:
                 description: The title of the Feature Toggle type
                 type: string
@@ -1277,13 +1177,11 @@ components:
                   - Performs multivariate or A/B testing
                   - Controls operational aspects of the system behaviour # US English?
                   - Gracefully degrades system functionality
-                  - Changez the features or product experiences that certain users receive
+                  - Changes the features or product experiences that certain users receive
                 minLength: 1
               lifetimeDays:
-                description: What's this?
+                description: What's this? # Question?
                 type: number
                 example: 40
-      required:
-        - version
-        - types
+