Update simple_edge_discovery.yaml

Fixes #225
Fixes #226

Author: Kevsy

code/API_definitions/Discovery/simple_edge_discovery.yaml

@@ -2,7 +2,7 @@
 openapi: 3.0.3
 info:
   title: Simple Edge Discovery API
-  version: 0.9.4
+  version: 0.9.4-rc.1
   description: |
     # Find the closest Edge Cloud Zone
     ---
@@ -12,13 +12,13 @@ info:
     Cloud Zone to a particular user device.
 
     # Purpose
-    Network operators may host multiple Multi-access Edge Cloud Zones in a
+    Network operators may host multiple Edge Cloud Zones in a
     given territory. Connecting your application to a server on the closest
     Edge Cloud Zone means packets travel the shortest distance between
     endpoints, typically resulting in the lowest round-trip latency. Note, the
     physical (GPS) location of a user device is not a reliable way to determine
     the closest Edge Cloud Zone, due to the way operator networks are routed -
-    so the operator will calculate the Edge Cloud Zone with the 
+    so the operator will calculate the Edge Cloud Zone with the
     _shortest network path_to the network-attached device identified in the API
     request.
 
@@ -77,7 +77,7 @@ info:
       GET /edge-cloud-zones?filter=closest HTTP/1.1
       Host: example.com
       Accept: application/json
-      Phone-Number: 441234567890
+      Phone-Number: +441234567890
     ```
     
     Example where API client is on a network-attached device:
@@ -92,16 +92,16 @@ info:
 
     ## Success
 
-    A JSON object is returned containing an array with a single member object. 
+    A JSON object is returned containing an array with a single member object.
     This contains identifiers for the closest Edge Cloud Zone. The HTTP status
     code will be`200 OK`. An example response:
     
     ```
     [
       {
         "edgeCloudZoneId": "4gt555-6457-7890-d4he-1dc79f44gb66",
-        "edgeCloudZoneName": "eu-west-2-wl1-man-wlz-1",
-        "edgeCloudProvider": "AWS"
+        "edgeCloudZoneName": "example zone name",
+        "edgeCloudProvider": "example zone provider"
       }
     ]
     ```
@@ -125,7 +125,7 @@ info:
     Any more general service failures will result in an error in the `5xx`range
     with an explanation.
 
-    # Notes for Simple Edge API publishers
+    # Notes for Simple Edge Discovery API publishers
 
     If an `IP-Address` header parameter is provided then the operator should
     assume the request is coming from a developer's server rather than a device
@@ -148,7 +148,7 @@ info:
     # Authorization and authentication
 
     CAMARA guidelines defines a set of authorization flows which can grant API
-    clients access to the API functionality, as outlined in the document 
+    clients access to the API functionality, as outlined in the document
     [CAMARA-API-access-and-user-consent.md]
     (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md).
     Which specific authorization flows are to be used will be determined during
@@ -202,53 +202,50 @@ paths:
         - name: filter
           in: query
           required: true
-          description: | 
+          description: |
             Filter the Edge Cloud Zones according to the parameter value.
             For this API the only supported value is `closest`.
           schema:
             type: string
-            enum: 
+            enum:
              - closest
 
-        - name: IP-Address
+        - name: IPv4-Address
           in: header
           required: false
-          description: The public IP allocated to the device.
-          examples:
-            ipv4:
-              value: "84.125.93.10"
-            ipv6:
-              value: "2001:db8:85a3:8d3:1319:8a2e:370:7344"
+          description: The public IPv4 address allocated to the device.
+          example: "84.125.93.10"
           schema:
-            type: string
-            format: ipv4/ipv6
-            oneOf:
-              - pattern: '^(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5]
-              )\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$'
-              - pattern: '^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f]
-              [0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))$'
+            $ref: "#/components/schemas/SingleIpv4Addr"
+            
+        - name: IPv6-Address
+          in: header
+          required: false
+          description: The public IPv6 address allocated to the device.
+          example: "2001:db8:85a3:8d3:1319:8a2e:370:7348"
+          schema:
+            $ref: "#/components/schemas/DeviceIpv6Address"
 
         - name: Network-Access-Identifier
           in: header
-          description: | 
+          description: |
             3GPP network access identifier for the subscription
             being used by the device.
           example: "[email protected]"
           required: false
           schema:
-            type: string
-            format: email
+            $ref: "#/components/schemas/NetworkAccessIdentifier"
+            
         - name: Phone-Number
           in: header
-          example: "441234567890"
+          example: "+441234567890"
           required: false
           description: |
             MSISDN in E.164 format (starting with country code) of
             the mobile subscription being used by the device. Optionally
             prefixed with '+'.
           schema:
-            type: string
-            pattern: '^\+?[0-9]{5,15}$'
+            $ref: "#/components/schemas/PhoneNumber"
 
       responses:
         "200":
@@ -318,20 +315,12 @@ components:
         Provider object (the name of the cloud provider or operator hosting that
         edge cloud zone).
       properties:
-        edgeCloudZone:
-          description: |
-            An Edge Cloud Zone, uniquely identified by a combination
-            of the value of the Edge Resource Name object and the value of the
-            Provider object (the name of the cloud provider or operator hosting
-            that egde cloud zone).
-          type: object
-          properties:
-            edgeCloudZoneId:
-              $ref: "#/components/schemas/EdgeCloudZoneId"
-            edgeCloudZoneName:
-              $ref: "#/components/schemas/EdgeCloudZoneName"
-            edgeCloudProvider:
-              $ref: "#/components/schemas/EdgeCloudProvider"              
+        edgeCloudZoneId:
+          $ref: "#/components/schemas/EdgeCloudZoneId"
+        edgeCloudZoneName:
+          $ref: "#/components/schemas/EdgeCloudZoneName"
+        edgeCloudProvider:
+          $ref: "#/components/schemas/EdgeCloudProvider"
 
     EdgeCloudZoneId:
       description: |
@@ -340,7 +329,6 @@ components:
       format: uuid
       additionalProperties: false
 
-
     EdgeCloudZoneName:
       description: |
         Edge Cloud Zone Name - the common name for the Edge Cloud Zone.
@@ -352,8 +340,6 @@ components:
         The company name of the Edge Cloud Zone provider.
       type: string
 
-
-
     ErrorResponse:
       description: Error code and human-readable description.
       type: object
@@ -370,6 +356,30 @@ components:
             This parameter appears when there is an error.
             A human readable explanation specific to this occurrence of the
             problem.
+            
+    PhoneNumber:
+     description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
+     type: string
+     pattern: '^\+[1-9][0-9]{4,14}$'
+     example: "+123456789"
+  
+    NetworkAccessIdentifier:
+     description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
+     type: string
+     example: "[email protected]"
+  
+    SingleIpv4Addr:
+     description: A single IPv4 address with no subnet mask
+     type: string
+     format: ipv4
+     example: "84.125.93.10"
+  
+    DeviceIpv6Address:
+     description: |
+      The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
+     type: string
+     format: ipv6
+     example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
 
 
 ###################################
@@ -578,3 +588,5 @@ components:
               "status": 504,
               "message": "The service is currently not available"
             }
+
+