explicit channel auth scheme

[elf-pavlik]

closes #155

TODO

• Once agreed on, update examples in all the channel types

---

Preview | Diff (doesn't show the changes in code snippets!)

[CxRes]

I would suggest that you add an implementation guidance box, otherwise spec users will wonder why we are adding channel auth in the examples even though it has no mention in the spec.

[elf-pavlik]

It also shows in the data model as required information on Subscription Service and Notification Channel. Actually that the only change that gets highlighted in the HTML diff.

[CxRes]

That should be "zero, one or many" (I disagree with @csarven 's way of describing, we have argued this previously, because there is no way to indicate that Subscription Service may not advertise this property at all and that would be OK). I would also suggest the property on Subscription Service be called authSchemes instead of channelAuthScheme for consistency with Notification Channels.

[elf-pavlik]

I would also suggest the property on Subscription Service be called authSchemes instead of channelAuthScheme for consistency with Notification Channels.

I think chanelAuthScheme is consistent with channelType, also having two different predicates only differ by final s could be confusing.

That should be "zero, one, or many"

If we want it always to be explicit it can't be zero, one of the examples uses None. In what scenarios would you see zero?

[CxRes]

I think chanelAuthScheme is consistent with channelType, also having two different predicates only differ by final s could be confusing.

Plural indicates that a thing is an array. Not having an "s" is the inconsistent thing, imho.

I strongly disagree with your definition of consistency. AuthSchemes are only meaningful in the context of the channel, but is a general thing. channelType is called so because type is vague thing even when described in the context of a channel (and can be confused with other kinds of "types" like "data type") and that we explicitly define a "Channel Type" in the spec.

If we want it always to be explicit it can't be zero, one of the examples uses None. In what scenarios would you see zero?

You could conceivably have a channel that you need to subscribe to (one a server will create on request only), but is otherwise public and does not require authorization (not that I would recommend anyone make one, but consistency demands that we allow such a thing).

What I would concede is that if you specify the property, then zero entries makes no sense. But you should be able to skip specifying channelAuthScheme altogether in the above scenario.

[csarven]

Thanks for putting this together and thinking about this problem/solution. Pardon the late reply.

Approving but see change requests. I'd like to see a short paragraph/section for #authentication-scheme describing a bit further. See review comments.

[csarven]

I couldn't suggest a change to add a paragraph/section (perhaps right after #authentication-authorization or a new subsection of the #protocol section.) The following suggestion would refer to Authentication Scheme.

Suggested change

	<li id="notify-channelAuthScheme">One or many <code>channelAuthScheme</code> property to state the supported authentication schemes.</li>
	<li id="notify-channelAuthScheme">One or many <code>channelAuthScheme</code> property to state the supported <a href="#authentication-scheme">authentication schemes</a>.</li>

[csarven]

Suggested change

	<li id="notify-channel-authScheme">One <code>authScheme</code> property to state the authentication scheme used for the channel.</li>
	<li id="notify-channel-authScheme">One <code>authScheme</code> property to state the <a href="#authentication-scheme">authentication scheme</a> used for the channel.</li>

[csarven]

Curious.. is authScheme intended to be consumed by SubscriptionClient? Or towards recording what's currently in use (and for unspecified use)?

Is it required / what might not function if omitted?

[csarven]

I presume "None" will map to notify:None .. but we mean something like notify:AuthenticationSchemeIsNotUsed?

[csarven]

I think requiring channelAuthScheme with at least one value encourages (more) complete and useful information. Just as specifying the type of the channel, its endpoint, features. Why wouldn't authentication scheme information be part of this? The only thing I can think of is that it is unknown (unprovided) to the DescriptionResource and that the values may change (for some reason).

As for singular/plural, singular suffices for RDF properties as atomic statements / arcs in graph.