Metaschema changed to detect invalid "observable" property in event c…

…lasses, and detect invalid "observables" property in objects. Update CHANGELOG.md with metaschema changes and improvements
ocsf · Mar 26, 2024 · db444ca · db444ca
1 parent 3c7d869
commit db444ca
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 89 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -76,8 +76,17 @@ Thankyou! -->
 ### Breaking changes
 
 ### Misc
-    1. New Extension registration for Sedara. #951
-    2. Add new ways to define observables to metaschema. #982
+1. New Extension registration for Sedara. #951
+2. New ways to define observables in the metaschema. #982 and #993
+    * (Current) Dictionary types using `observable` property in dictionary types. This allows defining all occurrences of attributes of this type as an observable.
+    * (Current) Objects using top-level `observable` property. This allows defining all occurrences attributes whose type is this object as an observable.
+    * _**(New)**_ Dictionary attributes using `observable` property in attribute. This allows defining all occurrences of this attribute as an observable.
+    * _**(New)**_ Object-specific attributes using `observable` property class's attributes. This allows defining object attributes as observables _only_ within instances of this specific object.
+    * _**(New)**_ Event class-specific attributes using `observable` property class's attributes. This allows defining class attributes as observables _only_ within instances of this specific class.
+    * _**(New)**_ Event class-specific attribute _paths_ using top-level `observables` property. The `observables` property holds an object mapping from an dotted attribute path to an observable `type_id`. This allows defining an observables _only_ within instances of this specific class, and only for the attributes at these paths, even for attributes that are within nested objects and arrays. This can also be used for top-level class attributes, which can be more convenient that defining a class attribute observable for classes that extend another, but don't otherwise change a attribute definition.
+3. Metaschema improvements. #993 
+    * Detect unexpected top-level properties in object and event class definitions. This was added at this point to detect invalid observable definitions: invalid `observable` property in event classes, and invalid `observables` property in objects.
+    * Remove hard-coded list of categories from `metaschema/categories.schema.json`, leaving this to the `ocsf-validator`. This change makes testing with alternate schemas that may add extra categories easier, as well as making it possible to validate private extensions that contain new categories.
 
 <!-- All available sections in the Changelog:
 

diff --git a/metaschema/common-event-object.schema.json b/metaschema/common-event-object.schema.json
@@ -0,0 +1,84 @@
+{
+    "$id": "https://schema.ocsf.io/common-event-object.schema.json",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Object",
+    "description": "Common metaschema shared between objects and event classes.",
+    "type": "object",
+    "anyOf": [
+        {
+            "required": [
+                "description",
+                "caption",
+                "name",
+                "attributes"
+            ]
+        },
+        {
+            "required": [
+                "extends"
+            ]
+        }
+    ],
+    "properties": {
+        "@deprecated": {
+            "$ref": "deprecated.schema.json"
+        },
+        "description": {
+          "type": "string",
+          "description": "A concise description of the object."
+        },
+        "caption": {
+          "type": "string",
+          "description": "A short, human friendly name for the object."
+        },
+        "name": {
+          "type": "string",
+          "description": "A name of the object. It must be a unique name. The name is all lower case letters, combine words using underscore.",
+          "pattern": "^[a-z0-9_]*$"
+        },
+        "extends": {
+            "type": "string",
+            "description": "An object that this one extends from."
+        },
+        "constraints": {
+            "type": "object",
+            "description": "Constraints that apply to the attribute requirements.",
+            "properties": {
+                "at_least_one": {
+                    "type": "array",
+                    "items": {"type": "string"}
+                },
+                "just_one": {
+                    "type": "array",
+                    "items": {"type": "string"}
+                }
+            },
+            "additionalProperties": false
+        },
+        "profiles": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "The list of profiles used to create the event."
+        },
+        "attributes": {
+            "type": "object",
+            "description": "A dictionary of attributes for the object.",
+            "properties": {
+                "$include": {
+                    "description": "A reference to another schema for attributes to include.",
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "format": "uri-reference"
+                    }
+                }
+            },
+            "patternProperties": {
+                "^[a-z0-9_]*$": {
+                    "$ref": "attribute.schema.json"
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}
diff --git a/metaschema/event.schema.json b/metaschema/event.schema.json
@@ -3,20 +3,13 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "title": "Event",
     "description": "Event classes are particular sets of attributes and objects representing a log line or telemetry submission at a point in time. Event classes have semantics that describe what happened: either a particular activity, disposition or both.",
-    "allOf": [
+    "anyOf": [
         {
-            "$ref": "object.schema.json"
+            "$ref": "common-event-object.schema.json"
         },
         {
+            "type": "object",
             "properties": {
-                "@deprecated": true,
-                "description": true,
-                "caption": true,
-                "name": true,
-                "extends": true,
-                "constraints": true,
-                "profiles": true,
-                "attributes": true,
                 "associations": {
                     "type": "object",
                     "description": "Associations indicate attributes in a schema which 'go together'. For example, if a schema has multiple users and multiple endpoints, associations can indicate which user attribute goes with which endpoint.",
@@ -47,8 +40,8 @@
                     },
                     "additionalProperties": false
                 }
-            },
-            "additionalProperties": false
+            }
         }
-    ]
+    ],
+    "unevaluatedProperties": false
 }
diff --git a/metaschema/object.schema.json b/metaschema/object.schema.json
@@ -3,85 +3,18 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "title": "Object",
     "description": "An object is a collection of contextually related attributes, usually representing an entity, and may include other objects. Each object is also a data type in OCSF. Examples of object data types are Process, Device, User, Malware and File.",
-    "type": "object",
     "anyOf": [
         {
-            "required": [
-                "description",
-                "caption",
-                "name",
-                "attributes"
-            ]
+            "$ref": "common-event-object.schema.json"
         },
         {
-            "required": [
-                "extends"
-            ]
-        }
-    ],
-    "properties": {
-        "@deprecated": {
-            "$ref": "deprecated.schema.json"
-        },
-        "description": {
-          "type": "string",
-          "description": "A concise description of the object."
-        },
-        "caption": {
-          "type": "string",
-          "description": "A short, human friendly name for the object."
-        },
-        "name": {
-          "type": "string",
-          "description": "A name of the object. It must be a unique name. The name is all lower case letters, combine words using underscore.",
-          "pattern": "^[a-z0-9_]*$"
-        },
-        "extends": {
-            "type": "string",
-            "description": "An object that this one extends from."
-        },
-        "observable": {
-            "$ref": "observable.schema.json"
-        },
-        "constraints": {
-            "type": "object",
-            "description": "Constraints that apply to the attribute requirements.",
-            "properties": {
-                "at_least_one": {
-                    "type": "array",
-                    "items": {"type": "string"}
-                },
-                "just_one": {
-                    "type": "array",
-                    "items": {"type": "string"}
-                }
-            },
-            "additionalProperties": false
-        },
-        "profiles": {
-            "type": "array",
-            "items": {"type": "string"},
-            "description": "The list of profiles used to create the event."
-        },
-        "attributes": {
             "type": "object",
-            "description": "A dictionary of attributes for the object.",
             "properties": {
-                "$include": {
-                    "description": "A reference to another schema for attributes to include.",
-                    "type": "array",
-                    "items": {
-                        "type": "string",
-                        "format": "uri-reference"
-                    }
-                }
-            },
-            "patternProperties": {
-                "^[a-z0-9_]*$": {
-                    "$ref": "attribute.schema.json"
-                }
-            },
-            "additionalProperties": false
+                "observable": {
+                    "$ref": "observable.schema.json"
+                }            
+            }
         }
-    }
+    ],
+    "unevaluatedProperties": false
 }