Subject: [core] content-formats for cbor YANG

From: peter van der Stok <[email-masked]>
Date: Thu, 20 Apr 2017 10:46:08 +0200

Hi Core,

Following the discussion on CoMI content-formats during ietf98, I want 
to propose the following;

Draft-ietf-core-yang-cbor deines the content-format 
application/yang+cbor which defines CBOR documents which contain the 
results of the mapping of a YANG document to CBOR as specified in the 
draft.

Draft-ietf-core-comi defines two additional content-formats:
1) application/yang-fetch+cbor that specifies the contents and semantics 
of a FETCH CoMI request payload
2) application/yang-patch+cbor that specifies the contents and semantics 
of a PATCH CoMI request payload

Looking forward to alternative proposals or noises of approval.

Greetings,

Peter

-- 
Peter van der Stok
vanderstok consultancy
mailto: [email-masked]
www: www.vanderstok.org
tel NL: +31(0)492474673     F: +33(0)966015248

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 20 Apr 2017 10:55:18 +0200

> On Apr 20, 2017, at 10:46, peter van der Stok <[email-masked]> wrote:
> 
> Hi Core,
> 
> Following the discussion on CoMI content-formats during ietf98, I want to propose the following;
> 
> Draft-ietf-core-yang-cbor deines the content-format application/yang+cbor which defines CBOR documents which contain the results of the mapping of a YANG document to CBOR as specified in the draft.
> 
> 1) application/yang-fetch+cbor that specifies the contents and semantics of a FETCH CoMI request payload
> 2) application/yang-patch+cbor that specifies the contents and semantics of a PATCH CoMI request payload
> 

Sounds very good to me.

Grüße, Carsten

---

From: Michel Veillette <[email-masked]>
Date: Thu, 20 Apr 2017 13:40:40 +0000

Hi Peter, Hi Carsten

The following table summarizes the different payload uses by CoMI.
'value' is defined in https://tools.ietf.org/html/draft-ietf-core-yang-cbor-04#section-4
'instance-identifier' is defined in https://tools.ietf.org/html/draft-ietf-core-yang-cbor-04#section-5.13.1

Use Case	                  | Request payload                         | Response payload
----------------------------------+-----------------------------------------+----------------------------------------
GET /c/instance-identifier        | na                                      | value
PUT /c/instance-identifier        | value                                   | na
POST /c/instance-identifier       | value                                   | na
DELETE /c/instance-identifier     | na                                      | na
GET /c                            | na                                      | CBOR array (instance-identifier, value)
PUT /c	                          | CBOR array (instance-identifier, value) | na
POST /c	                          | CBOR array (instance-identifier, value) | na
FETCH /c                          | CBOR array (instance-identifier)        | CBOR array (value)
iPATCH/c                          | CBOR array (instance-identifier, value) | na
POST /c/instance-identifier (RPC) | value                                   | value
GET /s (Notification)             | value or CBOR array (value)             | na

As you can see, the payload of a iPATCH /c request have the same format a PUT /c request, POST /c request and GET /c response.
What will be the rational to use a different Content-Format for the iPATCH?
Can we simply use (Content-Format: application/cbor) in all cases?

Quick note, draft-ietf-core-yang-cbor don't propose any Content-Format, this is left to  draft-ietf-core-comi.

Regards,
Michel

-----Original Message-----
From: core [mailto:[email-masked]] On Behalf Of Carsten Bormann
Sent: Thursday, April 20, 2017 4:55 AM
To: peter van der Stok <[email-masked]>
Cc: Core <[email-masked]>
Subject: Re: [core] content-formats for cbor YANG

Sounds very good to me.

Grüße, Carsten

_______________________________________________
core mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/core

---

From: peter van der Stok <[email-masked]>
Date: Thu, 20 Apr 2017 16:36:48 +0200

Hi Michel,

The semantics of the PUT and GET specify that the payload replaces 
(represents) the whole payload.
Applying PUT semantics to a PATCH payload has as consequence that you 
loose unintentionally large parts of the resource.
A different content-format signals this semantics difference.
The FETCH payload may contain only an array of YANG-CBOR identifiers and 
each identifier represents GET semantics

Not all CBOR documents represent YANG to CBOR mappings, that's why the 
content format
application/yang-data+cbor is proposed equivalent to 
application/yang-data+json.

Does that help?

Peter

Michel Veillette schreef op 2017-04-20 15:40:
> 'value' is defined in
> https://tools.ietf.org/html/draft-ietf-core-yang-cbor-04#section-4
> 'instance-identifier' is defined in
> https://tools.ietf.org/html/draft-ietf-core-yang-cbor-04#section-5.13.1
> 
> GET /c                            | na
>      | CBOR array (instance-identifier, value)
> As you can see, the payload of a iPATCH /c request have the same
> format a PUT /c request, POST /c request and GET /c response.
> Quick note, draft-ietf-core-yang-cbor don't propose any
> Content-Format, this is left to  draft-ietf-core-comi.
> 
> Regards,
> Michel
> 
>> 1) application/yang-fetch+cbor that specifies the contents and 
>> semantics of a FETCH CoMI request payload
>> 2) application/yang-patch+cbor that specifies the contents and 
>> semantics of a PATCH CoMI request payload
>>

---

From: peter van der Stok <[email-masked]>
Date: Thu, 20 Apr 2017 16:39:32 +0200

> (represents) the whole payload.
resource (oversight, apologies)
> The FETCH payload may contain only an array of YANG-CBOR identifiers
> and each identifier represents GET semantics
>

---

From: Michel Veillette <[email-masked]>
Date: Thu, 20 Apr 2017 16:21:40 +0000

Hi Peter

It still unclear to me what is the role of the CoAP method vs. the role of the Content-Format.
The PUT, POST and iPATCH methods all share the same payload (i.e. CBOR array (instance-identifier, value)).

- In the case of the PUT, the existing datastore is deleted and replaced by the provided payload.
- In the case of the POST, a new datastore is created with the provided payload.
- In the case of the iPATCH, the existing datastore is updated based on the provided payload.

For these three use cases, the method defines what to do with the payload, not the Content-Format.
My question is why iPATCH required a different Content-Format when PUT and POST use the same?

Regards,
Michel

-----Original Message-----
From: peter van der Stok [mailto:[email-masked]] 
Sent: Thursday, April 20, 2017 10:37 AM
To: Michel Veillette <[email-masked]>
Cc: Carsten Bormann <[email-masked]>; peter van der Stok <[email-masked]>; Core <[email-masked]>
Subject: Re: [core] content-formats for cbor YANG

Hi Michel,

The semantics of the PUT and GET specify that the payload replaces
(represents) the whole payload.
Applying PUT semantics to a PATCH payload has as consequence that you loose unintentionally large parts of the resource.
A different content-format signals this semantics difference.
The FETCH payload may contain only an array of YANG-CBOR identifiers and each identifier represents GET semantics

Not all CBOR documents represent YANG to CBOR mappings, that's why the content format application/yang-data+cbor is proposed equivalent to application/yang-data+json.

Does that help?

Peter

---

From: Andy Bierman <[email-masked]>
Date: Thu, 20 Apr 2017 09:30:40 -0700

Hi,

On Thu, Apr 20, 2017 at 1:46 AM, peter van der Stok <[email-masked]>
wrote:

> Draft-ietf-core-yang-cbor deines the content-format application/yang+cbor
> which defines CBOR documents which contain the results of the mapping of a
> YANG document to CBOR as specified in the draft.
>
I think the name application/yang-patch+cbor is very confusing, because
application/yang-patch+xml and
application/yang-patch+json are already defined in RFC 8072, and they work
completely differently
than the media types in CoMI.

I suggest application/coap-patch+cbor.

The reason this media-type is needed in RESTCONF is to distinguish a "plain
patch"
from a "structured patch". The payload for an RFC 5789 PATCH method is a
representation
of the target resource. A structured patch cannot use the same media-types
because the payload
is a predefined data structure. The resource content for the patch is
embedded inside.

Seems like the new media-types are needed instead of overloading
application/cbor.

> Peter

Andy

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 20 Apr 2017 18:38:57 +0200

> On Apr 20, 2017, at 18:21, Michel Veillette <[email-masked]> wrote:
> 
> Hi Peter
> 

That is a good question.

We definitely need a different format for the FETCH request body, which is a list of IDs, not a set of ID-value pairs.  (We used to have this argument whether the response should be just a list of values or that set; I think we are now at the set selected, which is strictly speaking a bit different from the representation of the whole resource.)

The body of an (i)PATCH is different in meaning, not in structure, from the representation bearing formats.  It is a bit of a taste thing whether we attach media types to semantics or to structural interoperability.

> 2) application/yang-patch+cbor that specifies the contents and semantics of a PATCH CoMI request payload

Just calling the thing application/cbor just tells us the serialization format, by the way; this is a bit like sending text/html as text/plain because any text also is structurally compatible with the latter.

Andy’s argument that yang-patch is taken for the different yang-patch format used with XML/JSON is a good one.  Note that there is no coap in the comi patch format either, so I don’t like application/coap-patch+cbor.  Right now I’m favoring application/yang-set+cbor.

Grüße, Carsten

---

From: Michel Veillette <[email-masked]>
Date: Thu, 20 Apr 2017 16:58:24 +0000

Hi Carsten and thanks for your comments.

About (application/yang-set+cbor)
Do you propose to use it only for iPATCH /c request ?
Or also for GET /c response, PUT /c request and POST /c request ?

If we move in that direction (structural interoperability), do we need to define a different Content-Format for each one used by CoMI?
- value
- CBOR array (instance-identifier)
- CBOR array (value)
- CBOR array (instance-identifier, value)

Regards,
Michel

-----Original Message-----
From: Carsten Bormann [mailto:[email-masked]] 
Sent: Thursday, April 20, 2017 12:39 PM
To: Michel Veillette <[email-masked]>
Cc: peter van der Stok <[email-masked]>; Core <[email-masked]>
Subject: Re: [core] content-formats for cbor YANG

That is a good question.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 20 Apr 2017 20:08:18 +0200

> Do you propose to use it only for iPATCH /c request ?

That was my intention.

> Or also for GET /c response, PUT /c request and POST /c request ?

We could stick with application/yang+cbor for that, but that would meant that they all use the same structure.  I see that your table doesn’t.
(Or we could go for structural interoperability only.)

> - CBOR array (instance-identifier, value)

Oh, right, I wasn’t aware that we use all of them.

So this would be (all in application/___+cbor):

yang-value
yang-ids
yang-values
yang-set (or just yang)

This could be four media types, or one media type with four different values for a parameter.  Since, in both cases, we will have four different content-formats in the end, I’d go with four media types so we can minimize confusion.

Grüße, Carsten

---

From: peter van der Stok <[email-masked]>
Date: Fri, 21 Apr 2017 09:18:53 +0200

>> If we move in that direction (structural interoperability), do we need 
>> to define a different Content-Format for each one used by CoMI?
>> - value
> This could be four media types, or one media type with four different
> values for a parameter.  Since, in both cases, we will have four
> different content-formats in the end, I’d go with four media types so
> we can minimize confusion.

Because the CoMI text now says that the payload of an array of one item 
can be optimized to just one item,
I like to suppress the yang-value+cbor and only retain the 
yang-values+cbor

Cheerio, Peter

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 21 Apr 2017 11:00:40 +0200

On Apr 21, 2017, at 09:18, peter van der Stok <[email-masked]> wrote:
> 
> Because the CoMI text now says that the payload of an array of one item can be optimized to just one item,
> I like to suppress the yang-value+cbor and only retain the yang-values+cbor

That would create an ambiguity if a value can ever be an array.

What is so bad about the media type being very specific about what the payload is?

Grüße, Carsten

---

From: Michel Veillette <[email-masked]>
Date: Fri, 21 Apr 2017 15:49:18 +0000

Hi Peter

About "payload of an array of one item can be optimized to just one item"

I agree with Carsten, I most cases, this rule have the potential to create ambiguities.
In the specific case of a notification, the payload can be either a CBOR map (single notification) or a CBOR array (multiple notifications).
A single Content-Format (e.g. yang-value+cbor) will work but a solution with two Content-Format seem to be cleaner.

Regards,
Michel

-----Original Message-----
From: Carsten Bormann [mailto:[email-masked]] 
Sent: Friday, April 21, 2017 5:01 AM
To: peter van der Stok <[email-masked]>
Cc: Michel Veillette <[email-masked]>; Core <[email-masked]>
Subject: Re: [core] content-formats for cbor YANG

On Apr 21, 2017, at 09:18, peter van der Stok <[email-masked]> wrote:
> 
> Because the CoMI text now says that the payload of an array of one 
> item can be optimized to just one item, I like to suppress the 
> yang-value+cbor and only retain the yang-values+cbor

Grüße, Carsten

---

From: peter van der Stok <[email-masked]>
Date: Mon, 24 Apr 2017 09:15:18 +0200

Michel,

See your point. Will change the text accordingly.
I hope that yang-cbor content-format will be defined in yang-cbor draft.

Peter

Michel Veillette schreef op 2017-04-21 17:49:
> In the specific case of a notification, the payload can be either a
> CBOR map (single notification) or a CBOR array (multiple
> notifications).
> A single Content-Format (e.g. yang-value+cbor) will work but a
> solution with two Content-Format seem to be cleaner.
> 
> Regards,
> Michel
>