How is `event_data` supposed to work?

[bradenmacdonald]

Let's say we have the CONTENT_OBJECT_ASSOCIATIONS_CHANGED event:

openedx-events/openedx_events/content_authoring/signals.py

Lines 239 to 249 in 34d3fce

	# .. event_type: org.openedx.content_authoring.content.object.associations.changed.v1
	# .. event_name: CONTENT_OBJECT_ASSOCIATIONS_CHANGED
	# .. event_description: Emitted when an object's associations are changed, e.g tags, collections
	# .. event_data: ContentObjectChangedData
	# .. event_trigger_repository: openedx/edx-platform
	CONTENT_OBJECT_ASSOCIATIONS_CHANGED = OpenEdxPublicSignal(
	event_type="org.openedx.content_authoring.content.object.associations.changed.v1",
	data={
	"content_object": ContentObjectChangedData,
	}
	)

And I want to add the context (course/library ID) to this event, like this:

  CONTENT_OBJECT_ASSOCIATIONS_CHANGED = OpenEdxPublicSignal( 
      event_type="org.openedx.content_authoring.content.object.associations.changed.v1", 
      data={ 
          "content_object": ContentObjectChangedData,
+         "context": ContextIdData,
      } 
  ) 

Is that sort of change allowed? If so, how would I update event_data in the comment/documentation of the event? If not, why is data a dictionary? How do we know from the in-line code annotation what key (e.g. content_object) the event data is under?

This is not explained in the docs as far as I can see.

[ormsbee]

FWIW, when I was involved in openedx-events arch design way back when, it was very much my intention that this would be the way to extend events: by adding new objects to the data dict, as opposed to modifying the definition of existing data. That being said, there was a lot of thought put in towards message compatibility during the message bus work, and I don't know if it had to change because of that.

[bradenmacdonald]

@mariajgrimaldi would you be able to advise us on this?

[bradenmacdonald]

Actually I got Claude to do an in-depth investigation here and I think it has explained everything.

Is that change allowed?

Yes — it's the sanctioned evolution path, confirming @ormsbee's comment. See ADR‑6 ("Event schema serialization and evolution"), which explicitly says:

• The top-level data dict of an OpenEdxPublicSignal can be evolved by adding new key/values.
• An attr Data class will not be evolved once in use. If new fields are required for an event, they can only be added into the top-level data dict.

So "context": ContextIdData as a new top-level key is exactly the intended shape. This is also why data is a dict in the first place — it is the only surface allowed to grow. (ADR‑6 even acknowledges the cost: "potential to have events be messier than they otherwise would be. Again, this could potentially be avoided by adding support for optional fields" — deferred.)

Mechanically, data being a dict is enforced in openedx_events/tooling.py:139-146: the keys become the keyword arguments that send_event(...) expects, and the event‑bus producer iterates signal.init_data to build the payload (openedx_events/apps.py:33). Adding a key means producers just pass an extra kwarg: CONTENT_OBJECT_ASSOCIATIONS_CHANGED.send_event(content_object=..., context=...).

Caveat worth noting in the issue: right now 0 of 75 signals in the repo use more than one top‑level key, so this would be the first one. You'll want a CHANGELOG entry and probably a coordinated bump on the consumer side.

How do you update the event_data annotation?

Honestly — the annotation schema has no answer for this 🚩, and that's the real doc gap issue #562 is exposing:

• The reference doc describes event_data as "What type of class attribute the event sends" (singular), and every in‑repo example uses a single class.
• The Sphinx renderer treats it as a free-form string label — it just prints Event data: <literal> on the generated page. So pragmatically you could write # .. event_data: ContentObjectChangedData, ContextIdData and it would render fine.
• The pylint checker at events_annotation_check.py:198-202 only inspects node.keywords[1].value.items[0][1].name — i.e. the class name of the first dict entry. So as long as the annotation matches the first entry's class, lint passes; the second key is invisible to the checker.

"How do we know from the annotation what key (e.g. content_object) the event data is under?"

You don't. 🚩 The annotation records only the class name, not the dict key. To know you're supposed to call send_event(content_object=...), you have to read the Python data={...} literal in signals.py. This is a real weakness of the current annotation scheme — worth calling out as a separate follow-up to enrich event_data (or introduce an event_payload_key/structured format).

What parses the event annotations, and how?

Two consumers, both built on the openedx/code-annotations package, driven by a single config file openedx_events_annotations.yaml that lists the valid tokens (.. event_type:, .. event_name:, .. event_description:, .. event_data:, .. event_key_field:, .. event_trigger_repository:, .. event_warning:).

1. Sphinx rendering (what produces the events page in the docs). Enabled in docs/conf.py:44 via code_annotations.contrib.sphinx.extensions.openedx_events. It calls StaticSearch, which does a regex scan over .py files for # .. <token>: <value> lines, groups consecutive ones, and returns {token: raw_string} dicts. Then the openedxevents directive generates one section per event, splitting event_type on . to derive the subdomain/subject headings. It's purely string handling — no AST, no awareness of the dict.

2. Pylint enforcement: pylintrc_tweaks loads edx_lint.pylint.events_annotation (see pylintrc:72), registering EventsAnnotationChecker. This checker uses the same config file + StaticSearch to locate annotation groups, then walks the astroid AST: for each OpenEdxPublicSignal(...) call it verifies event_type/event_name/event_data in the comment match the call's first positional/kwarg shape. Required annotations (type/name/data/description) are enforced as pylint errors E…80‑E…85.

Both are tolerant of extra text in event_data — which is why there's currently no clean answer for multi‑key payloads. Seems worth a follow-up PR to either (a) document a convention (comma-list the classes), or (b) change the annotation to name the dict keys (e.g. event_data: content_object=ContentObjectChangedData, context=ContextIdData), which would also give the lint checker something to enforce.

[ormsbee]

BTW, some of this was discussed in #38

[bradenmacdonald]

So, the ADR that resulted from that discussion says:

An attr Data class will not be evolved once in use. If new fields are required for an event, they can only be added into the top-level data dict.

But two PRs have added new fields within existing attr data classes: #553 and #404