Additional Info on Vendor Extensibility

doc/vendor-ext/vendor-ext.md

 # Vendor Extensibility
-This is a mechanism for the APIs to re-use, extend their functionalities and data models and engage with third-party API frameworks. 
+Mechanism for the APIs to re-use, extend their functionalities and data models and engage with third-party API frameworks (e.g. ETSI MEC)
 
-Is defined on 3GPP TS 29.122 and 29.500 and is tightly connected with “supported-features” and feature negotiation
+Vendor specific extensions are defined on 3GPP TS 29.122 (section 5.2.13) and 29.500 (section 6.6.3) and is tightly connected with "supported-features” and "feature negotiation" procedures.
 
-## Supported Features in Publish API:
-![Publish Supported Features](../images/vendor-ext/publish_supported_features.png)
+## Vendor Extensibility in CAPIF:
+Vendor Extensibility is a feature focused on the APIs that are published and exposed via CAPIF. 
+As a result, the feature is supported by the ServiceAPIDescription object (and any other objects embeded on it e.g. AefProfile). In the figure below, depicting all supported features of ServiceAPIDescription, 
+VendExt feature is noted, which enables vendor-specific extension in the body of the specific object.
 
-## Vendor extensions Data Models
+![Publish Supported Features](../images/vendor-ext/publish_supported_features_2.png)
 
-* Extend the information element with vendor specific fields
-### Fields have specific naming schemes:
-* Using the 6-digit IANA-assigned enterprise code:
+Vendor extensibility feature can be enabled and leveraged in 2 CAPIF APIs, Publish and Discover.
 
+## Vendor Extensibility in CAPIF APIs 
 
+### Publish API:
+A vendor can extend the ServiceAPIDescription object by adding additional member elements. However, in order to avoid duplication of member names inside a same object 
+it is necessary to comply with a naming scheme for vendor-specific data elements, to avoid clashing names between vendors.
+Vendor-specific member names in JSON objects shall be named in the following manner:
+```
+  "vendorSpecific-nnnnnnnnn": {
+        ...
+        }
+```
+
+where the value "nnnnnn" can be:
+
+1.  6-digit IANA-assigned enterprise code:
 
 ```
   "vendorSpecific-010415": {
@@ -20,7 +34,7 @@ Is defined on 3GPP TS 29.122 and 29.500 and is tightly connected with “support
         }
 ```
 
-* Using domain name:
+2.  domain name:
 
 
 ```
@@ -29,7 +43,7 @@ Is defined on 3GPP TS 29.122 and 29.500 and is tightly connected with “support
         }
 ```
 
-* Using URN:
+3. URN:
 
 
 ```
@@ -38,32 +52,62 @@ Is defined on 3GPP TS 29.122 and 29.500 and is tightly connected with “support
         }
 ```
 
-**Service API Description and AEF Profile Data**
+A concrete example of vendor-specific extensibility exists on section 9 of ETSI GS MEC 011 V3.2.1, where ETSI MEC extends the ServiceAPIDescription as depicted on the following two figures.
 
-![Service API Description](../images/vendor-ext/service_api_description.png)
+![Service API Description](../images/vendor-ext/service_api_description_2.png)
 
-![AEF Profile](../images/vendor-ext/aef_profile.png)
+![AEF Profile](../images/vendor-ext/aef_profile_2.png)
 
+**Example:**
+```json
+"vendorSpecific-urn:etsi:mec:capifext:service-info": {
+      "serializer": "JSON",
+      "state": "ACTIVE",
+      "scopeOfLocality": "MEC_SYSTEM",
+      "consumedLocalOnly": "True",
+      "isLocal": "True",
+      "category": {
+          "href": "https://www.location.com",
+          "id": "location_1",
+          "name": "Location",
+          "version": "1.0"
+      }
+  }
+
+  "vendorSpecific-urn:etsi:mec:capifext:transport-info": {
+      "name": "trasport1",
+      "description": "Transport Info 1",
+      "type": "REST_HTTP",
+      "protocol": "HTTP",
+      "version": "2",
+      "security": {
+          "grantTypes": "OAUTH2_CLIENT_CREDENTIALS",
+          "tokenEndpoint": "https://token-endpoint/"
+      }
+  }
+```
 
-### Discover Query Parameters
+### Discover API
 
-* Provisioning of vendor-specific query parameters to support additional vendor-specific filtering criteria
-### A vendor-specific query parameter shall be encoded as follows:
+In order to use vendor-specific fields as filters in Discover API, vendor-specific query parameter shall be encoded as follows:
     
-* query parameter name: 
-
-
+```json
+https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?
+       ...
+       vend-spec-<query parameter name>={
+          "target": <string that contains the JSON pointer to the attribute in the resource representation>, 
+          "value": <query parameter value>
+}
 ```
-"vend-spec-<query parameter name>”
-```
-
-* query parameter value encoded as JSON object:
-    * "target" 
-    * "value"
 
 **Example:**
-```
-GET {apiRoot}/3gpp-monitoring-event/v1/{scsAsId}/subscriptions?vend-spec-max-reports={"target": "/maximumNumberOfReports", value: "6"} 
+```json
+    https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?
+           ...
+           vend-spec-type={
+              "target": "/vendorSpecific-urn:etsi:mec:capifext:transport-info", 
+              "value": "REST_HTTP"
+    }
 ```