Field Deprecation in Schema Objects

[jayadeba]

Hello, I was browsing through the spec docs to find out how to mark deprecation at various levels for an API. I could find docs/prs specifying how to mark deprecation of an operation and deprecation of a parameter (query, header or an entire Schema Object) but its not clear how can we mark a field in a Schema Object deprecated? Is there a plan to add support for this?

Appreciate any clarification around this.

Thanks,
Jayadeba Jena

[ePaul]

In the current version 2.0 there is nothing directly in the spec, so you'll have to write it into the description.
For the next version, #524 + #637 added it.

[jayadeba]

@ePaul Thanks for the answer. I browsed through the above but i find only the following:

1. You deprecate an operation (operation object).
2. You can deprecate a parameter (parameter object level).
3. You deprecate a model/schema, which deprecates all the fields of a schema/model.

For 3, how do i deprecate just one field in the schema?

Thanks

[ePaul]

The problem is that a field in a schema doesn't have any location where data could be added, other than the field's schema. So you'll need to put it there:

definititions:
  Person:
    type: object
    properties:
      name:
        type: string
      age:
        type: integer
        deprecated: true
        description: The age of the person in years. This property is deprecated because you shouldn't care about someone's age.

Of course, this gets ugly when you are using $ref and one of the properties referring a schema is deprecated and another one not – you need to duplicate.

Maybe a better way to do this would be a list of deprecated properties in a schema, just like required.

[webron]

As @ePaul mentioned, you can deprecate a property because it's an instance of the Schema Object.

@ePaul - you've mentioned the deprecated being formatted as required in the Schema Object also in the PR and it may make sense to revisit (for the same reason required is defined top-level). Can you open a separate ticket on that?

[jayadeba]

@ePaul @webron doing a required like array for deprecation at schema level would be awesome. It would be fantastic if you guys are planning to do this in 3.0. We have lot of big schema objects in PayPal and it would look very ugly to tag deprecation at each field level.

[wparad]

Please no more "property" arrays like

required: [
  "name",
  "description"
]

I like the idea of the required and deprecated being defined at every level, version, resource, schema, and property.

[jayadeba]

The readability is better when we define it as an array like required. For tools that do some action based on the deprecation types of the attribute, its better too (looking at one place vs look at this property in all attributes). For a big schema object, its really convenient.

But you can support both at property level and as an array too.

[webron]

It's got nothing to do with readability - it's got to do with the ability to control what's required/deprecate when it comes to using allOf and similar directives.

[jayadeba]

Great. Thanks for the clarification.

[jayadeba]

Hi,

Feature request on deprecation specification:

Can the declaration of deprecation be in the form of an object instead of a boolean field? Something in the line of Java.

"deprecated": {
"since": "1.2",
"condemned": "true"
}

since would depict the minor release name since the field or operation is deprecated.
condemned would mean that this deprecated field/API can be removed any time from now.

Such decoration would help deprecation, warning and then removal progressively.

Thanks,
Jayadeba

[wparad]

Thinking about this more, I think the complexity of adding something like this outweighs the benefits. At the field level, the schema would start to become flooded with non-API specific indicators for purely reference, rather than of actual value. The deprecation flag doesn't actually have a functional impact. Can you imagine attempting to reuse the same schema object across API versions and methods, where depending on the method and version a field may or may not be deprecated.

At the different API levels, I feel like deprecation is already implied by the existence of a later version. I.e. Publishing two versions of the API, of course the earlier one is deprecated and the newer one is preferred, or at least that is what I always interpreted that to mean.

I do see the benefit of a way to indicate See instead to reference some sort of human readable documentation. But there already exists the status property and the links array, and by RFC 5988 you could use something like related. I don't see something like a depercatedBy relation, but maybe that is what needs to exist here.

[jayadeba]

When you say API versions, do you mean MAJORor MINOR?
The above things might be true for Major versions. What I'm talking about is deprecating fields in a minor versions.In a minor version if the field is deprecated it remains like this in newer minor versions until it is removed. This behavior doesn't change across minor versions.There are also runtime aspects where a container can read this info and automatically add the deprecation information at run time to the API responses.

See Instead or links or replacement are as well good to have in the deprecated object.

[wparad]

From your answer though it seems like you have some strict API implementation guidelines you follow which are not enforced by the spec. Given that it begs the question, should deprecation be directly called out in the OAI spec, or is it merely an implementation of already existing properties, fields, and semantics?

I'm tempted to say, leave it out of the spec, as there are already existing ways of representing this data (arguably in a meaningful way), however, maybe reviewing the guidelines you follow would be a good opportunity to understand why these other ways aren't sufficient for handling deprecation.