[1.x] Expand definitions of source and destination field sets (#967) (#…

…973)

CHANGELOG.next.md

@@ -24,6 +24,8 @@ Thanks, you're awesome :-) -->
 
 #### Improvements
 
+* Expanded field set definitions for `source.*` and `destination.*`. #967
+
 #### Deprecated
 
 ### Tooling and Artifact Changes

docs/field-details.asciidoc

@@ -803,9 +803,9 @@ example: `docker`
 [[ecs-destination]]
 === Destination Fields
 
-Destination fields describe details about the destination of a packet/event.
+Destination fields capture details about the receiver of a network exchange/packet. These fields are populated from a network event, packet, or other event containing details of a network transaction.
 
-Destination fields are usually populated in conjunction with source fields.
+Destination fields are usually populated in conjunction with source fields. The source and destination fields are considered the baseline and should always be filled if an event contains source and destination details from a network transaction. If the event also contains identification of the client and server roles, then the client and server fields should also be populated.
 
 ==== Destination Field Details
 
@@ -5185,9 +5185,9 @@ example: `3.2.4`
 [[ecs-source]]
 === Source Fields
 
-Source fields describe details about the source of a packet/event.
+Source fields capture details about the sender of a network exchange/packet. These fields are populated from a network event, packet, or other event containing details of a network transaction.
 
-Source fields are usually populated in conjunction with destination fields.
+Source fields are usually populated in conjunction with destination fields. The source and destination fields are considered the baseline and should always be filled if an event contains source and destination details from a network transaction. If the event also contains identification of the client and server roles, then the client and server fields should also be populated.
 
 ==== Source Field Details
 

generated/beats/fields.ecs.yml

@@ -562,9 +562,15 @@
   - name: destination
     title: Destination
     group: 2
-    description: 'Destination fields describe details about the destination of a packet/event.
-
-      Destination fields are usually populated in conjunction with source fields.'
+    description: 'Destination fields capture details about the receiver of a network
+      exchange/packet. These fields are populated from a network event, packet, or
+      other event containing details of a network transaction.
+
+      Destination fields are usually populated in conjunction with source fields.
+      The source and destination fields are considered the baseline and should always
+      be filled if an event contains source and destination details from a network
+      transaction. If the event also contains identification of the client and server
+      roles, then the client and server fields should also be populated.'
     type: group
     fields:
     - name: address
@@ -4286,9 +4292,15 @@
   - name: source
     title: Source
     group: 2
-    description: 'Source fields describe details about the source of a packet/event.
-
-      Source fields are usually populated in conjunction with destination fields.'
+    description: 'Source fields capture details about the sender of a network exchange/packet.
+      These fields are populated from a network event, packet, or other event containing
+      details of a network transaction.
+
+      Source fields are usually populated in conjunction with destination fields.
+      The source and destination fields are considered the baseline and should always
+      be filled if an event contains source and destination details from a network
+      transaction. If the event also contains identification of the client and server
+      roles, then the client and server fields should also be populated.'
     type: group
     fields:
     - name: address

generated/ecs/ecs_nested.yml

@@ -957,9 +957,15 @@ container:
   title: Container
   type: group
 destination:
-  description: 'Destination fields describe details about the destination of a packet/event.
-
-    Destination fields are usually populated in conjunction with source fields.'
+  description: 'Destination fields capture details about the receiver of a network
+    exchange/packet. These fields are populated from a network event, packet, or other
+    event containing details of a network transaction.
+
+    Destination fields are usually populated in conjunction with source fields. The
+    source and destination fields are considered the baseline and should always be
+    filled if an event contains source and destination details from a network transaction.
+    If the event also contains identification of the client and server roles, then
+    the client and server fields should also be populated.'
   fields:
     destination.address:
       dashed_name: destination-address
@@ -7570,9 +7576,15 @@ service:
   title: Service
   type: group
 source:
-  description: 'Source fields describe details about the source of a packet/event.
-
-    Source fields are usually populated in conjunction with destination fields.'
+  description: 'Source fields capture details about the sender of a network exchange/packet.
+    These fields are populated from a network event, packet, or other event containing
+    details of a network transaction.
+
+    Source fields are usually populated in conjunction with destination fields. The
+    source and destination fields are considered the baseline and should always be
+    filled if an event contains source and destination details from a network transaction.
+    If the event also contains identification of the client and server roles, then
+    the client and server fields should also be populated.'
   fields:
     source.address:
       dashed_name: source-address

schemas/destination.yml

@@ -4,9 +4,13 @@
   group: 2
   short: Fields about the destination side of a network connection, used with source.
   description: >
-    Destination fields describe details about the destination of a packet/event.
+    Destination fields capture details about the receiver of a network exchange/packet. These fields are populated from
+    a network event, packet, or other event containing details of a network transaction.
 
-    Destination fields are usually populated in conjunction with source fields.
+    Destination fields are usually populated in conjunction with source fields. The source and destination
+    fields are considered the baseline and should always be filled if an event contains source
+    and destination details from a network transaction. If the event also contains identification of the
+    client and server roles, then the client and server fields should also be populated.
   type: group
   fields:
 

schemas/source.yml

@@ -4,9 +4,13 @@
   group: 2
   short: Fields about the source side of a network connection, used with destination.
   description: >
-    Source fields describe details about the source of a packet/event.
+    Source fields capture details about the sender of a network exchange/packet. These fields are populated from
+    a network event, packet, or other event containing details of a network transaction.
 
-    Source fields are usually populated in conjunction with destination fields.
+    Source fields are usually populated in conjunction with destination fields. The source and destination
+    fields are considered the baseline and should always be filled if an event contains source
+    and destination details from a network transaction. If the event also contains identification of the
+    client and server roles, then the client and server fields should also be populated.
   type: group
   fields: