Usage of CloudEvents "subject"

[afrittoli]

Feature

We should document in the CloudEvents binding document how the subject should be populated when sending CDEvents.

Proposal

All CDEvents are related to an activity and an entity - like taskrun started or artifact published.
Entities are identified by an ID which we could use to fill in the subject of the CloudEvents.
That would allow CloudEvents consumers to easily filter events based on the subject.

Example:

{
    "specversion" : "1.0",
    "type" : "cd.events.taskrun.started",
    "source" : "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk",
    "subject" : "my-taskrun-123",  <=====
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "cdeventssource" : "tekton_ci_prod/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk",
    "cdeventsplatform" : "tekton_node123_clusterABC",
    "cdeventssourceevent":  "A123-5678-9012@jenkins_ci_prod/pipeline/my-source-pipeline",
    "datacontenttype" : "text/json",
    "data" : {
        "taskrun" : {
            "id": "my-taskrun-123", <=====
            "task": "my-task",
            "status": "Running",
            "URL": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk"
        }
    }
}

[erkist]

Your proposal makes a lot of sense to me. The type field would say what we are doing, and the subject field would say what we are doing it on/with/for.

I think we might need to provide a clear table in the spec stating for each event type what exactly the subject should be, just for clarity.

[afrittoli]

Your proposal makes a lot of sense to me. The type field would say what we are doing, and the subject field would say what we are doing it on/with/for.

I think we might need to provide a clear table in the spec stating for each event type what exactly the subject should be, just for clarity.

Yeah, that's a great idea.
The setup that I'm forming in my mind is, for each event a few elements will go in the CloudEvents context.
We could consider id and source as general cdevents context, mapped to CloudEvents context.
subject instead would map to a different event field based on the event type i.e. PIpelineRun ID, Environment ID etc..