[apps-discuss] Deprecation mechanism in JSON HOme Documents

[Jan Algermissen <[e-mail]>]

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"],
 }
}

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? 

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"]
 }
}

Jan


[1] http://tools.ietf.org/html/draft-nottingham-json-home-02