diff --git a/IETF-OCM.md b/IETF-OCM.md index af36fbf..e8697ed 100644 --- a/IETF-OCM.md +++ b/IETF-OCM.md @@ -1409,9 +1409,10 @@ request: ## Fields -* REQUIRED notificationType (string) - it MUST be one of the - registered values listed in the "OCM Notification Types" - registry (see [IANA Considerations](#iana-considerations)). +* REQUIRED notificationType (string) - a non-empty string, compared + exactly as sent. A Sending Server MUST use a value in the "OCM + Notification Types" registry (see [IANA + Considerations](#iana-considerations)). * REQUIRED senderDomain (string) - the OCM Server Address of the sender. A Receiving Server SHOULD use this information to verify the HTTP message signature and validate the underlying share or @@ -1434,6 +1435,20 @@ Registry. For each notification type, a specific format MAY be defined for the optional notification object. In the sections below, the base Notification types are detailed along with their specific payload. +## Receiver Processing + +Before applying a notification, the receiver MUST validate its envelope, +payload and identity bindings. + +* Malformed envelopes and malformed payloads for known notification + types MUST receive HTTP 400. Deprecated fields cannot replace required + payload fields. +* A receiver SHOULD accept and ignore a valid unknown notification + type. It MUST NOT reject it merely because the type is unknown, or + apply another type's payload requirements to it. +* A receiver MAY return HTTP 501 for a known, valid notification type + whose operation it does not implement. + ## Share Acceptance and Updating A notification MAY be sent by a recipient to let the provider know that @@ -2091,11 +2106,8 @@ the values that MAY appear in the "notificationType" field of an OCM notification sent to the "/notifications" endpoint (see [Notifications](#notifications)). -The "Scope" field indicates whether the notification refers to a -Resource, in which case the "providerId" field is REQUIRED in the -payload, or to a Recipient, i.e. to the shareType in a -[Share Creation Notification](#share-creation-notification), in which -case a corresponding identifier such as "userId" is REQUIRED in the +The "Scope" field indicates whether the notification concerns a +Resource or a Recipient. Each notification type defines its required payload. Registration Policy: Specification Required [RFC8126] diff --git a/spec.yaml b/spec.yaml index 430848f..967f0b9 100644 --- a/spec.yaml +++ b/spec.yaml @@ -219,8 +219,8 @@ paths: the actual notification. "400": description: > - Bad request due to invalid parameters, e.g. when `notificationType` is - invalid, not known or missing. + Invalid notification envelope or malformed payload for a known + notification type. content: application/json: schema: @@ -243,8 +243,8 @@ paths: does not have rights to access it. "501": description: > - The receiver doesn't support notifications, the resource type is not - supported. + Notifications or the requested operation are not implemented + by the receiver. content: application/json: schema: @@ -1091,9 +1091,9 @@ components: properties: notificationType: type: string + minLength: 1 description: > - A notification type that is understandable for both humans and - machines, providing information about an event. + A non-empty notification type, compared exactly as sent. Any value registered in the OCM IANA Registry for notification types MAY be used here. Implementers MAY define additional custom types, provided that they are registered in the OCM IANA Registry. @@ -1105,6 +1105,7 @@ components: key material and verify the HTTP Message Signature. resourceType: type: string + minLength: 1 description: > Resource type, according to the OCM IANA Registry for resource types. E.g. file, folder, calendar, contact, etc. Implementers MAY define @@ -1112,6 +1113,7 @@ components: respective OCM IANA Registry. shareType: type: string + minLength: 1 description: > Share type, according to the OCM IANA Registry for share types. E.g. user, group, federation, etc. Implementers MAY define @@ -1135,12 +1137,8 @@ components: additionalProperties: type: object description: > - This object MUST be keyed with the resource type or share type of this - notification. It contains its payload and it can vary according to the - implementers. In case of `file` resources, it MUST contain at least the - `providerId` of the underlying resource, and in case of `user`, `group`, - or `federation` share types, it MUST contain at least the `userId`, - `groupId`, or `mlsGroupId` of the underlying recipient, respectively. + Additional payload objects keyed by resource type or share type. + Required fields are defined by the notification type. example: legacyShareWasAccepted: notificationType: SHARE_ACCEPTED