Deprecate _result attrs in lieu of updated_ convention

[mikeradka]

Related Issue:

• Inconsistent Representation of Pre/Post-Event Target Object State #1601

Related PRs:

• Update Scheduled Job Activity class and expand job object attributes #1597

• Add FAQ for Object State ocsf-docs#134

Description of changes:

This PR deprecates the _result attributes that are used to represent updates to an object, in lieu of using the new updated_ convention.

Deprecated	New	Committed
entity_result	updated_entity	✅
file_result	updated_file. Address new link_target object in separate PR.	✅
resources_result	updated_resources	✅
web_resources_result	updated_web_resources	✅

Also added a few project words for the linter (metaschemas, CLSID), fixed a previous typo in CHANGELOG, and cleaned up minor json whitespace.

Vote Here:

👍 : deprecate these attributes in 1.9
👎 : do not deprecate these attributes in 1.9

[github-actions]

Schema Description Review

Automated suggestions for improving description clarity for LLM consumption. These are advisory — not required changes.

Looking at this compiled schema with my previous review in mind:

Progress Check

✅ All Previously Flagged Issues Resolved: The excellent class-level descriptions for updated_* attributes remain high quality (e.g., "The intended state of the file after the update..."), and the only new attribute (next_run_time in the job object) is appropriately deprecated, indicating this PR is correctly migrating from deprecated patterns.

✅ Structural Completeness: All changed attributes (updated_file, updated_entity, updated_web_resources, updated_job, src_endpoint) are properly typed as object_t with appropriate object type specifications, maintaining schema consistency.

✅ Cross-Reference Consistency: The cross_reference_index confirms type consistency across containers — no type conflicts detected.

New Finding

Anti-Pattern Findings

1. Pattern: Missing _id Sibling
   • Object/Class: job
   • Attribute: next_run_time
   • Issue: The next_run_time attribute uses timestamp_t type but lacks a corresponding next_run_time_dt sibling that would provide datetime_t representation for better timezone handling and display formatting.
   • Recommendation: Add next_run_time_dt attribute to the job object to provide datetime representation alongside the existing timestamp, following the established OCSF pattern where temporal attributes have both timestamp_t and datetime_t variants.

CHANGELOG Issues

None identified.

Summary

All previous description quality concerns have been addressed, with excellent class-level descriptions providing clear guidance for LLM consumers. One minor structural issue remains: the new next_run_time attribute in the job object lacks its expected _dt datetime sibling, which deviates from OCSF's temporal attribute conventions.

[mikeradka]

Alternative Convention Consideration

Consider renaming updated_object to new_object. The updated_ prefix implies the action completed successfully, which is misleading when the field also represents a failed attempt (without referring to documentation). new_ is outcome-neutral and forms a natural before/after pair with the existing web_resources attribute.

For example: new_web_resources

    "new_web_resources": {
      "caption": "New Web Resources",
      "description": "The new or intended <code>web_resources</code> after the update attempt. On <code>Success</code>, represents the actual post-update state; on <code>Failure</code>, represents the intended update that was not applied.",

[mikeradka]

Alternative Convention Consideration

Consider renaming updated_object to new_object. The updated_ prefix implies the action completed successfully, which is misleading when the field also represents a failed attempt (without referring to documentation). new_ is outcome-neutral and forms a natural before/after pair with the existing web_resources attribute.

For example: new_web_resources

    "new_web_resources": {
      "caption": "New Web Resources",
      "description": "The new or intended <code>web_resources</code> after the update attempt. On <code>Success</code>, represents the actual post-update state; on <code>Failure</code>, represents the intended update that was not applied.",

A good point was raised by @floydtree that new_ is interpretable as a wholly new object being created. revised_ and modified_ were also considered, but they carry the same success/failure ambiguity while drifting further from the Update activity that represents the majority use case. On balance, updated_ remains the most accurate and contextually grounded name, and the description carries the weight of clarifying the success/failure distinction.

[jedwardsol]

Alternative Convention Consideration

Consider renaming updated_object to new_object.

new implies to me that this object is being used with create activity. Whereas this PR is addressing the ambiguity in update events. So I prefer having the adjective updated in the name

[jedwardsol]

I notice there is one new dictionary attribute that wasn't in my previous review:

There is also the issue of what to do with Windows registry key and value events; which don't use the _result convention at all but instead have reg_value/prev_reg_value and reg_key/prev_reg_key.

A search also turns up prev_security_level and prev_security_level_id used in https://schema.ocsf.io/1.8.0/classes/device_config_state_change, though this is a discovery class, not an activity class.

[mlmitch]

I can appreciate that updated_* is a better descriptor than *_result. But is it really that much better? What are we gaining by changing this?

This changes causes churn in the schema where there will be a split on the community setting the old *_result fields and the new updated_* fields.

So, I'm struggling to see how the prospective benefits are worth the cost here.

[mikeradka]

I can appreciate that updated_* is a better descriptor than *_result. But is it really that much better? What are we gaining by changing this?

This changes causes churn in the schema where there will be a split on the community setting the old *_result fields and the new updated_* fields.

So, I'm struggling to see how the prospective benefits are worth the cost here.

I can see how that perspective arises. However, the term "result" has been repeatedly identified as ambiguous during our discussions, often interpreted as the final outcome of an operation - such as "job_result" implying the job's completion status and frequently suggesting success. This ambiguity often raises the question: "result of what?" Other examples include "ack_result," which specifically represents the acknowledgment result of a DCE/RPC call rather than an update to an object, and "query_result," which denotes the result of a query operation rather than an update to an object. These examples clearly illustrate that the "*_result" suffix is used to represent outcomes or results of actions, not updates to objects.

In contrast, the "updated_*" naming convention explicitly signifies an attempt to update an object, regardless of whether that attempt succeeds. To ensure clarity and prevent confusion, it is essential to adopt a consistent naming convention for all new objects related to update or modification activities. Avoiding mixed terminology eliminates potential misinterpretation and fosters a clear, uniform, and predictable standard.

While this change introduces some initial schema churn, it is a deliberate and necessary trade-off designed to minimize future disruption and complexity. By employing a deprecation strategy, we enable a smooth transition to version 2.0 by gradually phasing out legacy fields in favor of the clearer, standardized "updated_*" naming. This approach balances short-term inconvenience with long-term benefits, promoting consistency and predictability, simplifying integration, and reducing operational overhead.

If you have specific concerns about the implementation, we can also explore documentation strategies to help mitigate the impact of the transition and the use of deprecated fields.

Also curious for further inputs on whether these deprecations are warranted and if deeper discussion is needed @floydtree @pagbabian-splunk @Aniak5 @zschmerber @hmadison @jasonbreimer

[pagbabian-splunk]

Hopefully the updated_user won't conflict with the one in PR #1616: looks to be the same.

Need a description for link_target in dictionary.

[mikeradka]

PR is on hold until votes are cast on whether to deprecate these attributes or not. Please give a 👍 or 👎 in this PR description to cast a vote. Additional perspective and commentary is welcome.

[mikeradka]

Schema Anti-Pattern Check

Automated structural analysis for common schema design anti-patterns. These are advisory — not required changes.

Warnings

1. tautological-description — dictionary.updated_user
updated_user description "The updated user. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

2. tautological-description — dictionary.updated_file
updated_file description "The updated file. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

3. tautological-description — dictionary.updated_web_resources
updated_web_resources description "The updated web resources. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

4. tautological-description — dictionary.updated_resources
updated_resources description "The updated resources. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

5. tautological-description — dictionary.updated_entity
updated_entity description "The updated entity. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

Summary: 5 warning(s), 0 informational finding(s)

These generic 'see specific usage' descriptions were based on the suggestions and consensus in the 5/6/26 System Call and for parity with the dictionary descriptions in #1603 and #1597

[mikeradka]

We discussed this PR extensively in the Maintainer's call on 5/22 and determined to proceed with this PR. The link_target will be addressed in a separate PR.

[Aniak5]

Very nice improvement!