Backport schema changes from docs (#603)

* Update schema * Fixes from review
cognitedata · Feb 20, 2024 · c9ce092 · c9ce092
1 parent 888adcd
commit c9ce092
Show file tree

Hide file tree

Showing 16 changed files with 583 additions and 440 deletions.
diff --git a/schema/cognite_config.schema.json b/schema/cognite_config.schema.json
diff --git a/schema/continuation_point_throttling.schema.json b/schema/continuation_point_throttling.schema.json
@@ -2,12 +2,16 @@
     "$id": "continuation_point_throttling.schema.json",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "type": "object",
-    "allOf": [{ "$ref": "ua-throttling-config" }],
+    "allOf": [
+        {
+            "$ref": "ua-throttling-config"
+        }
+    ],
     "unevaluatedProperties": false,
     "properties": {
         "max-node-parallelism": {
             "type": "integer",
-            "description": "Maximum number of concurrent nodes accross all parallel requests"
+            "description": "Maximum number of concurrent nodes accross all parallel requests."
         }
     },
     "$defs": {
@@ -18,11 +22,11 @@
             "properties": {
                 "max-per-minute": {
                     "type": "integer",
-                    "description": "Maximum number of requests per minute, approximately"
+                    "description": "Maximum number of requests per minute, approximately."
                 },
                 "max-parallelism": {
                     "type": "integer",
-                    "description": "Maximum number of parallel requests"
+                    "description": "Maximum number of parallel requests."
                 }
             }
         }

diff --git a/schema/event_config.schema.json b/schema/event_config.schema.json
@@ -2,72 +2,88 @@
     "$id": "event_config.schema.json",
     "type": "object",
     "unevaluatedProperties": false,
-    "description": "Configuration for extraction OPC-UA events and alarams as CDF events or litedb time series",
-    "required": ["enabled"],
+    "description": "Configuration for extracting OPC UA events and alarams as CDF events or litedb time series",
+    "required": [
+        "enabled"
+    ],
     "properties": {
+        "enabled": {
+            "type": "boolean",
+            "description": "Set to `true` to enable reading events from the server"
+        },
+        "history": {
+            "type": "boolean",
+            "description": "Set to `true` to enable reading event history"
+        },
+        "all-events": {
+            "type": "boolean",
+            "description": "Set to `true` to read base OPC UA events, in addition to custom events.",
+            "default": true
+        },
+        "read-server": {
+            "type": "boolean",
+            "description": "Set to `true` to enable checking the server node when looking for event emitters",
+            "default": true
+        },
+        "destination-name-map": {
+            "type": "object",
+            "description": "Map source browse names to other values in the destination. For CDF, internal properties may be overwritten. By default `Message` is mapped to `description`, `SourceNode` is used to set the `assetIds`, and `EventType` is mapped to `type`. These may be replaced by overrides in `destination-name-map`.\n\nIf `StartTime`, `EndTime`, or `SubType` are specified, either on the event in OPC-UA itself, or translated through this map, they are set directly on the CDF event. `StartTime` and `EndTime` should be either `DateTime`, or a number corresponding to the number of milliseconds since 01/01/1970. If no `StartTime` or `EndTime` are specified, both are set to the `Time` property.",
+            "examples": [
+                {
+                    "MyProperty": "SubType",
+                    "MyEndTime": "EndTime"
+                }
+            ],
+            "patternProperties": {
+                ".*": {
+                    "type": "string",
+                    "description": "Target field to map to.",
+                    "enum": [
+                        "StartTime",
+                        "EndTime",
+                        "SubType",
+                        "Type"
+                    ]
+                }
+            }
+        },
         "event-ids": {
             "type": "array",
-            "description": "Event ids to map. Custom events must be subtypes of `BaseEventType`. This is used to specify which events should be extracted, instead of just extracting all events",
+            "description": "Allow-list of event type IDs to map. If this is included, only the events with type equal to one of these node IDs will be included.",
             "items": {
                 "$ref": "proto_node_id.schema.json"
             }
         },
+        "exclude-event-filter": {
+            "type": "string",
+            "description": "Regex filter on event type `DisplayName`, matches will not be extracted."
+        },
         "emitter-ids": {
             "type": "array",
-            "description": "Id of nodes to be subscribed to as event emitters. Empty defaults to the server node. This is used to add extra emitters that are not in the extracted node hierarchy, or that does not correctly specify the `EventNotifier` property",
+            "description": "List of event emitters to extract from. The default behavior is to extract events from nodes based on the `EventNotifier` attribute. This option ignores `EventNotifier` and extracts events from the given list of nodes.",
             "items": {
                 "$ref": "proto_node_id.schema.json"
             }
         },
         "historizing-emitter-ids": {
             "type": "array",
-            "description": "Should be a subset of the `emitter-ids` property. Used to make the extractor read history from certain emitter nodes. Requires `events.history` to be `true`",
+            "description": "List of node IDs that must be a subset of the `emitter-ids` property. These emitters will have their event history read. The server must support historical events. The `events.history` property must be `true` for this to work.",
             "items": {
                 "$ref": "proto_node_id.schema.json"
             }
         },
-        "enabled": {
-            "type": "boolean",
-            "description": "`true` enables reading events from the server"
-        },
         "discover-emitters": {
             "type": "boolean",
-            "description": "Automatically treat nodes with suitable `EventNotifier` as event emitters",
-            "default": true
-        },
-        "all-events": {
-            "type": "boolean",
-            "description": "Enable reading both custom and base OPC-UA events",
-            "default": true
-        },
-        "history": {
-            "type": "boolean",
-            "description": "`true` enables reading event history"
-        },
-        "exclude-event-filter": {
-            "type": "string",
-            "description": "Regex filter on event type `DisplayName`, matches will be ignored"
-        },
-        "read-server": {
-            "type": "boolean",
-            "description": "`true` enables checking the server node when looking for event emitters",
+            "description": "Automatically treat nodes with suitable `EventNotifier` as event emitters when they are discovered in the node hierarchy.",
             "default": true
         },
         "exclude-properties": {
             "type": "array",
-            "description": "List of `BrowseName`s of event properties that are to be excluded from automatic mapping to destination metadata. `LocalTime` and `ReceiveTime` are excluded by default. Be aware that a maximum of 16 metadata entries are allowed in CDF",
+            "description": "List of `BrowseName`s of event properties that are to be excluded from automatic mapping to destination metadata. By default, `LocalTime` and `ReceiveTime` are excluded. Be aware that a maximum of 16 metadata entries are allowed in CDF.",
             "items": {
                 "type": "string",
                 "description": "`BrowseName` of an event property"
             }
-        },
-        "destination-name-map": {
-            "type": "object",
-            "description": "Map source browse names to other values in the destination. For CDF, internal properties may be overwritten, by default `Message` is mapped to `description`, `SourceNode` is used to set the `assetIds`, and `EventType` is mapped to `type`. These may be replaced by overrides in `destination-name-map`. If `StartTime`, `EndTime`, or `SubType` are specified, either on the event in OPC-UA itself, or translated through this map, they are set directly on the CDF event. `StartTime` and `EndTime` should be either `DateTime`, or a number corresponding to the number of milliseconds since 01/01/1970. If no `StartTime` or `EndTime` are specified, both are set to the `Time` property.",
-            "examples": [{
-                "MyProperty": "SubType",
-                "MyEndTime": "EndTime"
-            }]
         }
     }
 }