How to deprecate properties

[bingosummer]

I want to mark the property foo deprecated. For example, ""

  "definitions": {
    "MyProperties": {
      "type": "object",
      "properties": {
        "foo": {
          "type": "string",
          "description": "I want to deprecate this field"
        }
    }
  }

I know we can set "deprecated": true for a path. But for the schema object, I didn't see the property deprecated in the official OpenAPI 2.0 doc https://spec.openapis.org/oas/v2.0#schema-object.

https://github.com/Azure/autorest/blob/main/Samples/test/deprecated/deprecated.yaml mentions "x-deprecated". But I didn't find any docs about it or any examples in azure-rest-api-specs.

Question:

1. Is there a way to mark a property deprecate?
2. If yes, after deprecated, what does it actually do? Can the user still use the property and get a warning?

[ghost]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @adrianhall, @KedarJoshi.

Issue Details

---

I want to mark the property `foo` deprecated. For example, "" ``` "definitions": { "MyProperties": { "type": "object", "properties": { "foo": { "type": "string", "description": "I want to deprecate this field" } } } ``` I know we can set `"deprecated": true` for a path. But for the schema object, I didn't see the property `deprecated` in the official OpenAPI 2.0 doc https://spec.openapis.org/oas/v2.0#schema-object. https://github.com/Azure/autorest/blob/main/Samples/test/deprecated/deprecated.yaml mentions "x-deprecated". But I didn't find any docs about it or any examples in azure-rest-api-specs. Question: 1. Is there a way to mark a property deprecate? 2. If yes, after deprecated, what does it actually do? Can the user still use the property and get a warning?

Author:	bingosummer
Assignees:	-
Labels:	`API Management`, `Service Attention`, `needs-triage`
Milestone:	-

[adrianhall]

Nothing to do with API Management here. API Management itself does nothing with the deprecated flag.

I'd hazard a guess it's about autorest more than anything.

The user doesn't get any warning that a property is deprecated. OpenAPI 2.0 does not allow you to mark a field as deprecated - only an API. OpenAPI 3.0 adds deprecated support to the field, but azure-rest-api-specs doesn't use 3.0 yet. I believe the x-deprecated property marks the property / method as deprecated in the SDKs.