Support @deprecated, source, and references in enum items

[floydtree]

Add support for @deprecated, source, and references in enum items.

@deprecated

Currently, the server doesn't support deprecation of individual enum items, for example -

        "activity_id": {
            "description": "The normalized identifier of the Data Security Finding activity.",
            "requirement": "required",
            "enum": {
                "1": {
                    "caption": "Create",
                    "description": "A new Data Security finding is created."
                },
                "2": {
                    "caption": "Update",
                    "description": "An existing Data Security finding is updated with more information."
                },
                "3": {
                    "caption": "Close",
                    "description": "An existing Data Security finding is closed, this can be due to any resolution (e.g., True Positive, False Positive, etc.)."
                },
                "4": {
                    "caption": "Suppressed",
                    "description": "An existing Data Security finding is suppressed due to inaccurate detection techniques or a known true negative."
                }
            }
        },

Consider a situation where we want to deprecate a specific item 4: Suppressed from the enum above. There's no method to do so. We can extend the general deprecation functionality (@deprecated tag) to allow deprecation to enums as well. To exemplify, the following metaschema attribute should deprecate the item in question -

       "4": {
                    "caption": "Suppressed",
                    "description": "An existing Data Security finding is suppressed due to inaccurate detection techniques or a known true negative.",
                    "@deprecated": {
                        "message": "Use the `status_id` attribute instead.",
                        "since": "1.4.0"
                    }
                }

fysa, this a real use-case we recently witnessed. Refer - https://github.com/ocsf/ocsf-schema/pull/1219/files#r1819023305

source

This will allow capture OS native values, similar to the usage of source with attributes.

references

This is needed to add Mitre D3fend references to specific enum values.

[rmouritzen-splunk]

@query-jeremy : FYI
There is no required change to ocsf/ocsf-validator, however if/when we use the deep type definition in ocsf_validator/types.py we'll want to change the enum value definition from this:

class OcsfEnumMember(TypedDict):
    caption: str
    description: NotRequired[str]
    notes: NotRequired[str]

to this:

OcsfEnumMember = TypedDict(
    "OcsfEnumMember",
    {
        "@deprecated": NotRequired[OcsfDeprecationInfo],
        "caption": str,
        "description": NotRequired[str],
        "source": NotRequired[str],
        "references": NotRequired[OcsfReferences],
    },
)

and move the definition of OcsfEnumMember and OcsfEnum down below OcsfDeprecationInfo and OcsfReferences.

I'll created a PR for this, but there's no rush in approving and publishing. ocsf/ocsf-validator#35