Subject: Re: [apps-discuss] Deprecation mechanism in JSON HOme Documents

From: Mark Nottingham <[email-masked]>
Date: Wed, 20 Mar 2013 13:03:40 +1100

Hi Jan,

On 25/02/2013, at 7:04 PM, algermissen1971 <[email-masked]> wrote:

> Hi Mark,
> 
> in your latest draft of JSON Homep[1] you define a deprecation mechanism that allows a provider to provide a hint to a consumer that a certain described resource is in a deprecation period.
> 
> As designed now, this mechanism cannot be used to hint the deprecation of a certain provided media type:
> 
> Suppose I have 
> 
> 
> "http://example.org/rel/widgets": {
>  "href": "/widgets/",
>  "hints": {
>    "representations": ["application/widgetlist"]
>  }
> }
> 
> and at some point, I have to evolve the media type in an incompatible way, yielding a new media type 'application/special-new-widgetlist'. To support both, new and old clients, I'd let the types coexist:
> 
> "http://example.org/rel/widgets": {
>  "href": "/widgets/",
>  "hints": {
>    "representations": ["application/widgetlist","application/special-new-widgetlist"],
>  }
> }

Yes...

> As time passes and clients pick up the shiny new media type, a point is reached where I want to hint older clients that an upgrade is in order. I'd like to deprecate the availability of the older media type 'application/widgetlist'.
> 
> However ... that is impossible right now since 'deprecated' only applies to the resource as a whole - which I deliberately do *not* want to change or remove.
> 
> What are your thoughts? Is there a certain design decision behind your approach that I am not seeing?

Nope, just started to get deprecation in. Will think on this, thanks...

> 
> What do you think of augmenting the deprecation mechanism to something like:
> 
> "http://example.org/rel/widgets": {
>  "href": "/widgets/",
>  "hints": {
>    "representations": ["application/widgetlist","application/special-new-widgetlist"],
>    "deprecated-representations" : ["application/widgetlist"]
>  }
> }

That'd be one way to do it. However, I suspect we're eventually going to want to put more information about representations in, so it could be metadata, e.g.,

 "hints": {
	"representations": { 
		"application/widgetlist": {
			"deprecated": true
		},
		"application/special-new-widgetlist": {
		}
	}
}

--
Mark Nottingham   http://www.mnot.net/

---

From: James M Snell <[email-masked]>
Date: Tue, 19 Mar 2013 19:05:35 -0700

This variation looks to be the most useful.

On Tue, Mar 19, 2013 at 7:03 PM, Mark Nottingham <[email-masked]> wrote:

> ​[snip]​
>
> That'd be one way to do it. However, I suspect we're eventually going to
> want to put more information about representations in, so it could be
> metadata, e.g.,
>
>  "hints": {
>         "representations": {
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: algermissen1971 <[email-masked]>
Date: Wed, 20 Mar 2013 08:01:39 +0100

> This variation looks to be the most useful. 

+1

Just did not want to be too destructive on Marks' original design :-)

Jan