Is Categories an enum or an object?

[davaya]

categories.json appears to be an enumerated list of items, but the items are called "attributes" as if they were properties of an object.:

{
  "caption": "Categories",
  "name": "category",
  "description": "Initial working list of categories (work in progress).",
  "attributes": {
    "system": {
      "caption": "System Activity",
      "description": "System Activity events.",
      "uid": 1
    },
    "findings": {
      "caption": "Findings",
      "description": "Findings events report findings, detections, and possible resolutions of malware, anomalies, or other actions performed by security products.",
      "uid": 2
    },
   ...

represents a list of enumerated items:

UID	Name	Description
1	system	System Activity: System Activity events
2	findings	Findings: Findings events report findings, detections, and possible resolutions of malware, anomalies, or other actions performed by security products.
...	...	...

But an example enum file is JSON data in a different format that represents the identical kind of enumerated list:

{
  "enum": {
    "1": {
      "caption": "Login",
      "description": "The event pertains to login activity."
    },
    "2": {
      "caption": "IAM",
      "description": "The event pertains to Identity and Access Management (IAM) activity (e.g. policy updates, user creations, etc.)."
    },
    "3": {
      "caption": "Operational",
      "description": "The event pertains to cloud resource operations activity (e.g. data downloads, launched virtual machines, etc.)."
    }
  }
}

UID	Name	Description
1	Login	The event pertains to login activity.
2	IAM	The event pertains to Identity and Access Management (IAM) activity (e.g. policy updates, user creations, etc.).
3	Operational	The event pertains to cloud resource operations activity (e.g. data downloads, launched virtual machines, etc.).

Proposal

Use the same data structure for enumerated lists in categories.json, all files in the enums directory, and other files where enums are embedded.

Using different data to represent the same kind of information is unnecessary. Putting numeric UIDs into strings is confusing because strings are often displayed in lexical order instead of numeric order (as can be seen in URL Categories). And using caption as a name may be unsuitable when the item should have an identifier but the caption (e.g. "System Activity") is not an identifier.

1. Rename the "attributes" property in categories.json to "enum"
2. Restructure all enums to have the same structure as categories.json, with a numeric "uid" property instead of putting the number in a string, and with an explicit property name (e.g. "login", "iam", "operational") instead of using the caption as the item name.

[rroupski]

The file contains a list of categories, although it may look like na enumeration it is just a list. The code that handles the objects, classes, dictionary, and categories expects a list of "attributes".

[davaya]

That sounds like a distinction without a difference. The code expects a list of "things", where each thing is defined in the list of categories.

The "attributes" used in objects is nothing like the "attributes" used in categories. Object attributes is not a list of the same kind of item, the items don't have UIDs, the items can be required or optional. If an enumeration walks like a duck and quacks like a duck, it is an enumeration no matter what it's called.

{
  "attributes": {
    "decision": {
      "description": "Authorization Result/outcome, e.g. allowed, denied",
      "requirement": "optional"
    },
    "permission": {
      "requirement": "optional"
    }
  },
  "description": "Details pertaining to Authorization Information",
  "extends": "object",
  "caption": "Authorization Information",
  "name": "authorization"
}

The more important question is can we define enumerated items to have proper (numeric) UIDs and identifiers (property names) the way categories do?

[paveljos]

String enums siblings have been addressed with #450