{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"enforce-response-contents-with-the-response-contains-property-rule","__idx":0},"children":["Enforce response contents with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response-contains-property"]}," rule"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide describes how to ensure that the API operation's response ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/response-contains-property"},"children":["contains a specific property"]}," ","with three different cases:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Single response containing one property"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Multiple responses containing one property"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Multiple responses containing multiple properties"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's get started!"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":2},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/openapi-starter"},"children":["Use the openapi-starter repository"]}," to set up a basic project for use with this guide."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://gist.github.com/bandantonio/c6047e3ee70c90da013a2f8e6757edb0"},"children":["Download the modified project files"]}," and use them to"," ","replace the corresponding files in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi"]}," folder:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":".\n└── openapi\n    ├── components\n    │   └── responses\n    │       ├── 200.yaml\n    │       ├── 201.yaml\n    │       └── 202.yaml\n    └── paths\n        ├── path-item-with-examples.yaml\n        ├── path-item.yaml\n        └── users_{username}.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure that the @redocly/cli has version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.0.0-beta.99"]}," or later"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you're using VS Code as your favorite code editor, we recommend you install the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/redocly-openapi/"},"children":["Redocly OpenAPI VS Code extension"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"We do, You do"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide is most effective when you follow along and complete the steps."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"case-0---check-that-the-current-openapi-description-is-valid","__idx":3},"children":["Case 0 - Check that the current OpenAPI description is valid"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After downloading the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi-starter"]}," repository, ensure that you installed the project's dependencies via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npm install"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once completed, in the project folder, execute the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx redocly lint"]}," command. You should receive confirmation that the OpenAPI description is valid:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx redocly lint\n\nvalidating /openapi/openapi.yaml...\n/openapi/openapi.yaml: validated in 39ms\n\nWoohoo! Your API description is valid. 🎉\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now you are ready to configure the rules."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"case-1---single-response-containing-one-property","__idx":4},"children":["Case 1 - Single response containing one property"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Imagine that your API description describes users' data, and it should have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," as a part of"," ","all successful (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},") responses. Let's define this."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," in the project folder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After the line 9, add the rule configuration block:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  no-unused-components: error\n  response-contains-property:\n    severity: error\n    names:\n      200:\n        - user_id\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx redocly lint\n\nvalidating /openapi/openapi.yaml...\n[1] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[2] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[3] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n/openapi/openapi.yaml: validated in 51ms\n\n❌ Validation failed with 3 errors.\nrun `openapi lint --generate-ignore-file` to add all problems to the ignore file.\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're using the Redocly OpenAPI extension for VS Code, this is how the lint errors look"," ","in the integrated terminal (Problems tab):"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/response-contains-property-one-ed384c8a2b637209.png","alt":"Response contains property problem in VS Code"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What does the lint output mean"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As you can see from the output, the rule triggered an error in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200.yaml"]}," file"," ","indicating there is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," property for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three \"copies\" of the error mean that there are three $refs within the OpenAPI description"," ","that refer to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," response schema object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"case-2---multiple-responses-containing-one-property","__idx":5},"children":["Case 2 - Multiple responses containing one property"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you want to check that your OpenAPI description contains property in all responses"," ","of a specific ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://en.wikipedia.org/wiki/List_of_HTTP_status_codes"},"children":["class"]},", you can use ranges."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's modify the previous example to check that all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," responses contain the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," property."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  no-unused-components: error\n  response-contains-property:\n    severity: error\n    names:\n      2xx:\n        - user_id\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx redocly lint\n\nvalidating /openapi/openapi.yaml...\n[1] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[2] openapi/components/responses/201.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[3] openapi/components/responses/202.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[4] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[5] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n/openapi/openapi.yaml: validated in 71ms\n\n❌ Validation failed with 5 errors.\nrun `openapi lint --generate-ignore-file` to add all problems to the ignore file.\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're using the Redocly OpenAPI extension for VS Code, this is how the lint errors look"," ","in the integrated terminal (Problems tab):"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/response-contains-property-range-cd44919610a6675e.png","alt":"Response contains property problem in VS Code"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What does the lint output mean"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are three ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," class responses defined for this guide, and you can see that the rule"," ","has successfully triggered errors with the missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," property for all of them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yet, three $refs within the OpenAPI description refer to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," response"," ","schema object and one $ref refers to each of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," responses, resulting in"," ","5 errors in total"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"case-3---multiple-responses-containing-multiple-properties","__idx":6},"children":["Case 3 - Multiple responses containing multiple properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Imagine that your API evolves, and in addition to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," for successful (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},") responses, it"," ","should have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ref_id"]}," properties for all other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," responses. Let's define this."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  no-unused-components: error\n  response-contains-property:\n    severity: error\n    names:\n      200:\n        - user_id\n      2xx:\n        - created_at\n        - ref_id\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx redocly lint\n\nvalidating /openapi/openapi.yaml...\n[1] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[2] openapi/components/responses/201.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"created_at\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[3] openapi/components/responses/201.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"ref_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[4] openapi/components/responses/202.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"created_at\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[5] openapi/components/responses/202.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"ref_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[6] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n[7] openapi/components/responses/200.yaml:2:1 at #/properties\n\nResponse object must contain a top-level \"user_id\" property.\n\n...\n\nError was generated by the response-contains-property rule.\n\n\n/openapi/openapi.yaml: validated in 50ms\n\n❌ Validation failed with 7 errors.\nrun `openapi lint --generate-ignore-file` to add all problems to the ignore file.\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're using the Redocly OpenAPI extension for VS Code, this is how the lint errors look"," ","in the integrated terminal (Problems tab):"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/response-contains-property-multiple-aa0017833e693ee2.png","alt":"Response contains property problem in VS Code"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What does the lint output mean"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, as there are multiple properties to check within the same response class,"," ","the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["properties defined in a more specific status code take priority"]}," over the properties defined"," ","in a status code range."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a result, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," is checked exclusively within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," status codes"," ","(that have three reference points), whereas ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ref_id"]}," are checked within"," ","the rest of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," status codes (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]},", which have one reference point each),"," ","resulting in 7 errors in total."]}]},"frontmatter":{"tocMaxDepth":3},"tagList":["admonition"],"title":"Enforce response contents with the response-contains-property rule","lastModified":"2025-05-28T16:01:32.000Z"}