Add namespacing to event-type

[inlined]

Overview

Add reverse-DNS namespacing to event-type. This commit has been spliced off of #129.

I agree that removing namespace from the spec was a step in the right direction because it was ambiguous what is being namespaced. This change proposes that event types are themselves namespaced. This can be important for any proxy or action that chooses to group related streams of events. As I've said before, there's a very big difference between "document.create" events when you're referring to a Word document or a Mongo document.

Updated seralization.md, including removing the "namespace" parameters that were already removed from spec.md.

Usage Scenarios

Hosted Software

A GitHub pull request event from github.com

{
  "source-authority": "github.com",
  "source-path": "cloudevents/spec/pull/129",
  "event-type": "com.github.pull.create"
}

Self-managed software

The same event on enterprise GitHub. Because the event is from the same software running in a new location, the source path and event type stay the same; only the source-authority changes.

{
  "source-authority": "git.internal.mycompany.com",
  "source-path": "cloudevents/spec/pull/129",
  "event-type": "com.github.pull.create"
}

Closes: #32

[duglin]

@inlined couple of questions for ya as we ponder this:

• how much duplication would there be between the namespace of the event-type and the source URI? You call it "the software that produces the event". Feels like there might be at least some. And what would it mean if they didn't match?
• kind of related, what if a non-github piece of software wanted to produce an event type of com.github.pull.create so the same router can handle events from both. I can see cases where the source URI has example.com but the event-type is com.github.pull.create. The "software that produces the event" may not be the best phrase in that case, right? It feels like the namespace of the event should scope the "semantics of the event" rather than the "source of the event".
• you made it mandatory (with a MUST). How firm are you on this? Would a SHOULD provide enough guidance? I'm wondering because while I do see the value in it, especially in an environment where you may get lots of events from lots of different sources, I'm nervous about forcing someone in a more constrained environment to add more text unnecessarily just so they're compliant with the spec.

[duglin]

@inlined just to add a little more concreteness to my 2nd bullet in the previous comments... if we do add this, would it make sense to define the namespace portion of it more like this:

---

The namespace portion of the event-type provides a classification mechanism to scope the event. For example, com.github.create is more meaningful than just create as it explicitly puts the event within a grouping of other semantically related events.

---

Not thrilled with the wording, but hopefully you get where I'm headed. just an idea....

[inlined]

how much duplication would there be between the namespace of the event-type and the source URI?

I suspect there would usually be duplication for services (e.g. S3) and almost never duplication with self-managed software. Other cases exist within a software organization if non-prod tiers are hosted at a different URI but still conform to the prod API definition.

kind of related, what if a non-github piece of software wanted to produce an event type of com.github.pull.create so the same router can handle events from both.

Indeed. Maybe I could use some help word-smithing this. I had originally used hosted + on-prem software as my mental model, but there's also a "compatibility mode" use case as well. E.g. Google Cloud Storage implements AWS S3's API. I see no problem with that team also supporting AWS's events, though any divergence in behavior should be Google's bug, not Amazon's. Amazon would "own" the semantics of all events prefixed by their domain.

Similarly, I would love it if domain-specific working groups came up with standard events that many vendors would conform to, such as org.cncf.iot.window.open

you made it mandatory (with a MUST). How firm are you on this? Would a SHOULD provide enough guidance?

I would need to think about this. Some software (especially any catalog services akin to Kubernetes' Service Catalog) would need this to be a MUST (and possibly add site ownership verification) were it to link the event type to any documentation, spec, etc. Otherwise there could be land rushes, name stealing, etc.

[ultrasaurus]

@duglin I don't see how it would work if event-type had no namespace. How do people make up new event types? I'd prefer to avoid some kind of central registry in the near-term. As a developer, I want to know that object.create or object.update has a specific payload -- for the latter, some vendors may include a diff, some may include the new object in its entirety, some may include new and old.

The proposal is to have namespaces for source and event type separate to allow for multiple orgs (different producers) to deploy the same software.

So, for example, in some future world, WordPress might have an event-type org.wordpress.post.create and I could host my WordPress blog that with a source of ultrasaurus.com/wp and if SAP were using WordPress for their blog, they might have a source of blogs.sap.com/ -- both would use the same event type, since it is generated by the same piece of software.

This seems to be a critical refinement to the spec in order to allow for interoperability.

[duglin]

I wasn't thinking of a centralized registry or anything like that. Nor was I suggesting that people not use namespaces. In the internet where you have lots of systems at play I totally agree with something more than just create as the event-type, and a semantic namespace makes sense. All I was suggesting is that there are some cases (like on-prem, limited in scope envs) where create is all that is needed because they know exactly what's going on and where the event is coming from. So tagging them as non-compliant and forcing them to add a unnecessary namespace seemed like overhead. Which is why I was asking for a SHOULD, it provided the proper guidance w/o being too cumbersome in certain cases. Not a major issue, just something I wanted to put out there.

[clemensv]

I'm with @duglin on this. I find SHOULD sufficient.

FWIW, our usage "Microsoft.Storage.BlobCreated" is already compliant. We own the .microsoft TLD.

[inlined]

@clemensv @duglin I'm not categorically against softening this to a "SHOULD." I'd like to lean on other successful specs as case studies where an analogous key either has a MUST (which lets us ask whether it was considered onerous) or has a SHOULD (which lets us ask whether any problems arose). Do any come to mind?

Also, I wonder if we could narrow the amount we weaken the claim. E.g. it MUST be namespaced. The namespace SHOULD be a domain associated with the product. The namespace MAY be used for routing and software MAY require the domain ownership be verified.

[duglin]

What about:

Description: Type of occurrence which has happened. Often this property is
used for routing, observability, policy enforcement, etc.
* Constraints:
  * REQUIRED
  * MUST be a non-empty string
  * SHOULD be prefixed with a reverse-DNS namespace associated with the
    semantics of the event.

The reason I dropped the MAY for the "Often..." sentence is because what a consumer does with this info is out of the spec's control. I think we could still use an additional sentence around the namespace to help explain it a bit more, after the "Often..." sentence. Perhaps something like: "Namespaces are useful to provide contextual information for the event, or to group it with related events." I dunno.... feel like it needs work.

[clemensv]

To @inlined's question - I don't know a lot of messaging/evening specs where such a name collision concern is explicitly addressed and fast rules are being set. HTTP is enormously successful with being pretty loose, see https://tools.ietf.org/html/rfc7230#section-3.2.1 and https://tools.ietf.org/html/rfc7231#section-4 where you "ought" to register names you use, but rarely anyone does.

I'm perfectly ok with this field with just being a string without any further rules and restrictions. If we make rules, the "reverse DNS" notation should at most be a recommendation.

[sslavic]

I guess this PR, if it would be accepted and merged, closes #32 - please consider amending the commit message appropriately.

[deissnerk]

@inlined

Similarly, I would love it if domain-specific working groups came up with standard events that many vendors would conform to, such as org.cncf.iot.window.open

I like that idea. I just wonder, if a producer that produces one of those standard events or even reuses events in a way you described as 'compatibility mode' SHOULD provide an event-type-version. That's probably a topic for a separate PR, though.

As CloudEvents focus on interoperability, I think that haveing a namespace is a MUST, but I agree that reverse DNS could be a "SHOULD".

[duglin]

Did not do a deep-dive discsusion on the 4/5 call, but there was a general sense that the direction was ok. Just need to work on the exact wording.

[nerdyyatrice]

Second (or third) the "SHOULD" instead of "MUST" suggestion.

[duglin]

@inlined can you rebase? Also, there were some requests for changes - are you still thinking about those?

[inlined]

Thanks for the feedback everyone. I've accepted the phrasing suggestions and rebased to fix the conflict.

[duglin]

@inlined I'm still unclear on this. Is it really the software that produces the event or the semantics of the event? I thought we wanted it to say com.github.pull.create even if the software component wasn't a github.com component, but it wanted receivers to act as if it did. Isn't the event type more about semantics of the event and less about where it came from - which would be source ?

[inlined]

It should be semantic namespacing. Could change it to something like

SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates
the organization which defines the semantics of this event type.

[duglin]

Works for me - thanks

[duglin]

@inlined this needs to be rebased due to the camelCase PR going in

[duglin]

@inlined I added "Closes: #32" to the first comment since I think resolving this PR will close that issue. Hope that's ok.

[inlined]

@duglin totally OK and thanks for the heads up about rebasing. Pushed a fix.

[duglin]

@inlined thanks for the rebase/update. Per our call on 4/12 we approved this PR pending the minor wording change we agreed to. Merging.