Add examples and reorder some processor configurations in schemas (#5216)

* update schemas according to review

Signed-off-by: Katherine Shen <katshen@amazon.com>

* fix build

Signed-off-by: Katherine Shen <katshen@amazon.com>

---------

Signed-off-by: Katherine Shen <katshen@amazon.com>

Author: shenkw1

data-prepper-plugins/csv-processor/src/main/java/org/opensearch/dataprepper/plugins/processor/csv/CsvProcessorConfig.java

@@ -37,7 +37,7 @@ public class CsvProcessorConfig {
     @JsonPropertyDescription("The character separating each column. Default value is <code>,</code>.")
     private String delimiter = DEFAULT_DELIMITER;
 
-    @JsonProperty("delete_header")
+    @JsonProperty(value = "delete_header", defaultValue = "true")
     @JsonPropertyDescription("If specified, the event header (<code>column_names_source_key</code>) is deleted after the event " +
             "is parsed. If there is no event header, no action is taken. Default value is true.")
     private Boolean deleteHeader = DEFAULT_DELETE_HEADERS;
@@ -68,6 +68,10 @@ public class CsvProcessorConfig {
     })
     private List<String> columnNames;
 
+    @JsonPropertyDescription("If true, the configured source field will be deleted after the CSV data is parsed into separate fields.")
+    @JsonProperty
+    private boolean deleteSource = false;
+
     @JsonProperty("csv_when")
     @JsonPropertyDescription("A <a href=\"https://opensearch.org/docs/latest/data-prepper/pipelines/expression-syntax/\">conditional expression</a> such as <code>/some_key == \"test\"</code>. " +
             "If specified, the <code>csv</code> processor will only run on events when the expression evaluates to true. ")
@@ -76,10 +80,6 @@ public class CsvProcessorConfig {
     })
     private String csvWhen;
 
-    @JsonPropertyDescription("If true, the configured source field will be deleted after the CSV data is parsed into separate fields.")
-    @JsonProperty
-    private boolean deleteSource = false;
-
     /**
      * The field of the Event that contains the CSV data to be processed.
      *

data-prepper-plugins/date-processor/src/main/java/org/opensearch/dataprepper/plugins/processor/date/DateProcessorConfig.java

@@ -198,6 +198,9 @@ public static boolean isValidPattern(final String pattern) {
     @JsonProperty("date_when")
     @JsonPropertyDescription("Specifies under what condition the <code>date</code> processor should perform matching. " +
             "Default is no condition.")
+    @ExampleValues({
+        @Example(value = "/some_key == null", description = "Only runs the date processor on the Event if some_key is null or doesn't exist.")
+    })
     private String dateWhen;
 
     @JsonIgnore

data-prepper-plugins/decompress-processor/src/main/java/org/opensearch/dataprepper/plugins/processor/decompress/DecompressProcessorConfig.java

@@ -33,6 +33,9 @@ public class DecompressProcessorConfig {
     @JsonPropertyDescription("The type of decompression to use for the keys in the event. Only <code>gzip</code> is supported.")
     @JsonProperty("type")
     @NotNull
+    @ExampleValues({
+            @Example(value = "gzip", description = "GZIP decompression.")
+    })
     private DecompressionType decompressionType;
 
     @JsonPropertyDescription("A list of strings with which to tag events when the processor fails to decompress the keys inside an event. Defaults to <code>_decompression_failure</code>.")

data-prepper-plugins/grok-processor/src/main/java/org/opensearch/dataprepper/plugins/processor/grok/GrokProcessorConfig.java

@@ -114,11 +114,14 @@ public class GrokProcessorConfig {
 
     @JsonProperty(TAGS_ON_TIMEOUT)
     @JsonPropertyDescription("The tags to add to the event metadata if the grok match times out.")
-    @ExampleValues({
-        @Example(value = "_timeout", description = "Events are tagged with this string if grok match times out.")
-    })
     private List<String> tagsOnTimeout = Collections.emptyList();
 
+    @JsonProperty(INCLUDE_PERFORMANCE_METADATA)
+    @JsonPropertyDescription("A boolean value to determine whether to include performance metadata into event metadata. " +
+            "If set to true, the events coming out of grok will have new fields such as <code>_total_grok_patterns_attempted</code> and <code>_total_grok_processing_time</code>." +
+            "You can use this metadata to perform performance testing and tuning of your grok patterns. By default, it is not included.")
+    private boolean includePerformanceMetadata = false;
+
     @JsonProperty(GROK_WHEN)
     @ExampleValues({
         @Example(value = "/type == \"ipv4\"", description = "When the IP type is IPV4, the processor will perform matching.")
@@ -127,12 +130,6 @@ public class GrokProcessorConfig {
             "If specified, the <code>grok</code> processor will only run on events when the expression evaluates to true. ")
     private String grokWhen;
 
-    @JsonProperty(INCLUDE_PERFORMANCE_METADATA)
-    @JsonPropertyDescription("A boolean value to determine whether to include performance metadata into event metadata. " +
-            "If set to true, the events coming out of grok will have new fields such as <code>_total_grok_patterns_attempted</code> and <code>_total_grok_processing_time</code>." +
-            "You can use this metadata to perform performance testing and tuning of your grok patterns. By default, it is not included.")
-    private boolean includePerformanceMetadata = false;
-
     public boolean isBreakOnMatch() {
         return breakOnMatch;
     }

data-prepper-plugins/mutate-event-processors/src/main/java/org/opensearch/dataprepper/plugins/processor/mutateevent/AddEntryProcessorConfig.java

@@ -66,7 +66,7 @@ public class AddEntryProcessorConfig {
     public static class Entry {
         @JsonPropertyDescription("The key of the new entry to be added. Some examples of keys include <code>my_key</code>, " +
                 "<code>myKey</code>, and <code>object/sub_Key</code>. The key can also be a format expression, for example, <code>${/key1}</code> to " +
-                "use the value of field <code>key1</code> as the key.")
+                "use the value of field <code>key1</code> as the key. Either one of <code>key</code> or <code>metadata_key</code> is required.")
         @AlsoRequired(values = {
                 @AlsoRequired.Required(name=METADATA_KEY_KEY, allowedValues = {"null"})
         })

data-prepper-plugins/mutate-event-processors/src/main/java/org/opensearch/dataprepper/plugins/processor/mutateevent/ConvertEntryTypeProcessorConfig.java

@@ -38,14 +38,14 @@ public class ConvertEntryTypeProcessorConfig implements ConverterArguments {
     static final String KEYS_KEY = "keys";
 
     @JsonProperty(KEY_KEY)
-    @JsonPropertyDescription("Key whose value needs to be converted to a different type.")
+    @JsonPropertyDescription("Key whose value needs to be converted to a different type. Cannot be declared at the same time as <code>keys</code>.")
     @AlsoRequired(values = {
             @AlsoRequired.Required(name = KEYS_KEY, allowedValues = {"null"})
     })
     private String key;
 
     @JsonProperty(KEYS_KEY)
-    @JsonPropertyDescription("List of keys whose values needs to be converted to a different type.")
+    @JsonPropertyDescription("List of keys whose values needs to be converted to a different type. Cannot be declared at the same time as <code>key</code>.")
     @AlsoRequired(values = {
             @AlsoRequired.Required(name = KEY_KEY, allowedValues = {"null"})
     })

data-prepper-plugins/mutate-event-processors/src/main/java/org/opensearch/dataprepper/plugins/processor/mutateevent/CopyValueProcessorConfig.java

@@ -86,14 +86,14 @@ public Entry() {
     private List<Entry> entries;
 
     @JsonProperty(FROM_LIST_KEY)
-    @JsonPropertyDescription("The key of the list of objects to be copied.")
+    @JsonPropertyDescription("The key of the list of objects to be copied. <code>to_list</code> must also be defined.")
     @AlsoRequired(values = {
             @AlsoRequired.Required(name = TO_LIST_KEY)
     })
     private String fromList;
 
     @JsonProperty(TO_LIST_KEY)
-    @JsonPropertyDescription("The key of the new list to be added.")
+    @JsonPropertyDescription("The key of the new list to be added. <code>from_list</code> must also be defined.")
     @AlsoRequired(values = {
             @AlsoRequired.Required(name = FROM_LIST_KEY)
     })

data-prepper-plugins/mutate-event-processors/src/main/java/org/opensearch/dataprepper/plugins/processor/mutateevent/ListToMapProcessorConfig.java

@@ -102,7 +102,7 @@ public String getOptionValue() {
     private boolean extractValue = false;
 
     @NotNull
-    @JsonProperty("flatten")
+    @JsonProperty(value = "flatten", defaultValue = "false")
     @JsonPropertyDescription("When <code>true</code>, values in the generated map output flatten into single items based on " +
             "the <code>flattened_element</code>. Otherwise, objects mapped to values from the generated map appear as lists. " +
             "Default is <code>false</code>.")
@@ -121,6 +121,9 @@ public String getOptionValue() {
     @JsonPropertyDescription("A <a href=\"https://opensearch.org/docs/latest/data-prepper/pipelines/expression-syntax/\">conditional expression</a>, " +
             "such as <code>/some-key == \"test\"</code>, that will be evaluated to determine whether the processor will be " +
             "run on the event. By default, all events will be processed unless otherwise stated.")
+    @ExampleValues({
+        @Example(value = "/some-key == \"test\"", description = "The operation will run when the value of the key is 'test'.")
+    })
     private String listToMapWhen;
 
     public String getSource() {

data-prepper-plugins/mutate-event-processors/src/main/java/org/opensearch/dataprepper/plugins/processor/mutateevent/MapToListProcessorConfig.java

@@ -65,16 +65,10 @@ public class MapToListProcessorConfig {
     @JsonProperty("exclude_keys")
     @JsonPropertyDescription("The keys in the source map that will be excluded from processing. Default is an " +
             "empty list (<code>[]</code>).")
-    @ExampleValues({
-        @Example(value = "[\"key1\"]", description = "When the key is 'key1', the processor will not include this key-value pair in the list and will leave it in the map.")
-    })
     private List<String> excludeKeys = DEFAULT_EXCLUDE_KEYS;
 
     @JsonProperty("tags_on_failure")
     @JsonPropertyDescription("A list of tags to add to the event metadata when the event fails to process.")
-    @ExampleValues({
-        @Example(value = "[\"_failure\"]", description = "{\"tags\": [\"_failure\"]} will be added to the event’s metadata in the event of a processing failure.")
-    })
     private List<String> tagsOnFailure;
 
     @JsonProperty("map_to_list_when")

data-prepper-plugins/mutate-event-processors/src/main/java/org/opensearch/dataprepper/plugins/processor/mutateevent/RenameKeyProcessorConfig.java

@@ -43,6 +43,9 @@ public static class Entry {
         @JsonProperty(defaultValue = FROM_KEY_REGEX)
         @JsonPropertyDescription("The regex pattern of the key of the entry to be renamed. " +
                 "This field cannot be defined along with <code>from_key</code>.")
+        @ExampleValues(
+                @Example(value = "regex", description = "Generic regex string.")
+        )
         @AlsoRequired(values = {
                 @AlsoRequired.Required(name = FROM_KEY, allowedValues = {"null"})
         })