diff --git a/ps-rev/draft-ietf-core-coap-pubsub.html b/ps-rev/draft-ietf-core-coap-pubsub.html index 1d38b48..7d2b905 100644 --- a/ps-rev/draft-ietf-core-coap-pubsub.html +++ b/ps-rev/draft-ietf-core-coap-pubsub.html @@ -1160,18 +1160,13 @@

The list can be represented as a Link Format document [RFC6690]. The link to each topic-configuration resource specifies the link target attribute 'rt' (Resource Type), with value "core.ps.conf" defined in this document.

-
+
-

-2.2. Topic Creation and Configuration +

+2.2. Topic-Configuration Representation

A CoAP client can create a new topic by submitting an initial configuration for the topic (see Section 2.4.3). It can also read and update the configuration of existing topics and delete them when they are no longer needed (see Section 2.5).

-

The configuration of a topic itself consists of a set of properties that can be set by a client or by the broker.

+

The configuration of a topic itself consists of a set of properties that can be set by a client or by the broker. The topic-configuration is represented as a CBOR map containing the configuration properties of the topic as top-level elements.

+

Unless specified otherwise, these are defined in this document and their CBOR abbreviations are defined in Section 3.

@@ -1717,47 +1713,38 @@

-
+
-

-2.2.2. Topic-Configuration Resource Representation +

+2.2.2. Default Values

-

A topic-configuration is represented as a CBOR map containing the configuration properties of the topic as top-level elements.

-

Unless specified otherwise, these are defined in this document and their CBOR abbreviations are defined in Section 3.

-
-
-
-2.2.2.1. Default Values -
-

Below are the defined default values for the topic parameters:

+

Below are the defined default values for the topic parameters:

    -
  • -

    'topic-name': There is no default value. This field is required and must be specified by the client or broker.

    +
  • +

    'topic-name': There is no default value. This field is required and must be specified by the client or broker.

    • -
  • -

    'topic-data': There is no default value. This field is required and must be specified by the client or broker.

    +
  • +

    'topic-data': There is no default value. This field is required and must be specified by the client or broker.

    • -
  • -

    'resource-type': The default value for a topic resource is "core.ps.conf".

    +
  • +

    'resource-type': The default value for a topic resource is "core.ps.conf".

    • -
  • -

    'media-type': The default value is an empty string, indicating that no media type is specified.

    +
  • +

    'media-type': The default value is an empty string, indicating that no media type is specified.

    • -
  • -

    'target-attribute': The default value is an empty string, indicating that no attribute is specified.

    +
  • +

    'target-attribute': The default value is an empty string, indicating that no attribute is specified.

    • -
  • -

    'expiration-date': The default value is an empty string, indicating that no expiration date is specified. If this field is not present, the topic will not expire automatically.

    +
  • +

    'expiration-date': The default value is an empty string, indicating that no expiration date is specified. If this field is not present, the topic will not expire automatically.

    • -
  • -

    'max-subscribers': The default value is -1, indicating that there is no limit to the number of subscribers allowed. If this field is not present, the pubsub system will not limit the number of subscribers for the topic.

    +
  • +

    'max-subscribers': The default value is -1, indicating that there is no limit to the number of subscribers allowed. If this field is not present, the pubsub system will not limit the number of subscribers for the topic.

    • -
  • -

    'observer-check': The default value is '86400', as defined in [RFC7641], which corresponds to 24 hours.

    +
  • +

    'observer-check': The default value is '86400', as defined in [RFC7641], which corresponds to 24 hours.

    • -
-
-
+
@@ -1857,7 +1844,7 @@

2.4.1. Retrieving all topic-configurations

A client can request a collection of the topics present in the broker by making a GET request to the collection URI.

-

On success, the server returns a 2.05 (Content) response with a representation of the list of all topic-configuration resources (see Section Section 2.2.2) in the collection.

+

On success, the server returns a 2.05 (Content) response with a representation of the list of all topic-configuration resources (see Section Section 2.2) in the collection.

Depending on the permission set each client MAY receive a different list of topics that they are authorized to read.

If there are existing topic-data resources under the collection resource, those will also be present in the response.

Example:

@@ -1907,7 +1894,7 @@

2.4.3. Creating a Topic

-

A client can add a new topic-configurations to a collection of topics by submitting a representation of the initial topic resource (see Section Section 2.2.2) in a POST request to the topic collection URI. The topic MUST contain at least a subset of the Section 2.2.1 , namely: topic-name and resource-type.

+

A client can add a new topic-configurations to a collection of topics by submitting a representation of the initial topic resource (see Section Section 2.2) in a POST request to the topic collection URI. The topic MUST contain at least a subset of the Section 2.2.1 , namely: topic-name and resource-type.

A CoAP endpoint creating a topic MAY specify a topic-data URI different than that used by the broker. The broker may then simply forward the observation requests to the topic-data URI as shown in Figure 5.

If the topic-data is empty the broker will assign a resource for a publisher to publish to. Please note that the topic will NOT be fully created until a publisher has published some data to it (See Section 2.6.1).

On success, the server returns a 2.01 (Created) response indicating the topic URI of the new topic and the current representation of the topic resource.

@@ -1952,9 +1939,9 @@

2.5.1. Getting a topic-configuration

A client can read the configuration of a topic by making a GET request to the topic resource URI.

-

On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the representation of the topic resource as specified in Section 2.2.2.

+

On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the representation of the topic resource as specified in Section 2.2.

If a topic manager (TBD) is present in the broker, retrieving topic information may require manager approval subject to certain conditions (TBD). If the conditions are not fulfilled, the manager MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor".

-

The response payload is a CBOR map, whose possible entries are specified in Section 2.2.2 and use the same abbreviations defined in Section 3.

+

The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in Section 3.

For example, below is a request on the topic "ps/h9392":

@@ -1984,10 +1971,10 @@ 

 2.5.2. Getting part of a topic-configuration
           

 
A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific parameters. This is done in order to retrieve part of the current topic resource.

-
The request contains a CBOR map with a configuration filter or 'conf-filter', a CBOR array with CBOR abbreviation. Each element of the array specifies one requested configuration parameter of the current topic resource (see Section 2.2.2).

-
On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the partial representation of the topic resource as specified in Section 2.2.2.

+
The request contains a CBOR map with a configuration filter or 'conf-filter', a CBOR array with CBOR abbreviation. Each element of the array specifies one requested configuration parameter of the current topic resource (see Section 2.2).

+
On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the partial representation of the topic resource as specified in Section 2.2.

 
If a topic manager (TBD) is present in the broker, retrieving topic information may require manager approval subject to certain conditions (TBD). If the conditions are not fulfilled, the manager MUST respond with a 4.03 (Forbidden) error.

-
The response payload is a CBOR map, whose possible entries are specified in Section 2.2.2 and use the same abbreviations defined in Section 3.

+
The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in Section 3.

 
Both request and response MUST have Content-Format set to "application/core-pubsub+cbor".

 
Example:

 

@@ -2307,7 +2294,7 @@ 

 2.7.1. Publish
           

 
A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section Section 2.4.3) and be in the half-created state in order to the publish operation to work (see Section 2.6.1).

-
A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource property. Please note that the topic-data URI is not the same as the topic-configuration URI used for configuring the topic (see Section 2.2.2).

+
A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource property. Please note that the topic-data URI is not the same as the topic-configuration URI used for configuring the topic (see Section 2.2).

 
On success, the server returns a 2.04 (Updated) response. However, when data is published to the topic for the first time, the server instead MUST return a 2.01 (Created) response and set the topic in the fully-created state (see Section 2.6.1).

 
If the request does not have an acceptable content format, the server returns a 4.15 (Unsupported Content Format) response.

 
If the client is sending publications too fast, the server returns a
@@ -2420,7 +2407,7 @@ 

 
A CoAP client can unsubscribe simply by cancelling the observation as described in Section 3.6 of [RFC7641]. The client MUST either use CoAP GET with the Observe Option set to 1 or send a CoAP Reset message in response to a notification.

 
In some circumstances, it may be desirable to cancel an observation and release the resources allocated by the broker. In this case, a client MAY explicitly deregister by issuing a GET request that has the Token field set to the token of the observation to be cancelled and includes an Observe Option with the value set to 1 (deregister).

 
As per [RFC7641] a server that transmits notifications mostly in non-confirmable messages MUST send a notification in a confirmable message instead of a non-confirmable message at least every 24 hours.

-
This value can be modified at the broker by the administrator of a topic by modifying the parameter "observer-check" on Section 2.2.2. This would allow to change the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource.

+
This value can be modified at the broker by the administrator of a topic by modifying the parameter "observer-check" on Section 2.2. This would allow to change the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource.

 
 

 

@@ -2484,7 +2471,7 @@ 

       

 3. CoAP Pubsub Parameters
       

-
This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and configuration process (see Section 2.2.2). The table below summarizes them and specifies the CBOR key to use instead of the full descriptive name.

+
This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and configuration process (see Section 2.2). The table below summarizes them and specifies the CBOR key to use instead of the full descriptive name.

 
Note that the media type application/core-pubsub+cbor MUST be used when these parameters are transported in the respective message fields.

 

 

diff --git a/ps-rev/draft-ietf-core-coap-pubsub.txt b/ps-rev/draft-ietf-core-coap-pubsub.txt
index 2f5c6ff..bc2e4ec 100644
--- a/ps-rev/draft-ietf-core-coap-pubsub.txt
+++ b/ps-rev/draft-ietf-core-coap-pubsub.txt
@@ -77,10 +77,9 @@ Table of Contents
      1.3.  Managing Topics
    2.  Pub-Sub Topics
      2.1.  Collection Representation
-     2.2.  Topic Creation and Configuration
+     2.2.  Topic-Configuration Representation
        2.2.1.  Topic Properties
-       2.2.2.  Topic-Configuration Resource Representation
-         2.2.2.1.  Default Values
+       2.2.2.  Default Values
      2.3.  Discovery
        2.3.1.  Broker Discovery
        2.3.2.  Topic Collection Discovery
@@ -324,7 +323,7 @@ Table of Contents
    attribute 'rt' (Resource Type), with value "core.ps.conf" defined in
    this document.
 
-2.2.  Topic Creation and Configuration
+2.2.  Topic-Configuration Representation
 
    A CoAP client can create a new topic by submitting an initial
    configuration for the topic (see Section 2.4.3).  It can also read
@@ -332,7 +331,12 @@ Table of Contents
    they are no longer needed (see Section 2.5).
 
    The configuration of a topic itself consists of a set of properties
-   that can be set by a client or by the broker.
+   that can be set by a client or by the broker.  The topic-
+   configuration is represented as a CBOR map containing the
+   configuration properties of the topic as top-level elements.
+
+   Unless specified otherwise, these are defined in this document and
+   their CBOR abbreviations are defined in Section 3.
 
 2.2.1.  Topic Properties
 
@@ -386,15 +390,7 @@ Table of Contents
       if the topic-data is not hosted by the broker but by another CoAP
       server it is up to that server to apply the observer-check value.
 
-2.2.2.  Topic-Configuration Resource Representation
-
-   A topic-configuration is represented as a CBOR map containing the
-   configuration properties of the topic as top-level elements.
-
-   Unless specified otherwise, these are defined in this document and
-   their CBOR abbreviations are defined in Section 3.
-
-2.2.2.1.  Default Values
+2.2.2.  Default Values
 
    Below are the defined default values for the topic parameters:
 
@@ -517,7 +513,7 @@ Table of Contents
 
    On success, the server returns a 2.05 (Content) response with a
    representation of the list of all topic-configuration resources (see
-   Section Section 2.2.2) in the collection.
+   Section Section 2.2) in the collection.
 
    Depending on the permission set each client MAY receive a different
    list of topics that they are authorized to read.
@@ -563,7 +559,7 @@ Table of Contents
 
    A client can add a new topic-configurations to a collection of topics
    by submitting a representation of the initial topic resource (see
-   Section Section 2.2.2) in a POST request to the topic collection URI.
+   Section Section 2.2) in a POST request to the topic collection URI.
    The topic MUST contain at least a subset of the Section 2.2.1 ,
    namely: topic-name and resource-type.
 
@@ -623,8 +619,7 @@ Table of Contents
 
    On success, the server returns a 2.05 (Content) response with a
    representation of the topic resource.  The response has as payload
-   the representation of the topic resource as specified in
-   Section 2.2.2.
+   the representation of the topic resource as specified in Section 2.2.
 
    If a topic manager (TBD) is present in the broker, retrieving topic
    information may require manager approval subject to certain
@@ -633,7 +628,7 @@ Table of Contents
    Content-Format set to "application/core-pubsub+cbor".
 
    The response payload is a CBOR map, whose possible entries are
-   specified in Section 2.2.2 and use the same abbreviations defined in
+   specified in Section 2.2 and use the same abbreviations defined in
    Section 3.
 
    For example, below is a request on the topic "ps/h9392":
@@ -664,12 +659,12 @@ Table of Contents
    The request contains a CBOR map with a configuration filter or 'conf-
    filter', a CBOR array with CBOR abbreviation.  Each element of the
    array specifies one requested configuration parameter of the current
-   topic resource (see Section 2.2.2).
+   topic resource (see Section 2.2).
 
    On success, the server returns a 2.05 (Content) response with a
    representation of the topic resource.  The response has as payload
    the partial representation of the topic resource as specified in
-   Section 2.2.2.
+   Section 2.2.
 
    If a topic manager (TBD) is present in the broker, retrieving topic
    information may require manager approval subject to certain
@@ -677,7 +672,7 @@ Table of Contents
    MUST respond with a 4.03 (Forbidden) error.
 
    The response payload is a CBOR map, whose possible entries are
-   specified in Section 2.2.2 and use the same abbreviations defined in
+   specified in Section 2.2 and use the same abbreviations defined in
    Section 3.
 
    Both request and response MUST have Content-Format set to
@@ -898,7 +893,7 @@ Table of Contents
    request to the topic-data URI as indicated in its topic resource
    property.  Please note that the topic-data URI is not the same as the
    topic-configuration URI used for configuring the topic (see
-   Section 2.2.2).
+   Section 2.2).
 
    On success, the server returns a 2.04 (Updated) response.  However,
    when data is published to the topic for the first time, the server
@@ -1021,7 +1016,7 @@ Table of Contents
    message instead of a non-confirmable message at least every 24 hours.
 
    This value can be modified at the broker by the administrator of a
-   topic by modifying the parameter "observer-check" on Section 2.2.2.
+   topic by modifying the parameter "observer-check" on Section 2.2.
    This would allow to change the rate at which different
    implementations verify that a subscriber is still interested in
    observing a topic-data resource.
@@ -1088,8 +1083,8 @@ Table of Contents
 
    This document defines parameters used in the messages exchanged
    between a client and the broker during the topic creation and
-   configuration process (see Section 2.2.2).  The table below
-   summarizes them and specifies the CBOR key to use instead of the full
+   configuration process (see Section 2.2).  The table below summarizes
+   them and specifies the CBOR key to use instead of the full
    descriptive name.
 
    Note that the media type application/core-pubsub+cbor MUST be used