updated documentation

docs/update-type-definition-guideline.rst

@@ -102,7 +102,7 @@ which produces the following type definition:
 	    "extendedTypes": [ "Facet" ]
 	}
 	
-At a certain point, the information-system-model introduces the following Property type, which models an event.
+At a certain point, the ``information-system-model`` introduces the following ``Property`` type, which models an event.
 
 .. code:: java
 	
@@ -267,9 +267,11 @@ which produces the following type definition:
 	}
 	
 
-So imagine you want to update the 'EventFacet' type definition to use this property type instead of the 'date' and 'event' properties.
+So imagine you want to update the ``EventFacet`` type definition to use this property type instead of the ``date`` and ``event`` properties.
 
-To update the 'EventFacet' there are different strategies:
+The objective is to obtain a facet with ``event`` property as an ``Event``.
+
+To update the ``EventFacet`` there are different strategies:
 
 
 Java Backwards Compatibility
@@ -409,7 +411,6 @@ which produces the following type definition:
 	    "extendedTypes": [ "Facet" ]
 	}
 	
-
 The implementation should be something like this:
 
 .. code:: java
@@ -544,9 +545,10 @@ The implementation should be something like this:
 
 
 With this strategy, any Java client reading the event facet instantiated with the old 
-model will remap the 'date' and 'event' properties to an instance of 'Event' named 'event'.
+model will remap the ``date`` and ``event`` properties to an instance of ``Event`` named ``event``.
 
-We receive 
+
+We receive:
 
 .. code:: javascript
 	
@@ -557,7 +559,7 @@ We receive
         "event": "certified"
     }
 
-which will be serialized in turn as:
+which will be serialized/deserialized in turn as:
 
 .. code:: javascript   
     {
@@ -575,8 +577,48 @@ which will be serialized in turn as:
     }
 
 The problem of this solution is that if the facet is updated to the new format in the server and
-there are old clients they will not be able to deserialise the new version.
+there are old clients they will not be able to deserialize the new version.
 
+With this solution the 'event' property in the server is of type ANY (an Object in Java)
+
+
+.. code:: java
+	
+	@ISProperty(name=EVENT_PROPERTY, type=Object.class, description = ....
+	public Event getTheEvent();
+	
+The ``@ISProperty`` annotation specifies the type of the property ``type=Object.class`` instead of letting the system to get the type from the function return, i.e. ``Event``.
+The type definition in JSON has:
+
+.. code:: javascript
+
+	"propertyType": "Any"
+
+
+PRO:
+ * the name of the variable is already ``event`` as we want as final objective.
+ 
+CONS:
+ * the server cannot check the validity of the variable received from an updating client. 
+
+The future release of ``EventFacet`` will 
+
+* remove ``type=Object.class`` from ``@ISProperty`` annotation;
+* remove deprecated methods from the Java interface and its implementation:
+ * ``public Date getDate();``
+ * ``public void setDate(Date date);``
+ * ``public String getEvent();``
+ * ``public void setEvent(String event);``
+* deprecate ``public Event getTheEvent();``
+* add ``public Event getEvent();``
+
+
+
+
+Java and Javascript Backwards Compatibility
+----------------------------
+
+This solution is Java compliant from a code perspective and the old properties are keep for old clients.
 
 .. code:: java
 	
@@ -810,6 +852,7 @@ The implementation should be the following:
 		 * 
 		 * It eventually instantiate {@link Event} if null.
 		 */
+		@JsonSetter("event")
 		public void setEvent(String event) {
 			if(event == null) {
 				this.theEvent = new EventImpl();
@@ -838,3 +881,74 @@ The implementation should be the following:
 	
 	}
 
+With this strategy, any Java client reading the event facet instantiated with the old 
+model will remap the 'date' and 'event' properties to an instance of 'Event' named 'theEvent'.
+The old properties 'date' and 'event' properties are still available for old clients.
+
+We receive 
+
+.. code:: javascript
+	
+    {
+        "type": "EventFacet",
+        "id": "d9f91175-8c33-4f68-8619-48e6feca4e47",
+        "date": "2024-01-08 12:52:59.907 +0100",
+        "event": "certified"
+    }
+
+which will be serialized/deserialized in turn as:
+
+.. code:: javascript
+	{
+        "type": "EventFacet",
+        "id": "d9f91175-8c33-4f68-8619-48e6feca4e47",
+        "date": "2024-01-08 12:52:59.907 +0100"
+        "event": "certified",
+        "theEvent": {
+            "type": "Event",
+            "what": "certified",
+            "when": "2024-01-08 11:52:59.907 +0000",
+            "who": null,
+            "where": null,
+            "why": null,
+            "how": null
+        }
+    }
+
+With this solution we use ``theEvent`` property in the server of type Event which validity can be checked by the server:
+ 
+PRO:
+ * the server can check the validity of the variable received from an updating client.
+ 
+CONS:
+  * the name of the variable is ``theEvent`` and only in a future step will be changed.
+  
+  
+
+The future release of ``EventFacet`` will 
+
+* remove deprecated methods from the Java interface and its implementation:
+ * ``public Date getDate();``
+ * ``public void setDate(Date date);``
+ * ``public String getEvent();``
+ * ``public void setEvent(String event);``
+* deprecate ``public Event getTheEvent();``
+* add ``public Event getEvent();``
+
+Both ``event`` and ``theEvent`` will coexist until the next version.
+
+
+
+This solution has the following issue:
+``date`` and ``event`` may not align with ``theEvent`` if updated from old clients.
+
+The proposed implementation involves ``setTheEvent()``, which could potentially overwrite ``date`` if invoked by Jackson beforehand. 
+Therefore, implementing this correctly requires careful consideration.
+
+It's important to note that only old clients might disalign the ``date``. 
+As a result, the most advanced values always reside in the old properties. 
+Conversely, a new client would have already corrected and aligned them.
+
+Of course, there is no resolution for bugged new clients causing misalignments, 
+but that's a separate issue not covered in this guide.
+