doc(Usage of discriminator): Encourage inheritance rather than polymorphism

documentation/API-design-guidelines.md

@@ -1057,11 +1057,54 @@ In this part, the error response structure must also be defined, which must be a
 </p>
 
 #### 11.5.1 Usage of discriminator
-
 As mentioned in Openapi doc [here](https://spec.openapis.org/oas/v3.0.3#discriminator-object) usage of discriminator may
 simplify serialization/deserialization process and so reduce resource consumption.
 
-To achieve this in the Camara context, we decided that :
+##### Inheritance
+The mappings section is not mandatory in discriminator, by default ClassName are used as values to populate the property. You can use mappings to restrict usage to subset of subclasses.
+
+
+``` yaml 
+    IpAddr:
+      type: object
+      properties:
+        addressType:
+            type: string
+      required:
+         - addressType
+      discriminator:
+        propertyName: addressType 
+        mappings:                   
+            - IPV4ADDR: Ipv4Addr
+            - IPV6ADDR: Ipv6Addr   
+
+    Ipv4Addr: 
+      allOf:            <-- extends IpAddr (no need to define addressType because it's inherited
+        - $ref: IpAddr
+        - type: object
+          required:
+            - address
+          properties:
+            address:
+                type: string
+                format: ipv4
+        ...
+
+    Ipv6Addr:
+      allOf:            <-- extends IpAddr
+        - $ref: IpAddr
+        - type: object
+          required:
+            - address
+          properties:
+            address:
+              type: string
+              format: ipv6
+        ...
+```
+
+##### Polymorphism
+To help usage of Camara object from strongly typed languages prefer to use inheritance than polymorphism ... Despite this, if you have to use it apply following rules:
 
     - objects containing oneOf or anyOf section MUST include a discriminator defined by a propertyName
     - objects involved in oneOf / anyOf section MUST include the property designed by propetyName
@@ -1086,7 +1129,7 @@ The following sample illustrates this usage.
           type: string
         address:
           type: string
-          format: ipv6
+          format: ipv4
         ...
 
     Ipv6Addr: <-- object involved in oneOf MUST include the objectype property
@@ -1099,7 +1142,7 @@ The following sample illustrates this usage.
           type: string
         address:
           type: string
-          format: ipv4
+          format: ipv6
         ...
 
 ```