Merge pull request #2018 from JKRhb/event-vs-observable

Add text regarding choosing between events and observable properties

index.html

@@ -1896,6 +1896,19 @@ <h3><code>EventAffordance</code></h3>
               <code>unsubscribeevent</code> unless the protocol supports implicit unsubscription mechanisms (e.g.,
               heartbeat to detect connection loss).
             </p>
+            <p>
+              EventAffordances are similar to observable PropertyAffordances in the sense that the Thing itself informs
+              interested Consumers about state changes. However, a main difference of EventAffordances is that not every
+              change of the associated resource needs to trigger an event message to be emitted, e.g. a critical
+              threshold for a numeric value. Furthermore, EventAffordances allow for more complex subscribing and
+              unsubscribing mechanisms via the definition of <code>subscription</code>, <code>dataResponse</code>, and
+              <code>cancellation</code> DataSchema definitions. Not all protocols might support these more advanced
+              mechanisms, however, which is why in some scenarios, events may be very similar to observable
+              PropertyAffordances. In these cases, the choice between a Property and a Event for modelling the
+              Affordance should be made based on the semantics of the underlying resource; for example, if the state of
+              the affordance is also supposed to be read or written by a Consumer, then a Property is most likely the
+              appropriate choice.
+            </p>
           </section>
           <section>
             <h3><code>VersionInfo</code></h3>

validation/td-validation.ttl

@@ -542,7 +542,15 @@
           <code>unsubscribeevent</code>, or both terms within an
           <a href="#dfn-array" class="internalDFN" data-link-type="dfn">Array</a>.</span></p><p class="note">
 		  It is considered to be good practice that each <code>subscribeevent</code> has a corresponding <code>unsubscribeevent</code> unless the protocol
-		  supports implicit unsubscription mechanisms (e.g., heartbeat to detect connection loss).</p>"""^^rdf:HTML .
+		  supports implicit unsubscription mechanisms (e.g., heartbeat to detect connection loss).</p>
+          <p>
+            EventAffordances are similar to observable PropertyAffordances in the sense that the Thing itself informs interested Consumers about state changes.
+            However, a main difference of EventAffordances is that not every change of the associated resource needs to trigger an event message to be emitted, e.g. a critical threshold for a numeric value.
+        Furthermore, EventAffordances allow for more complex subscribing and unsubscribing mechanisms via the definition of <code>subscription</code>, <code>dataResponse</code>, and <code>cancellation</code> DataSchema definitions.
+            Not all protocols might support these more advanced mechanisms, however, which is why in some scenarios, events may be very similar to observable PropertyAffordances.
+            In these cases, the choice between a Property and a Event for modelling the Affordance should be made based on the semantics of the underlying resource; for example, if the state of the affordance is also supposed to be read or written by a Consumer, then a Property is most likely the appropriate choice.
+          </p>
+          """^^rdf:HTML .
 
 :MultiLanguageShape a sh:NodeShape ;
     sh:targetClass td:MultiLanguage ;