{ "issues": [ { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5226", "id": 3996446341, "node_id": "I_kwDOAQkWPc7uNO6F", "number": 5226, "title": "Open Community (TDC) Meeting, Thursday 05 March 2026", "user": { "login": "github-actions[bot]", "id": 41898282, "node_id": "MDM6Qm90NDE4OTgyODI=", "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4", "gravatar_id": "", "url": "https://api.github.com/users/github-actions%5Bbot%5D", "type": "Bot", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 9, "created_at": "2026-02-26T16:15:39Z", "updated_at": "2026-03-04T15:55:30Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "## Weekly meetings happen on Thursdays at 9am - 10am Pacific\n\nThis agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. \n\nWhether attending or not, **anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals**.\n\nMeetings take place over Zoom: https://zoom-lfx.platform.linuxfoundation.org/meeting/92028872923?password=9ddcd542-4f5b-484a-a254-e00d8a8b15d8\n\n### Accessibility & Etiquette\n\n* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file).\n\n* Meetings are recorded for future reference, and for those who are not able to attend in-person.\n\n* We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting.\n\n* We look forward to your participation, but please consider these acts of etiquette:\n * Remain on mute when not speaking to prevent interruptions.\n * Blur your background to reduce visual distractions.\n * Use the Zoom meeting \"Raise Hand\" feature to notify the group when you wish to speak.\n\n| Blur My Background | Raise Hand |\n|-|-|\n| \"Screenshot | \"Screenshot |\n\n### Agenda Structure\n\n| Topic | Owner | Decision/NextStep |\n|-|-|-|\nIntros and governance meta-topics (5 mins) | TDC | |\nReports from Special Interest Groups (5 mins) | SIG members | |\nAny other business (add comments below to suggest topics) | TDC | |\n[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | |\n[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | |\n[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage | |\nIdentify next week's meeting host (2 mins) | All | Comment on next week's agenda |\n\n/cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5226/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5208", "id": 3963794344, "node_id": "I_kwDOAQkWPc7sQrOo", "number": 5208, "title": "Open Community (TDC) Meeting, Thursday 26 February 2026", "user": { "login": "github-actions[bot]", "id": 41898282, "node_id": "MDM6Qm90NDE4OTgyODI=", "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4", "gravatar_id": "", "url": "https://api.github.com/users/github-actions%5Bbot%5D", "type": "Bot", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 1, "created_at": "2026-02-19T16:14:40Z", "updated_at": "2026-02-26T06:10:55Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "## Weekly meetings happen on Thursdays at 9am - 10am Pacific\n\nThis agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. \n\nWhether attending or not, **anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals**.\n\nMeetings take place over Zoom: https://zoom-lfx.platform.linuxfoundation.org/meeting/92028872923?password=9ddcd542-4f5b-484a-a254-e00d8a8b15d8\n\n### Accessibility & Etiquette\n\n* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file).\n\n* Meetings are recorded for future reference, and for those who are not able to attend in-person.\n\n* We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting.\n\n* We look forward to your participation, but please consider these acts of etiquette:\n * Remain on mute when not speaking to prevent interruptions.\n * Blur your background to reduce visual distractions.\n * Use the Zoom meeting \"Raise Hand\" feature to notify the group when you wish to speak.\n\n| Blur My Background | Raise Hand |\n|-|-|\n| \"Screenshot | \"Screenshot |\n\n### Agenda Structure\n\n| Topic | Owner | Decision/NextStep |\n|-|-|-|\nIntros and governance meta-topics (5 mins) | TDC | |\nReports from Special Interest Groups (5 mins) | SIG members | |\nAny other business (add comments below to suggest topics) | TDC | |\n[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | |\n[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | |\n[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage | |\nIdentify next week's meeting host (2 mins) | All | Comment on next week's agenda |\n\n/cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5208/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5203", "id": 3932698487, "node_id": "I_kwDOAQkWPc7qaDd3", "number": 5203, "title": "Open Community (TDC) Meeting, Thursday 19 February 2026", "user": { "login": "github-actions[bot]", "id": 41898282, "node_id": "MDM6Qm90NDE4OTgyODI=", "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4", "gravatar_id": "", "url": "https://api.github.com/users/github-actions%5Bbot%5D", "type": "Bot", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 6, "created_at": "2026-02-12T16:16:46Z", "updated_at": "2026-02-20T15:40:28Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "## Weekly meetings happen on Thursdays at 9am - 10am Pacific\n\nThis agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. \n\nWhether attending or not, **anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals**.\n\nMeetings take place over Zoom: https://zoom-lfx.platform.linuxfoundation.org/meeting/92028872923?password=9ddcd542-4f5b-484a-a254-e00d8a8b15d8\n\n### Accessibility & Etiquette\n\n* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file).\n\n* Meetings are recorded for future reference, and for those who are not able to attend in-person.\n\n* We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting.\n\n* We look forward to your participation, but please consider these acts of etiquette:\n * Remain on mute when not speaking to prevent interruptions.\n * Blur your background to reduce visual distractions.\n * Use the Zoom meeting \"Raise Hand\" feature to notify the group when you wish to speak.\n\n| Blur My Background | Raise Hand |\n|-|-|\n| \"Screenshot | \"Screenshot |\n\n### Agenda Structure\n\n| Topic | Owner | Decision/NextStep |\n|-|-|-|\nIntros and governance meta-topics (5 mins) | TDC | |\nReports from Special Interest Groups (5 mins) | SIG members | |\nAny other business (add comments below to suggest topics) | TDC | |\n[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | |\n[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | |\n[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage | |\nIdentify next week's meeting host (2 mins) | All | Comment on next week's agenda |\n\n/cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5203/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5188", "id": 3853910004, "node_id": "I_kwDOAQkWPc7ltf_0", "number": 5188, "title": "Parsing of \"in: query\" parameters not clearly described", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 7, "created_at": "2026-01-25T21:50:39Z", "updated_at": "2026-01-27T01:19:53Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "In https://spec.openapis.org/oas/latest#parameter-locations, it is stated that the serialized form of an `in: query` parameter is appended to the URL; however it does not state how this appending is done, nor how multiple query parameters of distinct styles should be combined.\n\nRFC6570 is referenced in an appendix with a caution to not use the `&` form of uri templating and to append the query string manually, but again the use of combining multiple styles together is not clearly referenced.\n\nCan we explicitly reference that all `query` parameters are expected to be serialized as in the application/x-www-form-urlencoded media-type? This is not an extra serialization pass however, but rather an overlapping one -- e.g. for deepObject and for some other style/explode/type combinations the individual key name(s) is/are not the parameter name itself but may be something else or even omitted entirely.\n\nI think WHATWG is probably the best thing to reference here, but I'm not entirely sure.\n\nWe can also clarify (e.g. in one of the appendices that already talks about parameter decoding) that for `in: query`, it is always correct to use the application/x-www-form-urlencoded media type decoding to parse out the full list of keys/values from the query string (but not to treat this as an object as there may be duplicate keys, which may be used or ignored depending on the individual style and explode settings).\n\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5188/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5062", "id": 3550717595, "node_id": "I_kwDOAQkWPc7To6ab", "number": 5062, "title": "v3.2: issues with the path-item and server url templates", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 7, "created_at": "2025-10-24T19:18:48Z", "updated_at": "2025-10-26T19:56:19Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Thank you for the expanded sections on path and server url templating in the 3.2 spec (https://spec.openapis.org/oas/latest#path-templating and https://spec.openapis.org/oas/latest#server-variable-object respectively) -- this is quite helpful in ensuring closer specification compliance in implementations that perform matching of live HTTP requests against elements of the OpenAPI description (OAD).\n\nHowever I have some questions and concerns that might suggest there are errors with the specification, or perhaps areas where further clarifications could be added:\n\n- In both path templates and server urls, we do not explicitly disallow two adjacent template components - e.g. `/{foo}{bar}`. In the absence of specifying which one of these matches is greedy, there is no deterministic way of matching this, and should be prohibited. (I filter these out in regexes (see below) using a negative look-ahead assertion.)\n\n- https://spec.openapis.org/oas/latest#path-templating says that the path template ABNF is derived from RFC3986 s3.3 (via commit e4caedca690, by @baywet). But that section describes URI paths, not templates. Was this intended to refer to the uri template RFC instead?\n\nThe regular expressions that I am using in my implementation are below; I would appreciate a sanity check:\n\n- for path templates: each segment (split on `/`, after omitting the leading `/`) must match: `^(?:\\{[^{}]+\\}(?!\\{)|%[0-9A-F]{2}|[:@!\\$&'()*+,;=A-Za-z0-9._~-]+)+$`\n\n- for server url, the entire string must match: `^(?:\\{[^{}]+\\}(?!\\{)|%[0-9A-F]{2}|[\\x21\\x23\\x24\\x26-\\x3B\\x3D\\x3F-\\x5B\\x5D\\x5F\\x61-\\x7A\\x7E\\xA0-\\x{D7FF}\\x{F900}-\\x{FDCF}\\x{FDF0}-\\x{FFEF}\\x{10000}-\\x{1FFFD}\\x{20000}-\\x{2FFFD}\\x{30000}-\\x{3FFFD}\\x{40000}-\\x{4FFFD}\\x{50000}-\\x{5FFFD}\\x{60000}-\\x{6FFFD}\\x{70000}-\\x{7FFFD}\\x{80000}-\\x{8FFFD}\\x{90000}-\\x{9FFFD}\\x{A0000}-\\x{AFFFD}\\x{B0000}-\\x{BFFFD}\\x{C0000}-\\x{CFFFD}\\x{D0000}-\\x{DFFFD}\\x{E1000}-\\x{EFFFD}\\x{E000}-\\x{F8FF}\\x{F0000}-\\x{FFFFD}\\x{100000}-\\x{10FFFD}])+$`\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5062/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4986", "id": 3444364890, "node_id": "I_kwDOAQkWPc7NTNZa", "number": 4986, "title": "v3.0: set up schema maintenance", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" }, "1": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": { "0": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 6, "created_at": "2025-09-23T09:06:23Z", "updated_at": "2025-10-30T20:24:03Z", "closed_at": null, "assignee": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Prepare development branch for v3.0 schema maintenance:\n\n- [x] create branch `v3.0-dev-wip` - [diff to `dev`](https://github.com/OAI/OpenAPI-Specification/compare/dev...v3.0-dev-wip)\n- [x] delete `src/oas.md` - we do not plan a 3.0.5 spec release \n - [ ] otherwise: #5094 \n- [x] delete `src/schemas/validation/*`\n- [x] move `_archive_/v3.0/schemas/schema.yaml` and accompanying `README.md` to `src/schemas/validation/`\n- [x] move test-related files from `_archive_/v3.0/schemas/` to `tests/`\n- [x] make tests work and pass\n- [x] refactor tests to use same tools as the v3.1 tests\n- [x] test schema publishing workflow - also works for 3.0\n- [x] adjust selected 3.1 pass/fail test cases to increase schema coverage\n- [ ] rename branch `v3.0-dev-wip` to `v3.0-dev` (or squash-merge it into a branch freshly created from `dev`)", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4986/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4870", "id": 3323790465, "node_id": "I_kwDOAQkWPc7GHQSB", "number": 4870, "title": "Restructure how we mention the JSON Schemas", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" } }, "state": "open", "locked": false, "assignees": { "0": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 16, "created_at": "2025-08-14T22:45:53Z", "updated_at": "2025-11-21T04:13:47Z", "closed_at": null, "assignee": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "This is somewhat related to #4831...\n\nCurrently the schemas (used to validate OpenAPI documents, as well as provide aids to implementations parsing the OAD by identifying locations of schemas and other identifiable types) are described by https://spec.openapis.org as \"non-normative\", and by the specification as \"non-authoritative\".\n\n- \"non-normative\" means that the schemas are not an official formal part of the specification, but only there to be helpful and aid understanding;\n- \"non-authoritative\" means that the schemas are not from an official source.\n\nI believe neither of these things are true: the schemas are part of the specification in that they capture, to the best of their ability, the constraints and restrictions described by the specification, and we take effort to ensure that they are correct and in sync with the changes to the specification document, and the schemas do come from an official source (they are published from the very same repository as the specification text itself, authored by the same trusted people).\n\nI would like the schema links to be more prominent in the published specification, listed at the top of https://spec.openapis.org/oas/latest.html (perhaps below \"Editors\"), or farther up as two new subsections: \"Latest Schemas\" (four bullet points) and \"Previous Schemas\" (a single link to https://spec.openapis.org/#specifications). This could be templated so as not to require any manual spec editing should we wish to release a schema update/fix. Alternatively, we could make use of this via ReSpec (see https://respec.org/docs/#otherLinks)\n\nThe paragraph at https://spec.openapis.org/oas/latest#schema could be rewritten to indicate that the schemas can be trusted to perform validation of an OAD: while the schemas cannot cover every requirement and constraint of the specification, validation is guaranteed to NOT produce false failures -- that is, while the schemas cannot promise to fail validation on every invalid OAD, we can promise that we will never fail validation for a valid OAD.\n\nAlso, https://spec.openapis.org can contain similar wording changes (removing mention of them being non-normative): the schemas can be used to aid parsing, and will find many structural errors in the OAD, so it is fully expected and recommended that all tools make use of these.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4870/reactions", "total_count": 3, "+1": 3, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4803", "id": 3245427218, "node_id": "I_kwDOAQkWPc7BcUoS", "number": 4803, "title": "Create „pass“ test cases from examples in `oas.md`", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 0, "created_at": "2025-07-19T16:23:23Z", "updated_at": "2025-07-19T16:24:09Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Given the growing number of examples in the specification, it would be nice to (semi-)automatically create „pass“ test cases from Markdown spec text.\n\nThis would help keeping the examples correct and simplify reaching sufficient schema test coverage.\n\nMight be a nice hobby project for someone.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4803/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4788", "id": 3239950213, "node_id": "I_kwDOAQkWPc7BHbeF", "number": 4788, "title": "v3.x: Does the Encoding Object's contentType allow whitespace around commas?", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 0, "created_at": "2025-07-17T15:10:20Z", "updated_at": "2025-07-17T15:10:32Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I expected it would (e.g. `contentType: text/css, text/javascript, image/*`) by analogy with the `Accept` header, while @ralfhandl read it more literally and expects only `contentType: text/css,text/javascript,image/*` would be allowed. I suppose it depends on your assumptions on the phrase \"comma-separated list\" which is all we say about it.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4788/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4542", "id": 2986393252, "node_id": "I_kwDOAQkWPc6yAL6k", "number": 4542, "title": "Consider additional guidance on Server Objects", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 8441266563, "node_id": "LA_kwDOAQkWPc8AAAAB9yOBgw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/deployment", "name": "deployment", "color": "4D4608", "default": false, "description": "Servers and related deployment configuration" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 0, "created_at": "2025-04-10T17:29:59Z", "updated_at": "2025-11-09T22:33:57Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "@karenetheridge and @notEthan raised various points about confusion and usage of the Server Object and its `url` field in PR #4389.\n\nFrom @karenetheridge \n\n> We can also offer caution that if server urls are not absolute, then the retrieval URI will be used to resolve them, which might not be desirable because if the scheme+host of the retrieval URI may not actually be the same scheme+host as where the APIs are being hosted, the result will be that any matching of API HTTP requests against path-items in the OpenAPI document will fail.\n> \n> This caveat is not new with these changes, but a user might think that an absolute $self is sufficient to ward off this problem, which it isn't.\n\nFrom @notEthan (the part about server variables vs relative server URLs being the most relevant to this issue, see #4541 for other concerns raised in this quote):\n\n> I certainly agree/understand that the URIs of the API description and objects within are quite different than (or unrelated to) API server/endpoint URLs. My hesitation is on the idea that the retrieval URI for the OAD is likely to be more closely related to the server URL than $self (I've generally seen the OAD served from one place accompanying documentation, not with each deployment, and aren't server variables the better mechanism for deployment-specific URLs?).\n> \n> Or rather, my hesitation as an implementer of tooling is on whether that difference is worth implementing - I have one base URI for objects in the OAD (including servers), which will be changing to inherit from $self, and no place to put another base URI. It's not difficult to implement but it adds some complexity in a place I have doubts on the real utility of it.\n\nNote that some of this guidance could go on the Learn Site, which already has a [substantial page on the Server Object](https://learn.openapis.org/specification/servers.html).", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4542/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4512", "id": 2955577425, "node_id": "I_kwDOAQkWPc6wKohR", "number": 4512, "title": "Infrastructure: automatically check adherence to style guide", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 0, "created_at": "2025-03-28T09:48:40Z", "updated_at": "2025-03-28T09:48:40Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Support editors by automatically checking the rules in the [style guide](https://github.com/OAI/OpenAPI-Specification/blob/main/style-guide.md).\n\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4512/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4442", "id": 2922614242, "node_id": "I_kwDOAQkWPc6uM43i", "number": 4442, "title": "Is it possible to indicate the requiredness of a `multipart/form-data`'s request's `filename` directive?", "user": { "login": "TomerAberbach", "id": 23299544, "node_id": "MDQ6VXNlcjIzMjk5NTQ0", "avatar_url": "https://avatars.githubusercontent.com/u/23299544?v=4", "gravatar_id": "", "url": "https://api.github.com/users/TomerAberbach", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" }, "1": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 7, "created_at": "2025-03-15T22:50:30Z", "updated_at": "2025-09-25T16:52:10Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "As far as I can tell, the `required` property in the OpenAPI spec can be used to specify that an entire `multipart/form-data` part is required, but it cannot be used to indicate whether the [`filename` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition#filename) is required.\n\nThis would be pretty useful since some `multipart/form-data` endpoints require the `filename` directive while others do not. If OpenAPI allowed specifying those semantics, then that could be used in various generators that consume OpenAPI (e.g. an SDK generator could check whether the end-user supplied a `filename` if it's required).", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4442/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4221", "id": 2680953897, "node_id": "I_kwDOAQkWPc6fzBwp", "number": 4221, "title": "Provide guidance on using OAS with Overlay and Arazzo", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 3, "created_at": "2024-11-21T21:03:48Z", "updated_at": "2025-11-24T22:41:09Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 1, "completed": 1, "percent_completed": 100 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Many long-requested features for OAS can now be better handled by using the Overlay and/or Arazzo specifications.\r\n\r\nI think Arazzo mostly overlaps with the Link Object, but I might be wrong there. Some guidance as to when to use which would probably be good to add.\r\n\r\nOverlays solve many requests for global or default values, and if it is reasonably straightforward to do that, we should include info in the OAS pointing to the Overlay spec for that use case. Other use cases include various reference-and-modify constructs (hmm.. do we want to consider pushing this instead of the adjacent-fields-in-Reference-Object approach?)\r\n\r\nPutting this in the next patch release, although there may be additional things to do in minor releases here.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4221/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4212", "id": 2679528399, "node_id": "I_kwDOAQkWPc6ftlvP", "number": 4212, "title": "Support API-wide version information", "user": { "login": "dret", "id": 1848612, "node_id": "MDQ6VXNlcjE4NDg2MTI=", "avatar_url": "https://avatars.githubusercontent.com/u/1848612?v=4", "gravatar_id": "", "url": "https://api.github.com/users/dret", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." }, "1": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" }, "2": { "id": 7069061505, "node_id": "LA_kwDOAQkWPc8AAAABpVlRgQ", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/registries", "name": "registries", "color": "EEF971", "default": false, "description": "Related to any or all spec.openapis.org-hosted registries" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 21, "created_at": "2024-11-21T13:42:05Z", "updated_at": "2025-07-18T09:56:16Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "This could be used to represent the version information of the described API. The current `version` field is oftentimes misunderstood and misused to represent the API version information. Having a registry-based extension could help as a quick fix, and new versions (3.2 and/or 4) will hopefully fix the current gap at the standards level.\n\nThe risk is that this could then be used in newer versions as well. I don't know how much this should be see as an argument against the proposal.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4212/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4152", "id": 2605785655, "node_id": "I_kwDOAQkWPc6bUSI3", "number": 4152, "title": "Make the \"latest\" schema accessible programmatically", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" }, "1": { "id": 9388948106, "node_id": "LA_kwDOAQkWPc8AAAACL5_6ig", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/website", "name": "website", "color": "22a2c1", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": { "0": { "login": "pavelkornev", "id": 748043, "node_id": "MDQ6VXNlcjc0ODA0Mw==", "avatar_url": "https://avatars.githubusercontent.com/u/748043?v=4", "gravatar_id": "", "url": "https://api.github.com/users/pavelkornev", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 12, "created_at": "2024-10-22T15:25:45Z", "updated_at": "2026-02-12T18:07:02Z", "closed_at": null, "assignee": { "login": "pavelkornev", "id": 748043, "node_id": "MDQ6VXNlcjc0ODA0Mw==", "avatar_url": "https://avatars.githubusercontent.com/u/748043?v=4", "gravatar_id": "", "url": "https://api.github.com/users/pavelkornev", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "We don't want schema URIs with `latest` in place of the date because schema contents should not change unexpectedly. However, we need some way for folks to access the latest schemas, preferably without pulling all of the dates and sorting them.\r\n\r\nUnfortunately, GitHub pages does not support HTTP redirects (or setting media types independent of file extensions) so we need to figure out a workarond. Or move to Netlify or Cloudflare Pages or something else with actual proper HTTP support.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4152/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4147", "id": 2599472828, "node_id": "I_kwDOAQkWPc6a8M68", "number": 4147, "title": "Improve 3.1+ schema `$id` UX", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 47, "created_at": "2024-10-19T18:35:45Z", "updated_at": "2025-09-18T09:56:58Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Currently, we have the following schema document `$id`s for OAS 3.1 (shown relative to a base URI of `https://https://spec.openapis.org/oas/3.1/`, and without the trailing date segment that all schemas need to support updates:\r\n\r\n* `schema` # Validates everything _except_ the Schema Object, which is only validated against `type: [boolean, object]`\r\n* `schema-base` # Extends `schema` to validate Schema Objects against `dialect/base` _and_ require both `$schema` and `jsonSchemaDialect` to be set to `schema`'s `$id` if they are present\r\n* `dialect/base` # A dialect equivalent to the default 2020-12 dialect plus the OAS extensions\r\n* `meta/base` # The vocabulary metaschema for the OAS extensions\r\n\r\n`schema-base` was named to indicate that it incorporates `dialect/base`. No one is certain why the dialect and vocabulary are referred to as \"base\", but they are called that in the OAS text as well. I vaguely recall discussing the dialect as a base for further OAS-relevant extensions? Perhaps that is what the intent was.\r\n\r\nAFAICT, the advantage of `schema` is that it's self-contained. But giving it that name means that it is the schema that most people assume is what they want, yet it really does not produce the behavior they'd expect.\r\n\r\n`schema-base` is closer to what people would expect, but is (in my view) overly restrictive in locking `$schema` to `dialect/base`, as it is valid to switch metaschemas if `$schema` appears alongside `$id`, and conforming JSON Schema implementations know to treat `$id`-containing subschemas as embedded resources and check for a changed metaschema. However, this does ***not*** make `schema-base` wrong: Users might indeed want to enforce using _only_ `dialect/base`, and this is the correct way to do that.\r\n\r\nOn the other hand (and contrary to some of my comments earlier on Slack), `schema-base` locking `jsonSchemaDialect` to `dialect/base` is probably correct. If you want to set `jsonSchemaDialect` to something else, you would want a schema that validates Scheam Objects accordingly by default.\r\n\r\n-----\r\n\r\nWe probably shouldn't change how `schema` behaves, but we should make it more obvious that it is incomplete. We should also come up with some sort of intuitive name for a schema that is like `schema-base` but does not restrict `$schema`. This name needs to convey that _most users will want this new schema, and **not** the plain_ `schema`.\r\n\r\nIdeally, I'd prefer to make copies of the vocabulary and dialect and give them the URIs `dialect/oas` and `meta/oas` (`3.1` is already present earlier in the URI), but that is probably more trouble than it is worth given that I imagine very few people pay attention to those other than to just load them correctly when using `schema-base`.\r\n\r\nThe important thing is to have an intuitively-named schema that performs the default accepted Schema Object validation but still allows switching metaschemas on embedded resources. That is the default behavior of the OAS, and it's not currently provided.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4147/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4106", "id": 2541178869, "node_id": "I_kwDOAQkWPc6Xd0_1", "number": 4106, "title": "Representation of Client-Initiated Backchannel Authentication (CIBA)", "user": { "login": "SensibleWood", "id": 2420069, "node_id": "MDQ6VXNlcjI0MjAwNjk=", "avatar_url": "https://avatars.githubusercontent.com/u/2420069?v=4", "gravatar_id": "", "url": "https://api.github.com/users/SensibleWood", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502448849, "node_id": "LA_kwDOAQkWPc8AAAABg5N-0Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20config", "name": "security: config", "color": "b20805", "default": false, "description": "The mechanics of severs and structure of security-related objects" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 20, "created_at": "2024-09-22T17:34:10Z", "updated_at": "2025-09-03T10:37:04Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I'd like to raise a concern with including CIBA in the OAuth Flow Object in 3.2.0.\r\n\r\nI understand that CIBA can, feasibly, be implemented using bare OAuth 2.0 but realistically it's an OpenID Connect profile. A user is correlated by the Authorization Server using `login_hint`, `id_token_hint`, etc - these are OpenID Connect features.\r\n\r\nI think there needs to be a separation-of-concerns between OAuth 2.0 and OpenID Connect in OpenAPI. The semantics of OpenID Connect provides proofs-of-authentication, with support for request objects, ID tokens, _et al_. OpenID Connect obviously builds on top of OAuth, but if we go down the road of starting to bundle OpenID Connect profiles into the OAuth Flow it has the potential to get pretty messy .\r\n\r\nI propose an alternative approach:\r\n\r\n* OAuth Flow object stays as is. This is well known, and medalling with it might be a step backwards.\r\n* New OpenID Connect object, building on the existing pointer to discovery metadata through `openIdConnect` property. Implement with a description of how to process that metadata for various profiles such as:\r\n * Bare OpenID Connect\r\n * FAPI 1.0 Advanced and FAPI 2.0\r\n * CIBA\r\n\r\nI think that if we did it this way we can avoid duplicating OpenID Connect Discovery metadata in OpenAPI, and instead allow that to live where it needs to i.e. in the discovery endpoint. Implementing OpenID Discovery is a common practice, so I think we are in a good place to leverage an existing, external metadata source.\r\n\r\nThe descriptions - and maybe a _nice_ JSON Schema as an addendum that we provide to be helpful - will then help tooling makers make sense of the discovery metadata from the lens of OpenAPI.\r\n\r\nHappy to get involved if this approach is perceived as a good idea. I know OpenID in enough to detail to be vaguely useful.\r\n\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4106/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4084", "id": 2519394039, "node_id": "I_kwDOAQkWPc6WKub3", "number": 4084, "title": "Link Object (and Arazzo?): require referencing operation with unambiguous path template", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806279, "node_id": "MDU6TGFiZWw4MzgwNjI3OQ==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/bug", "name": "bug", "color": "fc2929", "default": true, "description": null }, "1": { "id": 6500556020, "node_id": "LA_kwDOAQkWPc8AAAABg3ac9A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref/id%20resolution", "name": "re-use: ref/id resolution", "color": "5F843B", "default": false, "description": "how $ref, operationId, or anything else is resolved" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 2, "created_at": "2024-09-11T10:50:32Z", "updated_at": "2026-02-10T18:19:04Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Assume paths `/foo` and `/bar` both have a Path Item Object that `$ref` the same external \"complete\" Path Item Object.\r\n\r\nIf a Link Object now `operationRef`s the `get` Operation Object within that external Path Item Object, which request should the client construct?\r\n\r\nIt could be both\r\n * `GET /foo` or\r\n * `GET /bar`\r\n\r\nProposal:\r\n* Add restriction to Link Object that `operationRef` and `operationId` MUST NOT reference a reusable/multi-used Path Item Object\r\n* Possibly: require that the `operationRef` value \"goes through\" a Paths Object", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4084/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4037", "id": 2471694030, "node_id": "I_kwDOAQkWPc6TUw7O", "number": 4037, "title": "Add requirements or recommendations about allow/deny lists for reference target retrieval", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6500556020, "node_id": "LA_kwDOAQkWPc8AAAABg3ac9A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref/id%20resolution", "name": "re-use: ref/id resolution", "color": "5F843B", "default": false, "description": "how $ref, operationId, or anything else is resolved" }, "2": { "id": 6502398197, "node_id": "LA_kwDOAQkWPc8AAAABg5K49Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20meta", "name": "security: meta", "color": "b20805", "default": false, "description": "Metadata in and about the specification" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 3, "created_at": "2024-08-17T22:29:05Z", "updated_at": "2025-08-19T06:41:01Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "As multi-document OADs become more important due to both new use cases and an increasing number of OADs that are far too large to work with as a single document, we should be more clear about the resource location and retrieval process.\r\n\r\nIn particular, there is a security risk to fetching resources from arbitrary locations. We should at least RECOMMEND some sort of allow/deny functionality, and require (MUST) a sensible default behavior.\r\n\r\nFor example, it's conceivable that a poorly designed API runtime tool running at improperly elevated privilege could be induced to load a sensitive file, get confused, and display it in an error message over the network. Or, a tool that does something bad like `eval()` fetched JSON could be sent a malicious bit of JavaScript instead. ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4037/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3853", "id": 2315923728, "node_id": "I_kwDOAQkWPc6KCjEQ", "number": 3853, "title": "Consolidated $ref-to-Some Object feature request", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500261740, "node_id": "LA_kwDOAQkWPc8AAAABg3IfbA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref-everywhere", "name": "re-use: ref-everywhere", "color": "fef2c0", "default": false, "description": "Requests to support referencing in more / all places" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 7, "created_at": "2024-05-24T17:50:03Z", "updated_at": "2026-01-09T17:17:31Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "This issure consolidates and replaces the numerous \"can the OAS allow `$ref` for...\" issues:\r\n\r\n* Security Requirement: #1850\r\n* Security Scheme: #1972 (but see also #3776 for an alternative)\r\n* Server: #2338 \r\n* Tags: #2905 \r\n* Operation: #2922 (but note that there are impacts on finding and resolving `operationId`)\r\n* Media Type: #3056 (closed because the specific use case is handled by overriding `description` with a Reference Object); also #2845 although there is more to that one)\r\n* Contact: #3552\r\n* License: #3569 ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3853/reactions", "total_count": 6, "+1": 1, "-1": 0, "laugh": 0, "hooray": 5, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3777", "id": 2278016758, "node_id": "I_kwDOAQkWPc6Hx8b2", "number": 3777, "title": "remove \"Optional OAuth2 security\" examples", "user": { "login": "AxelNennker", "id": 1721863, "node_id": "MDQ6VXNlcjE3MjE4NjM=", "avatar_url": "https://avatars.githubusercontent.com/u/1721863?v=4", "gravatar_id": "", "url": "https://api.github.com/users/AxelNennker", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6484311864, "node_id": "LA_kwDOAQkWPc8AAAABgn6_OA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/examples", "name": "examples", "color": "DE7939", "default": false, "description": "requests for more or better examples in the specification" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 3, "created_at": "2024-05-03T16:19:26Z", "updated_at": "2025-08-17T20:10:01Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I wonder why these \"Optional OAuth2 security\" examples were created in the first place.\r\n\r\nI agree that an API can have several options how the API client authenticates but having oauth2 security or alternatively none seems not a good security practice.\r\n\r\ne.g. here https://github.com/OAI/OpenAPI-Specification/blob/v3.2.0-dev/versions/3.0.3.md#optional-oauth2-security\r\n\r\nIf the example was intended to show multiple alternative security requirements or the combination of an oauth2 security object with another non-oauth2 security object, then the second one should not be empty.\r\nMaybe the API is migrating from apiKey to oauth2 and is deprecating api_key.\r\n\r\n```\r\n{\r\n \"security\": [\r\n {\r\n \"api_key\": []\r\n },\r\n {\r\n \"petstore_auth\": [\r\n \"write:pets\",\r\n \"read:pets\"\r\n ]\r\n }\r\n ]\r\n}\r\n\r\n```\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3777/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3774", "id": 2276015899, "node_id": "I_kwDOAQkWPc6HqT8b", "number": 3774, "title": "Establish governance docs for working groups", "user": { "login": "earth2marsh", "id": 54582, "node_id": "MDQ6VXNlcjU0NTgy", "avatar_url": "https://avatars.githubusercontent.com/u/54582?v=4", "gravatar_id": "", "url": "https://api.github.com/users/earth2marsh", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" }, "1": { "id": 3318135206, "node_id": "MDU6TGFiZWwzMzE4MTM1MjA2", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Process", "name": "Process", "color": "58BF2F", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": { "0": { "login": "earth2marsh", "id": 54582, "node_id": "MDQ6VXNlcjU0NTgy", "avatar_url": "https://avatars.githubusercontent.com/u/54582?v=4", "gravatar_id": "", "url": "https://api.github.com/users/earth2marsh", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 1, "created_at": "2024-05-02T16:54:00Z", "updated_at": "2024-06-07T19:33:00Z", "closed_at": null, "assignee": { "login": "earth2marsh", "id": 54582, "node_id": "MDQ6VXNlcjU0NTgy", "avatar_url": "https://avatars.githubusercontent.com/u/54582?v=4", "gravatar_id": "", "url": "https://api.github.com/users/earth2marsh", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "With the Workflows specification reaching a 1.0 release, it will outgrow the \"Special Interest Groups\" moniker. This issue is meant to track the updates required to various governing documents either within or outside this repo.\r\n\r\n1. Add/update docs for SIGs to explain how they evolve [either become a Working Group (Workflows), fold back into the spec (potentially Overlays), disband (?), or continue in perpetuity (Security never ends)]\r\n2. Outline any mechanisms necessary to establish and describe Working Groups\r\n3. Identify any related areas that might benefit from clarification, such as the description of the TOB.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3774/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3720", "id": 2253881378, "node_id": "I_kwDOAQkWPc6GV4Ai", "number": 3720, "title": "Why does the JSON schema for 3.0 specify patternProperties for component names but allows additional properties?", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806279, "node_id": "MDU6TGFiZWw4MzgwNjI3OQ==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/bug", "name": "bug", "color": "fc2929", "default": true, "description": null }, "1": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 5, "created_at": "2024-04-19T20:08:59Z", "updated_at": "2025-09-23T11:45:20Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "### Discussed in https://github.com/OAI/OpenAPI-Specification/discussions/2439\r\n\r\n
\r\n\r\nOriginally posted by **ryankinderman** January 11, 2021\r\nI've been working on some functionality that uses the JSON schema to help validate OpenAPI schemas, and recently noticed that the 3.0 schema allows any value for `{name}` in `/components/{component}/{name}`, while the [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-6) states that \"All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\\.\\-_]+$.`\" It seems like this could have been validated automatically by simply adding `additionalProperties: false` to the JSON schema.\r\n\r\nMy question is: Was not including `additionalProperties: false` in the JSON schema for 3.0 just an accidental omission, or was there some rationale behind not doing it?\r\n\r\nThanks for clarifying!
\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3720/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [ 4997 ] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3709", "id": 2246833475, "node_id": "I_kwDOAQkWPc6F6_VD", "number": 3709, "title": "Add tokenExchange grant type to list of allowed grant types for oauth2 shape", "user": { "login": "kaheidt", "id": 136550, "node_id": "MDQ6VXNlcjEzNjU1MA==", "avatar_url": "https://avatars.githubusercontent.com/u/136550?v=4", "gravatar_id": "", "url": "https://api.github.com/users/kaheidt", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502392139, "node_id": "LA_kwDOAQkWPc8AAAABg5KhSw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20access%20ctrl", "name": "security: access ctrl", "color": "b20805", "default": false, "description": "Permissions and controls distinct from authentication" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 0, "created_at": "2024-04-16T20:29:05Z", "updated_at": "2025-05-15T18:48:05Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "[Current spec](https://spec.openapis.org/oas/latest.html#fixed-fields-23) definition allows `implicit`, `password`, `clientCredentials`, and `authorizationCode` for oauth2 flows. This request is to include [tokenExchange](https://www.rfc-editor.org/rfc/rfc8693) in the list of grant types/flows.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3709/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3612", "id": 2159064904, "node_id": "I_kwDOAQkWPc6AsLdI", "number": 3612, "title": "Enhancing specification to describe token presentation mechanisms for OAuth 2.0", "user": { "login": "alex-feel", "id": 71711753, "node_id": "MDQ6VXNlcjcxNzExNzUz", "avatar_url": "https://avatars.githubusercontent.com/u/71711753?v=4", "gravatar_id": "", "url": "https://api.github.com/users/alex-feel", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 4, "created_at": "2024-02-28T14:12:24Z", "updated_at": "2025-05-15T20:32:39Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "## Issue Description\r\n\r\nDuring a recent discussion in https://github.com/OAI/OpenAPI-Specification/discussions/2867, it became apparent that the OpenAPI Specification lacks explicit guidelines on how clients should present access tokens to resource servers, especially considering the OAuth 2.0 authorization framework. This issue was highlighted in the context of OAuth 2.0's defined grant flows and the need for specifying how access tokens, once obtained, are used for resource access.\r\n\r\n## Relevant Discussion Points\r\n\r\n- **OAuth 2.0 Grant Flows**: The specification allows defining OAuth 2.0 flows, like the implicit flow, requiring the `authorizationUrl`. However, it stops short of detailing how the obtained access tokens should be presented to the resource server.\r\n \r\n- **Access Token Presentation**: The OAuth 2.0 specification mentions the use of the HTTP \"Authorization\" request header field with an authentication scheme for the access token type. Yet, \"typically\" does not encompass all possible scenarios, like the requirement for the Demonstration of Proof-of-Possession at the Application Layer (DPoP), which requires additional headers.\r\n\r\n- **OpenAPI Specification Limitation**: The current OpenAPI Specification does not support specifying the method of presenting an access token to a resource server. This limitation was acknowledged in a community call discussion.\r\n\r\n## Proposal for Enhancement\r\n\r\nGiven the diversity in access token types and presentation methods (e.g., Bearer tokens, DPoP), there is a clear need for the OpenAPI Specification to allow documenting the exact mechanism of access token presentation for a secured endpoint.\r\n\r\n### Suggested Improvements:\r\n\r\n1. **Extend the `securitySchemes` Object**: Introduce new fields within the `securitySchemes` object to specify the required headers or methods for presenting access tokens, including non-standard approaches.\r\n \r\n2. **Community Engagement**: Invite contributions and discussions from the OpenAPI community, through TDC calls, workflows sig, or security sig, to refine and agree upon the proposed enhancements.\r\n\r\n## Conclusion\r\n\r\nEnhancing the OpenAPI Specification to include explicit guidelines on access token presentation mechanisms would greatly aid in the accurate and comprehensive documentation of APIs, fostering better interoperability and understanding of secured API endpoints. I look forward to contributing to this discussion and helping drive the necessary changes.\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3612/reactions", "total_count": 3, "+1": 3, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3603", "id": 2149589107, "node_id": "I_kwDOAQkWPc6AICBz", "number": 3603, "title": "Add info to security considerations about outdated security practices, and link in new versions", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502398197, "node_id": "LA_kwDOAQkWPc8AAAABg5K49Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20meta", "name": "security: meta", "color": "b20805", "default": false, "description": "Metadata in and about the specification" } }, "state": "open", "locked": false, "assignees": { "0": { "login": "darrelmiller", "id": 447694, "node_id": "MDQ6VXNlcjQ0NzY5NA==", "avatar_url": "https://avatars.githubusercontent.com/u/447694?v=4", "gravatar_id": "", "url": "https://api.github.com/users/darrelmiller", "type": "User", "user_view_type": "public", "site_admin": true } }, "milestone": null, "comments": 4, "created_at": "2024-02-22T17:43:33Z", "updated_at": "2025-05-15T18:44:05Z", "closed_at": null, "assignee": { "login": "darrelmiller", "id": 447694, "node_id": "MDQ6VXNlcjQ0NzY5NA==", "avatar_url": "https://avatars.githubusercontent.com/u/447694?v=4", "gravatar_id": "", "url": "https://api.github.com/users/darrelmiller", "type": "User", "user_view_type": "public", "site_admin": true }, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "See PR #3584 from @AxelNennker for the background. We agreed in the TDC meeting 2024-02-22 to add info in security considerations and probably also on the learn site, and link to that and to any new RFCs in 3.0.4/3.1.1/3.2.0. \r\n\r\n@lornajane also noted that we should replace any examples using deprecated practices with ones that are current.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3603/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3530", "id": 2103044961, "node_id": "I_kwDOAQkWPc59Weth", "number": 3530, "title": "Define formats for URL templating with and without runtime expressions", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" }, "1": { "id": 5226531003, "node_id": "LA_kwDOAQkWPc8AAAABN4aIuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/format-registry", "name": "format-registry", "color": "9996E7", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 7, "created_at": "2024-01-26T23:14:18Z", "updated_at": "2025-08-19T22:10:28Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "PR #3234 proposes a `url-template` format, and is currently in discussion regarding the scope and naming of the format.\r\n\r\nPR #3235 applied the format to the current schema, resulting in a debate over whether different formats are needed for URL templates that use runtime expressions vs those that do not.\r\n\r\nThere might also be other templating use cases in the Workflows spec that don't quite fit in either of these.\r\n\r\nI'm filing this issue so we can track the various parts of the debate separately from the PRs, as PR #3235 overlaps with PR #3455 as well as having unresolved questions, so I am likely to close it.\r\n\r\nPaging @MikeRalphson , @frankkilcommins\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3530/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3486", "id": 2064506359, "node_id": "I_kwDOAQkWPc57Dd33", "number": 3486, "title": "Proposal: Create new repo for openapi tests, similar to json schema test suite", "user": { "login": "spacether", "id": 1912028, "node_id": "MDQ6VXNlcjE5MTIwMjg=", "avatar_url": "https://avatars.githubusercontent.com/u/1912028?v=4", "gravatar_id": "", "url": "https://api.github.com/users/spacether", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 3, "created_at": "2024-01-03T18:58:46Z", "updated_at": "2024-04-24T20:32:56Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "This issue is a proposal that a new repo be created that stores tests of openapi payloads, request, responses, and documents. These tests will help implementation verify that they have built features correctly.\r\n\r\nThere is existing prior work here that applies to json schema only in the json schema test suite: https://github.com/json-schema-org/JSON-Schema-Test-Suite\r\n\r\nNeed for this solution:\r\n- there are few tests here: https://github.com/OAI/OpenAPI-Specification/tree/main/tests/v3.1 and they do not provide full coverage for openapi features, they do not describe what is acceptable and unacceptable for openapi-only schema formats, they may not be well known in the community, they do not have coverage tests for different versions of the openapi spec\r\n- what is allowed for int32/int64/float/double is not explicitly defined in the spec or the format registry (for example is X.0 allowed in for int32?). Implementers need this info when building.\r\n- [I attempted to add int64 tests into the json schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite/pull/711) and was told that that repo is not the right place for that test, because the format is openapi-specific and is not listed in the json schema spec.\r\n\r\nBenefits:\r\n- tooling providers could have a verifiable way of proving that their implementation is conforming to the requirements\r\n- long term this should reduce the number of what is the correct way to implement x feature questions on this repo because you can point them to the existing test\r\n- including these tests in a separate repo will allow implmenters to include that repo as a subpackage and easily test against it. (I currently do this with the json schema test suite [here](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/src/test/resources))\r\n- General json schema 2020-12 tests should not be included here because they already exist in the json schema test suite. Refer users to that suite also. This reduces the maintenance workload.\r\n\r\nProposal Short Term:\r\n- create a new repo, Openapi Test Suite in the https://github.com/OAI org\r\n- have one folder for each version of the openapi test suite\r\n- move the existing tests into that\r\n- perhaps organize the tests in the same directory structure as the openap spec?\r\n- add tests in components/schemas/format.json which includes the int64 format tests in: https://github.com/json-schema-org/JSON-Schema-Test-Suite/pull/711\r\n\r\nI would be happy to add additional test for int32/float/double/int formats\r\n@karenetheridge mentioned that she could contribute tests from https://github.com/karenetheridge/OpenAPI-Modern/tree/master/t\r\n\r\nOpen Questions:\r\n- How thorough should these tests be?\r\n - My proposal is to incrementally add coverage bit by bit starting with easiest tests, which may be component schema formats.\r\n- Are you okay using the json schema test suite format for the schema test files?\r\n- What openapi versions will have tests?\r\n- Do these tests mean that the tooling MUST/MAY/verb implement these features? (How does json schema handle this Julian Berman?)", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3486/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3482", "id": 2054477821, "node_id": "I_kwDOAQkWPc56dNf9", "number": 3482, "title": "TOB info needs to be updated", "user": { "login": "dret", "id": 1848612, "node_id": "MDQ6VXNlcjE4NDg2MTI=", "avatar_url": "https://avatars.githubusercontent.com/u/1848612?v=4", "gravatar_id": "", "url": "https://api.github.com/users/dret", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 3318135206, "node_id": "MDU6TGFiZWwzMzE4MTM1MjA2", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Process", "name": "Process", "color": "58BF2F", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 8, "created_at": "2023-12-22T20:17:52Z", "updated_at": "2026-02-08T17:03:50Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "The list at https://github.com/OAI/OpenAPI-Specification/blob/main/TOB.md is outdated and should be updated.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3482/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3396", "id": 1929162371, "node_id": "I_kwDOAQkWPc5y_K6D", "number": 3396, "title": "The Response object's `default` field is confusing and inconsistently interpreted", "user": { "login": "ahl", "id": 677483, "node_id": "MDQ6VXNlcjY3NzQ4Mw==", "avatar_url": "https://avatars.githubusercontent.com/u/677483?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ahl", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6500500244, "node_id": "LA_kwDOAQkWPc8AAAABg3XDFA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20globals/defaults", "name": "re-use: globals/defaults", "color": "1E431E", "default": false, "description": "Default or global components that can be overridden in some way" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 9, "created_at": "2023-10-05T22:23:10Z", "updated_at": "2024-04-24T19:51:32Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "According both 3.0 and 3.1, in the`Response` object there MUST be at least one response code and it SHOULD be the response for a successful operation call. In addition the default describes “responses other than the ones declared for specific HTTP response codes”.\r\n\r\nThis means that if we had a `200` response and `default`, the latter would cover everything except for `200`. Many seem to interpret `default` to mean something like **response categories** not covered by explicit response codes. Consider this example from the OAI org:\r\n```yaml\r\nresponses:\r\n '200':\r\n description: pet response\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/Pet'\r\n default:\r\n description: unexpected error\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/Error'\r\n```\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml\r\n\r\nThis implies that `default` covers error types when in fact it covers non-error responses as well. In fact, the consumer wouldn't necessarily know if the API **might** reply with another success code such as a `204`. A more precise example might look like this:\r\n\r\n```yaml\r\nresponses:\r\n '200':\r\n description: pet response\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/Pet'\r\n 4xx:\r\n description: unexpected error\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/Error'\r\n 5xx:\r\n description: unexpected error\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/Error'\r\n```\r\n\r\nI would suggest the following actions:\r\n1. Update the example to interpret the spec more literally\r\n2. Clarify `default` since this confusion is not limited to this example, but extends to APIs in the wild\r\n3. Consider in 3.2 or 4.0 eliminating `default`\r\n4. Consider in 3.2 or 4.0 adding a new named `error` category that means \"both 4xx and 5xx\". This could be used in the way that `default` is often misused today", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3396/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3247", "id": 1669469827, "node_id": "I_kwDOAQkWPc5jghaD", "number": 3247, "title": "Feature request: standard file that describes what openapi features are supported by an implementation", "user": { "login": "spacether", "id": 1912028, "node_id": "MDQ6VXNlcjE5MTIwMjg=", "avatar_url": "https://avatars.githubusercontent.com/u/1912028?v=4", "gravatar_id": "", "url": "https://api.github.com/users/spacether", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806281, "node_id": "MDU6TGFiZWw4MzgwNjI4MQ==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/enhancement", "name": "enhancement", "color": "a2eeef", "default": true, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 4, "created_at": "2023-04-15T16:11:07Z", "updated_at": "2024-08-17T11:17:25Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Feature request: standard file that describes what openapi features are supported by an implementation\r\n\r\nIf all implementations provided a yaml or json file of what features were supported it would allow for easier comparison of implementations.\r\n\r\nWhat if we did this with the json schema descriptions of the openapi spec:\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.0/schema.yaml\r\n\r\nAnd the json path was the feature, like:\r\n`#/servers` and the value is a boolean or a FeatureSupportInfo object like so:\r\n\r\n```\r\nFeatureSupportInfo:\r\n type: object\r\n properties:\r\n supported:\r\n type: boolean\r\n docUrl:\r\n type: string\r\n verificationTestUrl:\r\n type: string\r\n required:\r\n - supported\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3247/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3162", "id": 1584385424, "node_id": "I_kwDOAQkWPc5eb82Q", "number": 3162, "title": "Request Content-Type matching underspecified?", "user": { "login": "openreply-dleinhaeuser", "id": 27406658, "node_id": "MDQ6VXNlcjI3NDA2NjU4", "avatar_url": "https://avatars.githubusercontent.com/u/27406658?v=4", "gravatar_id": "", "url": "https://api.github.com/users/openreply-dleinhaeuser", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" }, "1": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2023-02-14T15:38:44Z", "updated_at": "2025-07-20T00:11:18Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I have not been able to find any documentation that describes with sufficient detail how the `Content-Type` header of a request is matched against the entries of the `Request Body Object`.\r\nIn particular there is not a word lost on how to handle media ranges in the `Request Body Object` that have parameters, or if parameters are even supported there.\r\nWe had to learn that different OpenAPI validator implementations can have widely diverging behavior in this area.\r\n\r\nBehaviors we have encountered include but are not limited to:\r\n- matching all specified parameters and their values with the parameters of the request content type\r\n- matching all specified parameters but not allowing extra parameters (many clients automatically add `charset`)\r\n- matching all specified parameters but also requiring the parameters to be specified in the same order as in the OpenAPI document (probably a bug)\r\n- matching all specified parameters but being strangely specific about whitespace (very likely a bug)\r\n- doing what `type-is` does (ignore parameters on request content type, break if there are parameters in the Request Body Object)\r\n- doing a simple string comparison between request `Content-Type` header and Request Body Object entry (definitely a bug)\r\n\r\nThis divergence prompted me to look up what the semantics are supposed to be, but I have been unable to find anything in the OpenAPI spec or in the commonly cited RFCs that provides clarity here.\r\n\r\nIs there a definitive way this should be implemented? Is this unspecified on purpose?\r\n\r\nI would be grateful if you could help me gain some clarity here.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3162/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3108", "id": 1513441722, "node_id": "I_kwDOAQkWPc5aNUm6", "number": 3108, "title": "Support for CBOR", "user": { "login": "cyberphone", "id": 8044211, "node_id": "MDQ6VXNlcjgwNDQyMTE=", "avatar_url": "https://avatars.githubusercontent.com/u/8044211?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cyberphone", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 10, "created_at": "2022-12-29T06:56:22Z", "updated_at": "2026-02-05T05:55:23Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I have after almost a decade with JSON, decided to use CBOR as the foundation for new designs (except for browser-based applications where the JavaScript/JSON combo still makes sense).\r\n\r\nThe rationale is here: https://github.com/cyberphone/cbor-everywhere", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3108/reactions", "total_count": 10, "+1": 6, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 3, "rocket": 0, "eyes": 1 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3015", "id": 1361062551, "node_id": "I_kwDOAQkWPc5RICqX", "number": 3015, "title": "Endpoint-level and field-level role/permission support", "user": { "login": "rlondner", "id": 16330675, "node_id": "MDQ6VXNlcjE2MzMwNjc1", "avatar_url": "https://avatars.githubusercontent.com/u/16330675?v=4", "gravatar_id": "", "url": "https://api.github.com/users/rlondner", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502392139, "node_id": "LA_kwDOAQkWPc8AAAABg5KhSw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20access%20ctrl", "name": "security: access ctrl", "color": "b20805", "default": false, "description": "Permissions and controls distinct from authentication" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 9, "created_at": "2022-09-04T06:59:03Z", "updated_at": "2025-11-24T09:09:08Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "At the company we work at, we have a need to expose APIs to different actors who have different roles and thus accesses. Essentially, some users have more or less access to the same API endpoints and on each endpoint, they may have access to some response fields or not.\r\n\r\nHowever, at this point, there is no way to include this concept of role/permission support which we would at least want to use when generating documentation (and use one single OpenAPI definition file) - of course, it would mean that documentation support that new role/permission construct, but it starts with implementing it in the spec.\r\n\r\nIs this something other folks are interested in?\r\n\r\nIdeally, this issue should be assigned the Next.Proposal label.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/3015/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2936", "id": 1254392636, "node_id": "I_kwDOAQkWPc5KxIM8", "number": 2936, "title": "Compose all component types, not just schemas", "user": { "login": "k98kurz", "id": 4357561, "node_id": "MDQ6VXNlcjQzNTc1NjE=", "avatar_url": "https://avatars.githubusercontent.com/u/4357561?v=4", "gravatar_id": "", "url": "https://api.github.com/users/k98kurz", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500266780, "node_id": "LA_kwDOAQkWPc8AAAABg3IzHA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref-group-combine", "name": "re-use: ref-group-combine", "color": "B714E4", "default": false, "description": "Re-use requests involving grouping components and combining groups" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 4, "created_at": "2022-05-31T20:37:38Z", "updated_at": "2024-01-31T17:47:31Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "The current state of affairs is that responses can be defined as components and referenced with the `\"$ref\":\"{uri}\"` syntax, but these cannot be composed using the `allOf` directive. Trying to do so results in an error. Adding sibling properties also results in an error. So there is currently no way to define a response with a general schema and then add endpoint-specific models or examples. This seems like a gross oversight and major limitation.\r\n\r\nFor example, let's say that there are multiple endpoints that return lists of models following a standard response format, but each endpoint returns different models. It would be ideal to keep the reusable format of the response in a response component and compose it with the specific model under the path definition.\r\n\r\nWithout this functionality, the only options are to have invalid documents or abandon the use of response components.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2936/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2784", "id": 1049176464, "node_id": "I_kwDOAQkWPc4-iSmQ", "number": 2784, "title": "Enhance Response cache-control header", "user": { "login": "AMorgaut", "id": 49318, "node_id": "MDQ6VXNlcjQ5MzE4", "avatar_url": "https://avatars.githubusercontent.com/u/49318?v=4", "gravatar_id": "", "url": "https://api.github.com/users/AMorgaut", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" }, "1": { "id": 6487979546, "node_id": "LA_kwDOAQkWPc8AAAABgra2Gg", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/http", "name": "http", "color": "002288", "default": false, "description": "Supporting HTTP features and interactions" }, "2": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 5, "created_at": "2021-11-09T22:20:46Z", "updated_at": "2025-09-25T16:39:58Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I have been trying to use Open API to specify the expected Cache rules for some API routes\r\n\r\nWhile defining such rules through the `Expires` and/or `Pragma` headers can be quite simple (a date for `Expires` & the `no-cache` constant for `Pragma`), they are not the modern way to do it. `Pragma` is **deprecated**, and `Expires` is **ignored** when `Cache-Control` is defined.\r\n\r\n`Cache-Control` is also nowadays supported by all clients making it the most obvious solution to define the caching rules.\r\n\r\nUnfortunately, the current OPEN API `Header Object` support looks a bit limited for `Cache-Control`. Using pure JSON Schema definition might produce unexpected behavior without dedicated context for this header or for headers having similar Design.\r\n\r\nThis header value is defined as a comma-seperated list of properties called `directives`\r\nIf all directives were simple strings I could write something like that if I allowed any of them (or restrict to the on I accept by design)\r\n```yaml\r\n responses:\r\n 200:\r\n description: \"The request was successfully treated.\"\r\n headers:\r\n Cache-Control: \r\n schema:\r\n type: array\r\n items:\r\n type: string\r\n enum:\r\n - public\r\n - private\r\n - no-cache\r\n - no-store\r\n - must-revalidate\r\n - proxy-revalidate\r\n - immutable\r\n - no-transform\r\n - only-if-cached\r\n``` \r\n\r\nIf I want my route to prevent response to be cached I can easily design it a more simple way\r\n```yaml\r\n Cache-Control: \r\n schema:\r\n type: string\r\n enum:\r\n - no-store\r\n``` \r\nOr with the last JSON-Schema edition support of constants\r\n```yaml\r\n Cache-Control: \r\n schema:\r\n const: \"no-store\"\r\n``` \r\n\r\nBut some of the most important cache control properties are key value pairs like `max-age=300` \r\n\r\nI tried to express it the most reiable still simple way using adavanced JSON Schema feature unfortunately not really well supported (yet?) by Open API implementations\r\n\r\n## Sample 1\r\n\r\n- Pro: \r\n - shortest\r\n- Cons: \r\n - forbid different property order\r\n - forbid potentially acceptable other cache-control properties\r\n - not really the most inspectable \r\n```yaml\r\n Cache-Control: \r\n schema:\r\n const: \"public, max-age=300\"\r\n``` \r\n \r\n## Sample 2\r\n\r\n- Pro: \r\n - still short\r\n- Cons: \r\n - ⚠️❌ the specification doesn't say how to serialize the object \r\n```yaml\r\n Cache-Control: \r\n schema:\r\n const: [\"public\", {\"max-age\": 300}]\r\n``` \r\n\r\n## Sample 3\r\n\r\n- Pro: \r\n - explicit, no need for const support\r\n- Cons: \r\n - very verbose\r\n - pretty sure enum not well supported for numbers\r\n - ⚠️❌ the specification still doesn't say how to serialize the object \r\n \r\n```yaml\r\n Cache-Control: \r\n schema:\r\n type: array\r\n items:\r\n allOf:\r\n - type: string\r\n enum:\r\n - public\r\n - type: object\r\n properties:\r\n max-age:\r\n type: number\r\n enum:\r\n - 300\r\n required:\r\n - max-age\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2784/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2720", "id": 1003853463, "node_id": "I_kwDOAQkWPc471ZaX", "number": 2720, "title": "Allow definition of immutable values in Schema Object", "user": { "login": "fabiohecht", "id": 1263195, "node_id": "MDQ6VXNlcjEyNjMxOTU=", "avatar_url": "https://avatars.githubusercontent.com/u/1263195?v=4", "gravatar_id": "", "url": "https://api.github.com/users/fabiohecht", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861892491, "node_id": "MDU6TGFiZWw4NjE4OTI0OTE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/schema-object", "name": "schema-object", "color": "94d33b", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 16, "created_at": "2021-09-22T06:05:09Z", "updated_at": "2025-09-13T17:00:36Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I've come across the requirement of defining an _immutable_ field, that is, one that can only be set when the resource is created (POST). The field is not allowed to be modified, therefore it may not be changed via PUT/PATCH. This would be somewhat similar to writeOnly, but with an extra constraint that the field may only be written once, at creation.\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2720/reactions", "total_count": 7, "+1": 6, "-1": 1, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2697", "id": 987674892, "node_id": "MDU6SXNzdWU5ODc2NzQ4OTI=", "number": 2697, "title": "allowing $ref in descriptions", "user": { "login": "manasesjesus", "id": 24204142, "node_id": "MDQ6VXNlcjI0MjA0MTQy", "avatar_url": "https://avatars.githubusercontent.com/u/24204142?v=4", "gravatar_id": "", "url": "https://api.github.com/users/manasesjesus", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500261740, "node_id": "LA_kwDOAQkWPc8AAAABg3IfbA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref-everywhere", "name": "re-use: ref-everywhere", "color": "fef2c0", "default": false, "description": "Requests to support referencing in more / all places" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 10, "created_at": "2021-09-03T11:25:34Z", "updated_at": "2025-01-14T21:19:26Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Some descriptions can be long or very long. Allowing $ref would be useful to reference an external file with only text, e.g. markdown. It'd be great if **info.description** and **tags.name/description** could use it (without IDE validation errors).", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2697/reactions", "total_count": 12, "+1": 12, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2610", "id": 912828598, "node_id": "MDU6SXNzdWU5MTI4Mjg1OTg=", "number": 2610, "title": "[Request] Define parameters in Example Object", "user": { "login": "takuyahara", "id": 46240835, "node_id": "MDQ6VXNlcjQ2MjQwODM1", "avatar_url": "https://avatars.githubusercontent.com/u/46240835?v=4", "gravatar_id": "", "url": "https://api.github.com/users/takuyahara", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806281, "node_id": "MDU6TGFiZWw4MzgwNjI4MQ==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/enhancement", "name": "enhancement", "color": "a2eeef", "default": true, "description": "" }, "1": { "id": 6488251340, "node_id": "LA_kwDOAQkWPc8AAAABgrrbzA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/example%20obj/keywords", "name": "example obj/keywords", "color": "A08F3C", "default": false, "description": "Issues with the Example Object or exampel(s) keywords" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 3, "created_at": "2021-06-06T13:26:44Z", "updated_at": "2024-04-25T18:06:54Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Just shortly, I would like to request a capability to define parameters in Example Object to associate each parameters passed and response received.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2610/reactions", "total_count": 3, "+1": 3, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2564", "id": 875501619, "node_id": "MDU6SXNzdWU4NzU1MDE2MTk=", "number": 2564, "title": "Are these OpenAPI 3 paths ambiguous?", "user": { "login": "bfreuden", "id": 5137152, "node_id": "MDQ6VXNlcjUxMzcxNTI=", "avatar_url": "https://avatars.githubusercontent.com/u/5137152?v=4", "gravatar_id": "", "url": "https://api.github.com/users/bfreuden", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806283, "node_id": "MDU6TGFiZWw4MzgwNjI4Mw==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/question", "name": "question", "color": "cc317c", "default": true, "description": null }, "1": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "2": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 7, "created_at": "2021-05-04T14:09:01Z", "updated_at": "2024-04-25T18:04:41Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "As suggested by @MikeRalphson on [Stackoverflow](https://stackoverflow.com/questions/67382759/are-those-openapi-3-paths-ambiguous), I'm asking the question here as well.\r\n\r\n**Are those OpenAPI 3 paths ambiguous?**\r\n\r\n /shops/{shopId}/pets/{petId} \r\n /shops/{shopId}/pets/_search\r\n\r\nI want to answer **no** but, strictly reading the spec, I can't decide because they seem to fall into none of the 3 statements made by the spec:\r\n\r\n1. Neither path is _concrete_ (term used in the spec)\r\n2. Paths don't seem to meet the _Templated paths with the same hierarchy but different templated names_ criteria (that is not very clear to me, here is my understanding: `\"/shops/{}/pets/{}\" != \"/shops/{}/pets/_search\"`)\r\n3. Paths do not look like the _ambiguous_ example\r\n\r\nIn addition to the question asked on Stackoverflow, let me ask two additional questions (below).\r\n\r\n**Should the OA3 spec be improved?**\r\n\r\n@MikeRalphson's reading of the spec: path are not ambiguous because one is _more concrete_ than the other.\r\n\r\nIf paths are indeed not ambiguous, then the _more concrete_ notion might need to be defined.\r\n\r\n**How could the OA3 spec be improved?**\r\n\r\nWe might add an example like this:\r\n\r\n>Assuming paths sharing a **common** and **identical** prefix, ``/shops/{shopId}/pets``, the _more concrete_ definition, ``/shops/{shopId}/pets/_search``, will be matched first if used:\r\n> \r\n> /shops/{shopId}/pets/{petId}\r\n> /shops/{shopId}/pets/_search\r\n> \r\n\r\nOr we might only show **minimalistic** examples involving templated names, and say that they also apply in case of **common** and **identical** prefixes:\r\n\r\nFirst statement (concrete vs template case):\r\n> /{otherPlace}\r\n> /here\r\n\r\nSecond statement (considered identical and invalid):\r\n> /{id}\r\n> /{name}\r\n\r\nThird statement is left unchanged (ambiguous resolution): \r\n> /{entity}/me\r\n> /books/{id}\r\n\r\n**Related excerpt of the OA3 spec**\r\n\r\nThe \"Paths object\" paragraph of the OpenAPI 3 specification (https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#paths-object) is stating (3 sentences, 3 statements):\r\n\r\n> When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.\r\n\r\nThose 3 statements are followed by 3 examples (and that's it):\r\n\r\n>Assuming the following paths, the concrete definition, ``/pets/mine``, will be matched first if used:\r\n> \r\n> /pets/{petId}\r\n> /pets/mine\r\n> \r\n>The following paths are considered identical and invalid:\r\n> \r\n> /pets/{petId}\r\n> /pets/{name}\r\n> \r\n>The following may lead to ambiguous resolution:\r\n> \r\n> /{entity}/me\r\n> /books/{id}\r\n\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2564/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2542", "id": 858929267, "node_id": "MDU6SXNzdWU4NTg5MjkyNjc=", "number": 2542, "title": "OpenAPI vocabulary or dialect for code generation ", "user": { "login": "mkistler", "id": 800728, "node_id": "MDQ6VXNlcjgwMDcyOA==", "avatar_url": "https://avatars.githubusercontent.com/u/800728?v=4", "gravatar_id": "", "url": "https://api.github.com/users/mkistler", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861892491, "node_id": "MDU6TGFiZWw4NjE4OTI0OTE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/schema-object", "name": "schema-object", "color": "94d33b", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 12, "created_at": "2021-04-15T14:19:15Z", "updated_at": "2024-01-28T20:25:23Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Code generation tools often have special requirements or restrictions on the structure of an OpenAPI definition (document?) that improve the generated code. Here are some examples of restrictions from the IBM OpenAPI SDK generator:\r\n\r\n- Parameters must be unique by name only, irrespective of \"in\".\r\n\r\n **Rationale**: Operation parameters are often rendered as the parameters on a function or method in the target language of the code generator. Since most languages require parameters to have unique names, the code generator would need to incorporate the `in` of a parameter into its name to prevent name collisions. This is undesirable, since it exposes the mechanics of the API without adding any value.\r\n\r\n- There should be at most one success response with a response body. A 204 and other 2XX is okay, but no other combination of two or more 2XX responses.\r\n\r\n **Rationale**: In statically-typed languages like Java, the return value of a method must have a single static type. This makes it difficult to represent an operation with two different response schemas as a single method returning a single response type.\r\n\r\n- Property names and parameter names must be \"case-insensitive\" unique\r\n\r\n **Rationale**: Code generators often reformat the names of parameters, properties, and schemas to use idomatic case formatting for the target language: lower_snake_case for Python, lowerCamelCase for Java, etc. But this reformatting could introduce naming conflicts if two parameters, e.g. \"foo_bar\" and \"fooBar\" are not \"case-insensitive\" unique.\r\n\r\n- Arrays must contain items of a single type\r\n\r\n **Rationale**: Many languages require an array to contain only values of a single type.\r\n\r\n- Schema type must specify a single type -- no type arrays\r\n\r\n **Rationale**: Some widely-used statically-typed languages, e.g. Java and Go) have no provision for \"union\" types, making it impossible to define a `type: [ integer, string ]` typed property or parameter.\r\n\r\n- Don't use \"nullable\"\r\n\r\n **Rationale**: it's deprecated, and is just an alternate way of expressing type arrays\r\n\r\n- Don't use JSON schema \"not\"\r\n\r\n **Rationale** There's no obvious way to represent this in many widely used programming languages.\r\n\r\n- No \"if-then-else\" in JSON schema\r\n\r\n **Rationale** There's no obvious way to represent this in many widely used programming languages.\r\n\r\n- The API document should be \"self contained\" (no external \"$refs\")\r\n\r\n **Rationale**: External refs can easily create multiple namespaces for schemas, parameters, security schemes, etc. These are unnecessary complications for code generators.\r\n\r\n- All \"$refs\" must be to elements in the \"components\" section of the document\r\n\r\n **Rationale**: \"$ref\" targets outside of \"components\" are unnecessary complications for code generators.\r\n\r\n\r\nIt would be nice to have a common set of rules like this that could be codified into a \"Code generation\" vocabulary or dialect for OpenAPI.\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2542/reactions", "total_count": 6, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 3, "rocket": 0, "eyes": 3 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2530", "id": 854540163, "node_id": "MDU6SXNzdWU4NTQ1NDAxNjM=", "number": 2530, "title": "Clarification required for templated paths with same hierarchy but different templated names and methods", "user": { "login": "Jmcleodfoss", "id": 55663604, "node_id": "MDQ6VXNlcjU1NjYzNjA0", "avatar_url": "https://avatars.githubusercontent.com/u/55663604?v=4", "gravatar_id": "", "url": "https://api.github.com/users/Jmcleodfoss", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 1, "created_at": "2021-04-09T13:45:00Z", "updated_at": "2024-04-20T23:15:00Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "This is alluded to by @kapone89 in [Issue 2015](https://github.com/OAI/OpenAPI-Specification/issues/2015#issuecomment-536460869) but I believe it warrants an issue of its own to get clarification.\r\n\r\n[The spec states clearly](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#patterned-fields) that \"Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.\"\r\n\r\nBut what it there are there are two templated paths which differ by templated names and also HTTP methods? There is no ambiguity between them, as long as there is only a single path for each method, so I can't see any justification for disallowing this; the example provided by in [Issue 2015](https://github.com/OAI/OpenAPI-Specification/issues/2015#issuecomment-536460869) is:\r\n```\r\nGET /pets/{petId}\r\nDELETE /pets/{name}\r\n```\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2530/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2498", "id": 827928209, "node_id": "MDU6SXNzdWU4Mjc5MjgyMDk=", "number": 2498, "title": "Allow required as sibling of $ref (like summary/description)", "user": { "login": "radicarl", "id": 1108495, "node_id": "MDQ6VXNlcjExMDg0OTU=", "avatar_url": "https://avatars.githubusercontent.com/u/1108495?v=4", "gravatar_id": "", "url": "https://api.github.com/users/radicarl", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" }, "1": { "id": 6500484517, "node_id": "LA_kwDOAQkWPc8AAAABg3WFpQ", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20traits/merges", "name": "re-use: traits/merges", "color": "D99F0B", "default": false, "description": "Selective or modified re-use" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 5, "created_at": "2021-03-10T15:38:19Z", "updated_at": "2025-09-20T16:00:13Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hello,\r\n\r\nit would be great for reusability if I could overwrite the `required` field of parameter and header objects, like I can overwrite`summary` and `description` in OpenAPI 3.1.\r\n\r\n```yaml\r\npaths:\r\n /my-resource:\r\n parameters:\r\n - $ref: '#/components/parameters/Accept'\r\n required: true\r\n get:\r\n # some definition\r\n\r\ncomponents:\r\n parameters:\r\n Accept:\r\n name: Accept\r\n in: header\r\n required: false\r\n schema:\r\n type: string\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2498/reactions", "total_count": 19, "+1": 19, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2458", "id": 807384489, "node_id": "MDU6SXNzdWU4MDczODQ0ODk=", "number": 2458, "title": "How to state parameter requirements in HTTP headers?", "user": { "login": "lmmarsano", "id": 8139324, "node_id": "MDQ6VXNlcjgxMzkzMjQ=", "avatar_url": "https://avatars.githubusercontent.com/u/8139324?v=4", "gravatar_id": "", "url": "https://api.github.com/users/lmmarsano", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" }, "1": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 9, "created_at": "2021-02-12T16:51:17Z", "updated_at": "2024-11-21T18:17:38Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "For example, as [described in the guide](https://swagger.io/docs/specification/describing-request-body/multipart-requests/), in a request such as\r\n```http\r\nPOST /upload HTTP/1.1\r\nContent-Length: 428\r\nContent-Type: multipart/form-data; boundary=abcde12345\r\n--abcde12345\r\nContent-Disposition: form-data; name=\"profileImage\"; filename=\"image1.png\"\r\nContent-Type: application/octet-stream\r\n{…file content…}\r\n--abcde12345--\r\n```\r\nhow would a spec state that the `filename` parameter in header `Content-Disposition` is required and explain special usage in a description?\r\n[RFCs state that the filename parameter is optional.](https://tools.ietf.org/html/rfc7578#section-4.2)\r\nIt's not clear how to express parameters for a [header object](https://swagger.io/specification/#header-object).", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2458/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2454", "id": 797581323, "node_id": "MDU6SXNzdWU3OTc1ODEzMjM=", "number": 2454, "title": "`primaryData` attribute in Media Type Object", "user": { "login": "K-Adam", "id": 9156245, "node_id": "MDQ6VXNlcjkxNTYyNDU=", "avatar_url": "https://avatars.githubusercontent.com/u/9156245?v=4", "gravatar_id": "", "url": "https://api.github.com/users/K-Adam", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 4, "created_at": "2021-01-30T23:51:58Z", "updated_at": "2026-01-29T17:56:31Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "[Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#mediaTypeObject) should have an optional `primaryData` attribute, to specify the name of the property, where the primary data is located in the schema.\r\n\r\nIt is very common to return the response object wrapped in a top level property. This way, it is possible to provide additional metadata as well. Example:\r\n\r\n```yaml\r\nresponses:\r\n '200':\r\n description: successful operation\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n data:\r\n $ref: '#/components/schemas/User'\r\n meta:\r\n $ref: '#/components/schemas/Metadata'\r\n required: ['data']\r\n primaryData: data\r\n```\r\n\r\nThe OpenApi tools could better understand these type of responses. It would be possible to express, that the `data` attribute is not really part of any schemas/objects. It is just a wrapper.\r\n\r\nThe [SDK Generators](https://openapi.tools/#sdk) could benefit from this `primaryData` attribute as well. At the moment, these kind of responses usually have to be manually unwrapped.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2454/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2419", "id": 757044299, "node_id": "MDU6SXNzdWU3NTcwNDQyOTk=", "number": 2419, "title": "security scheme apiKey in body form data parameter", "user": { "login": "johakoch", "id": 53434855, "node_id": "MDQ6VXNlcjUzNDM0ODU1", "avatar_url": "https://avatars.githubusercontent.com/u/53434855?v=4", "gravatar_id": "", "url": "https://api.github.com/users/johakoch", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 11, "created_at": "2020-12-04T11:53:28Z", "updated_at": "2025-05-24T07:52:48Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "It is possible to define a security scheme as\r\n```\r\nQueryKey:\r\n type: apiKey\r\n in: query\r\n name: myparam\r\n```\r\ncorresponding to\r\n```\r\nparameters:\r\n - name: myparam\r\n in: query\r\n required: true\r\n```\r\nwhile the first approach adds the notion that the required parameter is related to security.\r\n\r\n\r\nHowever there seems to be no way to define a security scheme about a required parameter in an `application/x-www-form-urlencoded` body adding the same security notion.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2419/reactions", "total_count": 5, "+1": 5, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2417", "id": 756652355, "node_id": "MDU6SXNzdWU3NTY2NTIzNTU=", "number": 2417, "title": "JSON Schema path pattern", "user": { "login": "kstasik", "id": 676617, "node_id": "MDQ6VXNlcjY3NjYxNw==", "avatar_url": "https://avatars.githubusercontent.com/u/676617?v=4", "gravatar_id": "", "url": "https://api.github.com/users/kstasik", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 4, "created_at": "2020-12-03T22:47:18Z", "updated_at": "2024-01-28T02:07:27Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Can you explain why there is an escape character before **/** in json schema of openapi specification?\r\n\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.json#L793\r\n\r\nI tried to find a reason why it's there in https://json-schema.org/understanding-json-schema/reference/regular_expressions.html and https://www.ecma-international.org/publications/standards/Ecma-262.htm but i'm still not sure about it. I didn't find any explanation in specs.\r\n\r\nIMO this regexp is invalid, it only works in most of libraries because javascript automatically fixes invalid usages of escape character.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2417/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2409", "id": 742314425, "node_id": "MDU6SXNzdWU3NDIzMTQ0MjU=", "number": 2409, "title": "Add support for \"changelog\" in the \"info\" object", "user": { "login": "aedart", "id": 1523223, "node_id": "MDQ6VXNlcjE1MjMyMjM=", "avatar_url": "https://avatars.githubusercontent.com/u/1523223?v=4", "gravatar_id": "", "url": "https://api.github.com/users/aedart", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 7, "created_at": "2020-11-13T09:43:42Z", "updated_at": "2024-11-21T21:26:35Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "When maintaining an API specification, it would be really nice to offer a changelog for the API consumer. This can be as simple as a link to a changelog.\r\n\r\n## Possible Solution\r\nThe `info` object seems to be the most suitable place that such a parameter could be located (_as an optional parameter_).\r\nExample:\r\n```yaml\r\ninfo:\r\n version: 1.1.0\r\n title: My API Specification\r\n changelog: https://acme.com/docs/api/v1/changelog.md\r\n```\r\n\r\nNb: I know that this is currently possible via `x-` extension, yet not all tools seem to accept extensions.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2409/reactions", "total_count": 5, "+1": 5, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2400", "id": 736353495, "node_id": "MDU6SXNzdWU3MzYzNTM0OTU=", "number": 2400, "title": "npm package not published?", "user": { "login": "ahmadnassri", "id": 183195, "node_id": "MDQ6VXNlcjE4MzE5NQ==", "avatar_url": "https://avatars.githubusercontent.com/u/183195?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ahmadnassri", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 200699361, "node_id": "MDU6TGFiZWwyMDA2OTkzNjE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Schema", "name": "Schema", "color": "bfe5bf", "default": false, "description": "changes related to the schema(s)" }, "1": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 5, "created_at": "2020-11-04T19:03:00Z", "updated_at": "2026-01-08T17:46:23Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "there is a `package.json` with a package name: `oas-schemas` but this package doesn't exist in `npmjs.com` ...", "closed_by": { "login": "ahmadnassri", "id": 183195, "node_id": "MDQ6VXNlcjE4MzE5NQ==", "avatar_url": "https://avatars.githubusercontent.com/u/183195?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ahmadnassri", "type": "User", "user_view_type": "public", "site_admin": false }, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2400/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2398", "id": 735814144, "node_id": "MDU6SXNzdWU3MzU4MTQxNDQ=", "number": 2398, "title": "Add support OpenID Connect Hybrid Flow", "user": { "login": "Yuutakasan", "id": 1161494, "node_id": "MDQ6VXNlcjExNjE0OTQ=", "avatar_url": "https://avatars.githubusercontent.com/u/1161494?v=4", "gravatar_id": "", "url": "https://api.github.com/users/Yuutakasan", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 0, "created_at": "2020-11-04T05:05:31Z", "updated_at": "2024-08-08T12:19:29Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Can you use OAuth Flows Object to support OpenID connect hybrid flow?\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#oauthFlowObject\r\n\r\nPreventing Mix-Up Attacks with OpenID Connect\r\nhttps://openid.net/2016/07/16/preventing-mix-up-attacks-with-openid-connect/", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2398/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2356", "id": 705418317, "node_id": "MDU6SXNzdWU3MDU0MTgzMTc=", "number": 2356, "title": "Ordering of matches when no path is concrete", "user": { "login": "JonnySpruce", "id": 30812276, "node_id": "MDQ6VXNlcjMwODEyMjc2", "avatar_url": "https://avatars.githubusercontent.com/u/30812276?v=4", "gravatar_id": "", "url": "https://api.github.com/users/JonnySpruce", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 5, "created_at": "2020-09-21T09:04:36Z", "updated_at": "2024-04-25T18:07:41Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I'm a contributor for an OpenAPI Validator project, and one of our users has raised an issue that their the spec is not matching in the order they would expect (you can see the issue [here](https://github.com/RuntimeTools/OpenAPIValidators/issues/164)). \r\n\r\nThe issue effectively boils down to the user expecting a path with just one templated segment to be matched over a path with more than one templated segment, i.e.:\r\n```\r\n/{id1}/{id2}/{id3}\r\n/resource/{id}/new <- Expect this one to be picked\r\n```\r\nWith a request path like: `/resource/1/new`.\r\n\r\nCurrently we are matching simply based on the order of the paths as defined by the user in their specification file (which is probably not the correct approach). My question is whether it is specified anywhere how to resolve/match multiple templated matches?\r\n\r\nLooking at the [relevant part of the OpenAPI3 spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#patterned-fields), while it discusses preferring a concrete path over a path which uses templates, from the spec I couldn't see how paths would be chosen if both match the request, and both use templates in the path. Since the examples in the spec are fairly short, I wasn't sure if the above example would fall into the ambiguous category or not.\r\n\r\nI did manage to find a discussion in your issues [here](https://github.com/OAI/OpenAPI-Specification/issues/1459#issuecomment-359017334) which hints at the fact most people would match a path with more concrete segments, over one with less. Since we are a validation tool, I would prefer to be able to apply concrete rules.\r\n\r\nDo you have any advice/further reading on matching paths like the above example?", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2356/reactions", "total_count": 6, "+1": 6, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2347", "id": 699200850, "node_id": "MDU6SXNzdWU2OTkyMDA4NTA=", "number": 2347, "title": "Supporting of one separate 'required' option for query parameters", "user": { "login": "Morgunov-Vitaly", "id": 19765202, "node_id": "MDQ6VXNlcjE5NzY1MjAy", "avatar_url": "https://avatars.githubusercontent.com/u/19765202?v=4", "gravatar_id": "", "url": "https://api.github.com/users/Morgunov-Vitaly", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" }, "1": { "id": 6500484517, "node_id": "LA_kwDOAQkWPc8AAAABg3WFpQ", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20traits/merges", "name": "re-use: traits/merges", "color": "D99F0B", "default": false, "description": "Selective or modified re-use" }, "2": { "id": 6500500244, "node_id": "LA_kwDOAQkWPc8AAAABg3XDFA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20globals/defaults", "name": "re-use: globals/defaults", "color": "1E431E", "default": false, "description": "Default or global components that can be overridden in some way" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 2, "created_at": "2020-09-11T11:30:44Z", "updated_at": "2025-07-31T19:10:05Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi!\r\nFor example, there are several paths that include similar parameters, but with different required options: in some paths parameters are required, in others they are optional.\r\n\r\nIf we can specify the required option separately, we can reuse parameter descriptions. Like this:\r\n\r\n```yaml\r\n/api/v1/rootname:\r\n get:\r\n summary: 'Path example'\r\n parameters:\r\n - $ref: '#/components/parameters/queryFiltersDateFrom'\r\n - $ref: '#/components/parameters/queryFiltersDateTo'\r\n - $ref: '#/components/parameters/queryGroups'\r\n - $ref: '#/components/parameters/queryOrderByColumn'\r\n - $ref: '#/components/parameters/queryOrderByDirection'\r\n required:\r\n - 'filters[date_from]'\r\n - 'filters[date_to]'\r\n - 'groups'\r\n - 'order_by_column'\r\n - 'order_by_direction'\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2347/reactions", "total_count": 2, "+1": 2, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2342", "id": 694475862, "node_id": "MDU6SXNzdWU2OTQ0NzU4NjI=", "number": 2342, "title": "Parameters for Media Types", "user": { "login": "cjaccino", "id": 31144642, "node_id": "MDQ6VXNlcjMxMTQ0NjQy", "avatar_url": "https://avatars.githubusercontent.com/u/31144642?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cjaccino", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" }, "1": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." }, "2": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 19, "created_at": "2020-09-06T18:16:54Z", "updated_at": "2025-09-25T22:43:32Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "### Parameters for Media Types\r\n\r\nMedia Types can support parameters. Yet, to work with them in OpenAPI, one must define them statically against each media type. This has the unfortunate side effect of discouraging use of media type parameters by making them clumsy to manage within the API spec. \r\n\r\n```\r\ncontent:\r\n text/plain; charset=utf-8:\r\n ...\r\n text/plain; charset=iso-8859-1:\r\n ...\r\n```\r\n\r\nWithout a way to express the parameter, it has little or no semantic value for OpenAPI. Minor variations look like completely different media types. There is little room for negotiation over content parameters unless the API author takes the time to spell out each supported parameter as its own type.\r\n\r\nMedia Type parameters could be useful in some obvious ways:\r\n - versioning of the media type\r\n - specifying a 'profile' for the media type as described in RFC6906\r\n - negotiating support for embedded resources (i.e. HAL (https://tools.ietf.org/html/draft-kelly-json-hal-08)) , hypermedia style, or level of completeness of a representation.\r\n\r\nPrivate and vendor media types might better manage breaking changes by supporting multiple versions of representation without ever changing endpoints and methods. Perhaps there could be benefits to QA and regression test tooling, being able to validate support for the diversity of representation styles in the API contract. This could be had without having to iterate every parameter combination as a separate media type.\r\n\r\n### Examples\r\n**Versioning**\r\n```\r\nAccept: application/vnd.example-schema+json; version=1.0.4\r\n```\r\n\r\n```\r\ncontent:\r\n application/vnd.example-schema+json:\r\n parameters:\r\n version:\r\n type: string\r\n required: false\r\n description: |\r\n The version of the representation.\r\n default: 1.1.0\r\n enum:\r\n - 1.0.3\r\n - 1.0.4\r\n - 1.1.0\r\n schema:\r\n \t$ref: \"https://schemas.example.com/example\"\r\n```\r\n\r\n**Profile identification**\r\n```\r\nAccept: application/vnd.example-schema+json; profile=https://schemas.example.com/example/profiles/bob\r\n```\r\n\r\n```\r\ncontent:\r\n application/vnd.example-schema+json:\r\n parameters:\r\n profile:\r\n type: string\r\n required: false\r\n description: |\r\n The profile (rfc6906) for the representation.\r\n default: \"https://schemas.example.com/example/profiles/alice\"\r\n enum:\r\n - \"https://schemas.example.com/example/profiles/alice\"\r\n - \"https://schemas.example.com/example/profiles/bob\"\r\n schema:\r\n \t$ref: \"https://schemas.example.com/example\"\r\n```\r\n\r\n**Hypermedia style selection**\r\n```\r\nAccept: application/vnd.example-schema+json; hypermedia=HAL\r\n```\r\n```\r\ncontent: \r\n application/vnd.example-schema+json:\r\n parameters:\r\n hypermedia:\r\n type: string\r\n required: false\r\n description: |\r\n Hypermedia Style. Indicates whether links and other supplemental\r\n resource detail are provided in the representation.\r\n default: JSON_HYPERSCHEMA\r\n enum:\r\n hypermedia:\r\n - NONE\r\n - HAL\r\n - JSON_HYPERSCHEMA\r\n schema:\r\n \t$ref: \"https://schemas.example.com/example\"\r\n```\r\n\r\n**_Added after the original issue report_** \r\nI am inspired by what I read on Roy Fielding's blog entry \"[REST APIs must be Hypertext Driven](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven)\".\r\n\r\n> \"A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). _[Failure here implies that out-of-band information is driving interaction instead of hypertext.]_\"\r\n\r\nIf I understand him correctly, enriching OpenAPI's ability to semantically express media type parameters would improve its ability to convey the kinds of interactions Mr. Fielding expected to be inherent in the resource or resource representation, rather than in other parts of the HTTP message. Conversely, not supporting media type parameters might limit OpenAPI's ability to articulate a nuanced RESTful concept.\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2342/reactions", "total_count": 13, "+1": 9, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 4, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2322", "id": 683110144, "node_id": "MDU6SXNzdWU2ODMxMTAxNDQ=", "number": 2322, "title": "Auth URL Variables", "user": { "login": "michaelmerrill", "id": 8688257, "node_id": "MDQ6VXNlcjg2ODgyNTc=", "avatar_url": "https://avatars.githubusercontent.com/u/8688257?v=4", "gravatar_id": "", "url": "https://api.github.com/users/michaelmerrill", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502448849, "node_id": "LA_kwDOAQkWPc8AAAABg5N-0Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20config", "name": "security: config", "color": "b20805", "default": false, "description": "The mechanics of severs and structure of security-related objects" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2020-08-20T21:34:14Z", "updated_at": "2024-04-18T20:03:14Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Currently we can set the server variables for different environments like so:\r\n\r\n```(yaml)\r\nservers:\r\n - url: 'https://{environment}.example.com/v1'\r\n variables:\r\n environment:\r\n default: api\r\n enum:\r\n - api\r\n - sandbox.api\r\n - development.api\r\n - staging.api\r\n```\r\n\r\nIs it possible to also set variables for the authorization code urls? Normally you'd want to match these environments when authenticating. I'd imagine it would look something like this:\r\n\r\n```(yaml)\r\nsecuritySchemes:\r\n OAuth2:\r\n type: oauth2\r\n flows:\r\n authorizationCode:\r\n authorizationUrl: \r\n - url: 'https://{environment}.example.com/authorize'\r\n variables:\r\n environment:\r\n default: accounts\r\n enum:\r\n - accounts\r\n - sandbox.accounts\r\n - development.accounts\r\n - staging.accounts\r\n tokenUrl: \r\n - url: 'https://{environment}.example.com/token'\r\n variables:\r\n environment:\r\n default: accounts\r\n enum:\r\n - accounts\r\n - sandbox.accounts\r\n - development.accounts\r\n - staging.accounts\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2322/reactions", "total_count": 7, "+1": 7, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2313", "id": 678242504, "node_id": "MDU6SXNzdWU2NzgyNDI1MDQ=", "number": 2313, "title": "Indicate that parameterObject has dynamic enum ?", "user": { "login": "IOR88", "id": 9704409, "node_id": "MDQ6VXNlcjk3MDQ0MDk=", "avatar_url": "https://avatars.githubusercontent.com/u/9704409?v=4", "gravatar_id": "", "url": "https://api.github.com/users/IOR88", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861892491, "node_id": "MDU6TGFiZWw4NjE4OTI0OTE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/schema-object", "name": "schema-object", "color": "94d33b", "default": false, "description": "" }, "1": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2020-08-13T08:10:03Z", "updated_at": "2024-01-29T18:39:17Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I try to have a parameter, which enum values has to be requested from different endpoint. So I haven't found any way how I could do it in specification. I though about 2 ways or I indicate that enum is dynamic with additionalProperties or I use $ref as value for enum attribute but not sure if this will be with accordance to specification ?\r\n\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject\r\n\r\n```json\r\n{\r\n \"in\": \"query\",\r\n \"name\": \"name\",\r\n \"$ref\" : \"#/paths/enums/name\",\r\n \"schema\": {\r\n \"type\": \"object\",\r\n \"additionalProperties\": {\r\n \"dynamicEnum\": \"bool\"\r\n },\r\n \"enum\": {\"$ref\" : \"#/paths/enums/name\"}\r\n }\r\n}\r\n```\r\n\r\nAny thoughts ?", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2313/reactions", "total_count": 2, "+1": 2, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2296", "id": 665728490, "node_id": "MDU6SXNzdWU2NjU3Mjg0OTA=", "number": 2296, "title": "Use wildcard or regex in cookie name in Cookie Authentication", "user": { "login": "lauradP", "id": 25053643, "node_id": "MDQ6VXNlcjI1MDUzNjQz", "avatar_url": "https://avatars.githubusercontent.com/u/25053643?v=4", "gravatar_id": "", "url": "https://api.github.com/users/lauradP", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" }, "2": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" }, "3": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 2, "created_at": "2020-07-26T07:38:05Z", "updated_at": "2024-11-21T21:41:06Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi,\r\nI need to use Cookie Authentication for my APIs, but the authentication cookie name's in my app changes every time you log in (only the cookie name prefix is known: _shibsession_).\r\n\r\nI was looking for a way to specify cookies name pattern instead of the exact name. Is there such a feature? ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2296/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2284", "id": 654876520, "node_id": "MDU6SXNzdWU2NTQ4NzY1MjA=", "number": 2284, "title": "Security Schemes for different environments", "user": { "login": "aowss", "id": 6297886, "node_id": "MDQ6VXNlcjYyOTc4ODY=", "avatar_url": "https://avatars.githubusercontent.com/u/6297886?v=4", "gravatar_id": "", "url": "https://api.github.com/users/aowss", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2020-07-10T15:54:41Z", "updated_at": "2025-10-30T02:21:35Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi,\r\n\r\nat the moment, if we use a relative URL in openIdConnectUrl, it uses the URLs defined in servers. But these URLs are usually the URLs of the API or API Gateway. The OpenId Server URLs are usually different.\r\n\r\nThanks", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2284/reactions", "total_count": 4, "+1": 4, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2248", "id": 627945399, "node_id": "MDU6SXNzdWU2Mjc5NDUzOTk=", "number": 2248, "title": "[Announcement] OAuth2.1 and OAuth3 drafts", "user": { "login": "ybelenko", "id": 5541023, "node_id": "MDQ6VXNlcjU1NDEwMjM=", "avatar_url": "https://avatars.githubusercontent.com/u/5541023?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ybelenko", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" }, "2": { "id": 9550827670, "node_id": "LA_kwDOAQkWPc8AAAACOUYQlg", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/ai%20/%20llms", "name": "ai / llms", "color": "888888", "default": false, "description": "Issues related to AI (LLM) use cases" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 11, "created_at": "2020-05-31T11:36:40Z", "updated_at": "2025-10-29T21:58:03Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "OAuth2.1 and OAuth3 drafts has been announced.\r\n\r\n## [OAuth 2.1](https://oauth.net/2.1/):\r\n- [RFC6749 - OAuth 2.0 Core](https://tools.ietf.org/html/rfc6749)\r\n- [RFC6750 - Bearer token usage](https://tools.ietf.org/html/rfc6750)\r\n- [RFC7636 - PKCE](https://tools.ietf.org/html/rfc7636)\r\n- Native App & Browser-Based App BCPs(best current practices)\r\n- Security BCP(best current practice):\r\n - MUST support PKCE for all client types\r\n - No password grant\r\n - No implicit flow\r\n - Exact string matching for redirect URIs\r\n - No access tokens in query string\r\n - Refresh tokens must be sender-constrained or one-time use\r\n\r\n## [OAuth 3](https://oauth.net/3/):\r\n- In development under a new IETF working group\r\n- Re-thinking OAuth from the ground up\r\n- Not backwards compatible\r\n- Consolidate all various use cases in OAuth into a new framework\r\n\r\n-------------------------\r\n\r\nIt seems to me that changes to specification should be applied:\r\n- Deprecate `implicit` in [OAuth Flows Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#oauth-flows-object)\r\n- Deprecate `password` in [OAuth Flows Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#oauth-flows-object)\r\n- Deprecate `in: query` for `apiKey` type of security scheme(this one not sure, maybe `apiKey` isn't related to access tokens)\r\n\r\nDon't know whether I should subscribe @aaronpk to this thread, but at least he can confirm that I retyped text from his [What's New With OAuth and OIDC?](https://youtu.be/g_aVPdwBTfw) video presentation correctly.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2248/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2239", "id": 624353224, "node_id": "MDU6SXNzdWU2MjQzNTMyMjQ=", "number": 2239, "title": "Clarification on JWT Bearer access token from OAuth2 Client Credentials Grant...", "user": { "login": "cadethacker", "id": 12255072, "node_id": "MDQ6VXNlcjEyMjU1MDcy", "avatar_url": "https://avatars.githubusercontent.com/u/12255072?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cadethacker", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502392139, "node_id": "LA_kwDOAQkWPc8AAAABg5KhSw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20access%20ctrl", "name": "security: access ctrl", "color": "b20805", "default": false, "description": "Permissions and controls distinct from authentication" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2020-05-25T15:03:17Z", "updated_at": "2024-03-18T10:01:35Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hello,\r\nFirst time building a spec with OpenAPI and appreciate the thoughtfulness of this spec. The changes in OpenAPI3 are really nice. \r\n\r\nI'm lost on one point: The endpoints will be secured via Bearer JWT token, that was retrieved via OAuth2 Client Credentials grant. The JWT token will contain a correct audience and optional scopes for more granular authorization. The audience is properly validated when requested and rejected if not authorized already. \r\n\r\nReading this very closely and have some question/clarification, apologies if these are basic :D Be nice, I'm new :D \r\nhttps://swagger.io/docs/specification/authentication/\r\n\r\n**Clarification 1.** This page above shows a security scheme for both Bearer token AND OAuth2, but to me, those don't feel like different things. They feel like the same thing. The client uses OAuth2 Client Credentials grant to get the jwt access token (aka bearer token) , and passes it on the Authorization header to the API which validates it. So do I put *both* security schemes? At this point, just leaning toward bearer token. But it is OAuth2. \r\n\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#jwt-bearer-sample\r\n\r\n**Clarification 2.** The audience claim in the JWT is a key. We require the API, but also envoy (among many other in transit systems) to check the audience. But I am not sure where to specify this except in the comments in the top as to what the value of the audience is required to be. Can I use an extension? I have not quite wrapped my head around those yet... but working on it. `x-audience`? \r\n\r\nhttps://tools.ietf.org/html/rfc7519#section-4.1.3\r\nhttps://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter#config-http-filters-jwt-authn\r\n\r\n**Clarification 3.** If I need to specify the OAuth2 section the `authorizationUrl` but that changes per lifecycle. I knew so maybe this is obvious, but not sure how to specify different values per lifecycles. Just two really, QA and PR. \r\n\r\n**Clarification 4.** Is there a spot to list the JWKS? is that what the `x-jwks-token-keys` maybe? \r\n\r\n\r\nAnyway, huge thanks! Love the work you all have done. I just hate guessing on stuff like this and figured quicker to ask and get clarification than, guess and get it wrong. ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2239/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2236", "id": 620807833, "node_id": "MDU6SXNzdWU2MjA4MDc4MzM=", "number": 2236, "title": "[Question] Optional response payloads", "user": { "login": "jdegre", "id": 31138976, "node_id": "MDQ6VXNlcjMxMTM4OTc2", "avatar_url": "https://avatars.githubusercontent.com/u/31138976?v=4", "gravatar_id": "", "url": "https://api.github.com/users/jdegre", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806283, "node_id": "MDU6TGFiZWw4MzgwNjI4Mw==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/question", "name": "question", "color": "cc317c", "default": true, "description": null }, "1": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 7, "created_at": "2020-05-19T09:04:40Z", "updated_at": "2024-07-25T16:01:20Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi,\r\nHow to express in OpenAPI that a response payload is optional for a given HTTP response code?\r\n\r\nI noticed that the keyword \"required: true/false\" is applicable only to Request Body Object, but not to Response Body Object.\r\n\r\nSo, if a Response Body Object has a \"content\" field, does it indicate that a response payload is mandatory, and receiving an empty payload is considered as not allowed?\r\n\r\nMy goal is to express that a given HTTP response (mainly error codes, 4xx, 5xx) can be sent with, or without response payload. Per RFC 7231, the presence of response payloads in these error codes is encouraged (should) but it's not really mandated.\r\n\r\nThanks!\r\n/Jesús.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2236/reactions", "total_count": 2, "+1": 2, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2232", "id": 618670254, "node_id": "MDU6SXNzdWU2MTg2NzAyNTQ=", "number": 2232, "title": "Support for Proxy-Authorization in http security scheme", "user": { "login": "SakerGT", "id": 16981662, "node_id": "MDQ6VXNlcjE2OTgxNjYy", "avatar_url": "https://avatars.githubusercontent.com/u/16981662?v=4", "gravatar_id": "", "url": "https://api.github.com/users/SakerGT", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2020-05-15T03:24:04Z", "updated_at": "2020-07-08T20:17:22Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi - the OpenAPI 3.0.3 specification implies [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#securitySchemeObject) that for the `http` security scheme only Authorization header from RFC7235 may be used to supply credentials, such as a bearer token. Would it be at all possible to include support for Proxy-Authorization (without the need to use a specification extension)? The use case is to supply separate proxy and target credentials in one API request.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2232/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2190", "id": 592281615, "node_id": "MDU6SXNzdWU1OTIyODE2MTU=", "number": 2190, "title": "Support for Sensitive/PII/Personal Data", "user": { "login": "galvo", "id": 10434620, "node_id": "MDQ6VXNlcjEwNDM0NjIw", "avatar_url": "https://avatars.githubusercontent.com/u/10434620?v=4", "gravatar_id": "", "url": "https://api.github.com/users/galvo", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 861892491, "node_id": "MDU6TGFiZWw4NjE4OTI0OTE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/schema-object", "name": "schema-object", "color": "94d33b", "default": false, "description": "" }, "2": { "id": 5226531003, "node_id": "LA_kwDOAQkWPc8AAAABN4aIuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/format-registry", "name": "format-registry", "color": "9996E7", "default": false, "description": "" }, "3": { "id": 6502398197, "node_id": "LA_kwDOAQkWPc8AAAABg5K49Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20meta", "name": "security: meta", "color": "b20805", "default": false, "description": "Metadata in and about the specification" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 15, "created_at": "2020-04-02T00:32:40Z", "updated_at": "2025-09-21T18:44:02Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "It would be useful if you could tag schema properties and parameters as being sensitive or PII specific so that these could be tagged appropriately in API docs.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2190/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2146", "id": 566851002, "node_id": "MDU6SXNzdWU1NjY4NTEwMDI=", "number": 2146, "title": "Callbacks runtime expressions in multipart bodies", "user": { "login": "jdegre", "id": 31138976, "node_id": "MDQ6VXNlcjMxMTM4OTc2", "avatar_url": "https://avatars.githubusercontent.com/u/31138976?v=4", "gravatar_id": "", "url": "https://api.github.com/users/jdegre", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806283, "node_id": "MDU6TGFiZWw4MzgwNjI4Mw==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/question", "name": "question", "color": "cc317c", "default": true, "description": null }, "1": { "id": 2484499205, "node_id": "MDU6TGFiZWwyNDg0NDk5MjA1", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/links", "name": "links", "color": "6c98dd", "default": false, "description": "" }, "2": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 3, "created_at": "2020-02-18T12:11:21Z", "updated_at": "2025-09-21T18:45:13Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi,\r\nIn the OpenAPI spec, when defining a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callback-object), you can use a [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#runtime-expressions) in the form of:\r\n\r\n```\r\n$request.body#...\r\n```\r\nWhat goes after \"body\" should be a JSON pointer expression.\r\n\r\nHowever, when the HTTP request contains a multipart body, I fail to see how to reference a specific body part, where the JSON pointer expression is to be applied. \r\n\r\nAny hint on how to express this in OpenAPI?", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2146/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2142", "id": 565820317, "node_id": "MDU6SXNzdWU1NjU4MjAzMTc=", "number": 2142, "title": "Allow versioning at path:method level", "user": { "login": "damonsutherland", "id": 10148275, "node_id": "MDQ6VXNlcjEwMTQ4Mjc1", "avatar_url": "https://avatars.githubusercontent.com/u/10148275?v=4", "gravatar_id": "", "url": "https://api.github.com/users/damonsutherland", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." }, "1": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 8, "created_at": "2020-02-15T22:49:58Z", "updated_at": "2024-08-13T07:12:41Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "To facilitate the option of media-type versioning, it would be helpful to version at the path:method level. Here is the gist of my proposal: **move version from root level to path:method level and represent as an array of versions**. In making the change as described, my hope is that none of the existing functionality is sacrificed.\r\n\r\n## Single version example\r\n```\r\n/pets/{id}:\r\n put:\r\n tags:\r\n - \"pets\"\r\n versions:\r\n - version: \"default\"\r\n summary: \"...\"\r\n description: \"...\"\r\n ... all other properties formerly defined in the path-item\r\n```\r\n## Multiple version example\r\n```\r\n/pets/{id}:\r\n put:\r\n tags:\r\n - \"pets\"\r\n versions:\r\n - version: \"1\"\r\n summary: \"...\"\r\n description: \"...\"\r\n operationId: \"updatePet_v1\"\r\n consumes:\r\n - \"application/json\"\r\n - \"application/vnd.vendor.v1+json\"\r\n deprecated: true\r\n ... all other properties currently defined in the path-item\r\n - version: \"2\"\r\n summary: \"...\"\r\n description: \"...\"\r\n operationId: \"updatePet_v2\"\r\n consumes:\r\n - \"application/vnd.vendor.v2+json\"\r\n ... all other properties currently defined in the path-item\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2142/reactions", "total_count": 25, "+1": 25, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2027", "id": 505288322, "node_id": "MDU6SXNzdWU1MDUyODgzMjI=", "number": 2027, "title": "Define Oauth2 authentication Object", "user": { "login": "arthurharrison", "id": 22755581, "node_id": "MDQ6VXNlcjIyNzU1NTgx", "avatar_url": "https://avatars.githubusercontent.com/u/22755581?v=4", "gravatar_id": "", "url": "https://api.github.com/users/arthurharrison", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806283, "node_id": "MDU6TGFiZWw4MzgwNjI4Mw==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/question", "name": "question", "color": "cc317c", "default": true, "description": null }, "1": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "2": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2019-10-10T13:54:43Z", "updated_at": "2024-08-07T16:47:44Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I might be doing something wrong, but I could not find a way to define the Params object.\r\nFor example, the default uses username, password, client_id, client_secret, but instead, I just wanted an object with email (instead of username) and password beign passed. Is there a way to define it?\r\n\r\nThank you very much <3 ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2027/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2015", "id": 497992556, "node_id": "MDU6SXNzdWU0OTc5OTI1NTY=", "number": 2015, "title": "More example `same hierarchy` in path templating", "user": { "login": "ota42y", "id": 6755375, "node_id": "MDQ6VXNlcjY3NTUzNzU=", "avatar_url": "https://avatars.githubusercontent.com/u/6755375?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ota42y", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484311864, "node_id": "LA_kwDOAQkWPc8AAAABgn6_OA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/examples", "name": "examples", "color": "DE7939", "default": false, "description": "requests for more or better examples in the specification" }, "1": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "2": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 1, "created_at": "2019-09-25T00:59:05Z", "updated_at": "2024-04-20T23:15:38Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "We can't describe different templated name with same hierarchy.\r\n> Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. \r\n\r\nBut I can't understand what the `same hierarchy` means.\r\n\r\nWe can't describe these path templates\r\n```\r\n /pets/{petId}\r\n /pets/{name}\r\n```\r\n\r\nBut we can describe these?\r\n```\r\n /pets/{petId}\r\n /pets/{name}/hello\r\n```\r\n\r\nThese depth of the hierarchy is different but these is different templated name in same depth of hierarchy.\r\nWhen we get `/pets/1/hello` we can match bottom paths and name=1.\r\nThese is partially the same, but the whole is different.\r\n\r\nSo I want to add more example to this section.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/2015/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1995", "id": 485763878, "node_id": "MDU6SXNzdWU0ODU3NjM4Nzg=", "number": 1995, "title": "How to use Google ReCaptcha as \"security\"", "user": { "login": "NonPolynomial", "id": 11672744, "node_id": "MDQ6VXNlcjExNjcyNzQ0", "avatar_url": "https://avatars.githubusercontent.com/u/11672744?v=4", "gravatar_id": "", "url": "https://api.github.com/users/NonPolynomial", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2019-08-27T11:54:49Z", "updated_at": "2025-01-28T18:44:19Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi,\r\n\r\nI have a path and have to secure it with either an API key or for browser clients with Google ReCaptcha, where the client recaptcha token is used within the request payload.\r\n\r\nPayload\r\n```json5\r\n{\r\n \"g-recaptcha-response\": \"recaptcha client token which has to be verified\",\r\n // other payload data\r\n}\r\n```\r\n\r\nOpenAPI YAML\r\n```yaml\r\nopenapi: 3.0.0\r\n\r\ninfo:\r\n title: Test\r\n description: API\r\n version: 1.0.0\r\n\r\ncomponents:\r\n securitySchemes:\r\n ApiKey:\r\n type: apiKey\r\n name: X-Api-Key\r\n in: header\r\n\r\npaths:\r\n /a/b/c:\r\n post:\r\n description: ABC\r\n security:\r\n - ApiKey: []\r\n - GoogleRecaptcha: [] # <--- how?!\r\n responses:\r\n \"200\":\r\n description: success\r\n content:\r\n application/json:\r\n example:\r\n status: ok\r\n```\r\n\r\nHow do I define the security scheme for `GoogleRecaptcha`?", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1995/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1980", "id": 470409984, "node_id": "MDU6SXNzdWU0NzA0MDk5ODQ=", "number": 1980, "title": "Support for structured-headers de/serialization", "user": { "login": "ioggstream", "id": 1140844, "node_id": "MDQ6VXNlcjExNDA4NDQ=", "avatar_url": "https://avatars.githubusercontent.com/u/1140844?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ioggstream", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484685264, "node_id": "LA_kwDOAQkWPc8AAAABgoRx0A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/param%20serialization", "name": "param serialization", "color": "4309B7", "default": false, "description": "Issues related to parameter and/or header serialization" }, "1": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 9, "created_at": "2019-07-19T16:10:09Z", "updated_at": "2025-10-14T19:55:35Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "## I expect\r\n\r\nA way to express structured-fields serialization rfc8941\r\n\r\n- https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html\r\n\r\nHere are some examples:\r\n\r\n```\r\nExample-IntegerHeader: 42\r\nExample-BoolHdr: ?1\r\nExample-StringHeader: \"hello world\"\r\nExample-BinaryHdr: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:\r\nExample-StrListHeader: \"foo\", \"bar\", \"It was the best of times.\"\r\nExample-DictHeader: en=\"Applepie\", da=*w4ZibGV0w6ZydGU=*\r\n\r\n```\r\n## Note\r\n\r\nIn the near future, all http headers will probably be de/serialized using structured-header specs.\r\n\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1980/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1973", "id": 468039076, "node_id": "MDU6SXNzdWU0NjgwMzkwNzY=", "number": 1973, "title": "Add `info.lifecycle` with maturity/lifecycle informations.", "user": { "login": "ioggstream", "id": 1140844, "node_id": "MDQ6VXNlcjExNDA4NDQ=", "avatar_url": "https://avatars.githubusercontent.com/u/1140844?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ioggstream", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." }, "1": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 32, "created_at": "2019-07-15T09:56:32Z", "updated_at": "2024-08-06T16:17:55Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "## The proposal\r\n\r\nA `LifeCycle` object to describe the API lifecycle, eg:\r\n\r\n```\r\ninfo:\r\n lifecycle:\r\n maturity: published # or deprecated, retired, ...\r\n published_at: 2019-01-01\r\n deprecated_at: 2022-01-01\r\n retired_at: 2022-06-01\r\n```\r\n\r\nData related to other version may be specified eg. via link relations\r\n\r\n```\r\n links:\r\n - rel: prev\r\n url: https://prev-oas-spec\r\n - rel: next\r\n url: https://next-oas-spec\r\n\r\n```\r\n\r\n## Benefits\r\n\r\nAutomatic discovery of API status.\r\n\r\n## Considerations\r\n\r\n- http://apisjson.org/ seems not maintained anymore\r\n- we already have `deprecation` informations in operations\r\n- lifecycle could contain further informations related to eg. versioning (link to previous spec versions)\r\n\r\n\r\n## Related to\r\n\r\n#1397 ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1973/reactions", "total_count": 8, "+1": 8, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1971", "id": 466205943, "node_id": "MDU6SXNzdWU0NjYyMDU5NDM=", "number": 1971, "title": "[Feature Request] - Allow payload definition for JWT schema", "user": { "login": "ugurcemozturk", "id": 6145239, "node_id": "MDQ6VXNlcjYxNDUyMzk=", "avatar_url": "https://avatars.githubusercontent.com/u/6145239?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ugurcemozturk", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502392720, "node_id": "LA_kwDOAQkWPc8AAAABg5KjkA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20encryption", "name": "security: encryption", "color": "b20805", "default": false, "description": "Support for encryption in headers, payloads, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 11, "created_at": "2019-07-10T09:36:46Z", "updated_at": "2024-02-01T05:05:37Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "### Is your feature request related to a problem?\r\nYes. The clients will be able to know what they expect within the payload of the JWT. It will save time to parse the payload on the client-side.\r\n\r\n### Describe the solution you'd like\r\nIn the security schemas sections, the developer should be able to provide the JWT payload as another sub-schema.\r\nSomething like:\r\n```yaml\r\n securitySchemes:\r\n AppJwt:\r\n type: http\r\n scheme: bearer\r\n bearerFormat: JWT\r\n payload: '#/components/schemas/AppJwtPayload'\r\n schemas:\r\n AppJwtPayload: \r\n type: object\r\n properties:\r\n userId:\r\n type: string\r\n ```\r\nThanks.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1971/reactions", "total_count": 35, "+1": 35, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1970", "id": 465369780, "node_id": "MDU6SXNzdWU0NjUzNjk3ODA=", "number": 1970, "title": "Path Templating with multiple parameters allows for ambiguous parsing", "user": { "login": "richardwhiuk", "id": 346165, "node_id": "MDQ6VXNlcjM0NjE2NQ==", "avatar_url": "https://avatars.githubusercontent.com/u/346165?v=4", "gravatar_id": "", "url": "https://api.github.com/users/richardwhiuk", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 4, "created_at": "2019-07-08T17:11:19Z", "updated_at": "2025-08-19T22:41:35Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Currently the support for path segments is ambiguous even in simple cases:\r\n\r\nConsider:\r\n\r\n```\r\npaths:\r\n /{foo}:{bar}/update:\r\n post:\r\n summary: Example API with multiple parameters\r\n parameters:\r\n - name: foo\r\n in: path\r\n description: Foo\r\n required: true\r\n schema:\r\n type: string\r\n - name: bar\r\n in: path\r\n description: Bar\r\n required: true\r\n schema:\r\n type: string\r\n```\r\n\r\nIf the URL `/a:b:c/update` is received, there are two possible parses which, as far as I can tell, the spec doesn't state which is correct.\r\n\r\n- `foo` = `a`, `bar` = `b:c`\r\n- `foo` = `a:b`, `bar` = `c`\r\n\r\nThis means that two different implementations may have different interpretations of how parameters map through.\r\n\r\nNote, from an implementation perspective, this gets more challenging, as in order to parse the URL to work out which operation it is, you need to know the full structure of the path parameter, as that may break the ambiguity (e.g. if `bar` is an `enum` which can only take values `c`, or `d`, then the parse collapses into the second option).", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1970/reactions", "total_count": 2, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 2 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1953", "id": 456970720, "node_id": "MDU6SXNzdWU0NTY5NzA3MjA=", "number": 1953, "title": "Support for message level security", "user": { "login": "pleothaud", "id": 22974810, "node_id": "MDQ6VXNlcjIyOTc0ODEw", "avatar_url": "https://avatars.githubusercontent.com/u/22974810?v=4", "gravatar_id": "", "url": "https://api.github.com/users/pleothaud", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502392720, "node_id": "LA_kwDOAQkWPc8AAAABg5KjkA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20encryption", "name": "security: encryption", "color": "b20805", "default": false, "description": "Support for encryption in headers, payloads, etc." } }, "state": "open", "locked": false, "assignees": { "0": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 9, "created_at": "2019-06-17T14:33:27Z", "updated_at": "2024-02-01T05:05:47Z", "closed_at": null, "assignee": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "As expressed in issues #1464 and #1881 there is a need for describing signed and encrypted requests and response using OpenAPI. I would like to propose the following mechanisms to support message level security in OAS.\r\n\r\nThis proposal comes after some preliminary works summarized in the Google doc at https://docs.google.com/document/d/13THkz7867blJ464ohpz9MUrhMQp-28Cx77JvDHlyurc from OAI Google Drive (I can give access to this doc to who needs it)\r\n\r\nThe problem with the proposal in this document is that it was too complex and did not follow the Open API philosophy, so I tried here to put in place something more standard, mimicking the Security Scheme / Security Requirement mechanism people are used to.\r\n\r\nLet's take an example that shows how you could describe required requests signature and provided responses signature using JWT tokens (as you can see it uses the key description mechanism proposed by @whitlockjc in issue #1881) :\r\n```yaml\r\n# ...\r\ncomponents:\r\n\r\n keys:\r\n # Keys taken from Google's OIDC Discover Document (https://accounts.google.com/.well-known/openid-configuration)\r\n google-oauth-v3-1:\r\n description: \"JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/0\"\r\n type: JWK\r\n metadata:\r\n kid: 0905d6f9cd9b0f1f852e8b207e8f673abca4bf75\r\n e: AQAB\r\n kty: RSA\r\n alg: RS256\r\n n: yyeEmeK35F8P54ozfpsF79n59ZsOrcZdxQWsxrzm0qjdA5r_b-be-cQnWAw_2AoGdeWHX-Cz7uPFDMdEwzLGlpv3SELi34h8PkzjyO7xlbhsNs-ICnqUyUTA7CovKtpJ47PjiQnXcaRNCFUQbli8VlEqbVLuqFjC98igICpNYR-iiVIm0VCFtkq0p8vf1yQ493Pnx2Bm8fUx6SkeJ7wKPWQq_K4e6ZH40JWLk6c1U9W5qPKeckevdNLrdZY5lsTZ5zrRvuRBoIeZfp9bKSZGMtEja4xSCDKLrkcpb4qf6Ywx9rsZ4b8eHSLpVvUzNsj3GS7qK5flHzoccovhPVBbbQ\r\n use: sig\r\n\r\n messageSecurityOperations:\r\n signedJWTrequestOperation:\r\n securityType: signedJWTRequest\r\n alg:\r\n - PS256\r\n - PS512\r\n pubKeyRef:\r\n - jku+kid\r\n mandatoryStandardClaims:\r\n - iss\r\n - aud\r\n - iat\r\n - exp\r\n - jti\r\n \r\n signedJwtResponseOperation:\r\n securityType: signedJWTResponse\r\n pubKey: \r\n $ref: '#/components/keys/google-oauth-v3-1'\r\n \r\n messageSecuritySchemes:\r\n highSensitivityScheme-PostPutPatch:\r\n requestSecurity:\r\n $ref: '#/components/messageSecurityOperations/signedJWTrequestOperation'\r\n responseSecurity:\r\n 200:\r\n $ref: '#/components/messageSecurityOperations/signedJwtResponseOperation'\r\n# ...\r\n```\r\n\r\nAs you can see, there are two objects added in the `components` top level object:\r\n - `messageSecurityOperations`, which is a Map of `messageSecurityOperation`s describing the elementary signature and encryption operations that are required on API requests or performed as API responses\r\n - `messageSecuritySchemes` which is a Map of `messageSecurityScheme`s, each security scheme stating which `messageSecurityOperation` must be applied to the request before consuming the API and which `messageSecurityOperation` will be applied to the operation's responses, based on the response HTTP status code (all of these referencing the `messageSecurityOperation`s declared in the `messageSecurityOperations` object\r\n\r\nOnce these objects declared in the `components` object, it becomes possible to reference a `messageSecurityScheme` directly from an Operation, just like this:\r\n\r\n```yaml\r\n# ...\r\npaths:\r\n /pets:\r\n post:\r\n description: Creates a new pet in the store. Duplicates are allowed\r\n operationId: addPet\r\n messageSecurity: highSensitiveProfile-PostPutPatch\r\n requestBody:\r\n description: Pet to add to the store\r\n required: true\r\n content:\r\n application/jwt:\r\n schema:\r\n $ref: '#/components/schemas/NewPet'\r\n responses:\r\n '200':\r\n description: pet response\r\n content:\r\n application/jwt:\r\n schema:\r\n $ref: '#/components/schemas/Pet'\r\n default:\r\n description: unexpected error\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/Error'\r\n# ...\r\n\r\n```\r\n\r\nwhere the `messageSecurity: highSensitivityScheme-PostPutPatch` field of the `post` operation object specifies which message security scheme to apply to the operation (on requests and responses).\r\n\r\nThere are a few message level security operations that could be described this way:\r\n\r\n- Request Security Schemes\r\n\r\n1. JWSRequest (standard JWS compact signature)\r\n2. JWSDetachedRequest (request body unchanged, signature passed in a HTTP header)\r\n3. SignedJWTRequest (signed JWT)\r\n4. HTTPSigRequest (HTTPSignature standard description)\r\n5. EncryptedJWTRequest (encrypted JWT)\r\n6. JWERequest (standard compact JWE encrypted message)\r\n\r\n- Response Security Schemes\r\n\r\n1. JWSResponse\r\n2. JWSDetachedResponse\r\n3. SignedJWTResponse\r\n4. HTTPSigResponse\r\n5. EncryptedJWTResponse\r\n6. JWEResponse\r\n\r\nIf you feel comfortable with the presented structure of message level security description I can create separate issues for each of these message level security operations, specifying mandatory and optional attributes that could describe these operations.\r\n\r\nHappy to discuss!", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1953/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1934", "id": 448943958, "node_id": "MDU6SXNzdWU0NDg5NDM5NTg=", "number": 1934, "title": "OAuth refreshUrl property", "user": { "login": "pleothaud", "id": 22974810, "node_id": "MDQ6VXNlcjIyOTc0ODEw", "avatar_url": "https://avatars.githubusercontent.com/u/22974810?v=4", "gravatar_id": "", "url": "https://api.github.com/users/pleothaud", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 1, "created_at": "2019-05-27T17:14:55Z", "updated_at": "2024-02-06T14:08:38Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi,\r\n\r\nIs there any reason why the non-standard refreshUrl property was added to OAI?\r\n\r\nObtaining a new Access Token using the Refresh Token should be done using the TokenEndpoint, as stated in RFC 6749 (OAuth 2.0 Authorization framework):\r\n\r\n\"3.2. Token Endpoint\r\nThe token endpoint is used by the client to obtain an access token by presenting its authorization grant **or refresh token**. The token endpoint is used with every authorization grant except for the implicit grant type (since an access token is issued directly).\"\r\n\r\nThanks,\r\n\r\nPhilippe", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1934/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1881", "id": 426608063, "node_id": "MDU6SXNzdWU0MjY2MDgwNjM=", "number": 1881, "title": "Support describing security keys in OAS", "user": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806281, "node_id": "MDU6TGFiZWw4MzgwNjI4MQ==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/enhancement", "name": "enhancement", "color": "a2eeef", "default": true, "description": "" }, "1": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "2": { "id": 6502392720, "node_id": "LA_kwDOAQkWPc8AAAABg5KjkA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20encryption", "name": "security: encryption", "color": "b20805", "default": false, "description": "Support for encryption in headers, payloads, etc." } }, "state": "open", "locked": false, "assignees": { "0": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 9, "created_at": "2019-03-28T17:03:46Z", "updated_at": "2024-02-01T05:06:33Z", "closed_at": null, "assignee": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Often times when interacting with APIs, security keys are involved. From a JWT perspective, keys are used for encrypting, signing and verifying tokens. In issue #1464, keys are used for encrypting and signing requests/responses. I would like to propose that we officially support describing _security keys_ in OAS, starting with [JSON Web Keys](https://tools.ietf.org/html/rfc7517).\r\n\r\nShooting from the hip, here is a first-pass example:\r\n\r\n```yaml\r\n# ...\r\ncomponents:\r\n keys:\r\n # Keys taken from Google's OIDC Discover Document (https://accounts.google.com/.well-known/openid-configuration)\r\n google-oauth-v3-1:\r\n description: \"JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/0\"\r\n type: JWK\r\n metadata:\r\n kid: 0905d6f9cd9b0f1f852e8b207e8f673abca4bf75\r\n e: AQAB\r\n kty: RSA\r\n alg: RS256\r\n n: yyeEmeK35F8P54ozfpsF79n59ZsOrcZdxQWsxrzm0qjdA5r_b-be-cQnWAw_2AoGdeWHX-Cz7uPFDMdEwzLGlpv3SELi34h8PkzjyO7xlbhsNs-ICnqUyUTA7CovKtpJ47PjiQnXcaRNCFUQbli8VlEqbVLuqFjC98igICpNYR-iiVIm0VCFtkq0p8vf1yQ493Pnx2Bm8fUx6SkeJ7wKPWQq_K4e6ZH40JWLk6c1U9W5qPKeckevdNLrdZY5lsTZ5zrRvuRBoIeZfp9bKSZGMtEja4xSCDKLrkcpb4qf6Ywx9rsZ4b8eHSLpVvUzNsj3GS7qK5flHzoccovhPVBbbQ\r\n use: sig\r\n google-oauth-v3-2:\r\n description: \"JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/1\"\r\n type: JWK\r\n metadata:\r\n kid: a4313e7fd1e9e2a4ded3b292d2a7f4e519574308\r\n e: AQAB\r\n kty: RSA\r\n alg: RS256\r\n n: lO3_QoRd_D8UHAjFcdg0_8GOiLyWo4Viiy8cDLNGf8T1eQlqqhPYZmvGOPhyILWZ9FInOXT9AzH5KPfeOnMEzy4TqfGLtdcAlufqALe_qusmq7SSNIVfSw5iPZjzXk3BXjzoFNZLfqsoqheGzek-sJV1Ti5JQQ2hRPSZQhba9xVn6G8Uxr5ugVhHQ25P6HL4acjhuvpSPEFn7tivEIhWZEL35CeqHelf-48WA4PLzRVvfFMS-hW6erjX7uxT9mj8uT7zGl41_zBd9lMn2CQeP3aLDeQFoFaLaX2NZctRASErz6H9MIXQngM1piKnc84hmify-ZAsPpBcxw7heFpYRw\r\n use: sig\r\n# ...\r\n```\r\n\r\nAs you can see, each key has three common properties:\r\n\r\n* `description`: A human-readable description of the key\r\n* `type`: The _type_ of the key _(One could argue that JSON Web Keys are capable of describing any key and only JSON Web Keys should be supported but for now, this value would be free-form and it would be tooling specific as to how the values are validated.)_\r\n* `metadata`: This is the information describing the key based on the key type _(This field must be free-form to allow for future expansion)_\r\n\r\nOnce we have a common way to describe security keys, you have the ability to reference them using JSON References to use. Here are two examples:\r\n\r\n**Signed Reqeusts/Responses _(#1464)_**\r\n\r\n```yaml\r\n# ...\r\nkeys:\r\n payment-signing-key:\r\n description: The payment signing JSON Web Key\r\n type: JWK\r\n metadata:\r\n kty: EC\r\n crv: P-256\r\n x: PxlJQu9Q6dOvM4LKoZUh2XIe9-pdcLkvKfBfQk11Sb0\r\n y: 6IDquxrbdq5ABe4-HQ78_dhM6eEBUbvDtdqK31YfRP8\r\n# ...\r\n @context: https://example.com/paymentStandard/pay,\r\n amount: 255.00\r\n currency: USD\r\n signature:\r\n # Likely unnecessary as the key describes its algorithm\r\n alg\": ES256\r\n jwk:\r\n $ref: \"#/components/keys/payment-signing-key\"\r\n val\": \"RSLmFihg8QmXxM .... N0lGIdSEYvMMLTL8hEaYV9kW6A\"\r\n# ...\r\n```\r\n\r\n**JWT-based Security Scheme**\r\n\r\n**Note:** This example uses a JWT-based Security Scheme that **DOES NOT** exist yet and is only for example purposes. There is an ongoing discussion about supporting JWT for security in OAS but this is not indicative of what will be supported if/when a decision is made.\r\n\r\n```yaml\r\n# ...\r\ncomponents:\r\n keys:\r\n # Keys taken from Google's OIDC Discovery Document (https://accounts.google.com/.well-known/openid-configuration)\r\n google-oauth-v3-1:\r\n description: \"JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/0\"\r\n type: JWK\r\n metadata:\r\n kid: 0905d6f9cd9b0f1f852e8b207e8f673abca4bf75\r\n e: AQAB\r\n kty: RSA\r\n alg: RS256\r\n n: yyeEmeK35F8P54ozfpsF79n59ZsOrcZdxQWsxrzm0qjdA5r_b-be-cQnWAw_2AoGdeWHX-Cz7uPFDMdEwzLGlpv3SELi34h8PkzjyO7xlbhsNs-ICnqUyUTA7CovKtpJ47PjiQnXcaRNCFUQbli8VlEqbVLuqFjC98igICpNYR-iiVIm0VCFtkq0p8vf1yQ493Pnx2Bm8fUx6SkeJ7wKPWQq_K4e6ZH40JWLk6c1U9W5qPKeckevdNLrdZY5lsTZ5zrRvuRBoIeZfp9bKSZGMtEja4xSCDKLrkcpb4qf6Ywx9rsZ4b8eHSLpVvUzNsj3GS7qK5flHzoccovhPVBbbQ\r\n use: sig\r\n# ...\r\nsecurity:\r\n google-oath:\r\n type: http\r\n scheme: bearer\r\n bearerFormat: JWT\r\n jwk:\r\n $ref: '#/components/keys/google-oauth-v3-1'\r\n# ...\r\n```\r\n\r\nNow that we have some examples, let's get the conversation started.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1881/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1875", "id": 424338700, "node_id": "MDU6SXNzdWU0MjQzMzg3MDA=", "number": 1875, "title": "JWT-grant as a new Oauth2 flow", "user": { "login": "joergenb", "id": 1483360, "node_id": "MDQ6VXNlcjE0ODMzNjA=", "avatar_url": "https://avatars.githubusercontent.com/u/1483360?v=4", "gravatar_id": "", "url": "https://api.github.com/users/joergenb", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 9, "created_at": "2019-03-22T18:12:44Z", "updated_at": "2024-02-09T09:06:30Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "RFC7523 extends Oauth2 by using JWTs as grants. \r\n\r\nIt would be nice if this behaviour could be added as a new type of flow under the Oauth2 securityScheme, in addition to existing ones (authorizationCode, implicit, etc.)\r\n\r\nThe full name in the RFC is `urn:ietf:params:oauth:grant-type:jwt-bearer`, but I guess `JWT` will suffice. Apart from that, the `tokenUrl` and `scopes` would be needed.\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1875/reactions", "total_count": 7, "+1": 7, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1731", "id": 374284668, "node_id": "MDU6SXNzdWUzNzQyODQ2Njg=", "number": 1731, "title": "Support for \"dynamic\" authorization scopes", "user": { "login": "aparamon", "id": 2229284, "node_id": "MDQ6VXNlcjIyMjkyODQ=", "avatar_url": "https://avatars.githubusercontent.com/u/2229284?v=4", "gravatar_id": "", "url": "https://api.github.com/users/aparamon", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502392139, "node_id": "LA_kwDOAQkWPc8AAAABg5KhSw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20access%20ctrl", "name": "security: access ctrl", "color": "b20805", "default": false, "description": "Permissions and controls distinct from authentication" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 8, "created_at": "2018-10-26T08:46:13Z", "updated_at": "2025-11-12T18:20:10Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "According to\r\nhttps://swagger.io/docs/specification/authentication/#scopes,\r\n> * In case of OAuth 2, the scopes used in `security` must be previously defined in `securitySchemes`.\r\n> * In case of OpenID Connect Discovery, possible scopes are listed in the discovery endpoint specified by `openIdConnectUrl`.\r\n\r\nThis is limiting though, as application may want to provide \"dynamic\" scopes which depend on the endpoint. Consider e.g.\r\n````yaml\r\ncomponents:\r\n securitySchemes:\r\n OAuth2:\r\n type: oauth2\r\n flows:\r\n authorizationCode:\r\n scopes:\r\n pets:read: Grants pet read access\r\n pets:write: Grants pet write access\r\npaths:\r\n /pets/{id}/color:\r\n get:\r\n summary: Get pet color\r\n security:\r\n - OAuth2: [pets:{id}:read]\r\n````\r\nIn this case, the fine-grained `pets:{id}:read` scopes are used for accessing particular pet's color. For example, `/pets/felix/color` is accessible with scope `pets:felix:read`. However, it's impossible to pre-define all pet scopes in `securitySchemes`, as they depend on path and application state.\r\nSee also https://docs.docker.com/registry/spec/auth/scope/#resource-scope-grammar for example of really complex dynamic scope names.\r\n\r\nTo support interactive \"Try it out\" in Swagger-UI, the following approach might prove helpful:\r\n````yaml\r\ncomponents:\r\n securitySchemes:\r\n OAuth2:\r\n type: oauth2\r\n flows:\r\n authorizationCode:\r\n scopes:\r\n pets:read: Grants pet read access\r\n pets:write: Grants pet write access\r\npaths:\r\n /pets/{id}/color:\r\n get:\r\n summary: Get pet color\r\n security:\r\n - OAuth2: [pets:read OR pets:{id}:read]\r\n````\r\nThis way, if coarse-grained `pets:read` scope is selected in Swagger-UI, the lock icon status corresponding to `/pets/{id}/color` could be correctly updated. In the actual API client, any of coarse-grained `pets:read` and fine-grained `pets:{id}:read` (e.g. `pets:felix:read`) could be requested and used.\r\n\r\nHow to properly implement `OR` operator in YAML is a technical exercise ;-)", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1731/reactions", "total_count": 9, "+1": 9, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1702", "id": 366776156, "node_id": "MDU6SXNzdWUzNjY3NzYxNTY=", "number": 1702, "title": "Making Security Scheme Objects Extensible", "user": { "login": "cmheazel", "id": 7959995, "node_id": "MDQ6VXNlcjc5NTk5OTU=", "avatar_url": "https://avatars.githubusercontent.com/u/7959995?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cmheazel", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502448849, "node_id": "LA_kwDOAQkWPc8AAAABg5N-0Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20config", "name": "security: config", "color": "b20805", "default": false, "description": "The mechanics of severs and structure of security-related objects" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 1, "created_at": "2018-10-04T12:55:28Z", "updated_at": "2024-02-03T01:35:44Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "OpenAPI allows you to extend Security Scheme Objects. However, since the values of the Type field are fixed, and the contents of a security scheme are determined by the value of the Type field, then security schemes are not really extensible. We should add \"x-custom\" as a valid value to the Type field. This indicates that this is an extended (non-standard) Security Scheme Object. Extended Security Schemes should populate the \"x-type\" field to identify the type of custom scheme being described. x-type is an unrestricted string. It is up to the implementing community to manage its' values. #1004", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1702/reactions", "total_count": 2, "+1": 2, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1589", "id": 325601903, "node_id": "MDU6SXNzdWUzMjU2MDE5MDM=", "number": 1589, "title": "Support multiple contacts in info object", "user": { "login": "silverwind", "id": 115237, "node_id": "MDQ6VXNlcjExNTIzNw==", "avatar_url": "https://avatars.githubusercontent.com/u/115237?v=4", "gravatar_id": "", "url": "https://api.github.com/users/silverwind", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 8, "created_at": "2018-05-23T08:32:28Z", "updated_at": "2024-01-29T04:05:36Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "The [info object](https://swagger.io/specification/#infoObject) currently only allows a single [contact object](https://swagger.io/specification/#contactObject). I think it would be very useful to support an array of contact objects for projects with multiple people unrelated to each other working on it.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1589/reactions", "total_count": 6, "+1": 6, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1553", "id": 315769939, "node_id": "MDU6SXNzdWUzMTU3Njk5Mzk=", "number": 1553, "title": "Hypermedia and path variable", "user": { "login": "boubasse", "id": 26378133, "node_id": "MDQ6VXNlcjI2Mzc4MTMz", "avatar_url": "https://avatars.githubusercontent.com/u/26378133?v=4", "gravatar_id": "", "url": "https://api.github.com/users/boubasse", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 2484499205, "node_id": "MDU6TGFiZWwyNDg0NDk5MjA1", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/links", "name": "links", "color": "6c98dd", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 17, "created_at": "2018-04-19T08:10:23Z", "updated_at": "2024-01-28T20:28:45Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi everyone,\r\n\r\nI'm facing an issue an i don't know if there is a solution yet.\r\n\r\nIs it possible to pass an absolute URI from a links object as a variable for a path ?\r\n\r\nExample :\r\n\r\n```yaml\r\nlinks:\r\n pathLink:\r\n operationId: whatever\r\n parameters:\r\n pathUri: '$response.body#_links/whatever/href'\r\n```\r\nAnd then having as a path :\r\n\r\n```yaml\r\npaths:\r\n '{pathUri}':\r\n get:\r\n operationId: whatever\r\n parameters:\r\n - name: pathUri\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n```\r\n\r\nAccording to the specification, paths must be relative but in that specific case could it be acceptable ?\r\n\r\nThanks for your answers.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1553/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1552", "id": 315757048, "node_id": "MDU6SXNzdWUzMTU3NTcwNDg=", "number": 1552, "title": "Extensible enumerations (growable lists)", "user": { "login": "JonKohler", "id": 21041006, "node_id": "MDQ6VXNlcjIxMDQxMDA2", "avatar_url": "https://avatars.githubusercontent.com/u/21041006?v=4", "gravatar_id": "", "url": "https://api.github.com/users/JonKohler", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861892491, "node_id": "MDU6TGFiZWw4NjE4OTI0OTE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/schema-object", "name": "schema-object", "color": "94d33b", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 33, "created_at": "2018-04-19T07:25:46Z", "updated_at": "2025-10-07T13:28:34Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hey all,\r\nI did some searching in the OAI repo, and it didn't jump out at me as an existing feature request.\r\n\r\nThe issues with enum being \"non-growable\" without making a major semver change for an API have been talked about in several places. Zalando came up with nice framework within their API guidelines to handle this, which would be incredibly useful to upstream into the specification itself\r\n\r\nhttps://zalando.github.io/restful-api-guidelines/#112\r\n\r\n> Should: Used Open-Ended List of Values (x-extensible-enum) Instead of Enumerations [112]\r\n> Enumerations are per definition closed sets of values, that are assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid these issues, we strongly recommend to use an open-ended list of values instead of an enumeration unless:\r\n> \r\n> the API has full control of the enumeration values, i.e. the list of values does not depend on any external tool or interface, and\r\n> \r\n> the list of value is complete with respect to any thinkable and unthinkable future feature.\r\n> \r\n> To specify an open-ended list of values use the marker x-extensible-enum as follows:\r\n\r\n```\r\ndeliver_methods:\r\n type: string\r\n x-extensible-enum:\r\n - parcel\r\n - letter\r\n - email\r\n```", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1552/reactions", "total_count": 23, "+1": 18, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 3, "rocket": 0, "eyes": 2 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1520", "id": 310534912, "node_id": "MDU6SXNzdWUzMTA1MzQ5MTI=", "number": 1520, "title": "Formalize conformance test description format", "user": { "login": "tedepstein", "id": 692813, "node_id": "MDQ6VXNlcjY5MjgxMw==", "avatar_url": "https://avatars.githubusercontent.com/u/692813?v=4", "gravatar_id": "", "url": "https://api.github.com/users/tedepstein", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": {}, "state": "open", "locked": false, "assignees": { "0": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 5, "created_at": "2018-04-02T16:39:54Z", "updated_at": "2025-09-21T18:23:05Z", "closed_at": null, "assignee": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Discussed on TSC Meeting: April 2, 2018:\r\n\r\nRules and test cases in a conformance test suite might have a descriptive structure, something like this: \r\n* Rule description (human-readable)\r\n* Reference to the relevant part of the spec. \r\n* Set of test cases derived from this rule:\r\n * Example input\r\n * Expected result, as one of the following:\r\n * pass\r\n * error (corresponds to MUST, MUST NOT in the spec)\r\n * warning (corresponds to SHOULD, SHOULD NOT in the spec)\r\n * Comments (optional) \r\n\r\nOpenAPI implementations, including editors, generators, documentation formats, etc., are expected to validate the content, correctly detect error and warning conditions (without false-positives on valid content), expose and handle errors and warnings in whatever way is appropriate for that implementation. \r\n\r\nSome goals, and possibly non-goals, pending discussion:\r\n* Create a definitive conformance test suite as the set of all of these rules and test cases. \r\n* Use a uniform descriptive structure for the test cases in the suite, something like the preceding bullet list. \r\n* Make the rule and test case descriptions machine-_readable_. \r\n* Make the rules machine-_executable_ by adding structured representations of each rule, which could take different forms: \r\n * Where the rule can be expressed in JSON Schema, include it in a schema, which can be designed to be the standard schema for OpenAPI, or could be given a more limited scope of use, as an informative addition to the conformance test suite. \r\n * In other cases, or possibly in all cases, state the rule as a logical assertion using an expression language, preferably one that can be embedded or interpreted in different programming languages. \r\n\r\nConsider all of the above as a straw-man proposal, for discussion. ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1520/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1515", "id": 307155805, "node_id": "MDU6SXNzdWUzMDcxNTU4MDU=", "number": 1515, "title": "Extensible Security Scheme Object", "user": { "login": "cmheazel", "id": 7959995, "node_id": "MDQ6VXNlcjc5NTk5OTU=", "avatar_url": "https://avatars.githubusercontent.com/u/7959995?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cmheazel", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" }, "2": { "id": 7069061505, "node_id": "LA_kwDOAQkWPc8AAAABpVlRgQ", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/registries", "name": "registries", "color": "EEF971", "default": false, "description": "Related to any or all spec.openapis.org-hosted registries" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 6, "created_at": "2018-03-21T08:35:54Z", "updated_at": "2024-06-12T16:16:16Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "There are a number of issues regarding support for security controls which do not fall neatly under the \"apiKey\", \"http\", \"oauth2\", \"openIdConnect\" taxonomy. This suggests that we need a more extensible form of the Security Scheme Object. One that makes it easy to add security schemes to OpenAPI. I propose that we create a new branch to work this issue. Guiding principles are:\r\n1) Do no harm. The extensible security schemes should be backwards compatible with the current version.\r\n2) Use a registry approach. This allows new schemes to be added without requiring a change to OpenAPI.\r\nMore to come. ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1515/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1497", "id": 301315855, "node_id": "MDU6SXNzdWUzMDEzMTU4NTU=", "number": 1497, "title": "Vary presence and requirement of properties with CRUD operation", "user": { "login": "pplr", "id": 116019, "node_id": "MDQ6VXNlcjExNjAxOQ==", "avatar_url": "https://avatars.githubusercontent.com/u/116019?v=4", "gravatar_id": "", "url": "https://api.github.com/users/pplr", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861892491, "node_id": "MDU6TGFiZWw4NjE4OTI0OTE=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/schema-object", "name": "schema-object", "color": "94d33b", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 21, "created_at": "2018-03-01T08:26:13Z", "updated_at": "2024-12-11T19:03:16Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Properties of a schema could be marked as `readOnly` or `writeOnly` if they should not be used respectively in a request or response. Additionally, required properties are present in the `required` field. Request vs response is the only criteria that can alter a resource schema.\r\n\r\nThis was not sufficient to describe our legacy REST APIs where presence and requirement of resource's properties is highly dependent of CRUD operation. The was due, in part, to wrong design choices. However, we faced generic situations that cannot be expressed for example:\r\n* Write once / immutable property: for properties like slug or identifier. Those properties should not be part of update request. \r\n* Server side default value: this kind of property is required only in response.\r\n\r\nAll this can be achieved using composition. I don't think that's a reasonable solution because:\r\n* contract is not more human readable as resources are split in many schema\r\n* for polymorphic resources (using oneOf), there is too many different schema to create and duplication is inevitable \r\n \r\nWe used following vendor extensions to be able to produce the documentation of our API:\r\n\r\nField Name | Type | Description\r\n---|:---:|---\r\nx-createOnly | `boolean` | Relevant only for Schema \"properties\" definitions. Declares the property as \"create only\". This means that it MAY be sent as part of a POST request but SHOULD NOT be sent as part of the response or any other request type. If the property is marked as x-createOnly being true and is in the required list, the required will take effect on the POST request only. A property MUST NOT be marked as both x-createOnly and readOnly, writeOnly, x-updateOnly, x-createForbidden or x-updateForbidden being true. Default value is false.\r\nx-updateOnly | `boolean` | Relevant only for Schema \"properties\" definitions. Declares the property as \"update only\". This means that it MAY be sent as part of a PUT request but SHOULD NOT be sent as part of the response or any other request type. If the property is marked as x-updateOnly being true and is in the required list, the required will take effect on the PUT request only. A property MUST NOT be marked as both x-updateOnly and readOnly, writeOnly, x-createOnly, x-createForbidden or x-updateForbidden being true. Default value is false.\r\nx-createForbidden | `boolean` | Relevant only for Schema \"properties\" definitions. Declares the property as \"create forbidden\". This means that it MAY be sent as part of a PUT request or be sent as part of the response but SHOULD NOT be sent as part of any other request type. If the property is marked as x-createForbidden being true and is in the required list, the required will take effect on the PUT request and the response only. A property MUST NOT be marked as both x-createForbidden and readOnly, writeOnly, x-createOnly, x-updateOnly or x-updateForbidden being true. Default value is false.\r\nx-updateForbidden | `boolean` | Relevant only for Schema \"properties\" definitions. Declares the property as \"create and read only\". This means that it MAY be sent as part of a POST request or be sent as part of the response but SHOULD NOT be sent as part of any other request type. If the property is marked as x-updateForbidden being true and is in the required list, the required will take effect on the POST request and the response only. A property MUST NOT be marked as both x-updateForbidden and readOnly, writeOnly, x-createOnly, x-updateOnly or x-createForbidden being true. Default value is false.\r\nx-requiredCreate | `[string]` | List properties required in the POST request.\r\nx-requiredUpdate | `[string]` | List properties requires in the PUT request.\r\nx-requiredRead | `[string]` | List properties required in the response.\r\n\r\nBeing able to describe requirement and presence of resource's properties based on usage context could be a great enhancement. ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1497/reactions", "total_count": 10, "+1": 10, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1464", "id": 291622705, "node_id": "MDU6SXNzdWUyOTE2MjI3MDU=", "number": 1464, "title": "Support for JOSE (JSON Signature and Encryption) Standards", "user": { "login": "cyberphone", "id": 8044211, "node_id": "MDQ6VXNlcjgwNDQyMTE=", "avatar_url": "https://avatars.githubusercontent.com/u/8044211?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cyberphone", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6217272224, "node_id": "LA_kwDOAQkWPc8AAAABcpQLoA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Needs%20attention", "name": "Needs attention", "color": "5319e7", "default": false, "description": "The author has replied and people with triage rights should take action." }, "2": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" }, "3": { "id": 6502392720, "node_id": "LA_kwDOAQkWPc8AAAABg5KjkA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20encryption", "name": "security: encryption", "color": "b20805", "default": false, "description": "Support for encryption in headers, payloads, etc." } }, "state": "open", "locked": false, "assignees": { "0": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false } }, "milestone": null, "comments": 48, "created_at": "2018-01-25T16:03:59Z", "updated_at": "2026-03-04T12:36:38Z", "closed_at": null, "assignee": { "login": "whitlockjc", "id": 98899, "node_id": "MDQ6VXNlcjk4ODk5", "avatar_url": "https://avatars.githubusercontent.com/u/98899?v=4", "gravatar_id": "", "url": "https://api.github.com/users/whitlockjc", "type": "User", "user_view_type": "public", "site_admin": false }, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I'm not currently a user of OpenAPI but a follower of standards initiatives like OpenBanking/FAPI where members claim that OpenAPI currently does not support JOSE (JSON Signature and Encryption) standards forcing them to use various workarounds.\r\n\r\nI wonder if there is anybody out there with knowledge of the OpenAPI platform who could be interested in working with me to integrate the missing support?\r\n\r\nThere are also enhanced versions of JOSE JWS and JWE in the workings (through the IETF), providing **C**lear **T**ext support which should be a nice fit for information centric systems, here illustrated by a minute JWS-CT sample:\r\n\r\n```json\r\n{\r\n \"@context\": \"https://example.com/paymentStandard/pay\",\r\n \"amount\": \"255.00\",\r\n \"currency\": \"USD\",\r\n \"signature\": {\r\n \"alg\": \"ES256\",\r\n \"jwk\": {\r\n \"kty\": \"EC\",\r\n \"crv\": \"P-256\",\r\n \"x\": \"PxlJQu9Q6dOvM4LKoZUh2XIe9-pdcLkvKfBfQk11Sb0\",\r\n \"y\": \"6IDquxrbdq5ABe4-HQ78_dhM6eEBUbvDtdqK31YfRP8\"\r\n },\r\n \"val\": \"RSLmFihg8QmXxM .... N0lGIdSEYvMMLTL8hEaYV9kW6A\"\r\n }\r\n}\r\n```\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1464/reactions", "total_count": 8, "+1": 8, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1421", "id": 278075459, "node_id": "MDU6SXNzdWUyNzgwNzU0NTk=", "number": 1421, "title": "OpenAPI 3.x: Scope of API version in servers definition too course grained?", "user": { "login": "marwey", "id": 12638489, "node_id": "MDQ6VXNlcjEyNjM4NDg5", "avatar_url": "https://avatars.githubusercontent.com/u/12638489?v=4", "gravatar_id": "", "url": "https://api.github.com/users/marwey", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 6, "created_at": "2017-11-30T10:47:52Z", "updated_at": "2024-01-29T04:06:59Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hi, I was building a few OpenAPI 3.0 yaml files each describing a couple of paths. All path definitions are at version 1.\r\n\r\nMy server object is defined similiar to that pattern:\r\n\r\n``` \r\nservers:\r\n - url: https://development.gigantic-server.com/v1\r\n description: Development server\r\n - url: https://production.gigantic-server.com/v1\r\n description: Production server \r\n```\r\nWhat if I decide to change the path definition and/or the implementation of a path in a way that makes it incompatible to version 1? I would need to define a version 2 path. But certainly only for that specific path - all others should stay at version 1. \r\n\r\nHowever, my server definition from above would be useless since its scope is applied to all path. \r\n\r\nI can think of some workarounds - like e.g. putting the version number as part of the path definition or defining another yaml spec that only includes the version 2 path - but they are not really elegant and will cause other problems. \r\n\r\nWhat is best practice for this - I guess quite common - scenario? \r\nWhat was the intention of the spec authors to provide the above servers pattern?\r\n\r\nThanks!\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1421/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1416", "id": 275448355, "node_id": "MDU6SXNzdWUyNzU0NDgzNTU=", "number": 1416, "title": "Security Requirement Consistency with Server Objects", "user": { "login": "stevendearborn", "id": 6518685, "node_id": "MDQ6VXNlcjY1MTg2ODU=", "avatar_url": "https://avatars.githubusercontent.com/u/6518685?v=4", "gravatar_id": "", "url": "https://api.github.com/users/stevendearborn", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502448849, "node_id": "LA_kwDOAQkWPc8AAAABg5N-0Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20config", "name": "security: config", "color": "b20805", "default": false, "description": "The mechanics of severs and structure of security-related objects" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 9, "created_at": "2017-11-20T18:08:13Z", "updated_at": "2024-02-01T05:16:13Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "In OpenAPI 3.0 server objects can be defined at three basic levels: 1) entire JSON document (global - all resources and operations), 2) a path (all operations on a resource), and 3) an operation [on a resource], with the more specific overriding more global definitions. Security Requirement objects can be defined/specified at two levels: 1) globally and 2) on an operation, but not for an entire path.\r\n\r\nIf a path can have one or more servers distinguished for it, then the security on a resource server MAY be different than others more globally defined and in-effect [through Swagger Editor, Swagger UI]. Thus, adding security object to a path object will provide this flexibility in definition and use. It will provide a productive shorthand to specifying the same on each operation for the same reason that servers does.\r\n\r\n\r\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1416/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1397", "id": 270732827, "node_id": "MDU6SXNzdWUyNzA3MzI4Mjc=", "number": 1397, "title": "Request for API Version Chaining Feature", "user": { "login": "dberlind", "id": 6643130, "node_id": "MDQ6VXNlcjY2NDMxMzA=", "avatar_url": "https://avatars.githubusercontent.com/u/6643130?v=4", "gravatar_id": "", "url": "https://api.github.com/users/dberlind", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 779922953, "node_id": "MDU6TGFiZWw3Nzk5MjI5NTM=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/OAI-scope", "name": "OAI-scope", "color": "bee884", "default": false, "description": null }, "1": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." }, "2": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 13, "created_at": "2017-11-02T17:05:28Z", "updated_at": "2025-09-21T18:56:09Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Hey all, after discussions with Marsh at API Strat, I'm putting forth a feature request that allows for better API version discovery. It's basically triplets (aka hypermedia) for versions. \r\n\r\nToday, the spec allows for notation of the current version. However, humans and machines have no way of knowing if, when \"interrogating\" an particular OAS file, if you're looking at the most current version, if there's a previous version, or if there's a next version. It'd be great if machines/humans could see where in the chain of versions, they are when looking at a specific spec.\r\n\r\nSo,\r\n```yaml\r\ninfo: \r\n version: 2.4.1 (this version)\r\n previousVersion: \r\n nextVersion: \r\n```\r\npretty simple. from there, machines/humans can take care of the rest.\r\n\r\nBackground here is that tooling should be able to monitor a spec file to spot changes to the API. However, unless it's a super minor change, then those changes trigger a new version and subsequently, those changes are reflected in a new spec file (as opposed to the existing spec file). But currently, there's no way for machines/humans to determine from a current spec file if another spec file exists.\r\n\r\nExtra credit might be another field to give some additional status as to the production-level of the current spec file. For example:\r\n```yaml\r\ninfo: \r\n version: 2.4.1 (this version)\r\n previousVersion: \r\n nextVersion: \r\n productionStatus: Pre-Release\r\n```\r\n\r\nThis might be more difficult as its effectiveness would require standard vocabulary which might trigger a difficult debate. But, if there's interest in this feature, I do have suggested vocabulary that spans everything from pre-release to deactivated.\r\n\r\nThank you.\r\n\r\nDavid Berlind\r\nProgrammableWeb", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1397/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1387", "id": 267799288, "node_id": "MDU6SXNzdWUyNjc3OTkyODg=", "number": 1387, "title": "Components fields name too restrictive?", "user": { "login": "PerthCharern", "id": 26418622, "node_id": "MDQ6VXNlcjI2NDE4NjIy", "avatar_url": "https://avatars.githubusercontent.com/u/26418622?v=4", "gravatar_id": "", "url": "https://api.github.com/users/PerthCharern", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484311864, "node_id": "LA_kwDOAQkWPc8AAAABgn6_OA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/examples", "name": "examples", "color": "DE7939", "default": false, "description": "requests for more or better examples in the specification" }, "1": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2017-10-23T20:04:49Z", "updated_at": "2024-08-21T11:04:26Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Components fields name currently has this regex as restrictions: `^[a-zA-Z0-9\\.\\-_]+$` \r\nThis was mainly discussed and agreed on in #634. \r\n\r\nI found this restriction a little too restrictive. I'd imagine that for the Schemas part of the component, most people will use class names as field names. Allowing the period (.) is good because that allows you to add namespace to class name `Namespace.ClassName`. \r\n\r\nHowever, quite a number of languages have generics and APIs can have request body that are of type implementing generics. The current allowed characters make it very difficult to represent class name that is derived from generic type. The most intuitive (I think) way to represent generic class name as string is to use some kind of brackets/parentheses `Namespace.GenericClassName(AnotherClassName)`. Of course, one can bypass this by using the allowed underscore or hyphen instead, but that just looks plain ugly.\r\n\r\nShould we allow parentheses and/or brackets?", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1387/reactions", "total_count": 1, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1364", "id": 262638091, "node_id": "MDU6SXNzdWUyNjI2MzgwOTE=", "number": 1364, "title": "Is it possible to group parameters ?", "user": { "login": "starinfor", "id": 29474843, "node_id": "MDQ6VXNlcjI5NDc0ODQz", "avatar_url": "https://avatars.githubusercontent.com/u/29474843?v=4", "gravatar_id": "", "url": "https://api.github.com/users/starinfor", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500266780, "node_id": "LA_kwDOAQkWPc8AAAABg3IzHA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref-group-combine", "name": "re-use: ref-group-combine", "color": "B714E4", "default": false, "description": "Re-use requests involving grouping components and combining groups" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 3, "created_at": "2017-10-04T01:13:12Z", "updated_at": "2025-09-21T18:20:27Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Is it possible to group parameters ? For ex: Header \"address\" has parameters street,city,state", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1364/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1323", "id": 251027580, "node_id": "MDU6SXNzdWUyNTEwMjc1ODA=", "number": 1323, "title": "Inconsistency in runtime expression examples for request headers", "user": { "login": "hkosova", "id": 8576823, "node_id": "MDQ6VXNlcjg1NzY4MjM=", "avatar_url": "https://avatars.githubusercontent.com/u/8576823?v=4", "gravatar_id": "", "url": "https://api.github.com/users/hkosova", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 2, "created_at": "2017-08-17T18:12:18Z", "updated_at": "2025-09-21T18:40:44Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "[Runtime expression examples](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#examples-1) include the following:\r\n\r\nSource Location | example expression | notes\r\n---|:---|:---|\r\nRequested media type | `$request.header.accept` | \r\nRequest parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers.\r\n\r\nThe 2nd example says that headers MUST be defined as parameters. But the 1st example refers to the `Accept` header which is [not allowed](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-10) in parameters.\r\n\r\nIs `$request.header.accept` is an invalid example? Or are runtime expressions supposed to access _any_ request headers?\r\n\r\n---\r\n\r\nSimilarly, the section about [callback path keys](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#key-expression) provides an example with the `Content-Type` header:\r\n\r\n```\r\n$request.header.content-Type\tapplication/json\r\n```\r\nLike `Accept`, `Content-Type` is not allowed in parameters. Is this example valid or not?", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1323/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1034", "id": 220980881, "node_id": "MDU6SXNzdWUyMjA5ODA4ODE=", "number": 1034, "title": "Permit multiple externalDocs", "user": { "login": "ghost", "id": 10137, "node_id": "MDQ6VXNlcjEwMTM3", "avatar_url": "https://avatars.githubusercontent.com/u/10137?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ghost", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 83806281, "node_id": "MDU6TGFiZWw4MzgwNjI4MQ==", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/enhancement", "name": "enhancement", "color": "a2eeef", "default": true, "description": "" }, "1": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." }, "2": { "id": 6500266780, "node_id": "LA_kwDOAQkWPc8AAAABg3IzHA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref-group-combine", "name": "re-use: ref-group-combine", "color": "B714E4", "default": false, "description": "Re-use requests involving grouping components and combining groups" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 19, "created_at": "2017-04-11T14:58:44Z", "updated_at": "2025-09-20T16:06:10Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Documenting APIs often depend on multiple external factors - functional and non-functional aspects, change notes, governance, strategy, many more - and a single externalDocs reference is often insufficient, especially in complex scenarios where multiple parties are responsible for design/deployment/delivery of these aspects (not everyone is DevOps)\r\n\r\nWould we want to move the single object to an array/collection of objects:\r\n```\r\nexternalDocs:\r\n- description: link 1\r\n url: http://link/1\r\n- description: link\r\n url: http://link/2\r\n```\r\nor\r\n```\r\nexternalDocs:\r\n link1:\r\n description: link 1\r\n url: http://link/1\r\n link2\r\n description: link\r\n url: http://link/2\r\n```\r\n Gong further, form 2 may also benefit from becoming a reference:\r\n```\r\nexternalDocs:\r\n link1:\r\n url: http://link/1\r\n\r\npaths:\r\n /path1:\r\n get:\r\n externalDocs:\r\n - $ref: '#/externalDocs/link1'\r\n```\r\n\r\nWhile some of this may overlap with (the single) externalDocs avaulable in a tag, it is not entirely overlapping, and the link should ideally reside close to where it is needed instead of tracking it back through a tag that may not be immediately apparent will contain the required link.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1034/reactions", "total_count": 49, "+1": 34, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 15, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/859", "id": 197311155, "node_id": "MDU6SXNzdWUxOTczMTExNTU=", "number": 859, "title": "Proposal: Having an example for an entire operation in one place (request + response)", "user": { "login": "amarzavery", "id": 4521223, "node_id": "MDQ6VXNlcjQ1MjEyMjM=", "avatar_url": "https://avatars.githubusercontent.com/u/4521223?v=4", "gravatar_id": "", "url": "https://api.github.com/users/amarzavery", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488251340, "node_id": "LA_kwDOAQkWPc8AAAABgrrbzA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/example%20obj/keywords", "name": "example obj/keywords", "color": "A08F3C", "default": false, "description": "Issues with the Example Object or exampel(s) keywords" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 5, "created_at": "2016-12-23T04:22:01Z", "updated_at": "2025-05-15T18:46:19Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "The current mechanism to provide examples for artifacts in a swagger spec is fragmented. It does not give the consumer an overview (or a bird's eye view) of an example to complete that operation successfully.\r\n\r\nIf the example object is opened up and can be provided per operation then this solves the problem. People can provide multiple examples (variations) for that operation. It can be very easily used for documenting and (live/mock) testing the API.\r\n\r\nPlease read the detailed proposal over [here](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md). Currently we have implemented an extension named **\"x-ms-examples\"** for our specs. The **schema** for this extension can be found [here](https://github.com/Azure/autorest/blob/master/schema/example-schema.json).\r\n\r\nIt would be nice to see what the community thinks about it and if it is possible to get this approach formally in the open api specification.", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/859/reactions", "total_count": 2, "+1": 1, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 1 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/833", "id": 188309115, "node_id": "MDU6SXNzdWUxODgzMDkxMTU=", "number": 833, "title": "Add optional field to the Operation object to indicate initial version containing the implementation", "user": { "login": "JamesMGreene", "id": 417751, "node_id": "MDQ6VXNlcjQxNzc1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/417751?v=4", "gravatar_id": "", "url": "https://api.github.com/users/JamesMGreene", "type": "User", "user_view_type": "public", "site_admin": true }, "labels": { "0": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 2, "created_at": "2016-11-09T17:45:11Z", "updated_at": "2024-08-05T14:02:28Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "I would love to add a version-related field to the Operation object (so per HTTP method of an Endpoint) that indicates the first version of the API that shipped with this functionality implemented.\r\n\r\nFor instance, the current API version is `18.0.0` but operation \"GET /api/v1/jobs\" was first shipped in version `17.1.0`.\r\n\r\nNice to know for backward compatibility.\r\n\r\nAlso nice for developers to keep track of what versions offer what features. 😜 ", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/833/reactions", "total_count": 5, "+1": 4, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 1 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/782", "id": 176094723, "node_id": "MDU6SXNzdWUxNzYwOTQ3MjM=", "number": 782, "title": "Enhanced Operation Deprecation and versioning", "user": { "login": "darrelmiller", "id": 447694, "node_id": "MDQ6VXNlcjQ0NzY5NA==", "avatar_url": "https://avatars.githubusercontent.com/u/447694?v=4", "gravatar_id": "", "url": "https://api.github.com/users/darrelmiller", "type": "User", "user_view_type": "public", "site_admin": true }, "labels": { "0": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 18, "created_at": "2016-09-09T19:54:16Z", "updated_at": "2025-09-20T16:05:12Z", "closed_at": null, "assignee": null, "author_association": "MEMBER", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Currently, OpenAPI allows us to identify the version of the API being described and deprecate operations using a Boolean value.\n\nI would like to propose some additional metadata that makes it easier to track changes to APIs.\nIn addition to the existing `deprecated` flag, there is now a `deprecatedVersion` and `replacementOperationId` property. \n\nConsider the following API and two of its operations:\n\n```\n{\n \"openapi\" : \"3.0.0\",\n \"info\" : {\n \"title\" : \"My API\",\n \"version\" : \"1.0.313\"\n }\n{\n \"/foo\" : {\n \"get\" : {\n \"operationId\" : \"getFoo\",\n \"description\" : \"Return a foo\",\n \"deprecated\" : true,\n \"deprecatedVersion\" : \"1.0.312\",\n \"replacementOperationId\" : \"getFoo2\"\n \"responses\" : {\n \"200\" : {\n \"description\" : \"A foo representation\"\n }\n } \n\n },\n \"/foo2\" : {\n \"get\" : {\n \"operationId\" : \"getFoo2\",\n \"description\" : \"Return a foo\",\n \"responses\" : {\n \"200\" : {\n \"description\" : \"A completely different breaking foo representation\" \n }\n } \n }\n }\n}\n}\n```\n\nThe `deprecatedVersion` property indicates the API version in which this operation was deprecated. The `replacementOperationId` provides a pointer to a new operation that replaces the functionality of the deprecated operation.\n\nThese new properties enable a variety of useful capabilities:\n- Display documentation that is relevant to a particular API version. Operations that were deprecated prior to that version can be hidden by default to prevent accidently usage of operations that have been replaced.\n- Help developers migrate to new operations by allowing documentation of deprecated operations to point to replacement operations. \n- Generate client code that only supports operations available in a particular API version.\n- Makes it possible to manage APIs to that are changing incrementally instead of doing big bang updates that completely replace a prior API.\n- Help developers identify what has changed in a new API release.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/782/reactions", "total_count": 6, "+1": 6, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/738", "id": 166160812, "node_id": "MDU6SXNzdWUxNjYxNjA4MTI=", "number": 738, "title": "Proposal: Support for HTTP compression", "user": { "login": "michaelkourlas", "id": 1672388, "node_id": "MDQ6VXNlcjE2NzIzODg=", "avatar_url": "https://avatars.githubusercontent.com/u/1672388?v=4", "gravatar_id": "", "url": "https://api.github.com/users/michaelkourlas", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 779922953, "node_id": "MDU6TGFiZWw3Nzk5MjI5NTM=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/OAI-scope", "name": "OAI-scope", "color": "bee884", "default": false, "description": null }, "1": { "id": 6487979546, "node_id": "LA_kwDOAQkWPc8AAAABgra2Gg", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/http", "name": "http", "color": "002288", "default": false, "description": "Supporting HTTP features and interactions" }, "2": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 14, "created_at": "2016-07-18T18:30:04Z", "updated_at": "2026-01-29T17:56:38Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "This is a proposal to add support for [HTTP compression](https://en.wikipedia.org/wiki/HTTP_compression) to version 3.0 of the OpenAPI specification.\n\n**Rationale for this change**\n\nAt present, there is no robust way to determine from an OpenAPI specification what HTTP encodings a server is willing to accept for requests or is willing to encode responses in.\n\nIt is possible to list the `Content-Encoding` and `Accept-Encoding` HTTP headers as optional parameters in request and response objects, but this approach is complex and difficult to understand. Moreover, other standard HTTP headers, such as `Accept`, `Content-Type` and `Authorization`, are already represented by dedicated `consumes`/`produces` and `security` attributes. \n\n**Proposed addition to the specification**\n\nOne way to implement support for HTTP compression would be to add a field to the OpenAPI Object called `\"compression\"` that maps to a Compression Object.\n\nThe Compression Object would have two fields, `\"consumes\"` and `\"produces\"`:\n- The `\"consumes\"` field would map to an array of strings; each string is an encoding that the API is willing to accept in HTTP requests. In other words, the server is prepared to accept requests with a `Content-Encoding` header with a value consisting of any one of the items in the array.\n- The `\"produces\"` field would map to an array of strings; each string is an encoding that the API is prepared to send in HTTP responses. In other words, the server is prepared to send responses with a `Content-Encoding` header with a value consisting of any one of the items in the array.\n\nIt may be a good idea to allow the global compression settings to be overridden on a per-path basis by adding a `\"compression\"` field to the Path Item Object as well.\n\n**Example**\n\nThe following snippet describes an API that can accept requests with a `Content-Encoding` of `gzip`, `deflate`, or `compress`, and is capable of sending responses with a `Content-Encoding` of `gzip` or `deflate`:\n\n``` json\n\"compression\": {\n \"consumes\": [\n \"gzip\",\n \"deflate\",\n \"compress\"\n ],\n \"produces\": [\n \"gzip\",\n \"deflate\"\n ]\n}\n```\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/738/reactions", "total_count": 15, "+1": 15, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/726", "id": 164387775, "node_id": "MDU6SXNzdWUxNjQzODc3NzU=", "number": 726, "title": "Clarification on the purpose of the API license?", "user": { "login": "harrisj", "id": 2044, "node_id": "MDQ6VXNlcjIwNDQ=", "avatar_url": "https://avatars.githubusercontent.com/u/2044?v=4", "gravatar_id": "", "url": "https://api.github.com/users/harrisj", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 733277536, "node_id": "MDU6TGFiZWw3MzMyNzc1MzY=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/review", "name": "review", "color": "27f92e", "default": false, "description": null }, "1": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "2": { "id": 6994562383, "node_id": "LA_kwDOAQkWPc8AAAABoOiNTw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/editorial", "name": "editorial", "color": "FFFF00", "default": false, "description": "Wording and stylistic issues" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 18, "created_at": "2016-07-07T19:24:48Z", "updated_at": "2025-09-15T08:39:55Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "In the Swagger 2.0 specification, there is support for adding a `License` as one of the informational fields and the description for this is `License information for the exposed API.`\n\nThis seems a bit ambiguous, since a license could potentially be understood to apply to one or more of the following contexts:\n1. **Use of the API.** This situation seems to be already handled by the `termsOfService` section though.\n2. **Data retrieved from the API**\n3. **The specification JSON/YAML for the API** indeed, there is a license for the Swagger 2 specification\n4. **Client/server code generated via swagger-codegen** could some licenses theoretically extend to that?\n\nI am guessing that the item 3 is the intended use for the license field, but I will admit that at first I thought it was meant for the first case and I could not see how a license would actually apply. Is it possible to get some clarification of how licenses should be picked here and where they do and do not apply?\n", "closed_by": { "login": "MikeRalphson", "id": 21603, "node_id": "MDQ6VXNlcjIxNjAz", "avatar_url": "https://avatars.githubusercontent.com/u/21603?v=4", "gravatar_id": "", "url": "https://api.github.com/users/MikeRalphson", "type": "User", "user_view_type": "public", "site_admin": false }, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/726/reactions", "total_count": 9, "+1": 9, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": "reopened", "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/690", "id": 154348863, "node_id": "MDU6SXNzdWUxNTQzNDg4NjM=", "number": 690, "title": "Structural improvements: enhance headers handling", "user": { "login": "arno-di-loreto", "id": 10104551, "node_id": "MDQ6VXNlcjEwMTA0NTUx", "avatar_url": "https://avatars.githubusercontent.com/u/10104551?v=4", "gravatar_id": "", "url": "https://api.github.com/users/arno-di-loreto", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500500244, "node_id": "LA_kwDOAQkWPc8AAAABg3XDFA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20globals/defaults", "name": "re-use: globals/defaults", "color": "1E431E", "default": false, "description": "Default or global components that can be overridden in some way" }, "1": { "id": 6518029811, "node_id": "LA_kwDOAQkWPc8AAAABhIE98w", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/headers", "name": "headers", "color": "FF21FF", "default": false, "description": "" } }, "state": "open", "locked": false, "assignees": {}, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "comments": 18, "created_at": "2016-05-11T21:37:27Z", "updated_at": "2024-11-21T22:40:52Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Following (again) ideas from OAI/OpenAPI-Specification#563 and OAI/sig-moonwalk#115, extending OAI/OpenAPI-Specification#369:\n- define reusable response headers (like parameters or definitions as proposed in OAI/OpenAPI-Specification#563 by @fehguy )\n- set responses headers on each level: whole api, path, operation, responses (and response as stated in OAI/OpenAPI-Specification#369)\n\n``` YAML\npaths:\n responseHeaders:\n # Headers returned on all api responses\n /resources:\n responseHeaders:\n # Headers returned on all /resources operations responses\n get:\n responseHeaders:\n # Headers returned on all operations responses\n 200:\n headers:\n # Headers returned on this response\nschemas:\n responseHeaders:\n # reusable headers describe with a Header Object, used with $ref\n```\n\nThe problem is the naming consistency: `responseHeaders` almost everywhere vs `headers` on response level.\nWhat if we use `headers` or `responseHeaders` everywhere?\n\nnb: and don't forget to modify Header Object to include OAI/OpenAPI-Specification#321 (required) \n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/690/reactions", "total_count": 39, "+1": 39, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/563", "id": 132826980, "node_id": "MDU6SXNzdWUxMzI4MjY5ODA=", "number": 563, "title": "Add default responses", "user": { "login": "fehguy", "id": 249413, "node_id": "MDQ6VXNlcjI0OTQxMw==", "avatar_url": "https://avatars.githubusercontent.com/u/249413?v=4", "gravatar_id": "", "url": "https://api.github.com/users/fehguy", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500500244, "node_id": "LA_kwDOAQkWPc8AAAABg3XDFA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20globals/defaults", "name": "re-use: globals/defaults", "color": "1E431E", "default": false, "description": "Default or global components that can be overridden in some way" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 26, "created_at": "2016-02-10T21:50:13Z", "updated_at": "2024-11-23T21:33:30Z", "closed_at": null, "assignee": null, "author_association": "CONTRIBUTOR", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Currently, every single operation must declare its' own responses. This causes a whole bunch of duplication, which would be better served by having a top-level `responses` section in the spec. Like the `security` construct, operations could override the default responses on their own.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/563/reactions", "total_count": 58, "+1": 58, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/541", "id": 126828146, "node_id": "MDU6SXNzdWUxMjY4MjgxNDY=", "number": 541, "title": "Adding optional SLA definitions with the Spec", "user": { "login": "pjmolina", "id": 713005, "node_id": "MDQ6VXNlcjcxMzAwNQ==", "avatar_url": "https://avatars.githubusercontent.com/u/713005?v=4", "gravatar_id": "", "url": "https://api.github.com/users/pjmolina", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 12, "created_at": "2016-01-15T08:29:31Z", "updated_at": "2024-02-08T19:40:30Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Related to [#51](https://github.com/OAI/OpenAPI-Specification/issues/51)\n\nWe have identified in the market a need for measuring and enforcement SLA in APIs. Specially, API vendors would benefit from an standard import of SLA metrics to measure and track importing them along with the OpenAPI definition in an standard way.\n\nIn this line, we have started a R&D project by [Icinetic](http://www.icinetic.com) and the [University of Seville](http://www.isa.us.es/) at Spain to work on: **\"Extension on OpenAPI for the definition of Service Level Agreements (SLA)\"**.\n\nThe project is looking forward to:\n1. Setup a basic and optional profile extension to describe a set of plan prices over APIs, Quota enforcement policies, constraints, etc. \n2. This information can (always optionally) decorate the OpenAPI spec inline on in a side file/resource linked from the main spec.\n3. Third party tools like [Hivepod](https://www.hivepod.io/): can generate both: Swagger spec, service implementation, and SLA policy + SLA enforcement code, data repository to store the metrics and tools for analysis\n4. Third party tools like API Management tools can use this SLA info also to measure and track the level of compliant with respect this SLA specified.\n5. The ISA Research Group in the University of Seville is looking forward to provide tools for validation, creation and verification of SLAs for free.\n6. We will provide a reference implementation showing the full scenario: from sample Microservice being measured, using a data store to gather metrics and an analysis tool to visualize the SLA grade of compliance.\n7. Eventually, we would love to contribute to OAI (next version) with an open source extension for SLA definition.\n\nLooking forward for early feedback and to join forces with OAI wanting to support an extension for this in an standardized way. \n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/541/reactions", "total_count": 5, "+1": 5, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/508", "id": 116909071, "node_id": "MDU6SXNzdWUxMTY5MDkwNzE=", "number": 508, "title": "No provision to group API's and then $ref it to reference it in other file", "user": { "login": "mkeshavgarg", "id": 12976775, "node_id": "MDQ6VXNlcjEyOTc2Nzc1", "avatar_url": "https://avatars.githubusercontent.com/u/12976775?v=4", "gravatar_id": "", "url": "https://api.github.com/users/mkeshavgarg", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500266780, "node_id": "LA_kwDOAQkWPc8AAAABg3IzHA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20ref-group-combine", "name": "re-use: ref-group-combine", "color": "B714E4", "default": false, "description": "Re-use requests involving grouping components and combining groups" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 5, "created_at": "2015-11-14T07:47:42Z", "updated_at": "2024-02-08T19:40:31Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "In our application, we have apis divided among various modules.\n\nAs per swagger-spec, It becomes very difficult to have only one swagger file (api-docs) for all the modules considering the number of apis and also number of teams working on various modules.\n\nSo I started using $ref (purpose: same folder reference) and third party swagger parsers to dereference it. But I still cannot figure out a way in swagger to group apis with one $ref. \nSo that I can assign all apis for a particular module to a team and then just $ref in api-docs that can be dereferenced lately to get complete single api-docs file\n\nEg:\n\n```\n//something like that\n{\n 'pet' : '$ref': './pet.json',\n 'user' :'$ref': './user.json'\n}\n```\n\nWhich when dereferenced, will change to\n\n```\n{\n '/pet' : {},\n '/pet/{name}' : {},\n 'change/pet' : {},\n '/user': {},\n '/user/data': {}\n}\n```\n\nAny help would be appreciated.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/508/reactions", "total_count": 0, "+1": 0, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/369", "id": 77947179, "node_id": "MDU6SXNzdWU3Nzk0NzE3OQ==", "number": 369, "title": "Share header with multiple response objects", "user": { "login": "huangsam", "id": 515617, "node_id": "MDQ6VXNlcjUxNTYxNw==", "avatar_url": "https://avatars.githubusercontent.com/u/515617?v=4", "gravatar_id": "", "url": "https://api.github.com/users/huangsam", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6500500244, "node_id": "LA_kwDOAQkWPc8AAAABg3XDFA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/re-use:%20globals/defaults", "name": "re-use: globals/defaults", "color": "1E431E", "default": false, "description": "Default or global components that can be overridden in some way" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 12, "created_at": "2015-05-19T05:54:46Z", "updated_at": "2026-02-21T12:25:10Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Can there not just be a simple header generically at the response level not specific to each of the status codes? For our case, this kind of header is 99% the same across our codebase.\n\n``` yaml\n\n---\n\nresponses:\n 200:\n description: no error\n headers:\n Content-Type:\n description: application/json\n type: string\n```\n\nIt would be a pain to copy+paste this to each and every routine that supports HTTP JSON responses.\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/369/reactions", "total_count": 13, "+1": 13, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/213", "id": 49425922, "node_id": "MDU6SXNzdWU0OTQyNTkyMg==", "number": 213, "title": "Allow for overloading/aliasing of route path", "user": { "login": "brandonscript", "id": 1480253, "node_id": "MDQ6VXNlcjE0ODAyNTM=", "avatar_url": "https://avatars.githubusercontent.com/u/1480253?v=4", "gravatar_id": "", "url": "https://api.github.com/users/brandonscript", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 6487382687, "node_id": "LA_kwDOAQkWPc8AAAABgq2anw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/request%20matching", "name": "request matching", "color": "C2E0C6", "default": false, "description": "Matching requests to URL templates, media types, etc." }, "1": { "id": 6488285115, "node_id": "LA_kwDOAQkWPc8AAAABgrtfuw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/versioning", "name": "versioning", "color": "EAB042", "default": false, "description": "describing versions of APIs/endpoints/operations" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 34, "created_at": "2014-11-19T17:28:32Z", "updated_at": "2024-02-08T19:40:36Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Per this question: http://stackoverflow.com/questions/27004847/provide-alternate-international-spelling-for-defined-swagger-route/27013027#27013027\n\nIt would be great to allow aliasing of route paths for such uses as international spellings of words\n", "closed_by": null, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/213/reactions", "total_count": 8, "+1": 8, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/61", "id": 34173943, "node_id": "MDU6SXNzdWUzNDE3Mzk0Mw==", "number": 61, "title": "Add support for an OAuth 1.0 authorization scheme", "user": { "login": "cfournie", "id": 49264, "node_id": "MDQ6VXNlcjQ5MjY0", "avatar_url": "https://avatars.githubusercontent.com/u/49264?v=4", "gravatar_id": "", "url": "https://api.github.com/users/cfournie", "type": "User", "user_view_type": "public", "site_admin": false }, "labels": { "0": { "id": 861884514, "node_id": "MDU6TGFiZWw4NjE4ODQ1MTQ=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security", "name": "security", "color": "b20805", "default": false, "description": "" }, "1": { "id": 6502391379, "node_id": "LA_kwDOAQkWPc8AAAABg5KeUw", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/security:%20auth", "name": "security: auth", "color": "B60205", "default": false, "description": "Authentication including overlap with authorization" } }, "state": "open", "locked": false, "assignees": {}, "milestone": null, "comments": 42, "created_at": "2014-05-23T13:20:43Z", "updated_at": "2024-10-03T15:56:44Z", "closed_at": null, "assignee": null, "author_association": "NONE", "type": null, "active_lock_reason": null, "sub_issues_summary": { "total": 0, "completed": 0, "percent_completed": 0 }, "issue_dependencies_summary": { "blocked_by": 0, "total_blocked_by": 0, "blocking": 0, "total_blocking": 0 }, "body": "Currently, the Swagger 1.2 specification supports three authorization schemes: basic authentication, API key and OAuth2. One popular scheme that is missing is [OAuth 1.0](http://tools.ietf.org/html/rfc5849); can it be added to the next specification version?\n", "closed_by": { "login": "RobDolinMS", "id": 8301581, "node_id": "MDQ6VXNlcjgzMDE1ODE=", "avatar_url": "https://avatars.githubusercontent.com/u/8301581?v=4", "gravatar_id": "", "url": "https://api.github.com/users/RobDolinMS", "type": "User", "user_view_type": "public", "site_admin": false }, "reactions": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/61/reactions", "total_count": 15, "+1": 15, "-1": 0, "laugh": 0, "hooray": 0, "confused": 0, "heart": 0, "rocket": 0, "eyes": 0 }, "performed_via_github_app": null, "state_reason": null, "pinned_comment": null, "linked_prs": [] } ], "pulls": [ { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5230", "id": 3342967735, "node_id": "PR_kwDOAQkWPc7HQaO3", "number": 5230, "state": "open", "locked": false, "title": "Bump respec from 35.7.0 to 35.8.0", "user": { "login": "dependabot[bot]", "id": 49699333, "node_id": "MDM6Qm90NDk2OTkzMzM=", "avatar_url": "https://avatars.githubusercontent.com/in/29110?v=4", "gravatar_id": "", "url": "https://api.github.com/users/dependabot%5Bbot%5D", "type": "Bot", "user_view_type": "public", "site_admin": false }, "body": "Bumps [respec](https://github.com/speced/respec) from 35.7.0 to 35.8.0.\n
\nRelease notes\n

Sourced from respec's releases.

\n
\n

v35.8.0

\n

Enhancements

\n\n

Full Changelog: https://github.com/speced/respec/compare/v35.7.0...v35.8.0

\n
\n
\n
\nCommits\n\n
\n
\n\n\n[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=respec&package-manager=npm_and_yarn&previous-version=35.7.0&new-version=35.8.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)\n\nDependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`.\n\n[//]: # (dependabot-automerge-start)\n[//]: # (dependabot-automerge-end)\n\n---\n\n
\nDependabot commands and options\n
\n\nYou can trigger Dependabot actions by commenting on this PR:\n- `@dependabot rebase` will rebase this PR\n- `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it\n- `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency\n- `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)\n- `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)\n- `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)\n\n\n
", "created_at": "2026-03-02T07:43:56Z", "updated_at": "2026-03-02T07:43:57Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "140057d50769312db7200de8b88ecc2a23775108", "assignees": {}, "requested_reviewers": {}, "requested_teams": {}, "labels": { "0": { "id": 6190304304, "node_id": "LA_kwDOAQkWPc8AAAABcPiMMA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/dependencies", "name": "dependencies", "color": "0366d6", "default": false, "description": "Pull requests that update a dependency file" }, "1": { "id": 7210051804, "node_id": "LA_kwDOAQkWPc8AAAABrcCo3A", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/javascript", "name": "javascript", "color": "168700", "default": false, "description": "Pull requests that update Javascript code" } }, "milestone": null, "draft": false, "head": { "label": "OAI:dependabot/npm_and_yarn/respec-35.8.0", "ref": "dependabot/npm_and_yarn/respec-35.8.0", "sha": "cd72fd5a4b283a9b621c08c8c63ab7513bbd11f7", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "base": { "label": "OAI:main", "ref": "main", "sha": "e6646689c1daa50712ca407fca08d17e9a4eb3ae", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5230" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/5230" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5230" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5230/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5230/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5230/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/cd72fd5a4b283a9b621c08c8c63ab7513bbd11f7" } }, "author_association": "CONTRIBUTOR", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [ 5 ] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5229", "id": 3339105498, "node_id": "PR_kwDOAQkWPc7HBrTa", "number": 5229, "state": "open", "locked": false, "title": "schema-publish: Use commit date instead of author date", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "- Use commit date of last change to construct schema file names instead of author date\r\n - the date a change was merged into the spec version dev branch is easier to track/understand than the date the author made that change in their local repo\r\n- Improve console output of what happened why\r\n\r\n----\r\n\r\n- [x] no schema changes are needed for this pull request\r\n", "created_at": "2026-02-28T17:37:06Z", "updated_at": "2026-03-01T17:39:28Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "b153748006bdc93b4358771d5b38aa35e023ac43", "assignees": {}, "requested_reviewers": {}, "requested_teams": {}, "labels": {}, "milestone": null, "draft": false, "head": { "label": "ralfhandl:main-schema-publish-improved-console-output", "ref": "main-schema-publish-improved-console-output", "sha": "f4d2f058445543e61d84a6bde6eb8ec083d75607", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 797974223, "node_id": "R_kgDOL5Aezw", "name": "OpenAPI-Specification", "full_name": "ralfhandl/OpenAPI-Specification", "private": false, "owner": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "Fork of the OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/ralfhandl/OpenAPI-Specification", "created_at": "2024-05-08T21:01:03Z", "updated_at": "2026-02-27T03:11:36Z", "pushed_at": "2026-02-28T17:18:47Z", "homepage": "", "size": 5955, "stargazers_count": 1, "watchers_count": 1, "language": "Markdown", "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 0, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 0, "watchers": 1, "default_branch": "fork-main" } }, "base": { "label": "OAI:main", "ref": "main", "sha": "e6646689c1daa50712ca407fca08d17e9a4eb3ae", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5229" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/5229" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5229" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5229/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5229/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5229/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/f4d2f058445543e61d84a6bde6eb8ec083d75607" } }, "author_association": "CONTRIBUTOR", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5212", "id": 3317563942, "node_id": "PR_kwDOAQkWPc7FvgIm", "number": 5212, "state": "open", "locked": false, "title": "Fix http QUERY method link text to match its url", "user": { "login": "valerii15298", "id": 44531564, "node_id": "MDQ6VXNlcjQ0NTMxNTY0", "avatar_url": "https://avatars.githubusercontent.com/u/44531564?v=4", "gravatar_id": "", "url": "https://api.github.com/users/valerii15298", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "The text of link points to an older version of QUERY method draft(08), while actual url points to newer one(11). Changed text to match the url\r\n\r\n\r\n\r\n- [ ] schema changes are included in this pull request\r\n- [ ] schema changes are needed for this pull request but not done yet\r\n- [x] no schema changes are needed for this pull request\r\n", "created_at": "2026-02-23T20:24:24Z", "updated_at": "2026-02-27T10:56:03Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "fc14d6eaf1ac2e5b4282fa055f8d36785095dd23", "assignees": {}, "requested_reviewers": { "0": { "login": "miqui", "id": 5511018, "node_id": "MDQ6VXNlcjU1MTEwMTg=", "avatar_url": "https://avatars.githubusercontent.com/u/5511018?v=4", "gravatar_id": "", "url": "https://api.github.com/users/miqui", "type": "User", "user_view_type": "public", "site_admin": false } }, "requested_teams": {}, "labels": {}, "milestone": null, "draft": false, "head": { "label": "valerii15298:patch-8", "ref": "patch-8", "sha": "e66c0e52a05e22543f8746e46fac03e529af3088", "user": { "login": "valerii15298", "id": 44531564, "node_id": "MDQ6VXNlcjQ0NTMxNTY0", "avatar_url": "https://avatars.githubusercontent.com/u/44531564?v=4", "gravatar_id": "", "url": "https://api.github.com/users/valerii15298", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 1063149964, "node_id": "R_kgDOP15hjA", "name": "OpenAPI-Specification", "full_name": "valerii15298/OpenAPI-Specification", "private": false, "owner": { "login": "valerii15298", "id": 44531564, "node_id": "MDQ6VXNlcjQ0NTMxNTY0", "avatar_url": "https://avatars.githubusercontent.com/u/44531564?v=4", "gravatar_id": "", "url": "https://api.github.com/users/valerii15298", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/valerii15298/OpenAPI-Specification", "created_at": "2025-09-24T08:29:15Z", "updated_at": "2025-09-24T08:29:15Z", "pushed_at": "2026-02-24T15:56:29Z", "homepage": "https://openapis.org", "size": 10066, "stargazers_count": 0, "watchers_count": 0, "language": null, "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 0, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 0, "watchers": 0, "default_branch": "main" } }, "base": { "label": "OAI:v3.3-dev", "ref": "v3.3-dev", "sha": "edfb9602af3c706e34ee33213718d4dad8043a77", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5212" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/5212" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5212" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5212/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5212/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5212/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/e66c0e52a05e22543f8746e46fac03e529af3088" } }, "author_association": "NONE", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5204", "id": 3277703606, "node_id": "PR_kwDOAQkWPc7DXcm2", "number": 5204, "state": "open", "locked": false, "title": "v3.3 trial balloon: JSON-Compatible Data section", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "* Addresses #5140 (beyond putting `text/toon` in the media type registry, which has already been done).\r\n\r\nThere's a bit of a question if we want to mention TOON in the spec because of the LLM connection and its use in LLM-related HTTP APIs. I was looking for where to put it and noticed the \"[JSON Data](https://spec.openapis.org/oas/v3.2.0.html#json-data)\" and \"[Non-JSON Data](https://spec.openapis.org/oas/v3.2.0.html#non-json-data)\" sections, and thought maybe a \"JSON-Compatible Data\" section would fit in between them.\r\n\r\nPros of this approach:\r\n* It is a valid class of formats that doesn't quite fit either section\r\n* It lets us treat TOON as one of several things rather than promoting it specifically in a way that might seem dated in another year or two\r\n\r\nCons of this approach:\r\n* Unlike our sections on `text/event-stream`, `multipart`, and `form-urlencoded`, TOON would not appear in the Table of Contents\r\n* The other examples here (TOML and YAML) are popular formats, but not ones that are all that frequently used in HTTP APIs as far as I know (although obviously we use YAML for authoring OADs), so I'm not sure we want to call attention to them here (this is why they're not in the Media Type Registry- I did consider including them and decided not to).\r\n\r\nAdditional questions:\r\n* Should the format name (TOON, TOML, YAML) and acronym expansions (Token-Oriented Object Notation, Tom's Obvious Minimal Language, YAML Ain't a Markup Language) be included in addition to the media types?\r\n\r\nI'm fine with this going in, or reworking it substantially, or dropping the idea and closing #5140 as completed based on the media type registry entry. But I figured it would be easier to discuss a concrete change than the abstract.\r\n\r\n\"Screenshot\r\n\r\n\r\n- [X] no schema changes are needed for this pull request\r\n", "created_at": "2026-02-12T19:01:00Z", "updated_at": "2026-02-12T21:37:38Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "84a0300f07f84a665625806f8e9563ef6ec027bc", "assignees": {}, "requested_reviewers": {}, "requested_teams": {}, "labels": { "0": { "id": 6484314664, "node_id": "LA_kwDOAQkWPc8AAAABgn7KKA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/clarification", "name": "clarification", "color": "1D76DB", "default": false, "description": "requests to clarify, but not change, part of the spec" }, "1": { "id": 6487319529, "node_id": "LA_kwDOAQkWPc8AAAABgqyj6Q", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/media%20and%20encoding", "name": "media and encoding", "color": "C8CF04", "default": false, "description": "Issues regarding media type support and how to encode data (outside of query/path params)" } }, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "draft": false, "head": { "label": "handrews:json-compat", "ref": "json-compat", "sha": "18a125b16b85d8593a9188946578be490323c06e", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 123813998, "node_id": "MDEwOlJlcG9zaXRvcnkxMjM4MTM5OTg=", "name": "OpenAPI-Specification", "full_name": "handrews/OpenAPI-Specification", "private": false, "owner": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/handrews/OpenAPI-Specification", "created_at": "2018-03-04T17:56:28Z", "updated_at": "2026-02-05T19:03:15Z", "pushed_at": "2026-02-12T18:51:28Z", "homepage": "https://openapis.org", "size": 9316, "stargazers_count": 1, "watchers_count": 1, "language": "Markdown", "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": true, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 0, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 0, "watchers": 1, "default_branch": "main" } }, "base": { "label": "OAI:v3.3-dev", "ref": "v3.3-dev", "sha": "39af4a7729691b1bc0792278304beb1e9535c18c", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5204" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/5204" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5204" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5204/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5204/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5204/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/18a125b16b85d8593a9188946578be490323c06e" } }, "author_association": "MEMBER", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [ 5 ] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5192", "id": 3224505711, "node_id": "PR_kwDOAQkWPc7AMg1v", "number": 5192, "state": "open", "locked": false, "title": "dev: sync with main", "user": { "login": "oai-spec-publisher[bot]", "id": 192531091, "node_id": "BOT_kgDOC3nKkw", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/oai-spec-publisher%5Bbot%5D", "type": "Bot", "user_view_type": "public", "site_admin": false }, "body": "Merge relevant changes from `main` into `dev`.", "created_at": "2026-01-29T17:53:56Z", "updated_at": "2026-03-04T23:21:14Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "d7853cd9ab359e93fb54f212ecada7d97dc0149d", "assignees": {}, "requested_reviewers": {}, "requested_teams": {}, "labels": { "0": { "id": 693593339, "node_id": "MDU6TGFiZWw2OTM1OTMzMzk=", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/Housekeeping", "name": "Housekeeping", "color": "41C8B8", "default": false, "description": "" } }, "milestone": null, "draft": false, "head": { "label": "OAI:dev-sync-with-main", "ref": "dev-sync-with-main", "sha": "03ed04f4d04713ac0557dacf1699af41fe97ea2a", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "base": { "label": "OAI:dev", "ref": "dev", "sha": "f39f7f01cc0fab6254d1a3cebda7e87316432a48", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5192" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/5192" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5192" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5192/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5192/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5192/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/03ed04f4d04713ac0557dacf1699af41fe97ea2a" } }, "author_association": "CONTRIBUTOR", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5095", "id": 2967269939, "node_id": "PR_kwDOAQkWPc6w3PIz", "number": 5095, "state": "open", "locked": false, "title": "3.3: schema tests for unevaluatedProperties", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "Many Objects defined in the spec don't allow additional properties.\r\n\r\nTest these by taking a minimal instance that passes, inject a property with a very unlikely name and verify that it fails.\r\n\r\n- New \"fail\" test cases for Discriminator Object and External Documentation Object within a Schema Object, defined in `meta.yaml`\r\n- Table-driven test for Objects defined in `schema.yaml` with test cases in file `minimal-objects.yaml`\r\n\r\nThis brings subschema (\"function\") test coverage up to 100%.\r\n\r\n----\r\n\r\n- [x] no schema changes are needed for this pull request\r\n", "created_at": "2025-10-31T15:59:02Z", "updated_at": "2026-02-28T16:16:01Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "3bd7f88b11bc9665ee40c16a1764bdaaae513893", "assignees": {}, "requested_reviewers": { "0": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false } }, "requested_teams": {}, "labels": {}, "milestone": null, "draft": false, "head": { "label": "ralfhandl:3.3-test-unevaluatedProperrties", "ref": "3.3-test-unevaluatedProperrties", "sha": "0cf186dd5c5f95464a42d5ce196e2a1008973ae1", "user": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 797974223, "node_id": "R_kgDOL5Aezw", "name": "OpenAPI-Specification", "full_name": "ralfhandl/OpenAPI-Specification", "private": false, "owner": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "Fork of the OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/ralfhandl/OpenAPI-Specification", "created_at": "2024-05-08T21:01:03Z", "updated_at": "2026-02-27T03:11:36Z", "pushed_at": "2026-02-28T17:18:47Z", "homepage": "", "size": 5955, "stargazers_count": 1, "watchers_count": 1, "language": "Markdown", "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 0, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 0, "watchers": 1, "default_branch": "fork-main" } }, "base": { "label": "OAI:v3.3-dev", "ref": "v3.3-dev", "sha": "7707a82339c2106baa87bf46fb47be75a7c25247", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5095" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/5095" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5095" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/5095/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5095/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/5095/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/0cf186dd5c5f95464a42d5ce196e2a1008973ae1" } }, "author_association": "CONTRIBUTOR", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4997", "id": 2861612205, "node_id": "PR_kwDOAQkWPc6qkLyt", "number": 4997, "state": "open", "locked": false, "title": "3.0: disallow component names not conforming to the pattern", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "closes #3720 and #2439.\r\n\r\n- [X] schema changes are included in this pull request\r\n", "created_at": "2025-09-25T18:35:04Z", "updated_at": "2025-11-06T19:34:11Z", "closed_at": null, "merged_at": null, "merge_commit_sha": null, "assignees": {}, "requested_reviewers": {}, "requested_teams": {}, "labels": {}, "milestone": null, "draft": true, "head": { "label": "karenetheridge:ether/v3.0-components-constraints", "ref": "ether/v3.0-components-constraints", "sha": "b56237507606b24db3a2fe3c1e06d53f7a959fbb", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 393157068, "node_id": "MDEwOlJlcG9zaXRvcnkzOTMxNTcwNjg=", "name": "OpenAPI-Specification", "full_name": "karenetheridge/OpenAPI-Specification", "private": false, "owner": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/karenetheridge/OpenAPI-Specification", "created_at": "2021-08-05T19:57:43Z", "updated_at": "2025-10-14T01:49:32Z", "pushed_at": "2026-02-27T18:08:50Z", "homepage": "https://openapis.org", "size": 6089, "stargazers_count": 1, "watchers_count": 1, "language": "JavaScript", "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": true, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 1, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 1, "watchers": 1, "default_branch": "main" } }, "base": { "label": "OAI:v3.0-dev-wip", "ref": "v3.0-dev-wip", "sha": "1d84892f69b18855be6ebc7a1bd66204c913e5d7", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4997" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/4997" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4997" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4997/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4997/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4997/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/b56237507606b24db3a2fe3c1e06d53f7a959fbb" } }, "author_association": "MEMBER", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [ 3, 2, 3720 ] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4929", "id": 2808750147, "node_id": "PR_kwDOAQkWPc6naiBD", "number": 4929, "state": "open", "locked": false, "title": "Make patch optional in openapi field.", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "See discussion #4233 and issue #4147. Requiring the patch version is creating tremendous amounts of confusion. While we cannot seem to reach consensus on forbidding it, there has long been a consensus on not requiring it. Let's at least do that.\r\n\r\nAlso, the regex in the schema allowed for `-something` in the `openapi` field, which is not part of the OAS field definition at all so I removed it. We used to do `-rcN` releases, but we have no plan to do so for 3.2 anyway, and we ought not further overload an already confusing mechanism. If we need to note a pre-release version in the future, let's add a field for it.\r\n\r\n- [X] schema changes are included in this pull request\r\n", "created_at": "2025-09-08T15:52:18Z", "updated_at": "2025-11-24T12:22:27Z", "closed_at": null, "merged_at": null, "merge_commit_sha": null, "assignees": {}, "requested_reviewers": { "0": { "login": "lornajane", "id": 172607, "node_id": "MDQ6VXNlcjE3MjYwNw==", "avatar_url": "https://avatars.githubusercontent.com/u/172607?v=4", "gravatar_id": "", "url": "https://api.github.com/users/lornajane", "type": "User", "user_view_type": "public", "site_admin": false }, "1": { "login": "earth2marsh", "id": 54582, "node_id": "MDQ6VXNlcjU0NTgy", "avatar_url": "https://avatars.githubusercontent.com/u/54582?v=4", "gravatar_id": "", "url": "https://api.github.com/users/earth2marsh", "type": "User", "user_view_type": "public", "site_admin": false }, "2": { "login": "ralfhandl", "id": 951576, "node_id": "MDQ6VXNlcjk1MTU3Ng==", "avatar_url": "https://avatars.githubusercontent.com/u/951576?v=4", "gravatar_id": "", "url": "https://api.github.com/users/ralfhandl", "type": "User", "user_view_type": "public", "site_admin": false } }, "requested_teams": {}, "labels": { "0": { "id": 6488283496, "node_id": "LA_kwDOAQkWPc8AAAABgrtZaA", "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/labels/metadata", "name": "metadata", "color": "006b75", "default": false, "description": "tags, info, license, contact, markdown usage, etc." } }, "milestone": { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/milestones/18", "id": 11933973, "node_id": "MI_kwDOAQkWPc4AthkV", "number": 18, "title": "v3.3.0", "description": "The 3.3 release will follow immediately from 3.2, but contain the items that would have otherwise substantially delayed 3.2's release. It will be strictly compatible with both 3.1 and 3.2.\r\n\r\nAt the time this milestone was created, 3.3 is expected to have more comprehensive updates to parameters, form data modeling, and security configurations. These new approaches will be created alongside the older, complex approaches, which will be frozen (but still supported). The intent is for the new approaches to be incremental steps towards Moonwalk, where the older approaches will be dropped.", "creator": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "open_issues": 23, "closed_issues": 15, "state": "open", "created_at": "2024-11-21T18:10:27Z", "updated_at": "2026-02-12T19:01:27Z", "due_on": "2026-09-03T00:00:00Z", "closed_at": null }, "draft": true, "head": { "label": "handrews:opt-patch", "ref": "opt-patch", "sha": "1025758791edfa7c1b3775617fc866643508c4c2", "user": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 123813998, "node_id": "MDEwOlJlcG9zaXRvcnkxMjM4MTM5OTg=", "name": "OpenAPI-Specification", "full_name": "handrews/OpenAPI-Specification", "private": false, "owner": { "login": "handrews", "id": 2358015, "node_id": "MDQ6VXNlcjIzNTgwMTU=", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?v=4", "gravatar_id": "", "url": "https://api.github.com/users/handrews", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/handrews/OpenAPI-Specification", "created_at": "2018-03-04T17:56:28Z", "updated_at": "2026-02-05T19:03:15Z", "pushed_at": "2026-02-12T18:51:28Z", "homepage": "https://openapis.org", "size": 9316, "stargazers_count": 1, "watchers_count": 1, "language": "Markdown", "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": true, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 0, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 0, "watchers": 1, "default_branch": "main" } }, "base": { "label": "OAI:v3.3-dev", "ref": "v3.3-dev", "sha": "1919217a6dd07820557d7f9ce9231b1704a86680", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4929" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/4929" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4929" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4929/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4929/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4929/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/1025758791edfa7c1b3775617fc866643508c4c2" } }, "author_association": "MEMBER", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [ 4 ] }, { "url": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4926", "id": 2805692383, "node_id": "PR_kwDOAQkWPc6nO3ff", "number": 4926, "state": "open", "locked": false, "title": "uri resolution notes", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "body": "Not intended for merging in this form.\r\n\r\nNotes on my initial thoughts on how each uri-reference in the OAD should resolve.\r\n\r\nSee https://github.com/OAI/OpenAPI-Specification/discussions/4925#discussioncomment-14329850.", "created_at": "2025-09-07T03:39:42Z", "updated_at": "2026-01-25T22:10:03Z", "closed_at": null, "merged_at": null, "merge_commit_sha": "2f2fe9165fec7f60f14df96131df7304300783ec", "assignees": {}, "requested_reviewers": {}, "requested_teams": {}, "labels": {}, "milestone": null, "draft": true, "head": { "label": "karenetheridge:ether/v3.2-uri-resolution-notes", "ref": "ether/v3.2-uri-resolution-notes", "sha": "43316da33d51883da4c8d2744a0b1c4ce9feda45", "user": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "repo": { "id": 393157068, "node_id": "MDEwOlJlcG9zaXRvcnkzOTMxNTcwNjg=", "name": "OpenAPI-Specification", "full_name": "karenetheridge/OpenAPI-Specification", "private": false, "owner": { "login": "karenetheridge", "id": 303051, "node_id": "MDQ6VXNlcjMwMzA1MQ==", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4", "gravatar_id": "", "url": "https://api.github.com/users/karenetheridge", "type": "User", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": true, "url": "https://api.github.com/repos/karenetheridge/OpenAPI-Specification", "created_at": "2021-08-05T19:57:43Z", "updated_at": "2025-10-14T01:49:32Z", "pushed_at": "2026-02-27T18:08:50Z", "homepage": "https://openapis.org", "size": 6089, "stargazers_count": 1, "watchers_count": 1, "language": "JavaScript", "has_issues": false, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": true, "has_discussions": false, "forks_count": 0, "archived": false, "disabled": false, "open_issues_count": 1, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": {}, "visibility": "public", "forks": 0, "open_issues": 1, "watchers": 1, "default_branch": "main" } }, "base": { "label": "OAI:v3.2-dev", "ref": "v3.2-dev", "sha": "2933fe980be62544e2e5bb6571b42119994f31e2", "user": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "repo": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main" } }, "_links": { "self": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4926" }, "html": { "href": "https://github.com/OAI/OpenAPI-Specification/pull/4926" }, "issue": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4926" }, "comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/issues/4926/comments" }, "review_comments": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4926/comments" }, "review_comment": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}" }, "commits": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/4926/commits" }, "statuses": { "href": "https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/43316da33d51883da4c8d2744a0b1c4ce9feda45" } }, "author_association": "MEMBER", "auto_merge": null, "assignee": null, "active_lock_reason": null, "linked_issues": [] } ], "discussions": [ { "id": "D_kwDOAQkWPc4Akf48", "number": 5232, "title": "Proposed: Add oasdoc notation for linking to API elements", "body": "# Proposal: oasdoc\r\n\r\nSeveral programming languages support documentation annotations which\r\nmake it convenient to author more comprehensive documentation by\r\nallowing hyperlinks bewteen language elements.\r\n\r\n* Java has [`javadoc`](https://docs.oracle.com/en/java/javase/18/docs/specs/javadoc/doc-comment-spec.html)\r\n* Javascript has [`jsdoc`](https://jsdoc.app/).\r\n\r\nI propose OAS devise conventions for embedded documentation links in the\r\nOpenAPI source, so that tools (such as API doc rendering tools) can\r\nsupport well-known documentation anchors for OAS elements such as operations\r\nand schemas, and that `description` strings in OAS elements and\r\nexternal web pages can add links to those elements in a manner that is\r\nagnostic to the tool vendor.\r\n\r\n## Justification\r\n\r\nBy adding `oasdoc` as an extension or convention of the OpenAPI\r\nSpecification, API authors can use a tool-agnostic way to ennhance API\r\ndocumentation, so developers can render the API doc consistently across\r\ndifferent OAS-compliant tools.\r\n\r\nDownstream API consumers should be able to download an\r\nOpenAPI description from an API vendor's developer portal or open source\r\nrepository and render API documentation with the tool of their choice.\r\n\r\nFor example, it is useful to provide a summary of an APIs capabilities\r\nin the `info.description` Markdown text, and link to the important API\r\noperations. Some vendors may create anchors for each `operationId` but\r\nthere is no standard or convention.\r\n\r\nFor example, given the\r\n[The Train Travel API](https://bump.sh/bump-examples/doc/train-travel-api/)\r\nfrom bump.sh :\r\n\r\n```yaml\r\npaths:\r\n /stations:\r\n get:\r\n summary: Get a list of train stations\r\n description: Returns a paginated and searchable list of all train stations.\r\n operationId: get-stations\r\n```\r\n\r\nAdding infdormational links to the\r\nthe top-level `info.description` makes it easier to highlight\r\nthe important operations in the API:\r\n\r\n```markdown\r\n* To fetch a list of train stations, use the {@op list-stations} operation.\r\n* To fetch a list of reserved train trips, use the {@op list-trips} operation.\r\n* ... and so on\r\n```\r\n\r\n## API Documentation Vendor Differences\r\n\r\n### bump.sh\r\n\r\n`bump.sh` generates a URL for each operation.\r\n\r\nwhich does not even yield an anchor; it yields a unique URL such as\r\n\r\n`https://bump.sh/bump-examples/doc/train-travel-api/operation/operation-get-stations`\r\n\r\n### Redocly\r\n\r\nReDocly creates an anchor for the operation by concatenating:\r\n\r\n* the fixed string `\"tag/\"`\r\n* a sluggified name from the operation's `tags`\r\n* the fixed string `\"/operation/\"`\r\n* the `operationId` if one exists (else some other heuristic...)\r\n\r\nwhich would yields the anchor `#/tag/Stations/operations/get-stations`\r\n\r\nSuch vendor differences are an inhibitor to writing useful documentation.\r\nBy establishing a common (standard) notation, it's more likely API authors\r\nwill add links and API navigation aids, increasing the utility of the API doc.\r\n\r\nI propose the `oasdoc` notation, which authors can use to enhance\r\nAPI documentation and which tool vendors can treat as\r\na preprocessor to convert agostic links to vendor-specific links.\r\n\r\nThe API doc vendors may or may not create anchors for schemas or other OpenAPI elements.\r\nFor example, bump.sh does not provide anchors for reuest or response schemas;\r\nsee [The Train Travel API](https://bump.sh/bump-examples/doc/train-travel-api/).\r\nHowever, the API doc tooling vendors can transform the Markdown notation\r\ninto navigation links as per their implementation. For example, examining the source\r\nfrom the bump.sh Train travel API, the left hand navigation contains HTML:\r\n\r\n```html\r\n
  • \r\n \r\n Get a list of train stations\r\n GET\r\n
    • \r\n```\r\n\r\nThe response for the `list-stations` call is an object with a `data` property with\r\nan array of objects but there is no link to expose what those array items are, only\r\n\r\n> `data array[object]`\r\n\r\nThe response is defined as\r\n\r\n```yaml\r\n content:\r\n application/json:\r\n schema:\r\n allOf:\r\n - $ref: '#/components/schemas/Wrapper-Collection'\r\n - properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/Station'\r\n - properties:\r\n links:\r\n allOf:\r\n - $ref: '#/components/schemas/Links-Self'\r\n - $ref: '#/components/schemas/Links-Pagination'\r\n```\r\n\r\nso it would be more helpful to the reader if this internal `Station`\r\nschema was called out (so the developer reading the doc\r\nknew the schema name of the items was `Station`, not just an anonymous object),\r\nand the API doc had an anchor for the `Station` schema (and the other schemas that are referenced here)\r\nso that they could be referenced by name elsewhere.\r\n\r\n```html\r\ndata array [Station]\r\n```\r\n\r\nLikewise, the `description` for the `list-trains` operation could be more specific\r\nand document the response with an oasdoc link to the `Station` schema:\r\n\r\n```markdown\r\nThe response has a `data` object which is an array containing a page-worth\r\nof {@schema Station} objects.\r\n```\r\n\r\nThe tooling could inject an HTML link to the `Stations` schema.\r\n\r\n## Notation\r\n\r\nI propose specific notation for `oasdoc`.\r\n\r\noasdoc annotations have the form\r\n\r\n```text\r\nannotation ::= '{@' oasdoc-identifier name [ '|' options] '}'\r\n```\r\n\r\n### `{@op operationId}`\r\n\r\n### `{@op operationId|alt text}`\r\n\r\nAdd a hyperlink to the operation named by `operationid`.\r\nThe default hyperlink text is the `operationid` if no `alt text` is given.\r\n\r\n### `{@schema schemaName}`\r\n\r\nAdd a hyperlink to the named schema within /components/schemas/schemaName`\r\n\r\n### `{@property schemaName.property}`\r\n\r\n### `{@property .property}`\r\n\r\nThe second form may be used within the `description` text of a schema,\r\nto link to properties relative to that schema.\r\n\r\nAdd a hyperlink to the named property schema within /components/schemas/schemaName`\r\nThis also allows nested properties and arrays,\r\nfor example, use\r\n\r\n* `{@schema schemaName.subproperty}`\r\n* `{@schema schemaName.subpropertyA.subpropertyB}`\r\n* `{@schema schemaName.arrayX.items.subpropertyA.arrayY.items.subpropertyB}`\r\n\r\nto access nested elements.\r\n\r\n### `{@parameter parameterName|in:path}`\r\n\r\n### `{@parameter parameterName}`\r\n\r\nAdd a hyperlink to a parameter in `/components/parameters`\r\nthat matches the `parameterName`. If there are multiple parmaeters\r\nof the same name, select one with `in:`\r\nusing `in:path`, `in:headr`, `in:query`, `in:cookie`.\r\n\r\n### `{@response responseItemName}`\r\n\r\nAdd a hyperlink to the named response item\r\n\r\n### `{@securityScheme securitySchemeName}`\r\n\r\nAdd a hyperlink to the named security scheme.\r\n\r\n### `{@id identifier}`\r\n\r\nEstablish a name for a document element. This is like\r\nusing `` but does not assume HTML.\r\n\r\nIf used in the description in an operation that does not have\r\nan `operationId`, this ID can be used as the well-known\r\nanchor for the operation.\r\n\r\n### `{@link identifier|alt text}`\r\n\r\nAdd a hyperlink to an anchor at a location defined by `{@id identifier}`\r\n\r\nThe default hyperlink text is the `identifier` if no `alt text` is given.\r\n\r\n### Well-known anchors\r\n\r\nAs noted above, different API doc vendors have established\r\ndifferent conventions for the anchors or URIs for the operations and other elements.\r\n\r\nI propose `oasdoc` establish *well-known anchor names*\r\nfor OAS elements. This will allow linking to them from external (non oasdoc) sources\r\nsuch as tutorials in a devportal.\r\n\r\n* For each operation with an `operationId`, the anchor `#op-{operationId}`\r\n may be appended to the API doc URL to jump directly to that operation.\r\n This is important because vendors use different strategies which\r\n are sometimes comples and hard to use. See the [Redocly](#redocly)\r\n section above\r\n* For each schema with name `schemaName` in `/components/schemas`, the anchor `#schema-{schemaName}`\r\n\r\nAs noted, some tool vendors (like bump.sh) do not use anchors; each operation\r\nhas it's own URL and the bump.sh user experience manages those links to yield\r\nthe equivalemt of a \"Single Page App\". So supporting such links\r\nwould require vendor support, but I think it is possible.\r\n\r\n## Open Topics\r\n\r\n### Cross-API Links\r\n\r\nMany API providers have suites of APIs, each exposed via separate\r\nAPI documentation generated from multiple OpenAPI descirptions.\r\nIt is common for APIs to be inter-connected. For example,\r\none API may reference a resource *R* defined by another API,\r\nand thus it is convenient to link to the corresponding\r\n`GET /resources/{resourceId}`\r\noperation to fetch the resource that is referenced\r\nlocally (for example, in a response object property)\r\nvia a resource ID or URL property or an OAS.\r\n\r\nsuch cross-API links are hard to encode, as different tools\r\nand developer portals manage API document catalogs in many ways.\r\nA solution must also account for\r\nAPI versions (`info.version`), which adds a level of complexity.\r\n\r\nSyntax to be determined.\r\n\r\n### Subschemas within JSON Schema `allOf`, `oneOf`, `anyOf`, `if/then/else`\r\n\r\nJSON Schema supports conditional and unconditional schema composition\r\nwith `allOf`, `oneOf`, `anyOf`, `if/then/else` keywords.\r\nDIfferent API doc systems yield different rendering\r\nstrategies for these constructs.\r\n`allOf`, `oneOf` and `anyOf` each support an array of\r\nsubschemas.\r\n\r\n#### oasdoc support for the `allOf` keyword\r\n\r\nThe 200 response for the\r\n`get-stations` operation is defined as\r\n\r\n```yaml\r\n application/json:\r\n schema:\r\n allOf:\r\n - $ref: '#/components/schemas/Wrapper-Collection'\r\n - properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/Station'\r\n - properties:\r\n links:\r\n allOf:\r\n - $ref: '#/components/schemas/Links-Self'\r\n - $ref: '#/components/schemas/Links-Pagination'\r\n```\r\n\r\nand is rendered as an aggregation of the properties of each item:\r\n\r\n```text\r\ndata array[object]\r\n The wrapper for a collection is an array of objects.\r\nlinks object\r\n Links to the next and previous pages of a paginated response.\r\n```\r\n\r\n(These property descriptions come from the `Wrapper-Collection`).\r\n\r\nThus, to link to the `data` property for a schema defined with `allOf`,\r\none can simply link to the `schemaName.data` property.\r\n\r\n#### oasdoc support for the `oneOf` keyword\r\n\r\nIn the Train Travel API, the `Payment`\r\nschema is defined as\r\n\r\n```yaml\r\n oneOf:\r\n - title: Card\r\n description: A card (debit or credit) to take payment from.\r\n type: object\r\n properties:\r\n ...\r\n - title: Bank Account\r\n description: A bank account to take payment from. Must be able to make payments in the currency specified in the payment.\r\n type: object\r\n properties:\r\n\r\n```\r\n\r\nwhich bump.sh renders as a panel selector:\r\n\r\n> One of: Card object Bank Account object\r\n\r\nSelecting each option (\"Card object\" or \"Bank Account object\" in\r\nthe bump.sh experience)\r\nshows the properties of the selected `oneOf` schema inside a panel listing.\r\n\r\nRendering links to items within `oneOf` or `anyOf` constructs is\r\nnot straight forward in a complex conditionally-rendered UX.\r\n\r\nNeither the Train Travel (or Redocly's [Musuem AP](https://redocly.com/blog/museum-api-introduction))\r\nuse the `anyOf` keyword, but I believe it would be presented in a UX similar\r\nto `oneOf` and thus not easily accessible via a link.\r\n\r\n## Other components?\r\n\r\nThis proposal addresses well-known anchors for operations\r\n(by `operationId` or `{@id ...}` ) and named schemas\r\nin the `components/schemas` object. Is there need for\r\nwell-known anchors to other components?\r\nThose elements are already typically represented\r\nin API doc and, to my knowledge, do not merit other links\r\n(for example, does API documentation need to link\r\nto a parameter component, or a response object component\r\nby name)?\r\n", "created_at": "2026-03-03T20:24:33Z", "updated_at": "2026-03-04T18:30:18Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "DavidBiesack", "avatar_url": "https://avatars.githubusercontent.com/u/545944?u=26818946106e2d8ae8c0cb5e0b72d6c7f612d268&v=4" } }, { "id": "D_kwDOAQkWPc4AkXaI", "number": 5223, "title": "Default schema dialect for OAS 3.2", "body": "The 3.2 specification [text](https://spec.openapis.org/oas/v3.2.0.html#json-schema-keywords) document states \r\n\r\n> The OpenAPI Schema Object dialect for this version of the specification is identified by the URI https://spec.openapis.org/oas/3.1/dialect/base (the “OAS dialect schema id”).\r\n\r\nHowever all 3.2 schemas [2025‑11‑23](https://spec.openapis.org/oas/3.2/schema/2025-11-23), [2025‑09‑17](https://spec.openapis.org/oas/3.2/schema/2025-09-17) define default jsonSchemaDialect as https://spec.openapis.org/oas/3.2/dialect/2025-09-17\r\n\r\nWhat is the correct default schema dialect for OAS 3.2 then?", "created_at": "2026-02-25T12:29:26Z", "updated_at": "2026-03-04T18:14:28Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A8wO7", "body": "@p1c2u that's an oversight (as you might guess by `3.1` being in the URI even though it's 3.2). The schemas on the spec.openapis.org site under 3.2 are the correct ones." }, "user": { "login": "p1c2u", "avatar_url": "https://avatars.githubusercontent.com/u/1679024?v=4" } }, { "id": "D_kwDOAQkWPc4AkfkW", "number": 5231, "title": "Expressing responses to requests which paths are the URL of a resource", "body": "Sorry for the probably confusing title - please feel free to propose some better wording.\r\n\r\nIn a REST-compliant world, there is no need for the concept of a discrete resource identifier. To be more accurate, the URL of the resource is its canonical identifier, and there is no need for something else (like an `id` attribute). This URL is returned in the response to the request that creates a new resource - usually in the `Location` header but REST doesn't enforce that.\r\n\r\nIt makes expressing REST APIs with OpenAPI a bit confusing and awkward. For example, expressing the following endpoint to get an existing resource is less than ideal:\r\n\r\n```\r\npath: \"/foo/{fooId}\"\r\n```\r\n\r\nThe reason is that there is not guarantee that this is the path of the resource identified by `fooId`. It _may_ be but it may also be something else since the only guaranteed path to a resource is the one that was returned when the resource was created.\r\n\r\nFor example, foo#1 could totally we available at `foo/1` while foo#2 could be available at `resources/foo/2` and it would be perfectly correct in a REST compliant world. The first URL is the one that was returned when foo#1 was created, and the second one was the URL returned when foo#2 was created. This is totally legit as long as each URL allows to reach their corresponding resource, forever.\r\n\r\nStill, the response structure for these two URLs is the same: they are both resources of type foo, and the response reflects that.\r\n\r\nWith OpenAPI, it means that we must document each of these paths, even though they are by no mean contractual. The only contractual thing is that the URL returned on successful creation is the URL to the newly created resource. \r\n\r\nThis gets even more impractical when we consider the other verbs that apply to the same URL (DELETE, PUT...) and the URLs that are built from the URL (like `/foo/1/email`) that also need to be documented separately for each variant - even though it is not necessary.\r\n\r\nOne of my coworkers proposed that we just use `{fooURL}` as path, and declare `fooURL` in the list of parameters, but it does not work because OpenAPI enforces that paths start with a `/` - and also consider that paths are always relative to an hypothetical API Server URL.\r\n\r\nThe only approach that allows for the OpenAPI document to validate is to use `/{fooURL}` as path which is wrong: the resource URL may be absolute, which would lead to an incorrect URL at runtime. Enforcing that the URL of a resource is relative and does not start with a `/` is a very bold move that defeat the whole purpose of having the server assign an URL to the resource it is responsible for creating - basically REST.\r\n\r\nIs it possible to overcome this problem with the current specification? Can we express responses without having to enforce request's _path_?\r\n\r\nAnd what is the plan - if any - to take this issue into consideration in the next iteration of the specification?", "created_at": "2026-03-03T15:51:59Z", "updated_at": "2026-03-04T18:13:03Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "ericmorand", "avatar_url": "https://avatars.githubusercontent.com/u/125664?u=49b642a5a245d8e05b7932c275de651bee9901d0&v=4" } }, { "id": "D_kwDOAQkWPc4Aj6Mu", "number": 5193, "title": "OpenAPI 3.3 Proposal: API-Level Deprecation & Sunset Support", "body": "**Problem Statement**\r\nCurrently, OpenAPI only supports deprecation at the operation level via the deprecated: boolean field on Operation Objects. There is no standard way to signal that an entire API is being deprecated or sunset.\r\n\r\nThis forces API providers to:\r\n\r\n- Rely on prose in info.description (not machine-readable ???)\r\n- Use non-standard x- extensions (not interoperable)\r\n- Depend entirely on HTTP headers at runtime (consumers must actually call the API)\r\n- Mark every single operation as deprecated individually\r\n\r\n**Proposed Solution**\r\nAdd formal lifecycle management fields to OpenAPI, aligned with existing standards:\r\n\r\n- **RFC 8594**: Sunset HTTP Header\r\n- **IRFC 9745**: Deprecation HTTP Header\r\n\r\n\r\n**Two Approaches**\r\nApproach A: New Root-Level ```lifecycle``` Object\r\n```yaml\r\nopenapi: \"3.3.0\"\r\n\r\nlifecycle:\r\n stage: deprecated # active | deprecated | sunset | deactivated\r\n stageDate: \"2025-01-15T00:00:00Z\"\r\n \r\n deprecation:\r\n date: \"2025-01-15T00:00:00Z\"\r\n reason: \"Replaced by v2 API with improved performance\"\r\n migration:\r\n description: Migration guide\r\n url: https://docs.example.com/migrate\r\n replacement:\r\n description: User API v2\r\n url: https://api.example.com/v2/openapi.yaml\r\n contact:\r\n name: Migration Team\r\n email: migrate@example.com\r\n \r\n sunset:\r\n date: \"2025-07-01T00:00:00Z\"\r\n policy:\r\n url: https://docs.example.com/sunset-policy\r\n gracePeriod: P30D # ISO 8601 duration\r\n \r\n responseHeaders:\r\n Deprecation: \"@1736899200\"\r\n Sunset: \"Tue, 01 Jul 2025 00:00:00 GMT\"\r\n```\r\n \r\n**Pros:**\r\n\r\n- Clean separation of concerns (info = what, lifecycle = status)\r\n- Room for rich metadata without cluttering Info Object\r\n- Mirrors how other specs handle lifecycle (e.g., API governance tools)\r\n\r\n**Cons:**\r\n\r\n- Largish? change to the spec\r\n- New top-level object to learn\r\n\r\n**Approach B: Extend Info Object (Minimal Change)**\r\n\r\n```yaml\r\ninfo:\r\n title: User API (Legacy)\r\n version: \"1.4.2\"\r\n deprecated: true\r\n deprecationDate: \"2025-01-15T00:00:00Z\"\r\n sunsetDate: \"2025-07-01T00:00:00Z\"\r\n successorVersion: https://api.example.com/v2/openapi.yaml\r\n deprecationInfo: https://docs.example.com/deprecation/users-v1\r\n``` \r\n\r\n### Pros\r\n\r\n- Minimal spec change \r\n- Familiar location (Info Object already has metadata) \r\n- `deprecated: true` mirrors operation-level pattern \r\n\r\n### Cons\r\n\r\n- Mixes “what is this API” with “what’s happening to it” \r\n- Limited space for rich migration information \r\n\r\n---\r\n\r\n### Proposed Schema Additions\r\n\r\n#### Lifecycle Object (Approach A)\r\n\r\n| Field | Type | Description |\r\n|-------|------|--------------|\r\n| `stage` | string | Current lifecycle stage. Enum: `active`, `deprecated`, `sunset`, `deactivated` |\r\n| `stageDate` | string (date-time) | When current stage began |\r\n| `deprecation` | Deprecation Object | Deprecation details |\r\n| `sunset` | Sunset Object | Sunset details |\r\n| `responseHeaders` | Map\\[string, string\\] | Expected HTTP headers on responses |\r\n\r\n#### Deprecation Object\r\n\r\n| Field | Type | Description |\r\n|-------|------|--------------|\r\n| `date` | string (date-time) | **REQUIRED.** When deprecation takes/took effect |\r\n| `reason` | string | Human-readable explanation |\r\n| `migration` | External Documentation Object | Link to migration guide |\r\n| `replacement` | External Documentation Object | Link to replacement API |\r\n| `contact` | Contact Object | Who to contact for help |\r\n\r\n#### Sunset Object\r\n\r\n| Field | Type | Description |\r\n|-------|------|--------------|\r\n| `date` | string (date-time) | **REQUIRED.** When API stops accepting requests |\r\n| `policy` | External Documentation Object | Link to sunset policy |\r\n| `gracePeriod` | string (duration) | ISO 8601 duration for grace period |\r\n\r\n---\r\n\r\n### Info Object Extensions (Approach B)\r\n\r\n| Field | Type | Description |\r\n|-------|------|--------------|\r\n| `deprecated` | boolean | Whether the entire API is deprecated |\r\n| `deprecationDate` | string (date-time) | When deprecation takes effect |\r\n| `sunsetDate` | string (date-time) | When API will stop accepting requests |\r\n| `successorVersion` | string (uri) | URI to replacement API spec |\r\n| `deprecationInfo` | string (uri) | URI to deprecation documentation |\r\n", "created_at": "2026-02-01T01:01:12Z", "updated_at": "2026-03-01T00:21:02Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "miqui", "avatar_url": "https://avatars.githubusercontent.com/u/5511018?u=40e1f42a26376f801c59434987a2c9a2a5efe954&v=4" } }, { "id": "D_kwDOAQkWPc4AkVQA", "number": 5221, "title": "Use LLMs to improve clarity and accessibility for 3.2.1?", "body": "One thing worth considering is whether to do a 3.2.1 that is basically the result of us asking an LLM to rewrite the 3.2.0 spec for conciseness, clarity, and accessibility. I've long said that the spec would be much improved if we had a thorough review by a professional editor and tech writer. In the absence of finding that in a volunteer capacity, it might be worth seeing how LLMs could improve the prose.\r\n\r\nI am especially thinking of the more complex areas I've added over the last few patch and minor releases, particularly some of the appendices. They're so complicated that I sometimes have trouble figuring out what they mean and I researched and wrote them.\r\n\r\nI don't want to speak for anyone else, but this is not an area where I feel the need to preserve my own writing voice. I'm reluctant to use AI to write GitHub comments (and would say so if I did), but when it comes to the public specification text, I'm strongly in favor of producing the most useful text for OAS users.\r\n\r\nWe would, of course, be open (in the introduction) about the LLM involvement. But I think as long as we are clear about what we did and why we did it, people will understand that the usability of the OAS is what's important. This isn't like writing a novel where there's some assumption that you're primarily reading an author's personal creative vision. We just want this thing to work for people.", "created_at": "2026-02-23T23:09:30Z", "updated_at": "2026-02-27T09:13:07Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4AkQih", "number": 5209, "title": "AI Contributions", "body": "AI-assisted and AI-initiated contributions are becoming increasingly prevalent across the Open Source world.\r\nI haven't seen any official guidance within this project around expectations for this flavor of contribution, and thought it might be prudent to get out ahead of the deluge.\r\n\r\nIn particular, I would like to provide clear guidance for contributors regarding:\r\n\r\n* Are AI-assisted contributions welcome, and if so, how, and to whom are they attributed?\r\n* Are AI-initiated contributions welcome, and if so, how, and to whom, are they attributed?\r\n* Are there guidelines around how AI agents present and conduct themselves?\r\n * How does the Code-of-Conduct apply to AI agents?\r\n * Are AI agents expected to identify themselves as such?\r\n * Are AI agents expected to indicate to whom they are beholden? Are driverless contributions accepted?\r\n \r\nSome starting guidelines I'd personally like to see:\r\n* AI agents should not use human or near-human avatars\r\n* AI agents should not use false information in their bios\r\n* AI agents should indicate their nature in their PR descriptions\r\n* AI agents should indicate who are their operators.\r\n* AI-submitted PRs should not be merged until their operators have been explicitly-engaged, and both operators and repository owners have indicated they understand the agentic nature of the contribution.", "created_at": "2026-02-19T18:09:31Z", "updated_at": "2026-02-26T17:44:09Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "duncanbeevers", "avatar_url": "https://avatars.githubusercontent.com/u/7367?u=4ed0a151ef6aecd7ca8f93553c441507b22391fc&v=4" } }, { "id": "D_kwDOAQkWPc4Ajstq", "number": 5180, "title": "What folder can replace `_archive_` ?", "body": "[_archive_](https://github.com/OAI/OpenAPI-Specification/tree/main/_archive_)\r\n\r\nI want to reviewed some real world OpenAPI 3.2 spec examples.", "created_at": "2026-01-18T03:06:07Z", "updated_at": "2026-02-13T13:53:02Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "anlexN", "avatar_url": "https://avatars.githubusercontent.com/u/8686739?u=71954d5beae0f79abc736c8130c7e27083fbef18&v=4" } }, { "id": "D_kwDOAQkWPc4AkHZs", "number": 5206, "title": "OpenAPI Initiative specifications: Scope / vision statements", "body": "\r\n\r\n* The OpenAPI [Serialization] Specification describes how to serialize application data structures to HTTP messages, and deserialize HTTP messages to application data structures\r\n * _This is much more concise than the current introductory paragraph of the OAS, although perhaps less end-user friendly? Maybe there are different audiences- spec readers vs potential spec contributors?_ \r\n* The Overlay Specification transforms (valid? usable? ???) OpenAPI Description documents to (valid? usable? ???) OpenAPI Description documents, using documents that are separate from the input and output OADs\r\n * _This attempts to incorporate conditions on input and output into what the Overlay Specification's intro paragraph already says. I don't think my proposed wording here is great, it's just a starting point for discussion_\r\n* The Arazzo Specification provides a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions).\r\n * _This is just a copy-paste of Arazzo's intro paragraph. It could maybe be a bit more punch-y if we want to put these statements together on a web page, but that's a minor quibble._\r\n\r\nIn the context of Moonwalk, we could have a fourth specification:\r\n\r\n* The OpenAPI Semantics Specification adds semantic information, for humans and/or LLMs, to an existing (valid? usable? ???) OpenAPI Description, at an individual operation granularity\r\n * _This is not the greatest wording, but again, a starting point. The \"individual operation\" granularity is an attempt to explain the boundary with Arazzo. Or perhaps motivate a discussion about whether things should instead go into Arazzo.\r\n\r\n--------\r\n\r\nIn addition to these high-level statements, which are what I'm mainly focused on, there are practical overlap concerns that need to be hammered out. These should be done on an as-needed basis, rather than spending a lot of time trying to draw pre-emptive boundaries that might hinder innovation. Some known ones, or topics that might end up relevant to scope:\r\n\r\n* https://github.com/OAI/Arazzo-Specification/discussions/380\r\n* https://github.com/OAI/Arazzo-Specification/discussions/398\r\n* https://github.com/OAI/Overlay-Specification/discussions/128 (if we separate API serialization and semantics, semantic selection becomes an interesting boundary problem)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/5006 (pretty much _the_ classic OAS vs Overlay scope question)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/5120 (stumbled into the question of what sorts of OADs are in-scope for the Overlay specification)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/5193 (proposal with both serialization and semantic aspects, where the serialization could probably be done with the existing OAS, or with OAS + Overlay)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/5174 (arguably primarily application semantics, not serialization)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/4330 (similar to the previous)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/5172 (interesting question as to whether authorization (as opposed to authentication) is more semantic or serialization-oriented, or how to best arrange semantic vs syntactic parts)\r\n* https://github.com/OAI/OpenAPI-Specification/discussions/4651 (directly about semantics)", "created_at": "2026-02-12T19:37:26Z", "updated_at": "2026-02-12T19:37:26Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4Ai_l-", "number": 5140, "title": "TOON support in OpenAPI 3.3?", "body": "This proposal recommends adding support for TOON as a structured data format in the OpenAPI Specification, for example via a registered media type such as application/toon. The aim is not to replace JSON as the default wire format, but to provide an alternative representation for operations where the primary consumer is an LLM or AI agent and token-efficiency is a key requirement. TOON’s design—schema-aware, tabular-friendly, and punctuation-light—allows the same OpenAPI-described schema to be serialized with significantly fewer tokens than JSON, improving cost, latency, and context utilization in AI-heavy systems.", "created_at": "2025-11-24T17:04:56Z", "updated_at": "2026-02-09T18:52:43Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "miqui", "avatar_url": "https://avatars.githubusercontent.com/u/5511018?u=40e1f42a26376f801c59434987a2c9a2a5efe954&v=4" } }, { "id": "D_kwDOAQkWPc4Ai3Fu", "number": 5120, "title": "OAS and Overlays integration ideas", "body": "I'm splitting this off from #5116 as it has gotten by far the most response so far. I will port over the relevant comments.\r\n\r\nThe part of the original post of that discussion that kicked this off is:\r\n\r\n> Next, enable / encourage implementations to work together.\r\n> \r\n> * Determine what is needed from the other specs to avoid feature gaps\r\n> * Allow OADs to indicate they are unusable without first applying overlay(s)\r\n> * Allow OADs to indicate that they should be used via Arazzo workflows\r\n>\r\n> The latter two points require understanding the use cases, both for whether they should be done at all (Arazzo probably, Overlays maybe) and how (tight vs loose coupling).", "created_at": "2025-11-13T19:39:24Z", "updated_at": "2026-02-08T21:00:20Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4Ai1VU", "number": 5116, "title": "3.3+ planning ideas", "body": "This collects a set of themes and areas of work I am proposing as a focus for the 3.x line in the near-ish term. _Other people are strongly encouraged to propose additional areas of work! **(in their own GitHub discussions)**._ This is my personal set of suggested starting points.\r\n\r\nI will be expanding on all of these in separate new or existing discussions/issues. Please don't get too deep in the weeds on this discussion — _such comments will be moved to the appropriate feature issue/discussion if that happens._\r\n\r\nIn some cases I've linked to issues, but I have not tried to exactly match all themes to all issues. And sometimes I link to another issue with a larger list.\r\n\r\n## Organizing releases\r\n\r\nI am not specifying what ought to go into 3.3 vs 3.4 vs whatever, as I would prefer someone else with TSC authority guide that debate and make those decisions.\r\n\r\nThe first/next/later steps organization is to help provide options for release content and scheduling decisions. It is not necessary to work all first steps first, etc.\r\n\r\n## Themes\r\n\r\nI've grouped the work into four major themes, which are all related in some way:\r\n\r\n* The OpenAPI Initiative is an ecosystem of three specifications\r\n* The OAS needs to fully model HTTP interactions for both client and server\r\n* The OAS needs to support modern security configurations and workflows\r\n* The OpenAPI Initiative needs to understand LLM/AI use cases\r\n\r\nWe want the OAS to be powerful, flexible, and modern. There are things we know we can do, and other areas where we need to learn our community's needs.\r\n\r\n### Ecosystem of three specifications\r\n\r\n**_Description authors and users need to know when to use each of our specifications, and why._**\r\n\r\n#### First ecosystem steps\r\n\r\nFirst, figure out where we are and write it down!\r\n\r\n* Determine which requested OAS features are [best handled by Overlays](https://github.com/OAI/OpenAPI-Specification/issues/4221#issuecomment-3519901107)\r\n* Determine which OAS features are [redundant with Arazzo](https://github.com/OAI/Arazzo-Specification/discussions/380)\r\n* Document use cases (or deprecations) and best practices; link to the other specs\r\n\r\nDoing this is essential to organizing our own work and _consistently and usefully_ communicating with users. And not just the ones that ask questions on GitHub.\r\n\r\n#### Next ecosystem steps\r\n\r\nNext, enable / encourage implementations to work together.\r\n\r\n* Determine what is needed from the other specs to avoid feature gaps\r\n* Allow OADs to indicate they are unusable without first applying overlay(s) (#5120)\r\n* Allow OADs to indicate that they should be used via Arazzo workflows\r\n\r\nThe latter two points require understanding the use cases, both for whether they should be done at all (Arazzo probably, Overlays maybe) and how (tight vs loose coupling). \r\n\r\n### Fully modeling HTTP interactions\r\n\r\nThe OAS has both low-level HTTP modeling and high-level abstracted features. Both have gaps in them, and for low-level HTTP modeling, those gaps prevent working around gaps in higher-level features. All gaps disrupt the experience of using an OAD to automate API usage (for humans or LLMs).\r\n\r\n#### First HTTP steps\r\n\r\nHeader modeling is our biggest gap in describing HTTP usage. Many high-level features could be adequately, if not elegantly, supported by proper header modeling. Both @karenetheridge and @jeremyfiel have expressed interest in this, and @mikekistler brought up the Example Object naming convention.\r\n\r\n* Create a header modeling [registry](https://spec.openapis.org/registry/index.html) analogous to the media types registry\r\n* Clarify path matching behavior and allow manual order of precedence\r\n* Clarify `content` map key media type matching with structured suffixes and parameters\r\n* Codify correlating Example Objects based on the name throughout an operation\r\n\r\nNote that [RFC9110 §12.5.1](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept) provides examples of matching media types with parameters in `Accept`.\r\n\r\nPath matching: #213, #1970, #2015, #2356, #2530, #2564, #3162, OAI/sig-moonwalk#105, OAI/sig-moonwalk#119\r\nMedia type matching: #3162\r\nFor a (quite long) list of header modeling-related issues, see OAI/sig-moonwalk#108\r\n\r\n#### Next HTTP steps\r\n\r\n* Model media type parameters in `Accept` and `Content-Type` with minimal impact on media type matching\r\n* Consider how to have a whole-operation example (`application/http`?)\r\n* Consider WHATWG URL Patterns to enhance server-side matching\r\n\r\n#2342, OAI/sig-moonwalk#127, OAI/sig-moonwalk#183\r\n\r\n#### Later HTTP steps\r\n\r\n* Expand matching to more of the operation (moving towards \"signatures\")\r\n* Consider how to define and correlated some sort of sub-operation to address RPC and other use cases (needs to be discussed with Arazzo)\r\n\r\n### Modern Security\r\n\r\nThis area is complex and requires research and gathering expert input.\r\n\r\nThere are several great proposals including ones from @whitlockjc, @SensibleWood , and @alex-feel, but it will take us a while to understand how to incorporate all of those ideas without stepping on each other. So...\r\n\r\n#### First security steps\r\n\r\nThese steps leverage existing supported behavior to allow workarounds for current limitations, and to allow Arazzo to define auth workflows where we are unable to describe them with Security Schemes. \r\n\r\n* Add `application/jwt` and other security/encryption-related media types to our registry\r\n* Allow defining authorization / token / etc. servers in addition to API servers \r\n* Allow modeling auth endpoints like API endpoints\r\n\r\nAn alternative to the last two would be modeling auth servers with their own OADs and using Arazzo to connect them, but as some auth behavior is a bit different, that might actually be harder. But worth considering.\r\n\r\nMany of the following issues could _also_ get more elegant solutions in next/later steps, and for a few it's not clear where they fit: #61, #1416, #1464, #1731, #1881, #1995, #2027, #2232, #2284, #2296, #2322, #2419, #3983, #4836, #4925, OAI/sig-moonwalk#84, OAI/sig-moonwalk#50\r\n\r\nAssuming full header modeling support and Overlay support for adding configuration to every selected endpoint, more-or-less every requested security feature could be modeled this way. Although not elegantly.\r\n\r\n#### Next security steps\r\n\r\nWe probably want to be starting these alongside the first steps, I just think they'll take longer.\r\n\r\n* Enhance Security Schemes to support more configurations elegantly\r\n* Collaborate with Arazzo on security integration, [which is already happening](https://redocly.com/docs/respect/extensions/x-security)\r\n\r\nSome bits of these issues go here, some in the \"Later security steps\": #1702, #1875, #1934, #2239, #2398, #3612, #3709, #4106, #4807, OAI/sig-moonwalk#46, OAI/sig-moonwalk#69\r\n\r\n#### Later security steps\r\n\r\n* Rethink our whole approach to separate concerns and provide a comprehensive and extensible framework, with clear divisions between the OAS and Arazzo\r\n\r\n### Understanding AI use cases\r\n\r\nFor this, we need to convene a SIG, do a lot of research, and talk to a lot of people. \r\n\r\nHowever, we know that gaps in HTTP modeling and security support make it harder for LLMs to consume an API, so the above proposals have been chosen in part with that in mind.", "created_at": "2025-11-12T03:15:02Z", "updated_at": "2026-02-08T16:12:48Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4Ajdde", "number": 5174, "title": "Support specifying log levels for the attributes in an OpenAPI spec", "body": "# Problem\r\nCurrently, when I define an OpenAPI spec, there is no clear-cut way for me to specify (or consistently control) which attributes can/should be logged by the users of the spec. This means that there has to be an **implicit** level of trust that the user of the API spec will log the data appropriately - which presents a couple of problems:\r\n\r\n1. A developer using an OpenAPI spec (or the bindings generated from said spec) can easily log attributes (or an entire object) that may contain sensitive information. This could be avoided by allowing for the creation of sensible defaults.\r\n 1. The developer may not know the API schema/bindings well enough to make an informed decision about which attributes can/should be logged. This could be caused by inexperience, or by poor developer documentation.\r\n 2. A lot of us have left a `print()` statement in code that we only intended for use during debugging.\r\n2. A number of popular API Gateways can be configured using OpenAPI specs, but since these specs don’t contain any information about the loggability of attributes, the log outputs tend to be very minimal (to avoid leaking sensitive request info) - which can complicate debugging.\r\n 1. [AWS API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) allows you to [use an OpenAPI spec to directly configure an API gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-open-api.html).\r\n 2. [GCP API Gateway](https://docs.cloud.google.com/api-gateway/docs) allows you to [use an OpenAPI spec to directly configure an API gateway](https://docs.cloud.google.com/api-gateway/docs/openapi-overview).\r\n 3. [Kong](https://github.com/Kong/kong) allows you to convert an OpenAPI spec into a Kong spec [using their `openapi2kong` tool](https://github.com/Kong/openapi2kong).\r\n\r\n**TLDR: In the absence of proper information about which attributes are loggable, users of OpenAPI specs have to practice self-restraint with logging. Whilst a cautious approach is good, it directly impacts observability - which can hinder debugging efforts. Furthermore, since this self-restraint falls to individual developers, there are inherent inconsistencies in approach, and there’s an ever-present risk of a slip-up resulting in the leaking of sensitive information.**\r\n\r\n# Request\r\nI would like to be able to specify logging expectations as part of an OpenAPI spec. This would allow us to move from **implicitly** trusting developers/services to handle logging (and any redaction that may need to occur), to **explicitly** declaring expectations around logging. I think that this would provide a few benefits:\r\n1. The maintainers of an API spec are **already** the authority on that specific API, and they (hopefully) have the most domain knowledge about it. These people are therefore the best suited for saying which attributes are sensitive, and which can/should be logged.\r\n 1. Allowing maintainers to specify logging expectations would effectively just extend their existing authority.\r\n2. We would effectively be adding [log-specific] guardrails. By allowing the maintainers of an API spec to define logging expectations, we can minimise the risk of an inexperienced developer logging sensitive information.\r\n 1. The information about attribute loggability would be visible in the API spec, and it could be displayed as part of any documentation that's based on the spec.\r\n 2. When we generate bindings from an OpenAPI spec, we could also generate helper functions to control the logging/serialisation of objects and attributes.\r\n 1. This would mean that individual developers no longer have to make their own helper functions (or manually add object attributes to log fields).\r\n3. If the OpenAPI spec already defines the loggability of individual attributes, then API Gateways won't have to default to minimising/quashing logs in an effort to avoid outputting sensitive information. This should help with observability and debugging.\r\n4. If the full stack (e.g. JS client bindings, Go server bindings, AWS API Gateway) uses the same OpenAPI spec, then we could **consistently** output the same log fields. This consistency helps with observability and log correlation.\r\n 1. Obviously, trace headers help with correlation, but tooling to make use of these headers isn't always available. Even when trace headers _are_ available, there could still be a need to set log fields using attributes. \r\n\r\n## Potential Approach\r\n### Suggested Changes to OpenAPI\r\nI think that we should be able to specify logging expectations for individual object attributes inside of an OpenAPI schema - this could be done by adding a field called `loggability`. This `loggability` field could then be \r\nused to specify when an attribute can appear in logs (i.e. the log levels at which it can be added as a log field).\r\n\r\n#### Potential Values for the `loggability` Field\r\nLog levels differ between programming languages and log packages, so we could base the values for `loggability` on the [OpenTelemetry severity levels](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber). Since OpenTelemetry is a platform-agnostic open standard ([backed by the CNCF](https://www.cncf.io/projects/opentelemetry/)), there shouldn't be any concerns about favouring a specific language/log package/service provider.\r\n\r\nIt would make sense to **only log an attribute when the `loggability` field is explicitly defined**. This default behaviour is beneficial for two reasons:\r\n1. If we logged _every_ attribute by default, then the size of each log could get out of hand very quickly - which would create a lot of operational overheads.\r\n2. Logging everything by default would mean logging sensitive information by default.\r\n\r\nIn addition to **not logging attributes by default**, we could add a value to represent explicitly denying the logging of a field (e.g. `DO_NOT_LOG`). This would allow the maintainers of an OpenAPI spec to **explicitly** communicate that they do not want a field to be logged.\r\n\r\nGiven the aforementioned considerations, the values for `loggability` could look like this\r\n\r\n| Value | Source | Notes |\r\n|--------------|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| `TRACE` | [OpenTelemetry severities](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) | This is the lowest severity log level as it will output a lot of information. These logs are only visible when an application is configured to output logs at the `TRACE` level. |\r\n| `DEBUG` | [OpenTelemetry severities](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) | Typically only visible when a program is configured to output logs at the `DEBUG` level or lower (i.e. `DEBUG` or `TRACE`). |\r\n| `INFO` | [OpenTelemetry severities](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) | When a log is output in code, `INFO` is the default log level. In comparison, the _default_ for the `loggability` field is to be unset, and when this field is unset, the corresponding attribute should not be logged at all. |\r\n| `WARN` | [OpenTelemetry severities](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) | |\r\n| `ERROR` | [OpenTelemetry severities](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) | If a validation error occurs (i.e. when a request payload is malformed) then any attributes with `loggability: ERROR` could be added to the error log (assuming that the malformed payload is still parseable). |\r\n| `FATAL` | [OpenTelemetry severities](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) | |\r\n| ` ` / unset | | This is an empty string that represents a unset `loggability` field (which is the default). If an attribute has no `loggability` field defined, the attribute shouldn't be logged. |\r\n| `DO_NOT_LOG` | | A way to **explixcitly** denote that an attribute should **never** be logged, and that there was an intentional decision to not log the attribute. We could use `SENSITIVE` (or another value) instead, but this could be misinterpreted as an instruction to redact data. |\r\n\r\n##### Examples\r\n###### Error\r\n```yaml\r\n lunch:\r\n type: object\r\n description: Information about lunch\r\n properties:\r\n fruit:\r\n type: string\r\n loggability: ERROR\r\n description: Which piece of fruit was selected\r\n enum:\r\n - Apple\r\n - Orange\r\n - Banana\r\n```\r\n\r\nIn the above example, the `fruit` attribute has `loggability: ERROR` set on it - which means that the attribute can be added to logs that are `ERROR` level or lower.\r\n\r\nWith this configuration, we may log the attribute if a payload [containing the attribute] fails validation (e.g. if somebody specified `\"fruit\": \"guava\"`).\r\n\r\n###### Not Set/Default\r\n```yaml\r\n sweater:\r\n type: object\r\n description: Information about someone's sweater\r\n properties:\r\n colour:\r\n type: string\r\n description: The colour of the sweater\r\n enum:\r\n - It's not just blue\r\n - It's not turquoise\r\n - It's not lapis\r\n - It's actually cerulean\r\n```\r\n\r\nIn the above example, the `loggability` field hasn't been set on the `colour` attribute - so `colour` should never be output to logs.\r\n\r\n###### Do Not Log\r\n```yaml\r\n contactInfo:\r\n type: object\r\n description: Information used to contact a person\r\n required:\r\n - email\r\n - mobileNumber\r\n properties:\r\n email:\r\n type: string\r\n loggability: DO_NOT_LOG\r\n description: An email address\r\n format: email \r\n mobileNumber:\r\n type: string\r\n loggability: DO_NOT_LOG\r\n description: A UK-based mobile number\r\n pattern: ^(\\+44\\s?7\\d{3}|\\(?07\\d{3}\\)?)\\s?\\d{3}\\s?\\d{3}$\r\n```\r\n\r\nIn the above example, both `email` and `mobileNumber` have `loggability: DO_NOT_LOG`. This shows that a conscious decision has been made to prevent the logging of the attributes under any circumstances (since both attributes contain PII).\r\n\r\n### Possible Language-specific Usages\r\n#### Go\r\nThe `loggability` field could be used in multiple places when generating Go bindings for an OpenAPI spec:\r\n1. We could conditionally set [struct tags](https://www.digitalocean.com/community/tutorials/how-to-use-struct-tags-in-go) based on the `loggability` field. Struct tags are relatively free form, so purpose-specific struct tags could be set that suit individual needs.\r\n 1. [We _could_ set `json:\"-\"` on a struct field](https://www.digitalocean.com/community/tutorials/how-to-use-struct-tags-in-go#ignoring-private-fields) if there is a corresponding `loggability: DO_NOT_LOG` in the OpenAPI spec\r\n 2. These tags could be used by internal tooling (e.g. something could be written to enforce redaction).\r\n2. The `log/slog` package defines [a `LogValuer` interface which allows developers to control _how_ a struct should be logged](https://pkg.go.dev/log/slog#LogValuer) - we could autogenerate implementations of this interface based on the `loggability` fields within the OpenAPI spec.\r\n 1. [This `LogValuer` interface can be used to hide sensitive fields.](https://betterstack.com/community/guides/logging/logging-in-go/#hiding-sensitive-fields-with-the-logvaluer-interface)\r\n 2. This interface doesn't receive information about the log level - so it wouldn't be possible to conditionally alter the output.\r\n 3. Likewise, Zerolog defines [a `LogObjectMarshaler` interface which operates in a similar manner](https://pkg.go.dev/github.com/rs/zerolog#LogObjectMarshaler).\r\n3. We could autogenerate implementations of [the `Marshaler` interface](https://pkg.go.dev/encoding/json#Marshaler) in order to control how a struct is marshalled into JSON.\r\n\r\n#### Java\r\nThe `loggability` field could be used in multiple places when generating Java bindings for an OpenAPI spec:\r\n1. We could autogenerate [the `toString()` method](https://www.baeldung.com/java-tostring) to control which fields are output/masked.\r\n 1. This method doesn't receive information about the log level - so it wouldn't be possible to conditionally alter the output.\r\n2. We could generate a [Data Transfer Object (DTO)](https://www.baeldung.com/java-dto-pattern) for each object within the OpenAPI spec - to provide a restricted view of the attributes from the object.\r\n 1. This could be expanded so that there are multiple DTOs per object (i.e. one DTO per log level).\r\n\r\n## Considerations\r\n### OpenAPI Extension\r\nI was initially going to suggest this as an [OpenAPI Extension](https://spec.openapis.org/registry/extension/index.html) since logging isn't _fully_ related to OpenAPI, however, there are a few reasons that I'm suggesting it as part of the wider OpenAPI spec:\r\n1. The values for the `loggability` field (e.g. `ERROR`, `DEBUG`, `DO_NOT_LOG`) would **extend** the OpenTelemetry specification. Extending/altering a specification usually triggers debate, and I figured that suggesting this `loggability` field as a part of the wider OpenAPI specification would be more conducive to such a debate.\r\n2. My suggestion focuses on standardising logging across **all consumers** of a given OpenAPI spec. The implementation of OpenAPI extensions seems to vary across languages and providers - which would be counterproductive given my goal of having a common/standard approach.\r\n3. A growing number of teams employ a design-first approach to API development - which means that OpenAPI specs increasingly act as a source of truth for a company's data models. Since OpenAPI specs are often elevated to such a point of authority, I think it makes sense to allow OpenAPI specs to say how the data (that they model) should be logged.\r\n4. Whilst OpenAPI and OpenTelemetry are concerned with two different domains, there are already touchpoints/areas of common interest between the two (e.g. the `traceparent`, `tracestate`, and `X-Request-ID` headers).\r\n\r\n### Related Work/Issues\r\nhttps://github.com/OAI/OpenAPI-Specification/discussions/4330 requested an `x-sensitive-data` field and suggested some excellent approaches for redacting sensitive data. \r\n\r\nMy `loggability: DO_NOT_LOG` field would behave _similarly_ to @cristigirbovan's `full` masking proposal:\r\n\r\n```yaml\r\n x-sensitive-data: \r\n mask: full\r\n```\r\n\r\nBoth of our suggestions would seek to completely eliminate specified fields from logs, but the difference is that my \r\n`loggability: DO_NOT_LOG` field isn't specific to sensitive data - it's for _any_ field that we explicitly don't want to log.\r\n\r\nWhilst their proposal focuses on **known sensitive data** (and the most effective ways to redact it), my proposal\r\nis focused on logging in general (including attributes that aren't sensitive). Realistically, our proposals are complimentary \r\nsince my proposal focuses on **when** to log attributes, and theirs focuses on **how** to log [known sensitive] attributes.\r\n\r\nHypothetically, our proposals could be combined into one overarching spec change that governs logging and redaction as\r\na whole. For example:\r\n```yaml\r\n merchantTransaction:\r\n type: object\r\n description: Information about a purchase from a store\r\n required:\r\n - fullCardNumber\r\n - merchantID\r\n - amount\r\n properties:\r\n fullCardNumber:\r\n type: string\r\n description: A full 16 digit card number. We only output it for DEBUG/TRACE logs, and when we do log it, we redact everything but the last 4 digits.\r\n logging:\r\n loggability: DEBUG\r\n sensitive-data:\r\n mask: regex\r\n pattern: \"^[\\d]{12}\"\r\n merchantID:\r\n type: string\r\n logging:\r\n loggability: INFO\r\n description: The ID of the merchant where the transaction was made.\r\n amount:\r\n type: integer\r\n description: An int-based representation of the transaction amount. We don't want to log this because it could be commercially sensitive.\r\n logging:\r\n loggability: DO_NOT_LOG\r\n```\r\n\r\nThe above sample shows my proposal **in conjunction with** @cristigirbovan's `x-sensitive-data` proposal. Both of our\r\nproposed fields have been centralised under the `logging` field, the `x-` prefix has been removed, and I'm using my `DO_NOT_LOG` in lieu of `mask: full`.", "created_at": "2025-12-30T20:56:09Z", "updated_at": "2026-01-31T22:32:43Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "ae-ou", "avatar_url": "https://avatars.githubusercontent.com/u/28446937?u=afb27a271631c18c5f7fdcdaf607be647234c6c5&v=4" } }, { "id": "D_kwDOAQkWPc4Aj4NE", "number": 5191, "title": "Investigate OpenID FAPI", "body": "This is an OAuth2 profile from an [OpenID working group](https://openid.net/wg/fapi/).", "created_at": "2026-01-29T16:31:24Z", "updated_at": "2026-01-29T16:31:24Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4AjbMd", "number": 5172, "title": "Investigate OpenID AuthZEN", "body": "Just came across this: [AuthZEN: A New Standard for Fine-Grained Authorization](https://nordicapis.com/authzen-a-new-standard-for-fine-grained-authorization/) (See also the official [OpenID AuthZEN working group](https://openid.net/wg/authzen/)).\r\n\r\n", "created_at": "2025-12-27T17:41:25Z", "updated_at": "2026-01-29T16:26:51Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4Ai8wM", "number": 5130, "title": "Go OpenAPI 3.2 (upgrade initiative)", "body": "We recognise that many OpenAPI users experience difficult upgrade experiences and roadblocks along the way. Let's identify those roadblocks and discuss ways that we can help users to get past them by fixing tools, providing resources, socialising alternative approaches, or lobbying for change.", "created_at": "2025-11-20T18:06:48Z", "updated_at": "2026-01-18T01:08:06Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "lornajane", "avatar_url": "https://avatars.githubusercontent.com/u/172607?v=4" } }, { "id": "D_kwDOAQkWPc4AjZRS", "number": 5169, "title": "OpenAPI Specification Rendered with Astro Starlight", "body": "Repo: https://github.com/valerii15298/openapi-spec\r\nWebsite: https://valerii15298.github.io/openapi-spec\r\n\r\nI just took markdown file for `3.2.0` version and rendered it using Astro Starlight.\r\n\r\nAlso added fuzzy search with jumps to the headings for quicker navigation:\r\nhttps://youtu.be/eMxoI0SXpF0", "created_at": "2025-12-24T08:47:14Z", "updated_at": "2025-12-24T22:35:08Z", "category": { "name": "Tooling", "emoji": ":hammer_and_wrench:" }, "answer": null, "user": { "login": "valerii15298", "avatar_url": "https://avatars.githubusercontent.com/u/44531564?u=88ac74d9bacd20401518441907acad21063cd397&v=4" } }, { "id": "D_kwDOAQkWPc4AjQ_U", "number": 5158, "title": "Query Parameter Serialization using `content` field", "body": "How parameter serialization should work given this schema:\r\n```yaml\r\nopenapi: 3.1.0\r\ninfo: \r\n title:\r\n version:\r\npaths:\r\n /test:\r\n get: \r\n parameters: \r\n - in: query\r\n name: pet\r\n content:\r\n application/json: \r\n schema: \r\n type: string\r\n```\r\n\r\nIn case we want specify string value `cat` for the `pet` parameter.\r\nSince `pet` is defined using `application/json` I expect the serialized url query string to look like this(with quotes percent encoded since the correct json representation for string should be with double quotes `\"cat\"`):\r\n\r\n```\r\nhttps:/example.org/test?pet=%22cat%22\r\n```\r\nand **NOT** like this: \r\n```\r\nhttps:/example.org/test?pet=cat\r\n```\r\n**Is my assumption correct?**\r\n\r\n\r\n\r\nLooking at https://spec.openapis.org/oas/latest.html#parameter-object-examples there is this example which I was looking at which seems logical:\r\n\"Screenshot\r\n\r\n\r\nThe confusion for me is that swagger editor does not include quotes so it seems like the violation of the spec. And I am building similar UI tool, so I want to better understand how to implement parameter serialization which is one of the most complicated things to do with abnormal amount of edge cases and multiple specs involved.\r\nI created issue on their side: https://github.com/swagger-api/swagger-ui/issues/10661\r\n", "created_at": "2025-12-13T22:07:53Z", "updated_at": "2026-02-10T00:05:12Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A6LIZ", "body": "> https:/example.org/test?pet=%22cat%22\r\n\r\n..is correct. JSON-encoded strings have double quotes around them, and then those characters are url-encoded to %22.\r\n\r\nDoes the swagger editor properly encode other JSON values, e.g. objects and arrays?" }, "user": { "login": "valerii15298", "avatar_url": "https://avatars.githubusercontent.com/u/44531564?u=88ac74d9bacd20401518441907acad21063cd397&v=4" } }, { "id": "D_kwDOAQkWPc4Ai9ks", "number": 5133, "title": "Contradiction between Swagger Documentation and practical use of 'default' in query parameters", "body": "According to the official Swagger/OpenAPI documentation:\r\n\r\n>There are two common mistakes when using the default keyword: \r\n>- Using _default_ with required parameters does not make sense – if a value is required, the client must always send it, and the default value is never used.\r\n>- Using _default_ to specify a sample value. This is not intended use of default and can lead to unexpected behavior in some Swagger tools. Use the example or examples keyword for this purpose instead\r\n\r\nHowever, in practice, when we add default to a required parameter, Swagger tools (UI and code generators) use that value to:\r\n\r\n- Pre-fill the field in Try it out.\r\n- Generate the URL with the parameter included in Request Samples (e.g., curl). - Which is contradicting since you don't have to pass a default value.\r\n- Make testing easier without requiring manual input.\r\n\r\nOn the other hand, if we do not set a default, even for required parameters, the generated URL in samples omits the parameter, and the Try it out field remains empty, which often causes errors during testing.\r\nThis creates a contradiction:\r\n\r\n- Specification: _default_ is intended for optional parameters, used by the server when the client does not send a value.\r\n- Tools: default is treated as a way to auto-fill Try it Out and Request Samples, generating confusing URLs that dont need those parameters.\r\n\r\nQuestions:\r\n\r\nIs there an official recommendation to handle this inconsistency?\r\nAre there plans for Swagger UI to use example (or examples) for auto-filling required fields instead of relying on default?\r\nWhat is considered best practice to maintain semantic correctness while providing a good user experience?\r\n\r\nThanks!", "created_at": "2025-11-21T16:54:20Z", "updated_at": "2025-12-10T23:31:58Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "fabio-resende", "avatar_url": "https://avatars.githubusercontent.com/u/74406258?v=4" } }, { "id": "D_kwDOAQkWPc4AiOfX", "number": 5006, "title": "Are there plans to add support for global responses?", "body": "It would be helpful if OpenAPI specification allowed me to specify certain responses that will be returned for every endpoint in the specification, rather than having to document every response on every endpoint. (Although I would imagine people might want to apply those default responses to some sort of pattern matching, either by path or tag or other...)\r\n\r\nFor instance, if my API requires authentication on every endpoint, applies rate limiting to every endpoint, and can return a `500 Internal Server Error` for every endpoint, then it would be nice to define a default set of responses for 401, 403, 429 and 500. Those responses would also include e.g. rate limit headers.\r\n\r\nWhen following a design-first approach, this would significantly reduce the amount of copy-pasting of response references, reduce the chance of making errors, and reduce size of a fully-documented OpenAPI specification, which then decreases the resources required to process one when generating client-side docs.", "created_at": "2025-10-02T05:00:51Z", "updated_at": "2025-12-03T18:30:15Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "davidkeaveny", "avatar_url": "https://avatars.githubusercontent.com/u/1229960?v=4" } }, { "id": "D_kwDOAQkWPc4AitWf", "number": 5097, "title": "Support for CDDL", "body": "I would like to see support for CDDL.\r\n\r\nHere is a straw-man:\r\n\r\n```yaml\r\nopenapi: 3.1.0\r\n$self: https://example.com/schema.cddl\r\ninfo:\r\n title: API\r\n version: 1.0.0\r\npaths:\r\n /example:\r\n post:\r\n requestBody:\r\n content:\r\n application/cbor:\r\n schema: \r\n $id: RequestInCbor\r\n application/json:\r\n schema: \r\n $id: RequestInJson\r\n responses:\r\n '200':\r\n description: OK\r\n content:\r\n application/cbor:\r\n schema: \r\n $id: ResponseInCbor\r\n application/json:\r\n schema: \r\n $id: https://example.com/schema.cddl#ResponseInJson\r\n```\r\n\r\nThis could be useful for other data definition languages.", "created_at": "2025-11-02T20:14:58Z", "updated_at": "2025-11-21T05:21:54Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "OR13", "avatar_url": "https://avatars.githubusercontent.com/u/8295856?u=2335c8c0f974e510eae586582d050b606bf79a88&v=4" } }, { "id": "D_kwDOAQkWPc4AZUFm", "number": 3793, "title": "Definition of a breaking change", "body": "Most API vendors follow something akin to Postel's law, but careful what you send and liberal in what you accept and as a result don't consider adding new attributes to a payload response a \"breaking change\".\r\n\r\nHowever, something like changing the data type they would. But, OAS also supports format. So you can have a integer type and a format of int32 and int64. Wondering if you change the type is this considered a breaking change?\r\n\r\nCan see any standard for this?\r\n\r\nWould welcome thoughts.\r\n\r\n", "created_at": "2024-05-09T15:08:14Z", "updated_at": "2025-11-16T09:43:58Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A5DfC", "body": "I definitely agree, Breaking change definition is something that is opiniated , and depends on what you are doing \r\nyou might distinguish especially for OAS ,at least 3 models : \"on the wire breaking change\" , sdk generation breaking change , and may be functionnal breaking change , \r\n\r\nnotice that one of the pilar of OAS is JSON schema where you have as well no formal breaking change definition I found only this one ! \r\n**\" A braking change occurs when JSON instance that was valid under the old schema becomes invalid under the new schema. \"**\r\n\r\nit could be a starting point but a bit even this simple definition is challenging , for instance is removing a non mandatory query parameter is a breaking change , all depends is your client code rely on it or not , and on the context . is adding one is a breaking change ? it depends if the addition affect the run time execution \r\n\r\nso i would say let the tooling to setup rules and definition for breaking change customizable , as similar to linter rules \r\nyou migh found some definition for instance there \r\n\r\nhere is one of the implementation tooling : https://github.com/pb33f/libopenapi/tree/66b73b3210510514efd47320a85d0dbb47204c89/what-changed \r\nhere is another may be more accurate definitinon \r\n\r\nhttps://www.oasdiff.com/checks with the concept of breaking change level \r\n" }, "user": { "login": "dublintech", "avatar_url": "https://avatars.githubusercontent.com/u/1429798?v=4" } }, { "id": "D_kwDOAQkWPc4Ai02H", "number": 5115, "title": "Use deterministic id attributes for headers in the html spec.", "body": "## Context\r\nI am building a tool similar to swagger editor. And I wanna implement hover tooltips for fields in the spec.\r\nSo far I have been using `$comment` field from https://spec.openapis.org/oas/3.2/schema/2025-09-17.html\r\nLike in this instace to display hover tooltip for `parameter`\r\n```json\r\n\"parameter\": {\r\n \"$comment\": \"https://spec.openapis.org/oas/v3.2#parameter-object\",\r\n}\r\n```\r\n\r\nSince most tools(Monaco-editor for example) expect markdown for tooltip hovers I use original markdown spec file from this repo, parse it and extract needed markdown based on `$comment` field from the schema. (parsing html is not an option because html => markdown is not reliable result)\r\n\r\n
    \r\nJS sample code\r\n\r\n```ts\r\nimport { marked } from \"marked\";\r\n\r\nexport async function getHeadersMap(markdownURL: string) {\r\n const spec = await fetch(markdownURL).then((res) => res.text());\r\n\r\n const tokens = marked.lexer(spec);\r\n\r\n const headersMap: Record = {};\r\n\r\n tokens.forEach((t, idx) => {\r\n if (t.type === \"heading\") {\r\n const content = [t.raw];\r\n const name = (t.text as string).replaceAll(\" \", \"-\").toLowerCase();\r\n for (let i = idx + 1; i < tokens.length; i++) {\r\n const nextToken = tokens[i]!;\r\n if (nextToken.type === \"heading\" && nextToken.depth <= t.depth) {\r\n break;\r\n }\r\n content.push(nextToken.raw);\r\n }\r\n headersMap[name] = content.join(\"\");\r\n }\r\n });\r\n return headersMap;\r\n}\r\nconst url = \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/versions/3.1.2.md\";\r\nconst docsMap = await getHeadersMap(url)\r\n```\r\n\r\n---> The above will produce a map `id`=>`content` where `id` is id html attribute from the html spec and `content` is original markdown content for that id.\r\n
    \r\n\r\nThe problem arises with `fixed-fields` id:\r\n```json\r\n \"$comment\": \"https://spec.openapis.org/oas/v3.2#fixed-fields-10\",\r\n ```\r\n \r\nBecause ids for `Fixed Fields` headings are incremented globally with a number, for my case I just cannot extract tooltip information for specific field.\r\n\r\n## Proposal\r\n\r\nCan we use deterministic id attributes across the html spec?\r\nSo that it would be possible for people to parse original markdown and construct the same id attributes.\r\n\r\nInstead of this: https://spec.openapis.org/oas/v3.2#fixed-fields-10\r\n\r\nUse id something like this `https://spec.openapis.org/oas/v3.2#request-body-object--fixed-fields\r\n\r\n## Question\r\nIs there a better way to extract markdown content for specific OpenAPI document field programmatically?", "created_at": "2025-11-11T13:07:49Z", "updated_at": "2025-11-12T03:55:31Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "valerii15298", "avatar_url": "https://avatars.githubusercontent.com/u/44531564?u=88ac74d9bacd20401518441907acad21063cd397&v=4" } }, { "id": "D_kwDOAQkWPc4Ac45R", "number": 4233, "title": "3.3: allow `openapi` field to just specify MAJOR.MINOR and omit the PATCH number", "body": "Requiring `openapi: MAJOR.MINOR.PATCH` and then stating in the spec that PATCH actually is meaningless is confusing.\r\n\r\nBetter allow (or require?) to write `openapi: MAJOR.MINOR`.", "created_at": "2024-11-28T17:20:13Z", "updated_at": "2025-11-08T23:33:55Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "ralfhandl", "avatar_url": "https://avatars.githubusercontent.com/u/951576?u=5f0aff13ce0c500d621a7a56585182cbf8c0caf7&v=4" } }, { "id": "D_kwDOAQkWPc4AisI4", "number": 5096, "title": "[Feat] Add support for terminating events in streaming APIs", "body": "OAI 3.2.0 added support for streaming media types via the [itemSchema property](https://spec.openapis.org/oas/v3.2.0.html#fixed-fields-11), and that's a great improvement!\r\n\r\nObserving some APIs from wild that are widely used, it seems that it's a common practice to have a \"terminating event\" so the server can tell the client \"we're done\" (in an expected way, not like disconnecting them because something is wrong).\r\n\r\nSee [OpenAI](https://platform.openai.com/docs/api-reference/runs/createRun#runs_createrun-stream) which will reply back\r\n\r\n```\r\n[DONE]\r\n```\r\n\r\n> Note: in that scenario it's not JSON, it's a text token.\r\n\r\nThere does not seem to be a \"place\" for this information today, but maybe this is something that could be added to 3.3?", "created_at": "2025-10-31T17:19:57Z", "updated_at": "2025-11-03T16:20:04Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "baywet", "avatar_url": "https://avatars.githubusercontent.com/u/7905502?u=0019d9e9b489fa6c533f450c0bbe1b8c07360eda&v=4" } }, { "id": "D_kwDOAQkWPc4AiF93", "number": 4989, "title": "Clarification on Best Practices for Extending OpenAPI Specification", "body": " While working on an API design, I’ve come across scenarios where I need to include additional metadata and custom features that are not directly covered by the current OpenAPI Specification. \r\n\r\n**My questions are:** \r\n- What are the recommended best practices for extending the OpenAPI Specification with custom fields? \r\n- Should these extensions always go under the `x-` prefix, or are there cases where other approaches are acceptable? \r\n- How do such extensions affect tooling compatibility (e.g., code generators, validators, documentation tools)? \r\n- Is there a process for proposing new fields/features to be officially included in future versions of the specification? \r\n\r\nAny insights, examples, or references to community standards would be really helpful.\r\n", "created_at": "2025-09-23T14:19:06Z", "updated_at": "2025-10-29T21:24:50Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "fatema432", "avatar_url": "https://avatars.githubusercontent.com/u/200746827?u=2a0ba5410bd950da07064ca51e8afa3a7ebc3598&v=4" } }, { "id": "D_kwDOAQkWPc4AcbYD", "number": 4183, "title": "API specification format for hypermedia-centric APIs", "body": "Hi there!\r\n\r\nAt the company where I currently work, we started adopting a more hypermedia driven approach to our internal APIs, which includes the following changes in contrast to the traditional data-centric APIs.\r\n\r\n- using links to cross-reference different resources\r\n- URLs (possibly templated with parameters) are given in the links themselves, instead of being hardcoded in the API client. Therefore, the URLs namespace is fully controlled by the server.\r\n- available actions on a resource are encoded as links as well and are given dynamically by the server, instead of relying on the client to infer them from the resource data (e.g. status fields) thus keeping the client logic to the bare minimum\r\n- a resource response may or may not include related subresources (the server determines if it wants to include them)\r\n\r\nSpecifically, we are using [HAL](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11), and an alternative approach, [json:api](https://jsonapi.org/) also exists (but to my taste is much more verbose). We also love using OpenAPI for documenting the actual data fields, the request payloads for mutating requests and query parameters for filters etc. However, we found out that it requires lots of boilerplate for describing the `_links` object, and especially the `_embedded` resources.\r\n\r\nIs anyone out there using either HAL or json:api, or a similar approach with OpenAPI? And if so, are you interested in either abstracting OpenAPI to natively support these concepts, or perhaps in a separate specification format designed for this type of APIs? Right now I am working on a example document, inspired by OpenAPI, of how such a specification might look like, focusing on HAL support for now.", "created_at": "2024-11-09T21:21:36Z", "updated_at": "2025-10-29T21:19:06Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "someniatko", "avatar_url": "https://avatars.githubusercontent.com/u/15856706?v=4" } }, { "id": "D_kwDOAQkWPc4AhSIy", "number": 4865, "title": "Should we put out a 3.0.5 (or formal Errata for 3.0.4)?", "body": "For good reasons, we declared that we would not do a 3.0.5 release.\r\n\r\nHowever, we have discovered some outright errors in the 3.0.4 text, most notably the guidance around percent-encoding and `in: header`, and to a more ambiguous degree around `multipart`. It would not be hard to backport these (and whatever other few trivial-to-backport 3.1.2 fixes, as there are really not that many) and do a 3.0.5. Or we could do something novel and issue errata.\r\n\r\n### 3.0.5 option\r\n\r\nWe could do a quick 3.0.5, either by manually constructing the document out of the published 3.0.4 spec using something akin to our old process of patching different files across branches (I still have a somewhat quirky script I can use for this), or by making a `v3.0-dev` branch.\r\n\r\nPros:\r\n* It's what people will expect\r\n* It would be the same publication process we know\r\n\r\nCons:\r\n* It's annoying work\r\n* We said we wouldn't do it\r\n\r\n### Errata option\r\n\r\nWe could edit 3.0.4 in-place to add \"Errata\" links (ideally at the top of each section with errors) to something hosted on the spec site. Note that this is what IETF does, and we usually cite IETF as the precedent for _not_ updating in place, so this sort of update-in-place should be fine. (idk if W3C does this or not)\r\n\r\nPros:\r\n* We don't need to resurrect a branch\r\n\r\nCons:\r\n* No one will expect it or know to look for it\r\n* No one reads the top-level intro part, so we'd need to put more Errata links than an IETF RFC does\r\n* We'll still need to do annoying infrastructure work\r\n\r\nTagging @OAI/tsc \r\n\r\n\r\n", "created_at": "2025-08-13T18:16:56Z", "updated_at": "2025-10-29T20:38:54Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4Aimuq", "number": 5067, "title": "Response Object with optional empty response via content negotiation.", "body": "How would I model a Response Object where one of the `content` options is an empty response when all keys have to be a media type or media type range and there isn't a media type for empy responses?\r\n\r\nMy API uses [RFC7240](https://www.rfc-editor.org/rfc/rfc7240.html) `Prefer` headers, specifically `return=minimal` or `return=representation` to allow the client to request either an empty response or the resources full representation on some endpoints depending on its own requirements.\r\n\r\nthis would result in say a `POST` endpoint for a collection path where either of the following are possible:\r\n\r\n```http\r\nPOST /foo\r\ncontent-type: application/json\r\nprefer: return=minimal\r\n\r\n{\"foo\": \"bar\"}\r\n\r\n\r\nHTTP/1.1 201\r\npreference-applied: return=minimal\r\nlocation: http://example.com/foo/123\r\n```\r\n\r\nor \r\n\r\n```http\r\nPOST /foo\r\ncontent-type: application/json\r\nprefer: return=representation\r\n\r\n{\"foo\": \"bar\"}\r\n\r\n\r\nHTTP/1.1 201\r\npreference-applied: return=minimal\r\nlocation: http://example.com/foo/123\r\ncontent-type: application/json\r\n\r\n{\"foo\": \"bar\"}\r\n```\r\n\r\nThe closest i can get is the following:\r\n\r\n```yaml\r\n...\r\npost:\r\n parameters:\r\n - name: prefer\r\n in: header\r\n required: false\r\n schema:\r\n type: string\r\n enum: [ \"return=minimal\", \"return=representation\" ]\r\n requestBody:\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n foo:\r\n type: str\r\n required: true\r\n responses:\r\n \"201\":\r\n headers:\r\n location:\r\n schema:\r\n type: string\r\n format: uri\r\n preference-applied:\r\n schema:\r\n type: string\r\n enum: [ \"return=minimal\", \"return=representation\" ]\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n foo:\r\n type: str\r\n...\r\n```\r\n\r\nbut that implies that the `return=minimal` response returns the JSON body, is there an established value for the content key for \"no media type\"?\r\n\r\nand further, is there any way to tie the `Preference-Applied` header values to the individual responses to document it as a discriminator between the different responses?", "created_at": "2025-10-25T16:22:20Z", "updated_at": "2025-10-27T20:25:13Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A4Yp2", "body": "This is not an answer to your question, but rather an observation for the purpose of addressing this problem in the future: the problem is that for requests, \"requestBody\" is split out as a property of its own, allowing `\"required\":false` to be used when it is relevant, but there is nowhere to specify that a response body is optional because its \"content\" property is at the same level as the response headers. One possible solution is to add a \"responseBody\" underneath, which could have a \"required\" property, adjacent to \"content\".\r\n\r\n----------\r\n\r\nAs a potential stopgap solution, you could perhaps do this:\r\n\r\n```yaml\r\n...\r\n responses:\r\n \"201\":\r\n headers:\r\n ...\r\n content:\r\n application/json:\r\n description: \"used for prefer: return=representation\"\r\n schema:\r\n type: object\r\n properties:\r\n foo:\r\n type: str\r\n */*:\r\n description: \"no response body is returned for prefer: return=minimal\"\r\n schema: false\r\n```" }, "user": { "login": "danielknell", "avatar_url": "https://avatars.githubusercontent.com/u/229004?u=9e478bdda108f2ab302049de9cfbbf607bbc9e51&v=4" } }, { "id": "D_kwDOAQkWPc4AOrkB", "number": 2875, "title": "What is the meaning of an empty \"content\" definition?", "body": "For a Request Body Object, the \"content\" attribute must be defined. But what if no media type mappings are specified? Is an empty \"content\" definition valid? If so, what does it mean? Equivalent to \"content undefined\", i.e. an error? That any kind of content data is acceptable?\r\n\r\nThe same question arises for the \"content\" of a Response Object (although \"content\" is optional there) and a Parameter Object", "created_at": "2022-02-01T23:08:50Z", "updated_at": "2025-10-25T16:25:48Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AH-4p", "body": "From what I recall, `content` is available in three places - **Parameter Object**, **Request Body Object** and **Response Object**.\r\n\r\n**Parameter Object** - the documentation states that one and only one media type must be in the map, so no problem there.\r\n\r\n**Request Body Object** - I believe there's an oversight here. I think we should have mentioned that by minimum, a single map entry is required. The reason being is that **Request Body Object** is not a required field in an operation, and if you specify it, it means that there's necessarily a payload. If there's necessarily a payload, you need to define what kind of payload it is. Maybe some more feedback from the @OAI/tsc is needed here, but I think that's a clarification we can put in v3.1.1.\r\n\r\n**Response Object** - unlike request bodies, responses don't necessarily have a payload even when you define them, which is why `content` is an optional field here. In this case, I would treat an empty `content` map as if the `content` field wasn't there at all." }, "user": { "login": "kerrykimbrough", "avatar_url": "https://avatars.githubusercontent.com/u/6577913?u=d013ab8a076390303f38eacbb375b27f36a80942&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTU0NjM1", "number": 2699, "title": "Same endpoint for POST and GET method without the duplicate key error?", "body": "Hello everyone, I am kinda confused as to why this isn't a thing, or I am I doing this wrong entirely?\r\n\r\nI have a user profile path `api/user/profile` with a GET `api/user/profile/{userID}` and POST method on the same path. Why isn't that supported, seems like the usual? I mean both should point to the same profile and only differ whether it's a post or a get method. Is this an issue when using a single YAML file or would the issue persist if I split them up into separate files?\r\n\r\n(Using swagger)", "created_at": "2021-09-03T12:28:43Z", "updated_at": "2025-10-17T19:21:11Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AQEm-", "body": "A path item can contain only one $ref. You'll have to put the GET and POST definitions into the same file so they can be $ref'erenced together:\r\n```yaml\r\npaths:\r\n /task-items/create:\r\n $ref: 'paths/task-items.create.yml'\r\n /task-lists:\r\n $ref: 'paths/task-lists.yml' # <------\r\n```\r\n\r\n```yaml\r\n# task-lists.yml\r\nget:\r\n summary: Get task lists\r\n ...\r\n\r\npost:\r\n summary: Create a task list\r\n ...\r\n```" }, "user": { "login": "Nikola-Milovic", "avatar_url": "https://avatars.githubusercontent.com/u/50072027?u=0b76960ab4042a6859bad474955aa4bbdc4c7ebc&v=4" } }, { "id": "D_kwDOAQkWPc4AhXKW", "number": 4880, "title": "How to create a new version dev branch such as v3.3-dev?", "body": "According to [Branching and merging (3.1.2, 3.2.0, and later)](https://github.com/OAI/OpenAPI-Specification/blob/main/CONTRIBUTING.md#branching-and-merging-312-320-and-later) we will create branch `v3.3-dev` from `dev`, despite the fact that\r\n* `src/oas.md`\r\n* `src/schemas/**`\r\n* `tests/schema/**`\r\n\r\nare hopelessly outdated on `dev` and the current content of `v3.2-dev` is the actual semantic starting point for 3.3 development.\r\n\r\nShouldn't we rather create `v3.3-dev` from `v3.2-dev`?\r\n\r\n\r\n", "created_at": "2025-08-17T12:27:15Z", "updated_at": "2025-10-02T20:03:06Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "ralfhandl", "avatar_url": "https://avatars.githubusercontent.com/u/951576?u=5f0aff13ce0c500d621a7a56585182cbf8c0caf7&v=4" } }, { "id": "D_kwDOAQkWPc4AiGqK", "number": 4992, "title": "Represent XML tag with multiple namespaces", "body": "Hi, I need to represent a Soap request that has the Envelope like this \"\". \r\n\r\nIn the oas actually the request look like this:\r\n\r\n```json\r\n \"createEnvelopeRequest\": {\r\n \"type\": \"object\",\r\n \"required\": [\r\n \"soap:Body\"\r\n ],\r\n \"properties\": {\r\n \"soap:Body\": {\r\n \"type\": \"object\",\r\n \"required\": [\r\n \"CreateAuthReq\"\r\n ],\r\n \"properties\": {\r\n \"CreateAuthReq\": {\r\n \"$ref\": \"#/components/schemas/createRequest\"\r\n }\r\n },\r\n \"xml\": {\r\n \"name\": \"Body\",\r\n \"prefix\": \"soap\"\r\n }\r\n }\r\n },\r\n \"xml\": {\r\n \"name\": \"Envelope\",\r\n \"namespace\": \"http://schemas.xmlsoap.org/soap/envelope/\",\r\n \"prefix\": \"soap\"\r\n }\r\n },\r\n```\r\nHow can I modify this to have multiple namespace/attributes(xmlns:other) in the soap:Envelope tag?", "created_at": "2025-09-24T08:28:52Z", "updated_at": "2025-10-01T07:31:47Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A3gt4", "body": "The workaround is to declare the `other` prefix on the nested node (element or attribute) that needs it. Pulling an XML namespace declaration up to an enclosing XML element or the XML document root node is just a convenience/shorthand. From an XML perspective these are equivalent:\r\n\r\n~~~xml\r\n\r\n \r\n …\r\n \r\n\r\n~~~ \r\n\r\nand\r\n\r\n~~~xml\r\n\r\n \r\n …\r\n \r\n\r\n~~~\r\n\r\nWith OpenAPI 3.2 each element and attribute can be represented as a node with the corresponding `nodeType` and its specific `namespace`.\r\n" }, "user": { "login": "nickkpiccoli", "avatar_url": "https://avatars.githubusercontent.com/u/105112747?u=c3e4192c1a563d11598793415767a6c287b08268&v=4" } }, { "id": "D_kwDOAQkWPc4Ac_FK", "number": 4235, "title": "Allow more attributes for \"Reference Object\"", "body": "Hi,\r\n\r\nI'm adopting OAS 3.1.1 now (creation), and I'm pleased that for \"Reference Object\" you added overriding the \"summary\" and \"description\", but this is not enough, as other attributes should also be overridden, like readOnly, writeOnly, etc.\r\nactually, the fact you removed the attribute \"nullable\" (in favor of the type \"null\"), is not good, as I like to override this in the \"Reference Object\" as well.\r\nlet me explain why:\r\nwhile I'd like to define a complex type only once when I use it as a reference for example as a parameter to a method (path), I'd like to say that in this case, it can be \"null\", or \"readOnly\", or \"writeOnly\", but it is not in general \"null\", \"readOnly\" or \"writeOnly\", exactly as now I can have a different \"description\".\r\nBTW: The same goes for the default value, example(s), which can be different depending on the usage and not related to the type itself (especially the default, where depending on its usage it can be different, like in enum types).\r\n\r\nanother remark:\r\nI used to simulate it by \"inheriting\", i.e. creating a new schema, with \"allOf\" as the \"Reference Object\", and adding all properties that I like to override without specifying the actual schema (as it is inherited by \"allOf\"), but now that \"nullable\" is a type. I can't do this trick anymore, as I can't override the type (there is no sense overriding type when \"inheriting\").\r\nfurthermore, this trick does not work anymore for enum types (yet another \"complex\" schema that should not be defined several times, as it causes other issues).\r\n\r\nplease please consider this request, as it is absolutely useful, and it makes version 3.0.x + my trick better that 3.1.x", "created_at": "2024-12-02T14:30:28Z", "updated_at": "2025-09-25T17:23:43Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "Amit-XMPie", "avatar_url": "https://avatars.githubusercontent.com/u/55362889?v=4" } }, { "id": "D_kwDOAQkWPc4Agzl6", "number": 4796, "title": "Content type sniffing priority (3.3+)", "body": "This is somewhat related to https://github.com/OAI/OpenAPI-Specification/issues/3306. I have a use case where I want the API definition itself to be clear that the server will sniff one or more content types per [RFC 9110 §8.3](https://www.rfc-editor.org/rfc/rfc9110.html#section-8.3):\r\n\r\n> A sender that generates a message containing content SHOULD generate a Content-Type header field in that message unless the intended media type of the enclosed representation is unknown to the sender. If a Content-Type header field is not present, the recipient MAY either assume a media type of \"application/octet-stream\" **or examine the data to determine its type**.\r\n\r\nNotably, I don't want to imply that sniffing will occur _except when a client does not provide the `content-type` header_.\r\n\r\nThe precise use case for me here is creating a mock server that matches the implemented sniffing behavior which allows `content-type` for request messages to be omitted for supported content types.\r\n\r\nOne way I can envision this being achieved is by allowing a `sniffPriority` keyword to the [Media Type Object](https://spec.openapis.org/oas/v3.1#media-type-object). This would serve to indicate in what order a well-behaved server (or client?) implementation should attempt to sniff the content type.\r\n\r\nFor my use case, I primarily care about simply indicating that if a client does not supply `content-type` then the server will still attempt to parse the content as JSON, but I can easily imagine a scenario where this would be used to indicate (for example) that if a client doesn't supply `content-type`, a server will try to sniff `application/json-patch+json` before it tries to sniff `application/merge-patch+json` given the the latter is a superset of the former.\r\n\r\nI can also imagine that, in the same way, in cases where an API definition is being used to described an existing server implementation which doesn't supply a content type, `sniffPriority` could suggest to client the order in which they should sniff the content to match it to handling specific to a schema. (Obviously I wouldn't advocate a greenfield API ever omit `content-type`.)\r\n\r\nThis suggestion is a bit tentative because it's a bit unclear to me whether the complexity of its addition to OpenAPI is disproportionate to the demand, whether it's really the right approach, and whether it is actually reasonable to encourage sniffing in _any_ scenario.\r\n\r\nBut I would be curious to see more discussion (or links to prior discussion I haven't been able to find) when time permits.", "created_at": "2025-07-18T15:48:03Z", "updated_at": "2025-09-23T19:01:16Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "hudlow", "avatar_url": "https://avatars.githubusercontent.com/u/1070061?u=d7d6b3106931a19ad8a8fe53f15a3ad8d59dadee&v=4" } }, { "id": "D_kwDOAQkWPc4Ahcgl", "number": 4892, "title": "Can we create a subfolder like structure? to display it on readme.io", "body": "# How to Create Hierarchical Folder Structure in OpenAPI Documentation?\r\n\r\n## 🤔 Question\r\n\r\nI'm working with a large OpenAPI specification (40+ endpoints) and trying to organize my documentation with a **hierarchical folder structure** in ReadMe. I want to achieve something like this in the sidebar:\r\n\r\n```\r\n📁 User Management\r\n├── 📁 Users\r\n│ ├── 📄 Create User\r\n│ ├── 📄 List All Users\r\n│ ├── 📄 Get User by ID\r\n│ └── 📁 Authentication\r\n│ ├── 📄 User Login\r\n│ ├── 📄 Refresh Token\r\n│ └── 📄 Logout\r\n├── 📁 Roles & Permissions\r\n│ ├── 📄 Create Role\r\n│ ├── 📄 Assign Permissions\r\n│ └── 📄 List User Roles\r\n└── 📁 Profile Management\r\n ├── 📄 Update Profile\r\n ├── 📄 Change Password\r\n └── 📄 Upload Avatar\r\n\r\n📁 E-commerce\r\n├── 📁 Products\r\n│ ├── 📄 Create Product\r\n│ ├── 📄 List Products\r\n│ ├── 📄 Update Product\r\n│ └── 📁 Categories\r\n│ ├── 📄 Create Category\r\n│ ├── 📄 List Categories\r\n│ └── 📄 Get Products by Category\r\n├── 📁 Orders\r\n│ ├── 📄 Create Order\r\n│ ├── 📄 Get Order Status\r\n│ └── 📁 Order Management\r\n│ ├── 📄 Update Order Status\r\n│ ├── 📄 Cancel Order\r\n│ └── 📄 Process Refund\r\n└── 📁 Shopping Cart\r\n ├── 📄 Add to Cart\r\n ├── 📄 View Cart\r\n └── 📄 Remove from Cart\r\n```\r\n\r\n**Is this possible with ReadMe's current OpenAPI implementation?**\r\n\r\n## 🔍 What I've Already Tried\r\n\r\n### Attempt 1: Hierarchical Tag Names\r\n```yaml\r\ntags:\r\n - name: \"User Management > Users\"\r\n - name: \"User Management > Users > Authentication\"\r\n - name: \"User Management > Roles & Permissions\"\r\n - name: \"E-commerce > Products\"\r\n - name: \"E-commerce > Products > Categories\"\r\n - name: \"E-commerce > Orders\"\r\n```\r\n**Result:** Creates flat tags with `>` in the name, no nesting\r\n\r\n### Attempt 2: Tag Groups (x-tagGroups)\r\n```yaml\r\nx-tagGroups:\r\n - name: User Management\r\n tags:\r\n - Users\r\n - User Authentication\r\n - Roles & Permissions\r\n - Profile Management\r\n - name: E-commerce\r\n tags:\r\n - Products\r\n - Product Categories\r\n - Orders\r\n - Shopping Cart\r\n```\r\n**Result:** Groups tags but still flat structure within groups\r\n\r\n### Attempt 3: Path-based Organization\r\nTried organizing file references in nested folders:\r\n```yaml\r\npaths:\r\n /users/auth/login:\r\n $ref: ./paths/UserManagement/Users/Authentication/post-login.yaml\r\n /products/categories:\r\n $ref: ./paths/Ecommerce/Products/Categories/get-categories.yaml\r\n```\r\n**Result:** Works for file organization but doesn't affect ReadMe sidebar structure\r\n\r\n## 💭 Current Environment\r\n- **ReadMe**: Latest version\r\n- **OpenAPI**: 3.0.0\r\n- **Format**: YAML\r\n- **API Size**: 40+ endpoints across 8 main categories\r\n\r\n## ❓ My Questions\r\n\r\n1. **Does ReadMe support nested/hierarchical folder structures for OpenAPI imports?**\r\n \r\n2. **If yes, what's the correct way to implement this?** \r\n - Are there specific OpenAPI extensions?\r\n - Should I use a particular tag structure?\r\n - Is there documentation I missed?\r\n\r\n3. **If no, is this feature on ReadMe's roadmap?**\r\n\r\n## 🎯 Why I Need This\r\n\r\n- **Large API**: 40+ endpoints become difficult to navigate in flat structure\r\n- **Logical Grouping**: Related endpoints (like user authentication under users, or product categories under products) should be grouped\r\n- **Developer Experience**: Users expect intuitive folder-like navigation similar to REST API explorers\r\n- **Professional Appearance**: Clean, organized documentation\r\n\r\n## 💡 Potential Solutions (If Feature Doesn't Exist)\r\n\r\nIf this isn't currently supported, I'd love to see:\r\n\r\n### Option 1: Enhanced Tag System\r\n```yaml\r\ntags:\r\n - name: \"User Authentication\"\r\n x-readme-parent: \"Users\"\r\n x-readme-folder: true\r\n```\r\n\r\n### Option 2: Folder Extension\r\n```yaml\r\nx-readme-folders:\r\n - name: \"User Management\"\r\n children:\r\n - name: \"Users\"\r\n children:\r\n - name: \"Authentication\"\r\n```\r\n\r\n### Option 3: Auto-inference from Paths\r\nAutomatically create folders based on URL structure:\r\n```\r\n/users/auth/login → Users > Authentication > Login\r\n/products/categories → Products > Categories\r\n/orders/management/cancel → Orders > Management > Cancel\r\n```\r\n\r\n---\r\n\r\n**Can anyone help me figure out if this is possible, or should I submit this as a feature request?**\r\n\r\nLooking forward to your insights! 🙏", "created_at": "2025-08-20T13:50:16Z", "updated_at": "2025-09-23T19:00:04Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A2VFI", "body": "OpenAPI 3.2 will add a `parent` field to the [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/v3.2-dev/src/oas.md#tag-object) which essentially is Option 1 of your potential solutions." }, "user": { "login": "vaibhavshah08", "avatar_url": "https://avatars.githubusercontent.com/u/93999223?u=7254f68e875050a86915ac38052a0e064cc6aa1c&v=4" } }, { "id": "D_kwDOAQkWPc4AhP7i", "number": 4827, "title": "Is there any guidance on the maximum no of end-points an API can have?", "body": "Hi,\r\n\r\nAre there any best practices or recommendations on the maximum number of endpoints in an API?\r\n\r\nAlso, the size of the API becomes harder to maintain with each feature or endpoint. \r\n\r\nWe need more documentation of API other than API Specification itself to understand and update it in the right way. \r\n\r\nDo you have any ideas or suggestions?\r\n\r\nThanks,\r\nTeja", "created_at": "2025-08-11T12:10:33Z", "updated_at": "2025-09-24T07:37:26Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4A3Rlx", "body": "No, we don't provide best practices for API designers. The OpenAPI Specification (OAS) is intended to allow folks to describe what they have (including inheriting APIs of arguably questionable design). The scalability of your tools is probably more of a concern. The OAS does not care how many endpoints you add, so I am going to close this as out-of-scope for us (but it is certainly a real and valid maintainability concern! Just not one we can solve)." }, "user": { "login": "teja-v1", "avatar_url": "https://avatars.githubusercontent.com/u/34726305?u=082a69b2231daf959fc13906971956dea0539ff0&v=4" } }, { "id": "D_kwDOAQkWPc4Ad22F", "number": 4300, "title": "multiple path parameters and strings in same path segment conform to OAS 3.0.x ?", "body": "I'm battling with a (api) security vendor about the conformity to OAS 3.0.x of such specfile snippet:\r\n```\r\npaths:\r\n \"/MaterialStocks(Material='{Material}',Warehouse='{Warehouse}')\":\r\n parameters:\r\n - name: Material\r\n in: path\r\n required: true\r\n description: \"Article Number \\nAlphanumeric key uniquely identifying the material.\"\r\n schema:\r\n type: string\r\n maxLength: 18\r\n - name: Warehouse\r\n in: path\r\n required: true\r\n description: \"Warehouse Number / Warehouse Complex \\nNumber that identifies a complex, physical warehouse structure within the Warehouse Management system. \\nAll activities within a warehouse, for example, goods movements and physical inventory, are assigned to a specific warehouse number. The physical warehouse where these activities take place is identified by the warehouse number.\"\r\n schema:\r\n type: string\r\n maxLength: 3\r\n get:\r\n summary: Get entity from MaterialStocks by key\r\n description: Reads material ID and base unit of measure for a specific material\r\n operationId: getMaterialStocksByKey\r\n tags:\r\n - Material Stock\r\n parameters:\r\n - name: $select\r\n in: query\r\n description: \"Select properties to be returned, see [Select](https://help.sap.com/doc/5890d27be418427993fafa6722cdc03b/Cloud/en-US/OdataV2.pdf#page=68)\"\r\n explode: false\r\n schema:\r\n type: array\r\n uniqueItems: true\r\n items:\r\n type: string\r\n enum:\r\n - Material\r\n - Warehouse\r\n - MaterialBaseUnit\r\n - to_WhseMatlStks\r\n - name: $expand\r\n in: query\r\n description: \"Expand related entities, see [Expand](https://help.sap.com/doc/5890d27be418427993fafa6722cdc03b/Cloud/en-US/OdataV2.pdf#page=63)\"\r\n explode: false\r\n schema:\r\n type: array\r\n uniqueItems: true\r\n items:\r\n type: string\r\n enum:\r\n - to_WhseMatlStks\r\n responses:\r\n \"200\":\r\n description: Retrieved entity\r\n content:\r\n application/json:\r\n schema:\r\n title: MaterialStock\r\n type: object\r\n properties:\r\n d:\r\n $ref: \"#/components/schemas/ZAPI_WM_MATERIAL_STOCK_SRV.MaterialStock\"\r\n 4XX:\r\n $ref: \"#/components/responses/error\"\r\n 5XX:\r\n $ref: \"#/components/responses/error\"\r\n\r\n```\r\n\r\nThat security vendor tells me that those path parameters definitions ( `\"/MaterialStocks(Material='{Material}',Warehouse='{Warehouse}')\"`) are not conform and therefor their product cannot interpret it correctly.\r\nIt's true that in examples found on [swagger.io](https://swagger.io/docs/specification/v2_0/describing-parameters/#path-parameters) and other places around, the positional parameter is the path-segment such as in \"`/MaterialStocks/{Material}/{Warehouse}`\"\r\n\r\nOn the other hand, it seems that my spec file snippet is conform to RFC6570. I've found also a couple of examples of such specfile such as [here](https://oasis-tcs.github.io/odata-openapi/examples/TripPin.openapi3.json)\r\n\r\nSo my question would be basically: is that snippet conform to OAS 3.0.x or not?\r\n", "created_at": "2025-01-15T11:12:44Z", "updated_at": "2025-09-23T18:53:50Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "amolari", "avatar_url": "https://avatars.githubusercontent.com/u/17331976?v=4" } }, { "id": "D_kwDOAQkWPc4AZJk9", "number": 3771, "title": "Registry of media type modeling approaches", "body": "It's fairly common for people to want to model things that are not obviously mapped to the JSON Schema data model. We basically support a few media types, which would include any variations with a structured suffix (e.g. `+json`) as long as the additional features of the media type don't need to be modeled:\r\n\r\n* `application/json` is supported natively with the Schema Object\r\n* `application/xml` is supported (to some degree) with the XML Object\r\n* `application/x-www-form-urlencoded` is supported (to some degree) in message bodies with the Encoding Object\r\n* `multipart/form-data` is supported (to some degree) with the Encoding Object\r\n* `text/plain` is arguably supported by treating it as a single string, but [arguably](https://github.com/OAI/OpenAPI-Specification/issues/3761) you could do more with textual serialization of data\r\n\r\nThe spec talks about `multipart` in general, but other multipart formats use ordered rather than named parts, which makes the Encoding Object [unsuitable](https://github.com/OAI/OpenAPI-Specification/issues/3721). We also have requests for formats with [a little more information than JSON](https://github.com/OAI/OpenAPI-Specification/issues/3108).\r\n\r\nWe definitely want to keep some media types in the spec, as they are either commonly used in HTTP APIs, or have significant enough historical usage that they need an interoperable way to be modeled.\r\n\r\nBut other media types are more fringe, or emerging, or are such niche historical oddities that it's not worth trying to define an _mandatory_ interoperable approach. But they could still use some interoperability that's more opt-in.\r\n\r\nTherefore I'd like to propose a new registry for defining how the a media type can be mapped to the JSON Schema data model. In some cases, [this is pretty intuitive](https://github.com/OAI/OpenAPI-Specification/issues/3730) and doesn't even require much implementaton support. In other cases, it might get pretty elaborate, but we can let the community sort out what is worth imlementing or not.\r\n\r\n***Why not just use x-fields?***\r\n\r\nThis proposal is essentially \"x-fields for media types.\" The approaches might use x-fields, but not all would need any x-fields, and some might need a combination of multiple ones. This is not an area that always breaks down to fields - both the XML Object and the Encoding Object are more complex than that. This would give more flexibility, plus a single place to look for this specific topic.\r\n\r\n***What about things without media types?***\r\n\r\nStructured headers come to mind, and would have a similar approach but without a media type. They also go somewhere different than request/response bodies, which need something to put in `Content-Type` anyway. If there are non-header, non-body things that need dealing with that don't have a media type, we can cross that bridge when we get to it.\r\n\r\n***Relevant issues:***\r\n\r\nMany of the issues with the [`media and encoding`](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue+is%3Aopen+label%3A%22media+and+encoding%22) label are relevant to greater or lesser degrees. Many (such as `application/json-seq` or `multipart/mixed`) are sufficiently core that they ought to be in the spec. But others, such as `application/cbor` are less obvious fits at this time, but well worth community experimentation.\r\n", "created_at": "2024-05-01T18:11:31Z", "updated_at": "2025-09-23T18:50:29Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4Abmbv", "number": 4114, "title": "OAD Structure and referencing in OpenAPI 3.1", "body": "We've been having a lot of discussions about document structure and how OAS and JSON Schema references work in various places, such as\r\n\r\n- In recent TDC meetings\r\n- In PR #4100, which is for 3.0 but winds up discussing how 3.1 works in places\r\n- In Slack, particularly [this _looooong_ thread in the spec channel](https://open-api.slack.com/archives/C1137F8HF/p1726772743170639)\r\n\r\nI think we can continue discussing the 3.0 behavior in #4100, but (to the degree that these can be separated) thought it would be a good idea to start a discussion focused primarily on the behavior in 3.1, which _I think_ most folks feel is what we want going forward.", "created_at": "2024-09-25T14:33:45Z", "updated_at": "2025-09-23T18:50:03Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "mikekistler", "avatar_url": "https://avatars.githubusercontent.com/u/85643503?u=fa69466be602e63350acf34b52c559a819d4617b&v=4" } }, { "id": "D_kwDOAQkWPc4ActjQ", "number": 4211, "title": "Allow `description` to be an object as well as a string", "body": "Our company uses OpenAPI for contract first development. In practice this means that not only Developers utilize OpenAPI contracts, but also DevOps and Security teams.\r\n\r\nAs such, each team uses the contract for different purposes. This often means we add different descriptions for each team.\r\n\r\nHowever, since the description property value is `string`, to target each team, we need to use an agreed internal notation like `[team]` followed by information specific for that team. Adding multiple teams and descriptions within the `description` string value causes our descriptions to balloon in size and are incredibly difficult to read.\r\n\r\nIf descriptions could also be allowed to be objects (or worst case, array) we instead could use the team names as properties and value description targeted specifically to them.\r\n\r\nAlthough this may seem like a very specific use case, I think it could allow much more generic use cases. For example, many APIs allow for dynamic payloads or requests. While these can sometimes be accurately described by OpenAPI itself (and JSON Schema), sometimes this is simply not possible, and additional context in the form of nested descriptions would help immensely. \r\n\r\nOne example I can think of would be the somewhat common use of URL parameter filtering using some variation of `term[operator]=value`. I believe there was discussion in other thread about the fact that no official support could be added to OpenAPI because there is no consistent implementation across languages and libraries. While not great, a `description` object with properties of the operators would give some flexibility in the description of each available operator.\r\n\r\nPerhaps this (or a similar solution) could be considered for the next major version of the OpenAPI spec?", "created_at": "2024-11-21T12:24:28Z", "updated_at": "2025-09-23T18:49:27Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "darcyrush", "avatar_url": "https://avatars.githubusercontent.com/u/22768040?v=4" } }, { "id": "D_kwDOAQkWPc4AeNMu", "number": 4330, "title": "Proposal for OpenAPI Extension: x-sensitive-data", "body": "1. Summary\r\nThis proposal introduces a standardized way to define sensitive data fields in OpenAPI specifications using the x-sensitive-data extension. By integrating this directly into API contracts, we enable automatic data masking, hashing, and redaction across various API tools, including logging systems, API gateways, and security scanners.\r\n\r\n2. Problem Statement\r\nCurrently, OpenAPI lacks a standard way to identify and handle sensitive fields such as passwords, personal identifiable information (PII), or financial data. API providers must manually implement security policies, leading to inconsistencies and potential security gaps. This proposal addresses:\r\n- Automated masking for sensitive request/response data\r\n- Standardized compliance with regulations (GDPR, HIPAA, PCI-DSS)\r\n- Security enhancement by reducing accidental data leaks in logs\r\n- Developer-friendly API design with built-in security metadata\r\n\r\n3. Proposed Solution: x-sensitive-data Extension\r\nWe introduce x-sensitive-data as an optional extension for OpenAPI Schema Objects. This extension allows defining sensitive fields, specifying masking strategies, and enabling annotation-based processing where applicable.\r\n\r\n3.1 Example OpenAPI Usage\r\n```json\r\nopenapi: 3.1.0\r\ninfo:\r\n title: User API\r\n version: 1.0.0\r\npaths:\r\n /users:\r\n post:\r\n summary: Create a new user\r\n requestBody:\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/User'\r\n responses:\r\n '200':\r\n description: Successfully created user\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/User'\r\ncomponents:\r\n schemas:\r\n User:\r\n type: object\r\n properties:\r\n username:\r\n type: string\r\n password:\r\n type: string\r\n x-sensitive-data: \r\n mask: full\r\n email:\r\n type: string\r\n x-sensitive-data:\r\n mask: regex\r\n pattern: \"^[^@]+\"\r\n ssn:\r\n type: string\r\n x-sensitive-data:\r\n mask: hash\r\n algorithm: sha256\r\n```\r\n\r\n4. Features and Benefits\r\n\r\n4.1 Masking Strategies - examples\r\nStrategy Description\r\n- full -> Replace entire value with ***\r\n- regex -> Mask specific parts using regex pattern\r\n- hash -> Hash value (e.g., SHA-256)\r\n- remove -> Remove field completely from logs\r\n\r\n4.2 How It Works in API Tools\r\n- API Gateways: Enforce automatic masking before responses are sent.\r\n- Logging Systems: Automatically obfuscate sensitive fields.\r\n- Security Scanners: Detect misconfigured APIs exposing sensitive data.\r\n- Validation Tools: Ensure compliance with security policies.\r\n\r\n5. Optional Integration: Annotations for Code-Level Mapping\r\nFor languages like Java, TypeScript, and Python, we propose introducing standardized annotations that can be mapped to OpenAPI x-sensitive-data fields. Example:\r\n\r\n```java\r\n@MaskSensitive\r\npublic class User {\r\n private String username;\r\n\r\n @SensitiveData(strategy = MaskStrategy.FULL)\r\n private String password;\r\n\r\n @SensitiveData(strategy = MaskStrategy.HASH, algorithm = \"SHA-256\")\r\n private String ssn;\r\n}\r\n\r\nE.g. annotations are automatically generated from OpenAPI definitions:\r\n- @MaskSensitive (class-level) → indicates that some fields in the class should be masked based on their @SensitiveData annotations;\r\n- @SensitiveData (field-level) → specifies which fields are sensitive and how they should be masked.\r\n```\r\nFrameworks (Spring, FastAPI, Express) can use these annotations to automatically generate OpenAPI definitions with x-sensitive-data fields.", "created_at": "2025-02-05T08:18:29Z", "updated_at": "2025-09-23T18:33:06Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "cristigirbovan", "avatar_url": "https://avatars.githubusercontent.com/u/29273627?u=15258b78ab5f47ca85526453ded4685da28ec683&v=4" } }, { "id": "D_kwDOAQkWPc4Ahvwg", "number": 4925, "title": "Security Schema, env/server dependent", "body": "I have a microservice with endpoints secured using OAuth 2.0. The service runs in three different servers/environments (Local, Dev, and SIT), and each environment uses a different authorization server with its own Auth URL, Access Token URL, etc. Is there a way to define a single security schema that can adjust these URLs automatically based on the selected server/environment?", "created_at": "2025-09-05T18:49:53Z", "updated_at": "2025-09-22T23:28:26Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "DavDeDev", "avatar_url": "https://avatars.githubusercontent.com/u/104097735?u=3b94a6f9b983d14d328e5b28c447ad92a82b46d9&v=4" } }, { "id": "D_kwDOAQkWPc4Ah6t3", "number": 4955, "title": "Schema Releases", "body": "Currently the publication of new schema iterations happens quietly and often goes unnoticed.\n\nWe could announce new schema iterations more prominently by making them _releases_, for example with release names `X.Y Schemas YYYY-MM-DD` and tags `X.Y.schemas-YYYY-MM-DD`, see https://github.com/ralfhandl/express-experiments/releases for an experiment.\r\n\r\nThe latest release, whether spec release or schema release, is labeled \"Latest\" and will appear in the right sidebar of the repo start page.\r\n\r\nOn the \"Releases\" page the releases are sorted by tag in a semantic-version fashion. This means with spec releases tagged `X.Y.Z` and schema release tags prefixed with `X.Y.schemas-`, the spec releases will be on top in reverse order, then after the `X.Y.0` spec the schema releases in reverse order, then the pattern repeats for the preceding MAJOR.MINOR spec and schema releases.\n\nThe schema publishing workflow could automatically create a draft schema release corresponding to the schema publishing PR. When the PR is merged, the draft release can be published.\n\nWhat do you think?", "created_at": "2025-09-13T18:24:16Z", "updated_at": "2025-11-08T21:04:15Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "ralfhandl", "avatar_url": "https://avatars.githubusercontent.com/u/951576?u=5f0aff13ce0c500d621a7a56585182cbf8c0caf7&v=4" } }, { "id": "D_kwDOAQkWPc4AhUIi", "number": 4871, "title": "Schema test coverage: split tests into versioned directories", "body": "I noticed that all the schema tests are in `tests/schema/fail` and `tests/schema/pass`. These directories are going to get mighty huge as more and more tests are added for different spec versions.\r\n\r\n- could these be split up by one more subdir, by openapi spec version? That will make it easier to spot (e.g. by inspecting filenames) whether a particular keyword has any coverage or not.\r\n- this involves a bit more scripting, but instead of cloning all the passing 3.1 tests into 3.2, the test runner could do `s/3.1/3.2` for all tests in the 3.1 dir and also run them against the 3.2 schema -- because all valid 3.1 schemas should be valid 3.2 schemas. The fail tests would have to be copied manually though as some 3.1/fail tests could be in 3.2/pass (we SHOULD copy every new 3.2/pass test into 3.1/fail -- e.g. `openapi: 3.1` combined with `additionalOperations` should be a fail).\r\n\r\n\r\n\r\n---------------------\r\n\r\n...addendum that is probably of zero interest to anyone but me: I was originally thinking about writing up a request that the 3.2 schema make this change:\r\n\r\n```diff\r\n- pattern: '^3\\.2\\.\\d+(-.+)?$'\r\n+ pattern: '^3\\.[12]\\.\\d+(-.+)?$'`\r\n```\r\n\r\n...so as to allow the 3.2 schema (and implementations defaulting to 3.2) to parse 3.1 OADs, but then I realized there would be no way to do the above: that is ensure that 3.1 documents don't include 3.2-only constructs by mistake (which would then fail to work on a 3.1-only implementation).\r\n\r\nI was wanting to have to avoid my implementation having to parse the `openapi` line to determine the version if it was going to happily support 3.1 and 3.2 anyway -- since 3.2 is backwards compatible, so any implementation that supports 3.2 should be able to support everything and all OAD constructs in 3.1 so it seemed unnecessary. It was only when I started thinking about negative testing scenarios that I realized I was being dumb, and I'll have to bifurcate bits of my application for 3.2 after all, boo!", "created_at": "2025-08-14T23:45:31Z", "updated_at": "2025-09-08T07:08:13Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "karenetheridge", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4" } }, { "id": "D_kwDOAQkWPc4Af3AL", "number": 4622, "title": "How should parameter examples be written?", "body": "I'm trying to understand whether or not to apply serialization to parameter examples. If I'm following https://github.com/OAI/OpenAPI-Specification/issues/3041 and the changes added to 3.0.4, it looks like parameter examples should be serialized according to this table:\r\nhttps://spec.openapis.org/oas/v3.0.4.html#style-examples\r\n\r\nSo then I'd have parameters specified like this:\r\n```yaml\r\nparameters:\r\n - name: foo\r\n in: query\r\n required: true\r\n schema:\r\n type: string\r\n enum:\r\n - blue\r\n explode: false\r\n example: ?foo=blue # Instead of \"blue\"\r\n - name: colors\r\n in: query\r\n required: true\r\n explode: false\r\n schema:\r\n type: array\r\n items:\r\n type: string\r\n example: \"?color=blue,black,brown\" # Instead of [\"blue\", \"black\", \"brown\"]\r\n```\r\n\r\nHowever this seems to cause problems for the tooling I've tested with (swagger-ui, spectral, vacuum) and seems to contradict documentation around parameters elsewhere (where the serialization:\r\nhttps://swagger.io/docs/specification/v3_0/describing-parameters/#parameter-examples\r\n\r\nI work on a tool that generates Open API and am adding support for emitting parameter examples, but came across issues around tooling support as part of validation. I'm curious if there are _any_ tools that do work with the serialized examples.", "created_at": "2025-05-20T21:40:52Z", "updated_at": "2025-09-07T18:30:41Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AzEDe", "body": "I have filed several issues and PRs to move various parts of this to conclusion:\r\n\r\n* #4647 _**[Now split into...]**_\r\n * #4671 \r\n * #4672 \r\n * #4673 \r\n * (more example updates forthcoming)\r\n* #4648 \r\n* #4658\r\n * @mikekistler @lornajane I have added this as a release-blocking issue to #4595 so that we can merge this PR with the current names while we keep debating the permanent names. Let's not keep this held open once we agree on the behvior\r\n* #4659 \r\n* #4660 \r\n* #4661 \r\n* #4662 \r\n* #4664 \r\n" }, "user": { "login": "chrisradek", "avatar_url": "https://avatars.githubusercontent.com/u/14189820?u=c84dda13e31c2978b53e23f17006724a81efcf62&v=4" } }, { "id": "D_kwDOAQkWPc4AcPwu", "number": 4171, "title": "An SSE Proposal", "body": "### Introduction\r\n\r\nServer-Sent Events are an HTTP-based way for servers to push data to clients as \"events\", blessed with an official specification in Javascript on the client side. Unlikely websockets or gRPC it can't do bidirectional communication, but it also sticks to text-based HTTP rather than \"upgrading\" to a binary protocol.\r\n\r\nThe latter point I believe makes it suitable for description as a REST resource. For example it allows the description of complex resources such as \"progress\" - the server performs a long-running activity; this activity's progress can be modelled as a REST resource using SSE.\r\n\r\nGiven SSE is a free-text medium, just as HTTP is, I believe it would be wise to add certain opinions to the OpenAPI way of specifying it. This proposal is of what I think those opinions could be and why, and a possible resulting OpenAPI description.\r\n\r\n### The proposed opinions\r\n- While SSE can send any text data, it should be limited here to JSON. This allows the usual OpenAPI descriptors to be used in describing the shape of event data. In the future XML could be added if it were popular.\r\n- SSE has optional event names to accompany a particular data push. This allows clients to parse different event types differently, based on the event name. Event names should be mandatory in the OpenAPI specification, to allow simple generation and use of different possible events on the client side.\r\n- SSE has an event ID to send. My feeling is this should be made available in clients if it is present, but as it is more for clients to request from a certain point in a message stream, it does not need to be specified in OpenAPI.\r\n\r\n### The proposed format\r\nThe format tries to incorporate standard OpenAPI semantics.\r\n\r\nThe only deviation is how the event type is specified, as a key under the `anyOf` node. I considered an `x-` property, such as `x-event-name` in the component schema, but that would be difficult with any resources that are used in multiple event types. It also makes the event name appear optional, which I think would be a mistake. Open to alternatives, of course.\r\n\r\n```yaml\r\nresponses:\r\n \"200\":\r\n description: \"Activity in progress\"\r\n content:\r\n text/event-stream:\r\n anyOf:\r\n \"event_in_progress\":\r\n schema:\r\n $ref: \"#/components/schemas/EventProgess\"\r\n \"event_completed\":\r\n schema:\r\n $ref: \"#/components/schemas/EventWithCompletionData\"\r\n```\r\n### Additional comments:\r\n- The use of `anyOf` may not be what that is intended for, but it appears to be the best fit to my current understanding.\r\n- I wonder if each event could have its own content-type within the SSE format. That would allow any type of data in each event - clunky example:\r\n ```yaml\r\n anyOf:\r\n \"event_in_progress\":\r\n eventContentType: \"application/json\"\r\n schema:\r\n $ref: \"#/components/schemas/EventProgess\"\r\n \"event_completed\":\r\n eventContentType: \"text/plain\"\r\n schema:\r\n $ref: \"#/components/schemas/EventWithCompletionData\"\r\n ```\r\n\r\n### Thanks for reading\r\nI'd love feedback on this proposal. Very happy to work asynchonously in the Github-style, but also happy to join the calls and talk through it at some point, if there's time available in them.\r\n\r\n### P.s.\r\nThere was an issue opened on this already. I believe I've read the entire thing, but thought a new discussion might be a better (re)-starting place. Many thanks to nikojpapa's [comment](https://github.com/OAI/OpenAPI-Specification/issues/396#issuecomment-1958240639) that the proposed format was originally based on.", "created_at": "2024-11-01T07:32:38Z", "updated_at": "2025-09-06T03:49:40Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "robertlagrant", "avatar_url": "https://avatars.githubusercontent.com/u/1766161?u=e1d1d848c477aae35834789167e5599a9569b10a&v=4" } }, { "id": "D_kwDOAQkWPc4AgAZ_", "number": 4643, "title": "JSON Schema for YAML usage", "body": "Hi everybody, \r\n\r\nI'd like to open discussion on clarifying the following OpenAPI excerpt (3.x.y):\r\n> In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:\r\nTags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231).\r\nKeys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346).\r\n\r\nspecifically\r\n\r\n> Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231).\r\nWhat does it actually mean, or rather what was intended by this sentence? Let me explain my question further...\r\n\r\n---\r\n**1.** we can say that this sentence means that tag resolution is driven by JSON Schema ruleset (and its extended list of regular expressions), it effectively means that following YAML is invalid:\r\n\r\n```yaml\r\nopenapi: 3.0.4\r\n```\r\n\r\nIt can only be valid if we define it like this:\r\n\r\n```yaml\r\n! openapi: ! 3.0.4\r\n---\r\n\"openapi\": \"3.0.4\"\r\n---\r\n'openapi': '3.0.4'\r\n---\r\n!!str openapi: !!str \"3.0.4\"\r\n---\r\n```\r\n\r\n**2.** we can say that this sentence means that we can basically use any YAML Schema derived from JSON Shema ruleset (like Core) as long as the tag names are the same as in JSON Schema regardless of the resolution rules and extended list of regular expressions; which makes following valid YAML\r\n\r\n```yaml\r\nopenapi: 3.0.4\r\n```\r\n\r\n---\r\n\r\nI'm assuming it was intended to target option 1.? As we probably want to retain all the info during the YAML/JSON round-trips (but I might be completely wrong)\r\n\r\n```yaml\r\nkey: FALSE\r\n```\r\n\r\nbecomes\r\n\r\n```json\r\n{\"key\": \"FALSE\"}\r\n```\r\nand not\r\n{\"key\": false}", "created_at": "2025-05-29T20:26:29Z", "updated_at": "2025-09-06T03:48:05Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "char0n", "avatar_url": "https://avatars.githubusercontent.com/u/193286?u=c89f3c6595b483483d3f7d66cb8287e744bb52f4&v=4" } }, { "id": "D_kwDOAQkWPc4AR2H5", "number": 3102, "title": "Strategies on documenting filter query format in OpenAPI spec", "body": "My team is working on an OpenAPI spec for a new API, and we're implementing a new filtering capacity for resources.\r\n\r\nFor example:\r\n`/entity?page=1&results_per_page=50&filters= column-a eq value-b, column-b neq value-b, column-c lte value-c`\r\n\r\nI'd like to be able to denote the available options for filters for ALL endpoints where filter is a possible query param, but not quite sure what the best approach would be, since the format is specific to filters.\r\n\r\nAnyone have a suggestion or pattern for describing this?", "created_at": "2022-12-19T20:01:49Z", "updated_at": "2025-08-21T12:11:00Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "geoff-maddock", "avatar_url": "https://avatars.githubusercontent.com/u/55493?u=e455d661bd0987e03f8ce707ff01488b4342e814&v=4" } }, { "id": "D_kwDOAQkWPc4AhQqY", "number": 4836, "title": "Security: Add optional client_id attribute to OAuth2", "body": "If you use a 3rd party OAuth2 provider (like Google, Facebook, Microsoft), it is quite common to require the token needs to be created by your OAuth2 client, because your OAuth2 client requires specific scopes/permissions.\r\n\r\nAFAIK it is not possible to specify the client_id in [oauth-flow-object](https://spec.openapis.org/oas/latest.html#oauth-flow-object), is it?\r\n\r\nUse-case: We don't want to implement the redirecting flows in our api provider but require the api consumer to proactively fetch an token first (using Resource Owner Password Flow with required mTLS) but this requires passing the client_id.", "created_at": "2025-08-12T08:00:16Z", "updated_at": "2025-08-17T22:00:41Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "hfhbd", "avatar_url": "https://avatars.githubusercontent.com/u/22521688?u=1b966c21297436b7035142a38d270eac5d37aaaa&v=4" } }, { "id": "D_kwDOAQkWPc4AhQ7e", "number": 4841, "title": "Schema test coverage: which thresholds are useful?", "body": "The new [JSON Schema Test Coverage tool](https://github.com/hyperjump-io/json-schema-coverage) we are now using allows to set separate coverage thresholds for\r\n\r\n* **Lines**\r\n* **Statements** = JSON Schema keywords\r\n* **Functions** = subschemas\r\n* **Branches** = true/false branches for each keyword (except for keywords that don't branch such as annotation-only keywords like `title` and `description`)\r\n\r\n## Suggestion\r\n\r\nSet coverage thresholds of\r\n* 100% for lines\r\n* 100% for keywords (statements)\r\n* 100% for subschemas (functions)\r\n* no threshold for branches\r\n\r\n## Rationale\r\n\r\n### Lines and Statements\r\n\r\nThe natural threshold for lines and statements is 100% - if we have a line/keyword in our schema that we don't touch in at least one test case, then someone could remove that line/keyword and the automated PR status check for schema tests would still be green.\r\n\r\nIt also helps spotting test cases that fail for the wrong reason, such as the two test cases that are now being fixed by\r\n* https://github.com/OAI/OpenAPI-Specification/pull/4840\r\n\r\nThese were intended to cover schema lines\r\n\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/805084db4505e05e71da13c3b9d56564dacc07e6/src/schemas/validation/schema.yaml#L604-L608\r\n\r\nand failed before reaching that part of the schema due to another unintended failure condition.\r\n\r\n### Subschemas (Functions)\r\n\r\nSubschema coverage includes\r\n* the keyword `unevaluatedProperties` which takes a subschema as its argument, and \r\n* the keyword `properties` which takes a map as its argument where the map values are subschemas.\r\n\r\nThis means that we can only be sure to have covered all properties in our schema if we strive for subschema (function) coverage of 100%.\r\n\r\n### Branches\r\n\r\nCovering 100% of all branches seems less useful because for a keyword use such as\r\n\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/805084db4505e05e71da13c3b9d56564dacc07e6/src/schemas/validation/schema.yaml#L844-L846\r\n\r\nthe corresponding two branches can be covered with a \"pass\" test case providing an object, and a \"fail\" test case providing an array, which leaves both good cases (providing a boolean) or bad cases (providing a number, a string, or null) uncovered.", "created_at": "2025-08-12T13:31:21Z", "updated_at": "2025-08-14T16:46:29Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "ralfhandl", "avatar_url": "https://avatars.githubusercontent.com/u/951576?u=5f0aff13ce0c500d621a7a56585182cbf8c0caf7&v=4" } }, { "id": "D_kwDOAQkWPc4AhTdz", "number": 4866, "title": "provide API versions history", "body": "Hi there\r\n\r\nI found usefull to give a info about actual version and some brief history to an API consumer. Now, every API module has endpoints `/watchdog`, `/openapi` and `/versions`. `GET /versions` gives json which looks like this:\r\n\r\n```\r\n{\r\n \"module\": \"registration\",\r\n \"version\": \"1.2.1\",\r\n \"history\": [\r\n {\r\n \"version\": \"1.2.1\",\r\n \"date\": \"2025-08-14T14:03:04\",\r\n \"description\": \"* endpoint GET \\\"/aml-options\\\" extended with non-mandatory query param \\\"option\\\". If empty, all options are returned\"\r\n },\r\n {\r\n \"version\": \"1.2.0\",\r\n \"date\": \"2025-07-17T09:11:10\",\r\n \"description\": \"* endpoint GET \\\"/aml-options\\\" - added fields \\\"items_src\\\" and \\\"items_map\\\" if source is external\\n * \\\"items_src\\\" - link to external items source\\n * \\\"items_map\\\" - json with mapping between external source and aml-options item list structure\"\r\n}\r\n```\r\n\r\nDescription is formated in markdown.\r\n\r\nThis code is (like `/openapi`) dynamicaly generated. So the advantage of giving an API consumer info about history and actual changelist lays in the fact that the **developer knows anytime what he/she is working with and if required feature is already implemented or not**.\r\n\r\n---\r\n\r\n**The problem:** what is best way to include these informations in openapi documentation? Something like the dev opens Swagger and see it formated. I know about extensions (like including this json in \"x-api-history\"), but these are ignored by Swagger and there has to be some Swagger plugin development. Doesn't exist something like that nowadays? Or what do you see as preferable solution?\r\n\r\nThanks for advices and have a fine day :)\r\n\r\nAdam L.", "created_at": "2025-08-14T14:14:53Z", "updated_at": "2025-08-14T15:46:11Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "adam-lipovsky", "avatar_url": "https://avatars.githubusercontent.com/u/110613230?u=47aad4b9aaaa423c8d5779aa52496531bee20a30&v=4" } }, { "id": "D_kwDOAQkWPc4Ag49P", "number": 4807, "title": "Support oauth 2.0 token exchange (RFC 8693)", "body": "[RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) implements an extension to oauth, implement a new flow with `grant_type` set to `urn:ietf:params:oauth:grant-type:token-exchange` to represent a token exchange. It would be nice for this to be one of the supported flows in the OpenAPI spec", "created_at": "2025-07-22T20:16:14Z", "updated_at": "2025-07-23T17:10:43Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "HiranmayaGundu", "avatar_url": "https://avatars.githubusercontent.com/u/23412234?u=daa80a166fabaf20b85ddae5e52ab05a5583f1f8&v=4" } }, { "id": "D_kwDOAQkWPc4Agxp_", "number": 4784, "title": "Formalize Webhooks Subscribe/Unsubscribe", "body": "Webhooks were added in addition to callbacks in OAS 3.1 with this proposal:\r\nhttps://github.com/OAI/OpenAPI-Specification/pull/1974\r\n\r\nI understand callbacks to be typically delayed responses to a request - hence one provides a dedicated callback URL in order to identify the matching request a delayed response belongs to.\r\n\r\nWebhooks are different in that unrelated events/messages are sent to the client. Great to see that this was added in OAS 3.1.\r\n\r\nI was wondering whether an option could be added to formalize a client subscribing to events as well as unsubscribing from them. There likely will be an API to do so, but it won't be possible for a OAS tool chains to figure out what APIs to call to subscribe/unsubscribe to events and what parameters to use to identify a subscription. This could be as simple as the client's webhook URL, but there are implementations that use a different subscription identifier.\r\n\r\nFor the \"newPet\" webhook example, it would be good to have a reference to a path elements that performs the subscription on the server or the path elements a decorator identifying which webhook and whether it's a subscribe/unsubscribe.", "created_at": "2023-01-26T22:20:05Z", "updated_at": "2025-07-16T18:10:41Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "tpollingsf", "avatar_url": "https://avatars.githubusercontent.com/u/21070377?v=4" } }, { "id": "D_kwDOAQkWPc4AfMT2", "number": 4533, "title": "Add DateTime and Time without TimeZone", "body": "## Proposal\r\n\r\nI suggest adding `date-time-local` and `time-local` to the [Format Registry](https://spec.openapis.org/registry/format/).\r\n\r\nI am developing a [TOML Language Server](https://github.com/tombi-toml/tombi) with validation feature using JSON Schema.\r\n\r\n[LocalDatetime](https://toml.io/en/v1.0.0#local-date-time) and [LocalTime](https://toml.io/en/v1.0.0#local-time) are defined in TOML as specifications, but there is currently no corresponding String format in JSON Schema.\r\n\r\n[I sought help from the JSON Schema community](https://github.com/orgs/json-schema-org/discussions/894\r\n) and was referred here.\r\n\r\n\r\n## About naming\r\n\r\n`date-time-local` is named differently from TOML.\r\nI believe it is more consistent with other formats if it is first indicated to be a date.\r\nAlso, [datetime-local](https://developer.mozilla.org/ja/docs/Web/HTML/Element/input/datetime-local) exists in html.\r\n", "created_at": "2025-04-07T23:53:37Z", "updated_at": "2025-07-10T23:47:24Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "ya7010", "avatar_url": "https://avatars.githubusercontent.com/u/47286750?u=54e9fdee192a24fed001b131f88fb2f12d8fba46&v=4" } }, { "id": "D_kwDOAQkWPc4AgiXi", "number": 4756, "title": "Add example(s) to securitySchemes:", "body": "To help convey how an `apikey` might look (an UUID, an object Key, a ULID, a base64 string), I believe `example` or `examples` should be added to `securitySchemes`. Presumably the idea of not having it was due to security concerns someone would put in an actual key instead of an example. But a careless spec author could just as easily inadvertently expose a key in the `description` as in an `example`. \r\n\r\ncomponents:\r\n securitySchemes:\r\n ApiKeyAuth:\r\n type: apiKey\r\n in: header\r\n name: X-API-Key\r\n description: Use your provided key like ABC123.\r\n example: ABC123", "created_at": "2025-07-04T06:41:48Z", "updated_at": "2025-07-04T15:46:52Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "kentbulza", "avatar_url": "https://avatars.githubusercontent.com/u/41305590?v=4" } }, { "id": "D_kwDOAQkWPc4Aghhc", "number": 4751, "title": "Add responses field to Link Object to describe expected responses of a linked operation post-link execution", "body": "### Summary\r\n\r\nThis proposal suggests adding an optional `responses` field to the [`Link Object`](https://spec.openapis.org/oas/v3.1.0#link-object), using the same structure as the [`Response Object`](https://spec.openapis.org/oas/v3.1.0#response-object), that allows an API to specify a **context-specific subset** of the linked operation's possible respones. This gives downstream consumers clearer expectations in workflows and chains of operations.\r\n\r\n### Motivation\r\n\r\nIn OpenAPI, an operation's `responses` object describes the **complete set of possible responses** under any circumstances. However, in actual usage, only a **subset of those responses** are realistic given previous actions taken. For example:\r\n\r\n- After deleting a resource, a follow-up `GET` for that resource may return `404`, and not `200`\r\n- After a mutation, the new state of a resource may make only a few responses from a linked operation valid\r\n\r\nThis proposal gives API authors a way to formally capture these **contextual expectations** within the existing `Linked Object`\r\n\r\n### Proposal\r\n\r\nAdd an optional `responses` field to the `Link Object`, reusing the structure of the `Response Object`. \r\n```yaml\r\nLink Object:\r\n ...\r\n responses:\r\n : \r\n```\r\nEach status code: \r\n\r\n- Can be reused directly using $ref\r\n- Or overridden to reflect more specific context\r\n\r\nAny status code **not** listed is implicitly not expected in this context \r\n\r\n### Example\r\n\r\n```yaml\r\npaths:\r\n /user/{userId}:\r\n get:\r\n operationId: getUser\r\n responses:\r\n '200':\r\n description: A user object\r\n '404':\r\n description: User does not exist\r\n delete:\r\n operationId: deleteUser\r\n responses:\r\n '204':\r\n description: User deleted\r\n links:\r\n userShouldBeGone:\r\n operationId: getUser\r\n parameters:\r\n userId: $request.path.userId\r\n responses:\r\n '404':\r\n description: User no longer exists\r\n```\r\n\r\n### Benefits\r\n\r\n- Better modelling of workflows where one action alters the behaviour of another.\r\n- Enables more expressive API documentation and generation tools.\r\n- Aligns with real-world RESTful behaviour where resource state transitions are significant.\r\n\r\n### Alternatives\r\n\r\n- Current workaround: describe expected outcomes in human-readable `description` fields. However, these cannot be parsed or utilised meaningfully by tools or UIs.", "created_at": "2025-07-03T09:24:27Z", "updated_at": "2025-07-04T15:40:25Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "elmanm", "avatar_url": "https://avatars.githubusercontent.com/u/58848316?v=4" } }, { "id": "D_kwDOAQkWPc4AgLQX", "number": 4674, "title": "Should OpenAPI highlight the possibility of using the data URL scheme for external examples?", "body": "Originally raised here: https://github.com/OAI/OpenAPI-Specification/pull/4647/files#r2135992019\r\n\r\nMy baseline assumption is that the [`data`-URL-scheme](https://datatracker.ietf.org/doc/html/rfc2397) is already perfectly valid as a URI for `externalValue` in an Example Object. As far as I know we don't enumerate valid URL schemes that could be used in a URI, so there are plenty of schemes that are _valid_ as far as OpenAPI is concerned but _probably not resolvable by most tooling_. (Without getting into the broader question of when you can treat a URI as a URL...)\r\n\r\nFor example, I assume `ftp://example.com/foo.png` is a perfectly valid URI for an `externalValue` but not something most tools would attempt to resolve.\r\n\r\nWhat I'd like to resolve here is:\r\n\r\n1. Am I right that this is already valid?\r\n2. If we think this is useful and not an anti-pattern should we add examples showing its usage and its utility?\r\n3. Should we go out of our way to suggest that tooling (in... 3.??) _ought_ to be able to resolve data URLs in some way?\r\n\r\nSomething like: \r\n```yaml\r\nexternalValue: \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D\"`", "created_at": "2025-06-09T22:43:34Z", "updated_at": "2025-06-10T19:59:02Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "hudlow", "avatar_url": "https://avatars.githubusercontent.com/u/1070061?u=d7d6b3106931a19ad8a8fe53f15a3ad8d59dadee&v=4" } }, { "id": "D_kwDOAQkWPc4Af3Ql", "number": 4623, "title": "Introduction of message traits", "body": "To foster reusage and adoption of standards/conventions it would be helpful if we could define traits which can be applied to both request's & response's.\n\nA trait could include\n- Headers\n- Body properties\n\nAn example of a trait could be\n- Problem details \n- Cloud events\n\nThese traits can be defined directly in the openapi doc or alternatively sourced from a server.", "created_at": "2025-05-21T05:32:03Z", "updated_at": "2025-06-10T01:24:28Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "thompson-tomo", "avatar_url": "https://avatars.githubusercontent.com/u/19771933?v=4" } }, { "id": "D_kwDOAQkWPc4AaAQi", "number": 3902, "title": "Examples referencing other examples", "body": "So for example I have an example address which I want to refrence in an example customer:\r\n\r\n```yaml\r\ncomponents:\r\n\r\n examples:\r\n \r\n address:\r\n summary: Address example\r\n value:\r\n address1: 41 Main Street\r\n address2: Morningside\r\n address3: Edinburgh\r\n address4: Lothian\r\n postCode: EH21 8TF\r\n \r\n customerArrayExample1:\r\n summary: An array of 1 customer\r\n value:\r\n total: 1\r\n page: 1\r\n pageSize: 1\r\n customers:\r\n - id: \"123e4567-e89b-12d3-a456-426614174000\"\r\n firstName: \"John\"\r\n lastName: \"Doe\"\r\n email: \"john.doe@example.com\"\r\n phone: \"+1234567890\"\r\n address:\r\n $ref: '#/components/examples/address'\r\n```\r\n\r\nThis is accepted, however in Swagger Editor it appears as \r\n```json\r\n{\r\n \"total\": 1,\r\n \"page\": 1,\r\n \"pageSize\": 1,\r\n \"customers\": [\r\n {\r\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\r\n \"firstName\": \"John\",\r\n \"lastName\": \"Doe\",\r\n \"email\": \"john.doe@example.com\",\r\n \"phone\": \"+1234567890\",\r\n \"address\": {\r\n \"$ref\": \"#/components/examples/address\"\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\nIs this supported and if so what am I doing wrong?\r\n```json\r\n{\r\n \"total\": 1,\r\n \"page\": 1,\r\n \"pageSize\": 1,\r\n \"customers\": [\r\n {\r\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\r\n \"firstName\": \"John\",\r\n \"lastName\": \"Doe\",\r\n \"email\": \"john.doe@example.com\",\r\n \"phone\": \"+1234567890\",\r\n \"address\": {\r\n \"address1\": \"41 Main Street\",\r\n \"address2\": \"Morningside\",\r\n \"address3\": \"Edinburgh\",\r\n \"address4\": \"Lothian\",\r\n \"postCode\": \"EH21 8TF\"\r\n }\r\n }\r\n ]\r\n}\r\n```\r\nIs the desired result", "created_at": "2024-06-13T15:31:59Z", "updated_at": "2025-06-09T22:30:20Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "mcrobbj", "avatar_url": "https://avatars.githubusercontent.com/u/10534160?v=4" } }, { "id": "D_kwDOAQkWPc4AgGtZ", "number": 4651, "title": "Semantic tagging for interoperability (of 3rd party cloud platforms)", "body": "Greetings from Apidays Helsinki & North 2025. Today, APIs speak in schemas, but not that much yet in shared meanings. This leads to brittle integrations, redundant sync logic, and endless manual mapping. Are we able to fix that?\r\n\r\nright at heart of it by extending OpenAPI with:\r\n\r\nx-semantic-tag: to declare what each field exactly means regardless name of it (e.g., API item field name can be: \"purchase_state\" but we mark it schema:status.payment.order)\r\nx-master-data: empowers each business to declare, per integration context, which API is the source of truth for each field — enabling controlled, conflict-free sync across cloud platforms.\r\n\r\nThis simple, vendor-neutral metadata would enable:\r\n- Smarter, AI-assisted field matching across APIs\r\n- Clear master data governance per field --> per chosen joined platforms\r\n- Scalable sync automation with less conflict and duplication\r\n\r\nImagine cloud APIs that \"understand\" each other semantically — and sync data reliably with zero fragile glue code. With OpenAPI 3.1 and existing extension mechanisms, we’re nearly there.\r\n\r\nTomas Westerholm, CTO\r\n[tomas.westerholm@tietoa.fi](mailto:tomas.westerholm@tietoa.fi)\r\n\r\nExplored the idea with ChatGPT 4o: \r\n[Open API semantic tagging for interoperability.pdf](https://github.com/user-attachments/files/20594863/Open.API.semantic.tagging.for.interoperability.pdf)\r\n", "created_at": "2025-06-04T16:28:47Z", "updated_at": "2025-06-06T19:12:39Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "tietoafinlandoy", "avatar_url": "https://avatars.githubusercontent.com/u/56432442?u=e5822525953fc97284a687b618b07ef2af5cae19&v=4" } }, { "id": "D_kwDOAQkWPc4AgBJN", "number": 4644, "title": "Authorization and Multitenancy", "body": "Hey, MCP engineers!\r\n\r\nHow should we combine the [Authorization framework](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#2-3-2-authorization-base-url) and Multitenancy? The case: \r\nI have two MCP servers with one domain name: `mcp.com/foo/srv` and `mcp.com/bar/srv`. \r\n\r\nThe spec said: \r\n> If the MCP server URL is https://api.example.com/v1/mcp, then:\r\nThe authorization base URL is https://api.example.com\r\nThe metadata endpoint MUST be at https://api.example.com/.well-known/oauth-authorization-server\r\n\r\nSo, both servers will be redirected to `mcp.com/.well-known/oauth-authorization-server`. How can we then figure out what the server is called initially? \r\n\r\n", "created_at": "2025-05-30T12:59:23Z", "updated_at": "2025-05-30T20:05:44Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "dronnix", "avatar_url": "https://avatars.githubusercontent.com/u/2401009?u=e90828e9a8685443e0d13904fa71f9d001a18097&v=4" } }, { "id": "D_kwDOAQkWPc4Ad_ZA", "number": 4319, "title": "Optional discriminator property", "body": "I propose that we change the `discriminator` object in the next appropriate spec version to allow the discriminator property (named by the `propertyName` filed) to be an optional property. When the discriminator property is absent, this is interpreted as mapping to an implicit variant of the `oneOf`/`anyOf`/`allOf` with an empty schema. (This might be problematic for `oneOf`).\r\n\r\nThis has been discussed in the past and I don't recall any strong objections to it.\r\n\r\nMaking the discriminator optional allows a more natural transition from a \"monomorphic\" schema (without a discriminator) to a polymorphic schema. In particular, objects that validate to the monomorphic schema (without a discriminator property) would continue to be valid in the polymorphic schema.", "created_at": "2025-01-23T14:40:13Z", "updated_at": "2025-05-18T15:02:15Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "mikekistler", "avatar_url": "https://avatars.githubusercontent.com/u/85643503?u=fa69466be602e63350acf34b52c559a819d4617b&v=4" } }, { "id": "D_kwDOAQkWPc4AakTa", "number": 3967, "title": "Explicity mention that a media type object can be empty", "body": "Would it be helpful to explicitly mention that it is permissible to have an empty media type object? We could even add an example with an API responding with an image where the media type itself is enough to specify the response type.", "created_at": "2024-07-22T13:11:12Z", "updated_at": "2025-05-18T15:01:00Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "dret", "avatar_url": "https://avatars.githubusercontent.com/u/1848612?u=dacdfa5408d152704f36b2171ee14cf1c1eb2079&v=4" } }, { "id": "D_kwDOAQkWPc4AfnNM", "number": 4566, "title": "Where to register new specification extension namespaces?", "body": "https://spec.openapis.org/registry/namespace/ says to open a new Pull-Request and links to https://github.com/OAI/OpenAPI-Specification/pulls \r\nI've checked out the `gh-pages` branch and found the the `registry/extension.md` file. That page mentions `site.extension` but I don't know where/how that value gets defined. I searched for `x-sap` which is mentioned on the page, but that text is not in the repo either.\r\nI found `registries/_namespace/sap.md` , so I was able to copy that to define a new extension namespace (`registries/_namespace/fdx.md`) \r\nbut when I built/ran Jekyll locally via the instructions on `CONTRIBUTING.md` my local `http://127.0.0.1:4000/registry/extension/` contains only one row, for `x-twitter`; it does not show the content from `sap.md` or the new file I created.\r\n\r\n![Screenshot 2025-05-06 at 4 58 13 PM](https://github.com/user-attachments/assets/5de29c72-dd51-4d99-bfb7-a572c4d91ca0)\r\n\r\nHow does one submit a PR for new extension namespaces - namely, how to add a new namespace?", "created_at": "2025-05-06T21:01:36Z", "updated_at": "2025-05-15T20:35:46Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "DavidBiesack", "avatar_url": "https://avatars.githubusercontent.com/u/545944?u=26818946106e2d8ae8c0cb5e0b72d6c7f612d268&v=4" } }, { "id": "D_kwDOAQkWPc4Acsx6", "number": 4210, "title": "OAS 3.2 (and 3.3?) release planning", "body": "After struggling to figure out the right scope for 3.2, it occurred to me that a very quick, useful, and easy-to-implement 3.2, followed by a 3.3 that solves some more intractable problems that would otherwise have delayed 3.2 significantly, might be a better approach.\r\n\r\nIt was good that we did not put out a longer road map prior to the patch releases. Their scope was not clear, and it took us longer than expected to finish. But if we plan 3.2 and 3.3 together, that would be a pro-path-to-Moonwalk road map that would give our community some clarity. And this 3.2 \"core work\" as shown below would actually be quite easy to finish despite looking substantial, as much of it is already done.\r\n\r\n## 3.2 core work\r\n\r\nThis is what I think 3.2 should have in it no matter what we decide regarding 3.3. Aside from the XML stuff (which, as noted, we should only do if we have a champion willing to step up) and the little bits and pieces, ***most of this is already well-thought-through or even already written in PR form***. If this is our 3.2 release, we should be able to finish it very quickly.\r\n\r\n* Hierarchical, categorizable tags\r\n * Accepted proposal:\r\n * [2024-09-01-Tags-Improvement](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2024-09-01-Tags-Improvement.md)\r\n * Issues resolved:\r\n * #1367 \r\n * #2843 \r\n* Referencing and identification\r\n * Self-identifying documents\r\n * Accepted proposal:\r\n * [2024-08-01-Self-Identification](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2024-08-01-Self-Identification.md)\r\n * Issues resolved:\r\n * #1979\r\n * URI-references for Security Requirement -> Security Scheme\r\n * Previously-approved PR _(was punted due to branch changes and me considering a more comprehensive solution)_:\r\n * #3821 \r\n * Issues resolved\r\n * _Partially:_ #3776 \r\n * Encouraging some security guard-rails on de-referencing\r\n * #4037 \r\n* Data modeling\r\n * Streaming JSON media types\r\n * Previously approved PR _(was punted due to branch changes and me considering a more comprehensive solution)_:\r\n * #3735\r\n * Issues resolved:\r\n * #3730 \r\n * Server-Sent Event (SSE) `text/event-stream` format\r\n * Just treat it as a JSON object with no nesting- even easier than streaming JSON support\r\n * Discussion resolved:\r\n * #4171 \r\n * XML _(**IF** we can find a champion for the work; it is separate from everything else and could easily be punted to 3.3)_\r\n * #1652 \r\n * #630 \r\n * #3959\r\n* HTTP\r\n * HTTP methods\r\n * @ralfhandl and I have pretty nearly converged on a good and easy solution here:\r\n * [initial idea](https://github.com/OAI/OpenAPI-Specification/issues/1747#issuecomment-2258049947)\r\n * [later tweaks](https://github.com/OAI/OpenAPI-Specification/issues/1747#issuecomment-2484375717)\r\n * Issues resolved:\r\n * #1747\r\n * Empty responses _(clarification, maybe a field to make emptiness explicit?)\r\n * #3967\r\n * #2875 \r\n* Security\r\n * Best practices\r\n * #3777\r\n * #3603\r\n * Device authentication, OAuth2 metadata, and deprecation _(these were done on the old `v3.2.0-dev` branch and just need porting)\r\n * #4188 \r\n * _Possible_ Other enhancements _(I need some help figuring out the scale of these and whether they fit in 3.2 or 3.3)_\r\n * #3612\r\n * #3709 \r\n * #4023 \r\n * #3983 \r\n* Bits and pieces _(minor things, we can take or leave each one independently)_\r\n * Descriptions and names\r\n * #3722 \r\n * #1821 \r\n * #3538 \r\n * Examples\r\n * #859 \r\n * #3874 \r\n * Path templating\r\n * #3256\r\n * API governance\r\n * #726 \r\n * #4212 _(we don't seem to have an issue for just adding `api-version` so using this one for now)_\r\n * Maintainence\r\n * #2951 \r\n * #3934 \r\n * #3800 \r\n\r\n## 3.2 work if we are ***NOT*** going to also plan 3.3\r\n\r\nThese are things that I think we need to fix sooner rather than later, but the easier fixes _add a lot of complexity to areas that are already far too complex._ Incorporating these into 3.2 will make for more difficult-to-maintain bits of duct tape and will _not_ get us closer to Moonwalk. We'll also have to spend time debating which sub-optimal duct-tape solutions to accept, which I find unappealing. It's always hard to do those because no one will feel satisfied with it.\r\n\r\nThis is why I think we should do these more comprehensively as explained in the 3.3 section further down:\r\n\r\n* Media types\r\n * Multipart _(this needs a solution like letting the `encoding` field use keys like `\"0\"`, `\"1\"`, `\"2\"`, etc. to correlate Encoding Objects with positional, unnamed parts. And maybe `\"*\"` to match positions with no numbered encoding. That's the least-gross option I've come up with so far, and it's not pretty.)_\r\n * #3721 \r\n * #3725 \r\n* Parameters\r\n * Query String _(as much as I **really** want to support `in: queryString` and just use the HTTP message body solution for `application/x-www-form-urlencoded` to solve these, it would be far better to provide a simpler solution that addresses a lot more of our parameter problems and moves us closer to Moonwalk)_\r\n * #2511\r\n * #1502\r\n * Headers _(similar problem as for query string- modeling it all at once- but then we'd have two complex changes to two complex parameter areas, and **still** wouldn't have really solved these problems as we also have users who have relationships among parameters with different `in` values)_ \r\n * #4174\r\n * Path _(this would require some gross duct tape involving `allowReserved`, which is already a confusing area)_\r\n * #1710\r\n * Headers _(all of these boil down to modeling header structures, which we **could** do similar to how we handle JSON Streaming or form data, but they are more complex than JSON Streaming, and trying to build on the form data approach is **extremely** unappealing given the complexity of that area already, and how many things are built into it that are completely unsuitable for headers, and would require lots of \"if you are doing headers, field X SHALL be ignored\" etc.)_\r\n * #2458 \r\n * #3827\r\n * #2342\r\n * #2402\r\n * #667\r\n * #2784\r\n * #2296\r\n * #1980\r\n* Security\r\n * CIBA _(we have solutions already in the old `v3.2.0-dev` branch for these, but as @SensibleWood noted in issue #4106, it would be much better to reconsider this comprehensively)_\r\n * #3615 _(note that if we were to port this, some of the field anchor names do not match the final field names and would need fixing)_\r\n * Other enhancement _(I think these would be easier if we re-think things comprehensively as proposed for CIBA, etc., but this is not my area of expertise at all)_\r\n * #3612\r\n * #3709 \r\n * #4023 \r\n * #3983 \r\n\r\n\r\n## 3.3\r\n\r\nIf we immediately move on to 3.3, it would be centered around two _completely new mechanisms_ built _alongside_ the existing features, which would be frozen (whether they would be deprecated is another discussion we can have if and when it is relevant- it doesn't really matter for now). These would address all of the issues in the previous section.\r\n\r\nThe idea here is to try out something more moonwalk-ish that can be implemented in a straightforward manner.\r\n\r\nFor Security:\r\n * I'd basically defer to @SensibleWood and the ideas he's got going in this issue:\r\n * #4106 \r\n * These other issues might fit best here, too, although if any are simple and unrelated to 4106 they could go into 3.2\r\n * #3612\r\n * #3709 \r\n * #4023 \r\n * #3983 \r\n\r\nFor parameter and media type data modeling, my thoughts are are along the following lines, heavily influenced by the Moonwalk work on [figuring out what tasks are involved](https://modern-json-schema.com/analyzing-the-openapi-tooling-ecosystem) in implementing the OAS.\r\n\r\n***NOTE:** The purpose of this next lengthy section is to explain why we should **consider** a particular approach for 3.3. It is not intended to resolve the exact approach, which will need its own discussion and/or proposal.*\r\n\r\nFirst, let's review the problems:\r\n\r\nThe current approach to data modeling involves various combinations of the Schema, Encoding, Media Type, Parameter, and/or Header Objects:\r\n * while Parameter and Header are never used together, each can be used with all of the other three, and all of the other three are used in some HTTP message body scenarios\r\n * the Encoding, Header, and Parameter Objects have extremely complex field interactions, which are slightly different in each despite mostly having the same field names\r\n * the Encoding Object places complex conditionals on behavior for `form-urlencoded` vs `form-data`\r\n * we have always claimed that the Encoding Object supports `multipart/mixed`, but it never has (we dropped the claim in 3.0.4 and 3.1.1, but we know from Slack and issues that this support is needed)\r\n * HTTP headers cannot be modeled in any meaningful way, which is a major pain point; however, none of the current mechanisms are well-suited to modeling their structure\r\n * Many configurations of these objects appear valid but are not - sometimes they are _very_ invalid, meaning they cannot possible produce outcomes that comply with HTTP and other standards\r\n\r\nIn truth, there are three parts to data modeling. Of these three, modeling mostly works, but we treat mapping inconsistently, and conflate it with encoding\r\n\r\n* _Modeling the in-memory data_, which is done with Schema Objects\r\n * This is basically fine. Or, at least, we're not revamping the Schema Object _again_, so it's fine enough\r\n* _Mapping to non-JSON structures_ (ignoring XML which is handled differently)\r\n * This is extremely complex, involving `style`, `explode`, `contentType` (for `multipart`, and maybe sort-of for `form-urlencoded`?), special treatment of array schemas (for `multipart` _only_), and maybe `contentMediaType` and `contentSchema` (except that they overlap with other fields and are sometimes ignored)\r\n * `style` and `explode` also automatically trigger encoding/escaping behavior that is frequently undesirable or outright wrong\r\n * `style` and `explode` leverage RFC6570, but also include non-RFC6570 options that don't play nicely with RFC6570's assumptions\r\n * we are only able to map named things, because the `encoding` field correlates Schema and Encoding Objects by property (part) name; however, we need to handle sequential formats and formats like headers that have both a sequential and named aspect\r\n * we have blocked off some functionality of `style` and `explode` in some areas where it would be helpful, for various reasons – even when these reasons are good, the result is confusingly inconsistent behavior\r\n* _Encoding/escaping data_\r\n * For JSON, this is so trivial no one even thinks about it (e.g. a `\"` needs to be represented as either `\"\\\"\"` or with a unicode hex escape that I can't currently recall\r\n * For non-JSON, this is pretty complex, involving `allowReserved`, `contentEncoding`, rules that we inherit from other standards, and/or the Encoding Object's `headers` field\r\n * URI percent-encoding can be enabled even if no obviously-encoding-related fields are used, which is confusing\r\n * For URLs, the RFC6570-derived behavior _mostly_ works, but has some odd corners. Particularly in that it does not address things like using `+` as an escape for space in `form-urlencoded` data at all, and I imagine some APIs use that convention\r\n * For non-URLs, the RFC6570-derived behavior is often completely wrong, e.g. cookies with binary data are base64-encoded, not percent-encoded, and while HTTP header parameter values might be percent-encoded, the primary value generally is not\r\n\r\nWe would be better off making a single-schema approach to parameters (as proposed for Moonwalk!) that addresses these three parts in a comprehensive way. I do _not_ mean coming up with some elaborate universal way to map any JSON Schema to any other format. I mean something that is the same for all sequential formats, and the same for all named formats, and when you have something like an HTTP header that has a primary value followed by parameters (essentially a tuple where the 2nd entry is an object), it is consistent with the basic sequential and named rules. Furthermore, the mapping would be handled separately from the encoding, so it is _never_ possible (or at least not without really working hard at it) to use the wrong kind of encoding/escaping by accident.\r\n\r\nWhile this would not be trivial, it would produce something _far_ easier to implement than any patchwork of duct tape fixes to the current pile of Objects involved, solve far more of our users' problems, and produce valuable feedback for Moonwalk before we lock in a new major version.\r\n\r\n## Open questions\r\n\r\n* We could do something to expand the use of referencing, but do we want to?\r\n * Objects with unusual behavior\r\n * _Tag part only_ #3776 _(URI-references to Tag Objects are hard because they are in an array, which makes JSON Pointer fragments rather fragile)_\r\n * #4084 _(it's not clear to me that it's worth fixing anything in the Link Object that would add complexity, given that it does not seem to be used much and might be more-or-less obsolete with Arazzo)_\r\n * #3734 _(do we want to try again to improve the Path Item Object `$ref`? One option would just be to say that, for Path Item Objects, a Reference Object can overwrite any Path Object field (not just `summary` and `description`), which would move the `$ref` from the Path Item Object to the Reference Object and leverage the Reference Object's existing behavior)_\r\n * Objects that do not support referencing\r\n * #3853 _(one thing that we'd need to consider is avoiding other scenarios like with `operationRef` where the behavior depends on parent structures that might not be unique)_\r\n * Non-Objects _(we have generally leaned towards not doing these- perhaps Overlay helps?)_\r\n * #3902\r\n * #2697\r\n\r\n\r\n", "created_at": "2024-11-21T01:18:39Z", "updated_at": "2025-05-15T19:00:33Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "handrews", "avatar_url": "https://avatars.githubusercontent.com/u/2358015?u=edb337dc1bf53e9adf1623bae3432a3020dcf255&v=4" } }, { "id": "D_kwDOAQkWPc4AenkA", "number": 4395, "title": "Does the \"required\" attribute on fields apply to Response objects?", "body": "I'm trying to settle a debate with a colleague of mine. I contend that the required attribute should be completely ignored in any Response schema and he contends that it must be honored.\r\n\r\nThis is not an uncommon situation. One creates a schema with some required fields. References it in various Request payloads (say POST or PUT) as well as in some Response payloads (like a GET). \r\n\r\nMy argument, beyond common sense, is that the documentation is clear albeit by omission. Nowhere in the section on the Response body does it mention the required attribute but it _is_ mentioned in the Request body section.\r\n\r\nMy colleague's argument is akin to \"math is math\" and that required means required even if on the Response object. \r\n\r\nFor those wondering, the issue is coming up because SalesForce's External Services functionality is throwing a fit when it encounters a Response object with a null but required field. So, the real debate is whether SalesForce's External Services functionality is incorrectly interpreting the OpenAPI spec (my contention) or whether there is an omission in the OpenAPI documentation about honoring the required attribute on fields on Response schemas.\r\n\r\nIf for some reason, this should be honored (which IMO is crazy), then a needed feature is a way to simply disable the required attribute on a given schema reference. ", "created_at": "2025-02-28T20:47:37Z", "updated_at": "2025-05-13T20:40:39Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "Seven24", "avatar_url": "https://avatars.githubusercontent.com/u/32494670?v=4" } }, { "id": "D_kwDOAQkWPc4AfpW0", "number": 4570, "title": "Does OpenAPI define the outcome for requests with valid or invalid input?", "body": "This topic spun out of a conversation with @mikekistler concerning [the proposal for `itemSchema`](https://github.com/OAI/OpenAPI-Specification/pull/4554) in support of streaming media types.\r\n\r\nMike asked what I thought was a good question. If I have a `schema` and an `itemSchema`, the `itemSchema` will tell me in isolation whether an individual item in a stream is valid; but if I also include a `schema` does it necessarily imply that if, after the stream ends, the `schema` indicates that the collective content is _not_ valid, does that mean that the service should not have processed any of the items? (Or maybe, should roll back any changes.)\r\n\r\nI am not sure what the answer ought to be, but I think there's a broader question here that's interesting.\r\n\r\n_As a best practice_, I would guide API authors/implementors to define and implement request schemas (for content, parameters, headers, whatever) such that if input is considered invalid by a schema, the request will fail with `4xx` and without any side effects.\r\n\r\nBut I would also say that as a matter of pragmatism, it will likely be impossible for them to guarantee the converse: that if all the input validates against the corresponding schemas, the request will succeed with a `2xx` status code (aside from unpredictable `5xx` failures). For the APIs I work in every day, there are _usually_ validation aspects that cannot be defined in the schema. Compatibility with existing resource state, for example. A basic example of this would be using `If-Match` where the success of the request is not determined by the schema of the value provided for the header, but by how it relates to the state on the server.\r\n\r\nBut I don't think OpenAPI actually _says_ how a service implementation ought to behave with respect to request data validating or not validating against a schema. I think it just says \"this is the schema for the input\" and leaves the rest to the reader. \r\n\r\nA similar question might be asked about whether OpenAPI specifically says what response schemas mean with respect to behavior.\r\n\r\nI anticipate that the right thing to do here _is_ to leave some flexibility for an author/implementor to define the specifics of how a schema is used, but I think we'd do better to define which parts _are_ left to the author/implementor. I would also be supportive of nailing down _some_ aspects of this with respect to what a schema validation _failure_ means even if we can't nail down anything about what schema validation _success_ means.\r\n\r\nBut someone might, even outside of a streaming use case, might say that they want to define a correct schema but they also want to have a service which does its best to fulfill a request that has invalid data. I don't like the idea but I can certainly imagine the argument and the desirability of keeping that use case under the OpenAPI tent.", "created_at": "2025-05-08T16:18:44Z", "updated_at": "2025-05-10T00:06:24Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "hudlow", "avatar_url": "https://avatars.githubusercontent.com/u/1070061?u=d7d6b3106931a19ad8a8fe53f15a3ad8d59dadee&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTYyNDMx", "number": 2705, "title": "How should one cite the OpenAPI specification?", "body": "Is there an authoritative citation form we should use (Bibtex, EndNote, etc.)? If not, any chance someone involved would make one?\r\n\r\nI looked at Google Scholar, DBLP, in the specification itself, and didn't find anything.\r\n\r\nI can make my own, but probably wouldn't do as good a job as the OAI would.\r\n", "created_at": "2021-09-09T00:29:36Z", "updated_at": "2025-05-08T19:29:41Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "rpgoldman", "avatar_url": "https://avatars.githubusercontent.com/u/3274?u=6c178057fd80ad33925ef624bfe64ba07cc624c5&v=4" } }, { "id": "D_kwDOAQkWPc4Ae53_", "number": 4459, "title": "Should we add test cases asserting the validity of \"controversial\" or \"questionable\" practices?", "body": "### 🗣️ Discussion\r\n\r\nSome PRs proposing changes to the validation schema enforce constraints not specified in the OpenAPI specification. Such changes are considered *linty*.\r\n\r\nSuch changes are typically dismissed after maintainer review.\r\nSome discussion end in \"well, it's allowed by the spec\".\r\nThis discussion is intended to shorten the feedback loop between proposal-which-will-not-be-accepted to proposal-which-may-be-accepted.\r\n\r\nInstead of rejecting such PRs out-of-hand, I propose we instead open counter-PRs which add test cases explicitly asserting the validity of such controversial cases.\r\nThis will help to steer future contributors away from anti-patterns which are not explicitly disallowed by the specification, and provide specific points of adjustment should the specification change with regards to these anti-pattern test cases.\r\n\r\n[This PR](https://github.com/OAI/OpenAPI-Specification/pull/4458) seeks to add tests which assert certain anti-patterns are explicitly allowable, despite their incongruousness or meaninglessness.\r\nThe intention is not to lock the schema into these behaviors, but to guide contributors towards areas where their updates make sense (custom linters, etc…) rather than rejecting contributor PRs on first principles.", "created_at": "2025-03-19T01:34:10Z", "updated_at": "2025-03-26T09:55:30Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "duncanbeevers", "avatar_url": "https://avatars.githubusercontent.com/u/7367?u=4ed0a151ef6aecd7ca8f93553c441507b22391fc&v=4" } }, { "id": "D_kwDOAQkWPc4AeqZZ", "number": 4404, "title": "3.1.1: polymorphism and discriminator in request type", "body": "This line mentions the option to not repeat the child schemas using `anyOf` but the option to use a base type, here `Pet`: https://github.com/OAI/OpenAPI-Specification/blob/428007d4d8fbea8cc65f72b7c7250984127be6a7/versions/3.1.1.md?plain=1#L3379\r\n> This example shows the allOf usage, which avoids needing to reference all child schemas in the parent\r\n\r\nBut how does a response type look like?\r\n```yml\r\nmyResponseType:\r\n $ref: '#/components/schemas/Pet'\r\n```\r\nIs this all? How does the caller know a specific sub type of `Pet` like `Cat` is required and `{ \"petType\": \"Cat\" }` is not allowed?", "created_at": "2025-03-04T12:00:22Z", "updated_at": "2025-05-18T15:01:49Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AvXYU", "body": "@hfhbd The `allOf` syntax for `discriminator` is weird for the reason you mention. Among others. We keep trying to explain it better, but AFAIK none of the people who came up with it are still active with the project, so it's a bit of archaeology and we keep finding new surprises.\r\n\r\nWhat's going on here is that for _validation_ purposes, the `allOf` approach only works if you are validating using a child schema, which means you already have to know what child it will be. This is because `discriminator` is not allowed to change the validation outcome, because doing so in the `allOf` case would outright contradict the JSON Schema specification, for reasons that are too complex to go into here. JSON Schema has proposed an alternate keyword that may get incorporated one day, but that's more a question for them than for us.\r\n\r\n@mikekistler is working on the latest attempt to improve `discriminator`, which you can read at #4339. We'll keep trying to improve the explanation in future releases. Ultimately, it needs to be replaced with something more compatible with JSON Schema validation (or whatever gets used for data definition and validation in 4.0 \"Moonwalk.\")\r\n\r\nI know that's not a satisfactory answer, but it's the best I have for you. `discriminator` was designed from a code generation perspective, doing static analysis on the OpenAPI Description, independent of runtime value. JSON Schema, on the other hand, is a [runtime constraint system](https://modern-json-schema.com/json-schema-is-a-constraint-system), which is a completely different design approach. The approaches collide badly in the `allOf` form of `discriminator`.\r\n\r\n" }, "user": { "login": "hfhbd", "avatar_url": "https://avatars.githubusercontent.com/u/22521688?u=1b966c21297436b7035142a38d270eac5d37aaaa&v=4" } }, { "id": "D_kwDOAQkWPc4AdzwQ", "number": 4298, "title": "A Deno SDK for Any OpenAPI Through URL Imports", "body": "Traditional API integration workflows are cumbersome, requiring separate SDKs that bloat your project with hundreds of unnecessary files. I love the deno URL import functionality and decided to make this: https://oapis.org (GitHub: https://github.com/janwilmake/oapis)\r\n\r\nAs long as there's a openapi.json available at the domain, you can import a type safe fetch-function as follows:\r\n \r\n```typescript\r\n// Save this as test.ts and run it using `deno run --allow-net --allow-import test.ts`\r\n\r\n// Import the chat completion function directly\r\nimport createChatCompletion from \"https://oapis.org/ts/chatcompletions.com/createChatCompletion\";\r\n\r\n// Use it without any SDK installation\r\nconst completion = await createChatCompletion({\r\n headers: {\r\n \"X-LLM-API-Key\": \"YOUR_SECRET\",\r\n \"X-LLM-Base-Path\": \"https://api.deepseek.com/v1\",\r\n },\r\n body: {\r\n messages: [\r\n { role: \"system\", content: \"You are a helpful assistant.\" },\r\n { role: \"user\", content: \"Hello!\" },\r\n ],\r\n model: \"deepseek-chat\",\r\n },\r\n});\r\n\r\nif (completion.body) {\r\n console.log(completion.body.choices[0].message.content);\r\n //Hello! How can I assist you today? 😊\r\n} else {\r\n console.log(\"ERROR\", completion.status);\r\n}\r\n// This works like a charm!\r\n```\r\n\r\nHope you like it. Feedback appreciated!", "created_at": "2025-01-12T21:45:13Z", "updated_at": "2025-03-19T01:43:45Z", "category": { "name": "Tooling", "emoji": ":hammer_and_wrench:" }, "answer": null, "user": { "login": "janwilmake", "avatar_url": "https://avatars.githubusercontent.com/u/97664551?u=baa6b5ea77a6f0a9cb71659f031839eb83e1e54f&v=4" } }, { "id": "D_kwDOAQkWPc4AeydS", "number": 4427, "title": "How to represent dynamic type in response body ?", "body": "Hello, guys! thanks for your contribution!\r\n\r\n I am new to OpenAPI, hope you guys can help me to understand this question:\r\n\r\nI have a legacy API like this:\r\n\r\n`POST /sea/{locator}`, depends on the path parameter `locator`, the response body may contains objects of different types.\r\n\r\nfor example:\r\n\r\n`POST /sea/user` will have response like this:\r\n\r\n```\r\n{\r\n \"code\": \"200\",\r\n \"total\" : 2\r\n \"data\" : [\r\n {\r\n \"id\" : 1\r\n \"name\": \"rose\"\r\n }\r\n {\r\n \"id\" : 2\r\n \"name\": \"jack\"\r\n }\r\n ]\r\n}\r\n```\r\n\r\nwhile `POST /sea/task` will have response like this:\r\n\r\n```\r\n{\r\n \"code\": \"200\",\r\n \"total\" : 2\r\n \"data\" : [\r\n {\r\n \"id\" : 1\r\n \"name\": \"do homework\",\r\n \"status\" : \"canceled\"\r\n }\r\n {\r\n \"id\" : 2\r\n \"name\": \"clean house\",\r\n \"status\" : \"finished\"\r\n }\r\n ]\r\n}\r\n```\r\n\r\nand there are many other types ...\r\n\r\n", "created_at": "2025-03-12T11:10:19Z", "updated_at": "2025-03-19T01:35:30Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AvnQl", "body": "Yes, I agree with @ralfhandl . If that is not feasible, you just have to use a `oneOf` or `anyOf` schema and there's no real way to correlate the path parameter and the response type. This is something we are working to fix in OAS 4.0 a.k.a. \"Moonwalk\", and you can follow the discussions in the OAI/sig-moonwalk repository if you are interested." }, "user": { "login": "OldFarmer86", "avatar_url": "https://avatars.githubusercontent.com/u/202945119?u=abc3544a819880b82cb756e15642a11be9a9bf7c&v=4" } }, { "id": "D_kwDOAQkWPc4AezDZ", "number": 4428, "title": "Where is a changelog for 3.1.1?", "body": "I could not find what changed between 3.1.0 and 3.1.1. ", "created_at": "2025-03-12T19:22:51Z", "updated_at": "2025-03-19T01:34:54Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "anton-okolelov", "avatar_url": "https://avatars.githubusercontent.com/u/12091051?u=fe6dd8fe2338bfe696f28bc4f6877de4223f6d5e&v=4" } }, { "id": "D_kwDOAQkWPc4AenWM", "number": 4391, "title": "RFC: Extension Authoring Best Practices (Adhering to OpenAPI Conventions/Standards)", "body": "The purpose of this discussion is to talk about best practices as they relate to authoring extensions. While the OpenAPI itself doesn't voice an opinion as it relates to extension authoring best practices, I personally think that extension authors should take into account the conventions and _\"style\"_ that the OpenAPI specification itself adheres to. The goal would be a consistent authoring and consumption experience for OpenAPI documents, including extensions.\r\n\r\n## Conventions\r\n\r\nBelow are a list of conventions _(not exhaustive)_ that are not documented within the OpenAPI, but that happen to exist and could/should have an impact on OpenAPI extension authors.\r\n\r\n### Components Are for Reuse\r\n\r\nThe OpenAPI Specification has a [Components Object](https://swagger.io/specification/#components-object) which is used to contain all definitions that are to be reused _(referenced by name or other supported mechanism)_ elsewhere throughout the OpenAPI document. Fortunately for extension authors, the _Components Object_ supports extensions. This being said, any time an extension author needs to define objects that will be referenced from elsewhere within the OpenAPI document, defining an extension within the _Components Object_ is the preferred way of doing this.\r\n\r\nBased on the way that OpenAPI defines reusable definitions, each _\"type\"_ has a container within the _Components Object_ and each type-specific definition is within the container. So all _Schema Objects_ are defined within `#/components/schemas`, and Security Definitions are defined within `#/components/securityDefinitions`, etc. There is no unnecessary nesting, and each type-specific container contains **only** definitions of that type _(you cannot define a \"Schema Object\" alongside a \"Security Definition\")_.\r\n\r\n### Location Dictates Type\r\n\r\nWhen authoring or consuming an OpenAPI document, reasoning about an object definition is as simple as knowing where in the OpenAPI document the typed object is defined. _(For example, every definition within `#/components/parameters` is a \"Parameter Object\", and every definition within `#/paths/{pathPattern}/parameters` is a \"Parameter Object\".)_ That being said, nowhere in OpenAPI are there locations where different types can be defined alongside each other. _(For example, OpenAPI does not have an array/map of \"Operation Objects\" having a `type` property that dictates the HTTP method for that operation, nor can you defined a \"Parameter Object\" and a \"Schema Object\" in the same hierarchical location.)_\r\n\r\n**Note:** _Security Definitions_ do have a `type` property that dictates which type of _Security Definition_, but this is more of a sub-type and less about different types themselves being defined alongside each other.\r\n\r\n## Use Case\r\n\r\nLet's use a real-world example where we want to define a quota limit as part of API Management for the API being described, and then applying that quota to an operation. This example defines a metric _(read requests)_, a quota limit _(referencing a metric)_ and applies a quota to a specific _Operation Object (referencing a metric)_. The reusable type in this case is the metric, while the limit and quota application are not reusable themselves.\r\n\r\n## Options to Discuss\r\n\r\nBelow are a few options _(not exhaustive, and there are likely permutations of these that could be discussed as well)_ to discuss.\r\n\r\n### Option 1 (Fully Compliant, Uses Components)\r\n\r\nThis option fully adheres to the OpenAPI conventions mentioned above. Below is the sample OpenAPI:\r\n\r\n```yaml\r\nopenapi: '3.0'\r\nx-acme-api:\r\n quotaLimits:\r\n read-requests-limit:\r\n metric: read-requests # References the 'read-requests' metric by name\r\n unit: 1/min/{project}\r\n values:\r\n STANDARD: 5000\r\ncomponents:\r\n x-acme-metrics:\r\n read-requests:\r\n displayName: Read requests\r\n valueType: INT64\r\n metricKind: DELTA\r\npaths:\r\n /hello:\r\n get:\r\n x-acme-quota:\r\n read-requests: 1 # References the 'read-requests' metric by name\r\n # ...\r\n```\r\n\r\n### Option 2 (Fully Compliant, No Components)\r\n\r\nThis option fully adheres to the OpenAPI conventions mentioned above, but instead of using the _Components Object_ for the reusable types _(metrics)_, they are now isolated within a standalone extension _(`x-acme-api`)_. Below is the sample OpenAPI:\r\n\r\n```yaml\r\nopenapi: '3.0'\r\nx-acme-api:\r\n metrics:\r\n read-requests:\r\n displayName: Read requests\r\n valueType: INT64\r\n metricKind: DELTA\r\n quotaLimits:\r\n read-requests-limit:\r\n metric: read-requests # References the 'read-requests' metric by name\r\n unit: 1/min/{project}\r\n values:\r\n STANDARD: 5000\r\npaths:\r\n /hello:\r\n get:\r\n x-acme-quota:\r\n read-requests: 1 # References the 'read-requests' metric by name\r\n # ...\r\n```\r\n\r\n### Option 3 (Noncompliant, Uses Components for Non-Reusable Types)\r\n\r\nThis option uses the _Components Object_ for types that are not reusable. Below is the sample OpenAPI:\r\n\r\n```yaml\r\nopenapi: '3.0'\r\ncomponents:\r\n x-acme-metrics:\r\n read-requests:\r\n displayName: Read requests\r\n valueType: INT64\r\n metricKind: DELTA\r\n x-acme-quota-limits:\r\n read-requests-limit:\r\n metric: read-requests # References the 'read-requests' metric by name\r\n unit: 1/min/{project}\r\n values:\r\n STANDARD: 5000\r\npaths:\r\n /hello:\r\n get:\r\n x-acme-quota:\r\n read-requests: 1 # References the 'read-requests' metric by name\r\n # ...\r\n```\r\n\r\n### Option 4 (Noncompliant, Location Does Not Dictate Type, Security Definitions Approach)\r\n\r\nThis option is like _Option 2_, but it uses the same approach used for _Security Definitions_ where the _\"type\"_ is dictated by a `type` property and the other adjacent properties are mixed and type-specific. Below is the sample OpenAPI:\r\n\r\n```yaml\r\nopenapi: '3.0'\r\nx-acme-api:\r\n read-request-metric:\r\n type: metric\r\n displayName: Read requests\r\n valueType: INT64\r\n metricKind: DELTA\r\n read-requests-limit:\r\n type: quota-limit\r\n metric: read-request-metric # References the 'read-request-metric' metric by name\r\n unit: 1/min/{project}\r\n values:\r\n STANDARD: 5000\r\npaths:\r\n /hello:\r\n get:\r\n x-acme-quota:\r\n read-request-metric: 1 # References the 'read-request-metric' metric by name\r\n # ...\r\n```\r\n\r\n### Option 5 (Noncompliant, Location Does Not Dictate Type, Kubernetes Approach)\r\n\r\nThis option is like _Option 2_, but it uses the [Objects in Kubernetes](https://kubernetes.io/docs/concepts/overview/working-with-objects/) approach where you have a common wrapper definition and type is dictated by a combination of `kind` and `spec` instead of location. Below is the sample OpenAPI:\r\n\r\n```yaml\r\nopenapi: '3.0'\r\nx-acme-api:\r\n read-request-metric:\r\n kind: metric\r\n spec:\r\n displayName: Read requests\r\n valueType: INT64\r\n metricKind: DELTA\r\n read-requests-limit:\r\n kind: quota-limit\r\n spec:\r\n metric: read-request-metric # References the 'read-request-metric' metric by name\r\n unit: 1/min/{project}\r\n values:\r\n STANDARD: 5000\r\npaths:\r\n /hello:\r\n get:\r\n x-acme-quota:\r\n read-request-metric: 1 # References the 'read-request-metric' metric by name\r\n # ...\r\n```", "created_at": "2025-02-28T16:01:32Z", "updated_at": "2025-03-05T16:44:04Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "whitlockjc", "avatar_url": "https://avatars.githubusercontent.com/u/98899?u=f1fd705cdf16fbe97db19f3055f7a5e2e60657dd&v=4" } }, { "id": "D_kwDOAQkWPc4AeR6H", "number": 4343, "title": "Support for WebTransport over HTTP/3 QUIC", "body": "I am building a new protocol H3Net (https://h3net.switchnomix.com) and we are using HTTP/3 QUIC. As we have to do bidirectional messaging, we have options of streaming, websockets and WebTransport. We believe `WebTransport` suits best for our use cases. Does OpenAPI schema have plans to support WebTransport endpoints which are not natively supported in OpenAPI 3.0? The specification and schema is available on the website and I am happy to provide more details as required. Thanks", "created_at": "2025-02-09T23:02:11Z", "updated_at": "2025-02-14T01:06:30Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "shivarammysore", "avatar_url": "https://avatars.githubusercontent.com/u/1679347?v=4" } }, { "id": "D_kwDOAQkWPc4AVjUP", "number": 3373, "title": "how to reference callback that defined under the components to the path operation?", "body": "when the callbacks are defined under the components and need to be referenced using **$ref**. how do define the $ref?\r\nis this mentioned method okay to define the **$ref** under the callbacks? But the Swagger Editor gives an error.\r\n\r\n{\r\n \"openapi\": \"3.1.0\",\r\n \"info\": {\r\n \"title\": \"My API\",\r\n \"version\": \"1.0.0\"\r\n },\r\n \"components\": {\r\n \"callbacks\": {\r\n \"myCallback\": {\r\n \"{$request.path}/success\": {\r\n \"post\": {\r\n \"requestBody\": {\r\n \"content\": {\r\n \"application/json\": {\r\n \"schema\": {\r\n \"type\": \"object\"\r\n }\r\n }\r\n }\r\n },\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"Callback was successful\"\r\n },\r\n \"400\": {\r\n \"description\": \"Bad request\"\r\n }\r\n }\r\n }\r\n },\r\n \"{$request.path}/failure\": {\r\n \"post\": {\r\n \"requestBody\": {\r\n \"content\": {\r\n \"application/json\": {\r\n \"schema\": {\r\n \"type\": \"object\"\r\n }\r\n }\r\n }\r\n },\r\n \"responses\": {\r\n \"500\": {\r\n \"description\": \"Internal server error\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n },\r\n \"paths\": {\r\n \"/example\": {\r\n \"post\": {\r\n \"requestBody\": {\r\n \"required\": true,\r\n \"content\": {\r\n \"application/json\": {\r\n \"schema\": {\r\n \"type\": \"object\"\r\n }\r\n }\r\n }\r\n },\r\n \"callbacks\": {\r\n \"$ref\": \"#/components/callbacks/myCallback\"\r\n },\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"Success response\"\r\n },\r\n \"400\": {\r\n \"description\": \"Bad request\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n\r\n![test](https://github.com/OAI/OpenAPI-Specification/assets/56576410/ce4352bb-d0ba-4e0c-98a1-c52772ba2b8f)\r\n", "created_at": "2023-09-20T03:42:29Z", "updated_at": "2025-02-06T16:36:50Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Aa6Uq", "body": "Replace\r\n```\r\n\"callbacks\": {\r\n\"$ref\": \"#/components/callbacks/myCallback\"\r\n},\r\n```\r\nwith\r\n```\r\n\"callbacks\": {\r\n \"myCallback\": {\r\n \"$ref\": \"#/components/callbacks/myCallback\"\r\n }\r\n},\r\n```" }, "user": { "login": "RSH17", "avatar_url": "https://avatars.githubusercontent.com/u/56576410?u=51f132710d3b977a0bf3f775a144601a4d229f80&v=4" } }, { "id": "D_kwDOAQkWPc4Ad8TF", "number": 4313, "title": "OpenAPI data archive format?", "body": "I have an OpenAPI for which i periodically make a full snapshot of the data. I would like to store/offer this data in a standard format, eg a zip file containing the spec, all API responses grouped into JSON files an an index teling which URLs are in which file\r\n\r\nFor the web we have [WARC](https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.0/) but has anything like that ever been proposed for the data hosted by an OpenAPI service? \r\n\r\nI know it's trivially to build something myself, but especially with an archive format it would be nice to have independent tooling to verify the implementation, eg to be able to run simulated fetch-es against the archive and then comparing with the real-time version", "created_at": "2025-01-20T12:40:22Z", "updated_at": "2025-01-21T20:11:26Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "unilynx", "avatar_url": "https://avatars.githubusercontent.com/u/2772353?v=4" } }, { "id": "D_kwDOAQkWPc4AT636", "number": 3283, "title": "Discriminator: Is mapping multiple property values to the same schema valid?", "body": "I have a use-case where I have two objects, Comparison and Composite, that both share an operator property, but Composite has a collection of both itself and Comparisons. To discriminate, I figured I would use the operator property. Both Comparison and Composite have their own set of possible operators. I created a discriminator like this:\r\n```yaml\r\nAny: {}\r\nCondition:\r\n type: object\r\n properties:\r\n operator:\r\n type: string\r\n discriminator:\r\n propertyName: operator\r\n mapping:\r\n eq: \"#/components/schemas/Comparison\"\r\n neq: \"#/components/schemas/Comparison\"\r\n gte: \"#/components/schemas/Comparison\"\r\n lte: \"#/components/schemas/Comparison\"\r\n gt: \"#/components/schemas/Comparison\"\r\n lt: \"#/components/schemas/Comparison\"\r\n in: \"#/components/schemas/Comparison\"\r\n notIn: \"#/components/schemas/Comparison\"\r\n or: \"#/components/schemas/Composite\"\r\n and: \"#/components/schemas/Composite\"\r\n anyOf:\r\n - \"$ref\": \"#/components/schemas/Comparison\"\r\n - \"$ref\": \"#/components/schemas/Composite\"\r\n Comparison:\r\n description: Check a property meets some condition\r\n properties:\r\n property:\r\n type: string\r\n argument:\r\n \"$ref\": \"#/components/schemas/Any\"\r\n operator:\r\n \"$ref\": \"#/components/schemas/ComparisonOperators\"\r\n type: object\r\n Composite:\r\n description: Multiple Conditions\r\n properties:\r\n operator:\r\n \"$ref\": \"#/components/schemas/CompositeOperators\"\r\n conditions:\r\n type: array\r\n items:\r\n \"$ref\": \"#/components/schemas/Condition\"\r\n type: object\r\n ComparisonOperators:\r\n type: string\r\n enum:\r\n - eq\r\n - neq\r\n - lte\r\n - lt\r\n - gte\r\n - gt\r\n - in\r\n - notIn\r\n CompositeOperators:\r\n type: string\r\n enum:\r\n - andX\r\n - orX\r\n ```\r\n\r\nAnd put it in swagger editor. It didn't complain, but I can't find a similar example. Was wondering if the mapping was meant to contain only unique One-To-One entries or if a Many-To-One like this is allowed.", "created_at": "2023-05-22T15:24:23Z", "updated_at": "2025-01-16T21:13:05Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AWxjX", "body": "Ron Ratovsky answered in slack:\r\n> yes, it is perfectly valid." }, "user": { "login": "Aweptimum", "avatar_url": "https://avatars.githubusercontent.com/u/40273116?u=5b66bb9075103c8b7b97d94cbf3290a85ec1e8c4&v=4" } }, { "id": "D_kwDOAQkWPc4AZkGQ", "number": 3827, "title": "How to define Header parameter values?", "body": "I've not found any sufficient way to define header parameter values such as below: \r\n\r\n- `rel` in a `link` header \r\n- `q` in an `accept` header\r\n- `name` in `content-disposition` header\r\n- cache directives\r\netc...\r\n\r\nCan someone share an example of that? ", "created_at": "2024-05-20T20:02:53Z", "updated_at": "2025-01-08T04:05:03Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "jeremyfiel", "avatar_url": "https://avatars.githubusercontent.com/u/32110157?u=d826152c23fccb7f43f4ccfa2cda785ba8c79df0&v=4" } }, { "id": "D_kwDOAQkWPc4AdrAI", "number": 4289, "title": "No way to describe a path-item with an empty URI path", "body": "@ralfhandl said [in this thread](https://github.com/OAI/OpenAPI-Specification/pull/4272#issuecomment-2568922715) that URLs with trailing slashes can be treated differently than those without... but we have no way of expressing that at present, as all entries under `/paths` must be prefixed with a slash (https://spec.openapis.org/oas/v3.1.1#patterned-fields). Is this something we want to be able to express?", "created_at": "2025-01-05T00:45:45Z", "updated_at": "2025-01-07T19:22:43Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "karenetheridge", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4" } }, { "id": "D_kwDOAQkWPc4Adpbv", "number": 4285, "title": "Creating Models and APIs is separate packages", "body": "I have a go project and am using Swagger 2.0 and now want to move to Openapi 3.0 \r\n\r\nI am using these commands for the same - \r\n\r\nAPI- \r\nopenapi-generator generate \\\r\n -g go \\\r\n -i openapi.yaml \\\r\n -o ./openapi_client \\\r\n --global-property apis,supportingFiles=false,models=false \\\r\n --additional-properties sortParamsByRequiredFlag=false,packageName=client,modelPackage=project-root/openapi_models\r\n\r\nModel-\r\nopenapi-generator generate \\\r\n -g go \\\r\n -i openapi.yaml \\\r\n -o ./openapi_models \\\r\n --global-property models,supportingFiles,apis=false \\\r\n --additional-properties packageName=models,nullable=false\r\n\r\nThe code does get created but the API files fail to import the models when they get generated resulting into a lot of undefined errors. Appreciate any help on this. Thanks!", "created_at": "2025-01-02T17:03:50Z", "updated_at": "2025-01-05T17:47:46Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "ramani527", "avatar_url": "https://avatars.githubusercontent.com/u/115122472?v=4" } }, { "id": "D_kwDOAQkWPc4AdYpQ", "number": 4262, "title": "formalize reference locations in the OpenAPI document schema", "body": "In my implementation I take note of the reference location of various entities while parsing an openapi document -- e.g. when following a `$ref` in the schema that points to `#/$defs/parameter-or-reference` I make a note of the data location (in the openapi document being parsed) that this is a location of a parameter entity. This builds up a registry of location -> entity type maps, which I make use of at runtime when resolving a `$ref` in the openapi document -- e.g. when validating an HTTP request against the openapi description, and I am processing a parameter object in the description, if I see a `$ref` to something that I expect is a parameter object, when resolving this reference I check in the entity registry to confirm that the target of the reference is indeed a parameter (and if not, this constitutes a runtime error). [I also have plans to check all `$ref` targets at parse time, at least for those pointing to the local document, as part of an extra linting step, but haven't implemented this yet.]\r\n\r\nThis means I am dependent on the name of the references in the openapi schema. Everything is using the same naming convention of `#/$defs/foo-or-reference` and `#/$defs/foo` in the schema definitions, but theoretically this could change at any time as there are no guarantees as to how the schema is constructed. Therefore it would be useful to formalize some of these locations and use `$anchor`s in these definitions, and make use of the plain-name fragment form in the `$ref`s, and document their use, so we are free to move things around in the schema while still preserving a name that can be relied upon by implementors.\r\n\r\nref. https://open-api.slack.com/archives/C06A0RPNPGE/p1734458650755389", "created_at": "2024-12-17T18:17:44Z", "updated_at": "2024-12-22T19:21:52Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "karenetheridge", "avatar_url": "https://avatars.githubusercontent.com/u/303051?v=4" } }, { "id": "D_kwDOAQkWPc4Ac3zR", "number": 4231, "title": "How to combine the 4 of 5 responses as a $ref?", "body": "Hi. I am draft the API specification. Here is my question?\r\nFor each API, there are 5 responses, such as \r\n```\r\n...\r\n\"responses\":{\r\n \"200\":{\r\n // the 200 responses if different for each API\r\n },\r\n \"400\":{\r\n \"$ref\": \"#/components/schemas/Error400\"\r\n },\r\n \"401\":{\r\n \"$ref\": \"#/components/schemas/Error401\"\r\n },\r\n \"404\":{\r\n \"$ref\": \"#/components/schemas/Error404\"\r\n },\r\n \"429\":{\r\n \"$ref\": \"#/components/schemas/Error429\"\r\n }\r\n}\r\n...\r\n```\r\n\r\nSince the 200 is different for each API with different response schema, but the 400-429 is same. May I combine 400-429 into one $ref?\r\nSuch as \r\n```\r\n\"responses\":{\r\n \"200\":{\r\n // the 200 responses if different for each API\r\n },\r\n \"4xx\":{\r\n \"$ref\":\"xxx\"\r\n }\r\n}\r\n...\r\n```", "created_at": "2024-11-28T02:40:37Z", "updated_at": "2024-12-19T17:54:09Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4ArhST", "body": "In OpenAPI, we don't have this feature, but you could use an Overlay to add the group as a separate step. There's a similar-ish example [in the Overlays docs](https://learn.openapis.org/overlay/example-add-filter-parameters.html) but please let us know if you need more context on what this is and how to do it?" }, "user": { "login": "Yao544303", "avatar_url": "https://avatars.githubusercontent.com/u/6713442?u=c5c8489c511beae08ef6ec0ba1addce53eb97664&v=4" } }, { "id": "D_kwDOAQkWPc4AdFiB", "number": 4245, "title": "Puzzled about syntax", "body": "I'm familiarising myself with OpenAPI (aka Swagger) and have a question that no amount of web searching has shed light on.\r\n\r\nThis is what I see when I peruse a generated Doc for some \"Model\"\r\n\r\n![image](https://github.com/user-attachments/assets/12b7e957-caa4-4f94-ba1a-e6ab7bee0f2d)\r\n\r\nWhat is that syntax? does it have a name? Is it simply a generic way to display a structure? It is not JSON, YAML, XML etc but why? why this obscure syntax? Is it just a friendly way of displaying stuff or can it also be consumed, does OpenAPI have the ability to consume that syntax?\r\n", "created_at": "2024-12-06T17:34:32Z", "updated_at": "2024-12-19T15:38:31Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AsTIe", "body": "That looks like a Swagger tool, correct? You should ask Swagger support about it. That format is not part of the OpenAPI Specification, so it must be something that they chose. (I'm one of the more prolific contributors to the recent 3.0.4 and 3.1.1 releases that we just published, so I'm very familiar with what is and is not in the spec)." }, "user": { "login": "The-Futurist", "avatar_url": "https://avatars.githubusercontent.com/u/12262952?u=5d5c6292e02ab192a5de90ddc630ee60743e52dd&v=4" } }, { "id": "D_kwDOAQkWPc4Ac3Yn", "number": 4230, "title": "Support specifying webhook security scheme", "body": "Webhook security often involves signing various parts of the request with a symmetric signing algorithm such as HMAC-SHA256 and including the signature as a header. There's lots of variance about the format of the signature. Others employ asymmetric algorithms or some just use a plain shared secret aka API key.\r\n\r\nIn all those cases though, webhook security is a different scheme to the top level spec security. We need a way to configure webhook security clearly and support common signing schemes.\r\n\r\nRelated issues\r\n* https://github.com/OAI/OpenAPI-Specification/issues/1953\r\n* https://github.com/OAI/OpenAPI-Specification/issues/344\r\n* https://github.com/OAI/OpenAPI-Specification/issues/1464\r\n\r\nSlack thread\r\n* https://open-api.slack.com/archives/C0EDH2QKD/p1730871606673419", "created_at": "2024-11-27T17:39:47Z", "updated_at": "2024-11-28T09:34:28Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "mfbx9da4", "avatar_url": "https://avatars.githubusercontent.com/u/1690659?u=b4336f4686cb4fce41a0d11976604954129ccdc2&v=4" } }, { "id": "D_kwDOAQkWPc4Acp-z", "number": 4207, "title": "Open Api has wrong json when generate json in browser", "body": "Hello! I have a problem with the Open api specification in when generating json in the browser via a link.\r\nVersion Open Api UI org.springdoc:springdoc-openapi-ui:jar:1.6.0\r\n\r\nI have a description of the field in the yml file\r\n![image](https://github.com/user-attachments/assets/c991433e-bb7e-49af-8f53-a4012817b01d)\r\n\r\nWhen i start my app and jpen link localhost:8082/swagger-ui.html, i have this page:\r\n![swagger page](https://github.com/user-attachments/assets/a7c2984a-922b-4642-afae-00ee3d9a1173)\r\n\r\nWhen I click on the link \"/v3/api-docs\", I get a generated json file:\r\n![json swagger](https://github.com/user-attachments/assets/86ef548d-4376-45f4-a859-6d4ea1070d50)\r\n\r\nAs can be seen from the description of the yml-file, the field \"ids\" has a type: \"string \" and a length: 255.\r\nBut when json is generated, the length for this field is 2147483647.\r\n\r\nHelp please. How to fix this problem?\r\n", "created_at": "2024-11-19T09:54:42Z", "updated_at": "2024-11-19T16:19:02Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "UrKas16", "avatar_url": "https://avatars.githubusercontent.com/u/83245989?u=bb580ac03bd56e35a765b4dc143a8aa6e043908b&v=4" } }, { "id": "D_kwDOAQkWPc4AcVn5", "number": 4174, "title": "is there a way to describe that one of a couple of headers is required?", "body": "We wanted to describe a GET endpoint that requires oneOf two headers.\r\nOur nodejs+fastify+ajv+json schema combo has no problem describing and validating this.\r\nBut when trying to create an openapi 3.1.x spec for this we didn't find anyway to describe this.\r\n\r\nThe request headers area ([parameters](https://spec.openapis.org/oas/v3.1.1.html#parameter-locations)) allows a `schema` but it is for a specific named header (field `name`).\r\n\r\nfor now we're just describing this requirement via the description of the endpoint.\r\n\r\nAm I missing somehting? or is this a limitation of the current specs?\r\nIf the latter, is there any interest in changing it in the future?\r\n", "created_at": "2024-11-05T11:22:32Z", "updated_at": "2024-11-18T19:26:43Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AqzEm", "body": "@samzilverberg you are not missing anything. This will almost certainly be changed in [4.0 \"Moonwalk\"](https://github.com/OAI/sig-moonwalk/discussions). I'm not sure there's much we could do in 3.2 as adding cross-parameter relationships would be complex to do in a backwards-compatible manner." }, "user": { "login": "samzilverberg", "avatar_url": "https://avatars.githubusercontent.com/u/229485?u=01e6ade9d110a67f365047ad8250216497800e00&v=4" } }, { "id": "D_kwDOAQkWPc4AOL30", "number": 2813, "title": "Security: Access token example value", "body": "I've a requirement to provide example value for access token for Oauth type security schemes.\r\nMy request will look like this.\r\n\r\ncurl\r\n-X **POST**\r\n-H \"Content-Type: **application/json**\"\r\n-H \"Authorization: **my-oauthtoken 0000.xxxxxxxxx**\"\r\n\r\nI tried to set **Authorization** header in parameters object. But, it violates the openapi specification.\r\nAnd there is no way to provide 'example' in securityScheme object. Is there any alternative ways to provide example for Authorization.\r\n\r\nNotes auth type:\r\n- **Authorization type** : OAuth2 \r\n- **Flow** : Authorization code\r\n\r\nThanks in advance!\r\n\r\n", "created_at": "2021-12-02T11:56:54Z", "updated_at": "2024-11-11T22:05:55Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Rajesh-KG", "avatar_url": "https://avatars.githubusercontent.com/u/77315676?v=4" } }, { "id": "D_kwDOAQkWPc4AaDa_", "number": 3918, "title": "As per OAS, when defining discriminator with explicit mapping, should implicit discriminator value still be accepted?", "body": "Hi, I have not found any information about this in the documentation (potential hint for extension), so I am asking here.\r\n\r\nLet's say I have the following schema which explicitly defines mapping for `Bar` and `Baz` objects:\r\n\r\n```yaml\r\nFoo:\r\n type: object\r\n discriminator:\r\n propertyName: type\r\n mapping:\r\n BAR: '#/components/schemas/Bar'\r\n BAZ: '#/components/schemas/Baz'\r\n required:\r\n - type\r\n properties:\r\n type:\r\n type: string\r\n```\r\n\r\nI know that when a discriminator is not present, an implicit mapping is to be considered to aid (de)serialization, in this case `type: Bar` would map to `Bar`, and `type: Baz` would map to `Baz`.\r\n\r\nBut when I define explicit mapping, should the implicit value still be allowed, or should the API accept only the manually specified options?", "created_at": "2024-06-17T06:10:01Z", "updated_at": "2024-11-11T22:00:33Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Alnjf", "body": "@ondrej-simon I think you're making this more complicated than it is. The algorithm is very simple:\r\n\r\n* If there is an explicit mapping for the exact, case-sensitive value, then use the explicit mapping\r\n* Otherwise, if there is an implicit mapping for the exact, case-sensitive value, then use the implicit mapping\r\n* If neither exists, fail\r\n\r\nThere are no other checks involved. There's nothing that \"masks\" based on differences in case. There's nothing preventing multiple values from mapping (implicitly or explicitly) to the same schema. It's just those two steps, nothing else.\r\n\r\nI've adjusted your scenarios accordingly:\r\n\r\n## Scenario 1 - no mapping specified\r\n\r\n_This scenario is correct as you wrote it (although I'd make similar phrasing changes to the \"Result\" column as in the next two scenarios._\r\n\r\n## Scenario 2 - partial mapping specified\r\n\r\n### Schema definition\r\n\r\n```yaml\r\nFoo:\r\n type: object\r\n discriminator:\r\n propertyName: type\r\n mapping:\r\n BAR: '#/components/schemas/Bar'\r\n required:\r\n - type\r\n properties:\r\n type:\r\n type: string\r\nBar:\r\n type: object\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\nBaz:\r\n type: object\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\n```\r\n\r\n### Execution matrix\r\n\r\n|`type` attribute value in input JSON|Result|\r\n|----|----|\r\n|Empty|❌ - the `type` attribute is required|\r\n|`Bar`|✅ - implicit mapping _because matching is case-sensitive_|\r\n|`Baz`|✅ - _maps to `Baz` object thanks to implicit mapping_|\r\n|`bar`|❌ - no mapping exists, _no component name matches_|\r\n|`baz`|❌ - no mapping exists, _no component name matches_|\r\n|`BAR`|✅ - maps to `Bar` object thanks to explicit mapping|\r\n|`BAZ`|❌ - no mapping exists, only implicit `Baz` is supported|\r\n\r\n_There is nothing in the Discriminator Object specification that prevents two values (`Bar` and `BAR`) from mapping to the same schema. Defining an explicit mapping for `BAR` doesn't have any impact on `Bar` (or `bar`, or `bAr`, etc.)._\r\n\r\n## Scenario 3 - exhaustive mapping specified\r\n\r\n### Schema definition\r\n\r\n```yaml\r\nFoo:\r\n type: object\r\n discriminator:\r\n propertyName: type\r\n mapping:\r\n BAR: '#/components/schemas/Bar'\r\n BAZ: '#/components/schemas/Baz'\r\n required:\r\n - type\r\n properties:\r\n type:\r\n type: string\r\nBar:\r\n type: object\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\nBaz:\r\n type: object\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\n```\r\n\r\n### Execution matrix\r\n\r\n|`type` attribute value in input JSON|Result|\r\n|----|----|\r\n|Empty|❌ - the `type` attribute is required|\r\n|`Bar`|✅ - implicit mapping _because matching is case-sensitive_|\r\n|`Baz`|✅ - implicit mapping _because matching is case-sensitive_|\r\n|`bar`|❌ - no mapping exists, _no component name matches_|\r\n|`baz`|❌ - no mapping exists, _no component name matches_|\r\n|`BAR`|✅ - maps to `Bar` object thanks to explicit mapping|\r\n|`BAZ`|✅ - maps to `Baz` object thanks to explicit mapping|" }, "user": { "login": "ondrej-simon", "avatar_url": "https://avatars.githubusercontent.com/u/91841260?v=4" } }, { "id": "D_kwDOAQkWPc4Abf-n", "number": 4105, "title": "Invalid Schema renders correctly", "body": "Hello,\r\n\r\nThere are two things that I would like to have in OpenAPI that the seems not to be possible according to the documentation. Strangely, if I try to implement them, the result HTML is rendered as I would expect, even though schema validation errors also appear.\r\n\r\n1. Extend/override properties of a parameter defined externally.\r\n\r\nExample:\r\n```yaml\r\n# ...\r\n\r\n/external-param:\r\n get:\r\n description: Uses a parameter defined in another file.\r\n parameters:\r\n - $ref: reusableParam.yaml\r\n responses:\r\n 200:\r\n description: OK\r\n/external-param-combined:\r\n get:\r\n description: Uses a parameter defined in another file and combines with local parameters.\r\n parameters:\r\n - name: reusableParam\r\n allOf:\r\n - $ref: reusableParam.yaml\r\n - required: true\r\n - schema:\r\n type: number\r\n default: 50\r\n responses:\r\n 200:\r\n description: OK\r\n\r\n# ...\r\n```\r\n\r\n2. Extend/Override a set of responses defined externally.\r\n\r\nExample:\r\n```yaml\r\n# ...\r\n\r\n /external-responses-combined:\r\n get:\r\n description: Uses multiple responses defined in another file and combines with local responses.\r\n responses:\r\n allOf:\r\n - $ref: '#/components/responses/GeneralResponses'\r\n - 200:\r\n description: OK\r\n\r\ncomponents:\r\n responses:\r\n GeneralResponses:\r\n $ref: generalResponses.yaml\r\n\r\n# ...\r\n```\r\n\r\nAlso strange, when executing the same code in a local [swagger-ui](https://github.com/swagger-api/swagger-ui) project (`npm run dev`) OR with a local static files server (I used [Caddy](https://caddyserver.com/) and [http-server](https://github.com/http-party/http-server)) it works and doesn't show any schema validation errors.\r\n\r\nCan someone help me understand this behaviour? Here is a complete example:\r\nrepo: https://github.com/guizoxxv/open-api-example\r\nhtml: https://guizoxxv.github.io/open-api-example/\r\n\r\nThank you.", "created_at": "2024-09-19T21:54:30Z", "updated_at": "2024-11-11T21:57:27Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "guizoxxv", "avatar_url": "https://avatars.githubusercontent.com/u/20052395?u=7459c013df35525317a859be828ab8ac37cf68d5&v=4" } }, { "id": "D_kwDOAQkWPc4AP1-S", "number": 2948, "title": "Default field in schema object with type `object`", "body": "Hello! Is it possible to specify a default object property for object, using `default` field? \r\nFor example I want to specify a default `foo` property in `Bar` object. I want to specify default `Foo` object only in the property of objects `Bar`. If it is possible, please provide an example.\r\n\r\n```yml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: 'Example'\r\n version: 0.1.0\r\nservers:\r\n - url: 'http://example.com'\r\npaths:\r\n '/foo':\r\n delete:\r\n responses:\r\n '200':\r\n description: OK\r\ncomponents:\r\n schemas:\r\n Foo:\r\n type: object\r\n properties: \r\n text:\r\n type: string\r\n number:\r\n type: number\r\n Bar:\r\n type: object\r\n properties:\r\n foo:\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\n default: \"Is it possible to specify a default Foo object here?\"\r\n```", "created_at": "2022-06-17T12:24:44Z", "updated_at": "2024-11-07T10:45:43Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4ALfsL", "body": "Yes, it is possible.\r\n\r\nOpenAPI 3.0 uses [JSON Schema (draft 5)](https://json-schema.org/specification-links.html#draft-5) spec to define schemas.\r\n\r\nThe `default` keyword is defined in [JSON Schema Validation spec, section 6.2](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-6.2):\r\n\r\n> There are no restrictions placed on the value of this keyword.\r\n>\r\n> This keyword can be used to supply a default JSON value associated with a particular schema. It is RECOMMENDED that a default value be valid against the associated schema.\r\n\r\nOpenAPI 3.0 clarifies semantics of the keyword in [section 4.7.25.1 of the spec](https://spec.openapis.org/oas/v3.0.0#properties):\r\n\r\n> The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `\"foo\"` but cannot be `1`.\r\n\r\nIt means you may use `default` keyword to document what default behaviour of your API would be like if value is omited, for example.\r\n\r\nYour example may be modified as:\r\n\r\n```yaml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: Example\r\n version: 0.1.0\r\nservers:\r\n- url: http://example.com\r\npaths:\r\n /foo:\r\n delete:\r\n responses:\r\n '200':\r\n description: OK\r\ncomponents:\r\n schemas:\r\n Foo:\r\n type: object\r\n properties:\r\n text:\r\n type: string\r\n number:\r\n type: number\r\n Bar:\r\n type: object\r\n properties:\r\n foo:\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\n default:\r\n text: abc\r\n number: 123\r\n```" }, "user": { "login": "mtovt", "avatar_url": "https://avatars.githubusercontent.com/u/96553816?v=4" } }, { "id": "D_kwDOAQkWPc4Aasl0", "number": 3983, "title": "Dynamic Scopes", "body": "After trying to architect a good way for doing RAR with OAuth2, I stumbled upon the question on how to implement fine-grained access control. How to do this right? My intuition was to add `{variableName}` in the scope to make it more fine-grained, and document it clearly.\r\n\r\nI found these materials that confirmed my strategy:\r\n\r\n- https://github.com/keycloak/keycloak/discussions/8486\r\n- https://github.com/OAI/OpenAPI-Specification/issues/1731\r\n- Example of dynamic scopes: https://distribution.github.io/distribution/spec/auth/scope/\r\n- Why it's not a good idea: https://auth0.com/blog/on-the-nature-of-oauth2-scopes/\r\n- This guy has a lot to say: https://auth0.com/blog/authors/vittorio-bertocci/\r\n- This is useful to gather OpenAPIs stance on this topic: https://github.com/OAI/OpenAPI-Specification/labels/security%3A%20access%20ctrl\r\n\r\nAll in all, it seems that it's possible to create scopes with dynamic parts. Maybe disliked by some developers and authorities (such as Vittorio Bertocci) but definitely possible - and implemented by some people - and not uncompatible with oauth2.\r\n\r\nAs an example, I will implement my database management and use API like this:\r\n\r\n```json\r\n{\r\n \"components\": {\r\n \"securitySchemes\": {\r\n \"oauth2\": {\r\n \"type\": \"oauth2\",\r\n \"flows\": {\r\n \"authorizationCode\": {\r\n \"authorizationUrl\": \"https://auth.example.com/oauth/authorize\",\r\n \"tokenUrl\": \"https://auth.example.com/oauth/access_token\",\r\n \"x-scopes-parameters\": [\r\n { \"name\": \"projectSlug\", \"description\": \"Refers to a project\" },\r\n { \"name\": \"databaseSlug\", \"description\": \"Refers to a database\" }\r\n ],\r\n \"scopes\": {\r\n \"admin\": \"Access to managing all projects\",\r\n \"user:project:{projectSlug}\": \"Access to use all databases in a project, with or without user separation.\",\r\n \"user:project:{projectSlug}:read\": \"Access to read all databases in a project, and write to all user-separated databases.\",\r\n \"admin:project:{projectSlug}\": \"Access to manage an entire project\",\r\n \"admin:db:{databaseSlug}\": \"Access to manage a database\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nTo make things clearer, I'll add `x-scope-parameters` to my openapi specification, as such:\r\n\r\n```json\r\n{\r\n \"definitions\": {\r\n \"ScopeParameters\": {\r\n \"type\": \"array\",\r\n \"description\": \"OAS extension that specifies the parameters you use in your scopes.\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"additionalProperties\": false,\r\n \"properties\": {\r\n \"name\": { \"type\": \"string\" },\r\n \"schema\": {\r\n \"oneOf\": [\r\n {\r\n \"$ref\": \"#/definitions/Schema\"\r\n },\r\n {\r\n \"$ref\": \"#/definitions/Reference\"\r\n }\r\n ],\r\n \"description\": \"Defaults to string, but can be further defined here if it has a specific syntax (using format or regex, for example)\"\r\n },\r\n \"description\": { \"type\": \"string\" }\r\n }\r\n }\r\n },\r\n \"AuthorizationCodeOAuthFlow\": {\r\n \"type\": \"object\",\r\n \"description\": \"See https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type for a good understanding\",\r\n \"required\": [\"authorizationUrl\", \"tokenUrl\", \"scopes\"],\r\n \"properties\": {\r\n \"authorizationUrl\": {\r\n \"type\": \"string\",\r\n \"format\": \"uri-reference\"\r\n },\r\n \"tokenUrl\": {\r\n \"type\": \"string\",\r\n \"format\": \"uri-reference\"\r\n },\r\n \"refreshUrl\": {\r\n \"type\": \"string\",\r\n \"format\": \"uri-reference\"\r\n },\r\n\r\n \"x-scopes-parameters\": { \"$ref\": \"#/definitions/ScopeParameters\" },\r\n \"scopes\": {\r\n \"type\": \"object\",\r\n \"additionalProperties\": {\r\n \"type\": \"string\"\r\n }\r\n }\r\n },\r\n \"patternProperties\": {\r\n \"^x-\": {}\r\n },\r\n \"additionalProperties\": false\r\n }\r\n }\r\n}\r\n```\r\n\r\nJust sharing my research and ADR here. Maybe it helps, and curious to hear others takes on this!\r\n", "created_at": "2024-07-31T11:26:30Z", "updated_at": "2024-10-03T16:59:27Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "janwilmake", "avatar_url": "https://avatars.githubusercontent.com/u/97664551?u=baa6b5ea77a6f0a9cb71659f031839eb83e1e54f&v=4" } }, { "id": "D_kwDOAQkWPc4Abrcz", "number": 4118, "title": "OpenAPI Country restrictions?", "body": "Hi! I am currently in the Philippines and I'm experiencing this error message:\r\n\r\n{\"code\":-1002,\"msg\":\"You are not authorized to execute this request\"}\r\n\r\nI'm thinking it has something to do with the VPN I use.\r\n\r\nThanks. Can anyone help?", "created_at": "2024-09-30T03:14:38Z", "updated_at": "2024-09-30T15:32:54Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "madice6", "avatar_url": "https://avatars.githubusercontent.com/u/183332592?v=4" } }, { "id": "D_kwDOAQkWPc4AaabD", "number": 3951, "title": "Understanding references to polymorphic types with \"allOf\" and \"discriminator\"", "body": "Hi everyone,\r\n\r\nI have a question about the Pet, Cat, and Dog polymorphism example using \"allOf\" and \"discriminator\" from the OpenAPI specification. There have been several discussions and issues in the past about this topic, but I could not find an answer to this specific question.\r\n\r\nA short summary of the example:\r\nThe \"Pet\" schema object defines properties common to all pets. The \"Dog\" and \"Cat\" schemas use \"allOf\" to combine all pet properties with properties specific to a \"Dog\" or \"Cat\".\r\n\r\nThe \"Pet\" schema also contains the \"discriminator\" object, which according to the specification, \"can be used to aid in serialization, deserialization, and validation.\"\r\n\r\nWhat I could not find information about is what this means when another schema object references the \"Pet\" within one of its properties, like in this example:\r\n\r\n````yaml\r\nPetStore:\r\n type: object\r\n properties:\r\n availablePets:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/Pet'\r\n````\r\n\r\nIf the \"discriminator\" object is just an \"aid\" and does not change the semantics of allOf, then I would expect that simply referencing the 'Pet' schema object here is not sufficient if the goal is to allow only valid \"Cat\" or \"Dog\" objects as values for 'availablePets'.\r\n\r\nWith the current definition, none of the constraints defined for a \"Cat\" or \"Dog\" would be validated — only the ones defined for the \"Pet\".\r\n\r\nIs this assumption correct? If yes, then I would assume that \"oneOf\" could be used here to restrict the values to \"Cat\" or \"Dog\" as intended.\r\n\r\nBest regards\r\nMartin", "created_at": "2024-07-11T16:21:28Z", "updated_at": "2024-09-21T17:42:36Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "mhonert", "avatar_url": "https://avatars.githubusercontent.com/u/48153876?v=4" } }, { "id": "D_kwDOAQkWPc4AbdE9", "number": 4099, "title": "Looking for OpenAPI with PHP8 atrributes, symfony, NelmioApiDocBundle learning resources", "body": "Hello, having trouble to find learning resources about how to use PHP8 attributes with openAPI, symfony. Using [Nelmio](https://symfony.com/bundles/NelmioApiDocBundle/current/index.html) but really getting often various problems which I am not able to find answers to. Have read symfony Nelmio bundle documentation, some other documentations but I can't remember there being talked about problems I have.\r\nFor example recently I was strugling to overwrite property of the documenation for specific class field. It has some documentation, class is reused. In one place I wanted to change the documentation for that field without duplicating everything. Was getting so much errors and only when finnally one guy helped in symfony slack, I was able to solve. If I had seen this problem in tutorial, I could have remembered and solved quickly.\r\n\r\nTried searching in udemy but I find only general openAPI tutorials or general PHP, general how to make API. But not a combination of php, openapi, symfony, or at least without symfony. But probably since I use NelmioApiDocBundle, it has some effect also.", "created_at": "2024-09-17T05:51:48Z", "updated_at": "2024-09-17T18:17:51Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "darius-v", "avatar_url": "https://avatars.githubusercontent.com/u/6602631?u=28a2bcd7a2a4733339662caf6c5a9deb35addc41&v=4" } }, { "id": "D_kwDOAQkWPc4Aa7ut", "number": 4036, "title": "Clarification Needed on Path Template Normalization in Find Function for Swagger Document Generation", "body": "Could you clarify the rationale behind [normalizing path templates](https://pkg.go.dev/github.com/getkin/kin-openapi@v0.127.0/openapi3#Paths.Find) in the `Find` function? Specifically, in cases where different paths use similar templates (like `{iid}` and `{did}`), is normalization intended to handle such scenarios? We're evaluating whether this behavior is essential for Swagger document generation, and understanding its original purpose would help us decide if and when normalization makes sense.\r\n\r\nHere is an example of the expected document:\r\n```\r\n /identities/{iid}:\r\n get:\r\n description: Gets an identity by its ID\r\n operationId: getIdentityByID\r\n parameters:\r\n - description: The identity ID \r\n in: path\r\n name: iid\r\n required: true\r\n schema:\r\n example: id\r\n type: string\r\n ...\r\n /identities/{did}:\r\n get:\r\n description: Gets an identity by its DID\r\n operationId: getIdentityByDID\r\n parameters:\r\n - description: The identity DID \r\n in: path\r\n name: did\r\n required: true\r\n schema:\r\n example: did\r\n type: string\r\n ...\r\n```", "created_at": "2024-08-16T15:23:09Z", "updated_at": "2024-09-02T21:10:48Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "dwertent", "avatar_url": "https://avatars.githubusercontent.com/u/64066841?u=ebf9e11fd07007730bfc96249fd4f4f680ace8f4&v=4" } }, { "id": "D_kwDOAQkWPc4Aa6nZ", "number": 4023, "title": "Add token endpoint auth method to the tokenURL in the securitySchemes", "body": "Currently there is no way to define the token endpoint auth method, tooling just defaults to client_secret_post\r\nBy adding authMethod to the tokenURL in the securitySchemes so it aligns with Oauth spec would tooling supports more than just client secret post. Could this be added to v3.2.0-dev?\r\n\r\nsecuritySchemes:\r\n bearerAuth: # arbitrary name for the security scheme\r\n description: This is the endcode JWT Access token\r\n type: http\r\n scheme: bearer\r\n bearerFormat: string\r\n oauthAuthCode:\r\n description: Auth Code RFC8725 compliant\r\n type: oauth2\r\n flows: \r\n authorizationCode:\r\n authorizationUrl: 'https://oauth.simple.api/authorization'\r\n tokenUrl: 'https://oauth.simple.api/token'\r\n authMethod: client_secret_jwt\r\n scopes:\r\n myscope: myScope\r\n\r\nwhere authMethoid is one of:\r\n\r\n- client_secret_post\r\n- client_secret_jwt\r\n- private_key_jwt\r\n- none\r\n- tls_client_auth\r\n- self_signed_tls_client_auth\r\n\r\nThe tooling seems to default to client_secret_post at the moment", "created_at": "2024-08-15T10:18:05Z", "updated_at": "2024-08-15T10:19:02Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "mcrobbj", "avatar_url": "https://avatars.githubusercontent.com/u/10534160?v=4" } }, { "id": "D_kwDOAQkWPc4AU_ga", "number": 3345, "title": "Conversion of Swagger 2.0 to OpenAPI", "body": "I am working on Spring boot and have to convert entire project along with all UI elements to OpenAPI. Currently we are using Swagger 2.0 for the same. I have SwaggerController where we are setting up the documentation details and SwaggerConfigController where we are loading config details. I am not able to understand it in depth and that's why cannot work on its conversion as well. Can someone please help me with this issue\r\n", "created_at": "2023-08-09T10:33:38Z", "updated_at": "2024-08-06T04:33:22Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Afarb", "body": "There is a tool for this - someone wrote a blog post on it here: https://dev.to/derberg/convert-swagger-2-0-to-openapi-3-0-3joj\r\n\r\n(this does not imply the endorsement of the blog post or tool, it's just informational)" }, "user": { "login": "6savage9", "avatar_url": "https://avatars.githubusercontent.com/u/126058093?v=4" } }, { "id": "D_kwDOAQkWPc4AX5JJ", "number": 3608, "title": "Use of oneOf with a discriminator, when the child schemas are identical?", "body": "Hello,\r\nI have been trying to clean up a schema which is using `oneOf`, and have run into some issues which may be due to some bad understandings of how `oneOf` should be used, and hoped to get some guidance.\r\n\r\n### Situation\r\n\r\nFor an example I will use the Cat/Dog/Lizard/etc example, and for your information, I am using v3.0.1 of the spec (however this question seems relevant for at least all 3.x.y versions).\r\n\r\nI have currently tried to use `oneOf` with a `discriminator` so that I can return a typed schema, and describe nicely what the child schemas will look like.\r\n\r\nNote that in my example I have:\r\n\r\n- Used a simple `oneOf`\r\n- The `pet_type` field is present on all `oneOf` entities.\r\n- I have added a new animal `Snake` which **happens to have the same properties (currently, although may not in future) as `Lizard`**.\r\n\r\nThis looks like so:\r\n```yaml\r\ncomponents:\r\n schemas:\r\n PetType:\r\n oneOf:\r\n - $ref: '#/components/schemas/Cat'\r\n - $ref: '#/components/schemas/Dog'\r\n - $ref: '#/components/schemas/Lizard'\r\n - $ref: '#/components/schemas/Snake'\r\n discriminator:\r\n propertyName: pet_type\r\n mapping:\r\n CAT: '#/components/schemas/Cat'\r\n DOG: '#/components/schemas/Dog'\r\n LIZARD: '#/components/schemas/Lizard'\r\n SNAKE: '#/components/schemas/Snake'\r\n Cat:\r\n description: A representation of a cat\r\n type: object\r\n properties:\r\n pet_type:\r\n type: string\r\n description: The type of the Pet.\r\n huntingSkill:\r\n type: string\r\n description: The measured skill for hunting\r\n enum:\r\n - clueless\r\n - lazy\r\n - adventurous\r\n - aggressive\r\n required:\r\n - pet_type\r\n - huntingSkill\r\n Dog:\r\n description: A representation of a dog\r\n type: object\r\n properties:\r\n pet_type:\r\n type: string\r\n description: The type of the Pet.\r\n packSize:\r\n type: integer\r\n format: int32\r\n description: the size of the pack the dog is from\r\n default: 0\r\n minimum: 0\r\n required:\r\n - pet_type\r\n - packSize\r\n Lizard:\r\n description: A representation of a lizard\r\n type: object\r\n properties:\r\n pet_type:\r\n type: string\r\n description: The type of the Pet.\r\n lovesRocks:\r\n type: boolean\r\n required:\r\n - pet_type\r\n Snake:\r\n description: A representation of a snake\r\n type: object\r\n properties:\r\n pet_type:\r\n type: string\r\n description: The type of the Pet.\r\n lovesRocks:\r\n type: boolean\r\n required:\r\n - pet_type\r\n```\r\nI had initially thought this was valid, but after some issues with code generation I wondered if it is not.\r\n\r\nLooking at the Specification on [Discriminator Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#discriminator-object) it says:\r\n\r\n> the payload MUST, by validation, match exactly one of the schemas described by Cat, Dog, or Lizard. In this case, a discriminator MAY act as a \"hint\" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema.\r\n\r\nIf I read this correctly, the \"MUST\" part says that the specification must be able to identify which schema a payload will map to using the field names and the presence of values alone, and the discriminator is an optional shortcut, but should be unnecessary.\r\n\r\nAnd so, this above setup may not be valid, because there is no unique fields between `Snake`/`Lizard` to identify which type it is, without inspecting the field value of `pet_type`.\r\n\r\n### Concrete Observations\r\n\r\nI was using some tooling for generation of these examples, so while I understand that the tooling is external to the specification, I will just give some details of what I observed. Feel free to ignore.\r\n\r\nUsing [Swagger Editor](https://editor.swagger.io/) showed no issues with the specification.\r\n\r\nAnd while using [OpenAPI Generator](https://openapi-generator.tech/) the specification again showed no warnings, and I saw:\r\n\r\n- For Java Generation\r\n - Successful generation by default, using the discriminator field to switch between types which are the same.\r\n- For C# Generation\r\n - Unsuccessful generation by default, but this might be overcome by using the option `useOneOfDiscriminatorLookup` (default false).\r\n\r\nBut, obviously these can be ignored as implementation specifics.\r\n\r\n### Question\r\nIs it valid to have multiple schemas under a OneOf which fields are the same? And if not is there another recommended way to do this?\r\nI would like to model this the \"right\" way, and clear up any misunderstandings I may have.\r\nEven if I can get all the generation working with extra options, it would be good to ensure we follow the schema correctly.\r\n\r\n### My thoughts currently\r\nI was especially considering how OneOf can handle schema evolution.\r\nThe above example only returns the needed information currently (under a reliable type with a discriminator that a consumer can rely on; SNAKE/LIZARD). And by having the ability to have these schemas the same for the moment, I can later decide to add new fields (like `hasRattle` to Snake) and these types can begin to deviate, in a non-breaking way (because I wouldn't need to change the value of `pet_type`).\r\nWhile if the schemas need to be unique based on Field Presence alone, then it could be hard to avoid breaking changes while using OneOf.\r\n\r\nIf this is a valid pattern according to OAS, that is good, and I can continue to use the generator with the understanding that it should be supported.\r\n\r\nIf it is invalid, it feels like this will rule out the use of `oneOf`. And that the next best thing would be combining all these types simply into `PetType` with many optional fields. It would be less descriptive, but would in the end return the same information.\r\n\r\nThanks for any thoughts/advice.", "created_at": "2024-02-24T13:09:10Z", "updated_at": "2024-07-15T21:31:35Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Ag19J", "body": "Hey @davidjlynn , oneOfs are incredibly hard to understand. It's more about the a validation rule for a json instance than it is about a polymorphic \"type system\".\n\nI wrote a blog to help folks sort this out https://medium.com/@smikulcik/oneof-explained-c0264c429735\n\nBut yeah. If you have two identical oneOf options. No JSON instance that validates against either of those options can validate against the oneOf object." }, "user": { "login": "davidjlynn", "avatar_url": "https://avatars.githubusercontent.com/u/4130622?u=36c5c4fe649b55b192b6281a03de041f1c20c28a&v=4" } }, { "id": "D_kwDOAQkWPc4AP1W2", "number": 2946, "title": "How to document a fully dynamic API ?", "body": "Hello,\r\n\r\nI'm writing a platform that allows user to build their API. Some endpoints are \"statics\", most of them are really dynamic and we can't know in advance what one endpoint looks like, how it behaves. Requests, validations, responses quite likely depend on what the users set up.\r\n\r\nAny suggestions, documentation, maybe third parties that make it work this way ?\r\n\r\nThanks\r\n", "created_at": "2022-06-16T14:16:32Z", "updated_at": "2024-06-14T16:59:47Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "moweerkat", "avatar_url": "https://avatars.githubusercontent.com/u/98748817?v=4" } }, { "id": "D_kwDOAQkWPc4AaA00", "number": 3910, "title": "Can we have examples reference other examples, this would cut down file size and support reusability.", "body": "See https://github.com/OAI/OpenAPI-Specification/discussions/3902#discussioncomment-9767663\r\n\r\nThere doesn't seem to be any way around this apart from the work around suggested in the response.\r\nWould be good if this was supported in the spec.", "created_at": "2024-06-14T07:34:09Z", "updated_at": "2024-06-14T16:02:03Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "mcrobbj", "avatar_url": "https://avatars.githubusercontent.com/u/10534160?v=4" } }, { "id": "D_kwDOAQkWPc4AZ1o7", "number": 3874, "title": "Examples using HTTP messages, preferably at the Operation Object", "body": "Something I've been pondering recently is how to provide an example of an api request in a format similar to how one might find it out in the wild while playing with an api client or cURL. Particularly, because we don't have a great way to define header values and their parameters, it's very difficult to deliver a message to a developer for how a request should be composed. related: https://github.com/OAI/OpenAPI-Specification/discussions/3827\r\n\r\n\r\nI suppose you could just use an `externalValue` to a file in `.http` or `.md` to represent that. But, considering most doc UI's will not parse an `externalValue` for view, can we find a better way to represent that? The other reason is the `externalValue` keyword is only available at `requestBody` XOR `responseBody`, I want to represent the full example. \r\n\r\nThis could possibly be something for the Arazzo Specification to consider. @frankkilcommins \r\n\r\nThe glaring omission is an `Examples` object at the `PathItem Object` to bring together both the request and response bodies. \r\n\r\nThis is a sample of what I would like to document. \r\n\r\n```bash\r\nPOST /thing HTTP/1.1\r\naccept: application/json; charset=utf8; q=0.9, text/plain; charset=utf8; q=0.8\r\nauthorization Bearer XXX\r\ncontent-type: application/json; charset=utf8\r\ncontent-length: 50\r\nx-custom-header: thing; some_param=some_value\r\nprefer: respond-async; wait=10\r\n\r\n{ ... }\r\n---\r\n202 Accepted HTTP/1.1\r\ncontent-type: application/json; charset=utf8\r\ncontent-length: 500\r\nlink: ; rel=\"/status-monitor\"\r\n\r\n{ ... }\r\n```\r\n", "created_at": "2024-06-03T20:24:04Z", "updated_at": "2025-07-22T17:49:00Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "jeremyfiel", "avatar_url": "https://avatars.githubusercontent.com/u/32110157?u=d826152c23fccb7f43f4ccfa2cda785ba8c79df0&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzkzMzYw", "number": 2600, "title": "Webhook Path parameters", "body": "Can we use Webhook Path parameters and how do we define where in path are the parameters?\r\nFor example is code bellow is allowed: \r\nand the \"receiver\" should implement path for webhook\r\nmessaging/{param1}/{param2}/{param3}/response\r\n\r\n```\r\n \"webhooks\": {\r\n \"messaging/{param1}/{param2}/{param3}/response\": {\r\n \"post\": {\r\n \"parameters\": [\r\n { \"name\": \"param1\",\r\n \"in\": \"path\",\r\n \"required\": \"true\"\r\n },\r\n { \"name\": \"param2\",\r\n \"in\": \"path\",\r\n \"required\": \"true\"\r\n } ,\r\n { \"name\": \"param3\",\r\n \"in\": \"path\",\r\n \"required\": \"true\"\r\n }\r\n ....\r\n```\r\n\r\n", "created_at": "2021-06-02T13:45:51Z", "updated_at": "2024-05-14T15:24:54Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "jrihtarsic", "avatar_url": "https://avatars.githubusercontent.com/u/10476027?u=3c70efd46e7c4eb0a2b1cd11285b87e6a7e33376&v=4" } }, { "id": "D_kwDOAQkWPc4AZLwt", "number": 3778, "title": "Is required keyword reserved for requests only?", "body": "Hi,\r\n\r\nwe have been using required keyword both for request and response objects. Our idea was to show which fields in the response that will always be there, and which might be there. \r\n\r\nNow there is debate if that is correct, as some say required keyword should only be used for requests.\r\n\r\nso for starters, is that correct, that it shouldn’t be used for responses? \r\n\r\nIf so, how should fields that will always be in response and those that might be there be differentiated?\r\n\r\nalso, if anyone could post some links to some info about the subject that would be great. \r\n\r\ncheers! ", "created_at": "2024-05-03T16:49:38Z", "updated_at": "2024-05-05T01:39:01Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AjgqE", "body": "Yes, you would put `phone_number` (or however you spell the field) in the schema's `required` keyword, but leave the `work_number` field out. Which is exactly what you would do for requests. The Schema Object doesn't \"know\" whether it's a request or response or parameter or header or whatever - it's just a structural description." }, "user": { "login": "Zahak", "avatar_url": "https://avatars.githubusercontent.com/u/764398?v=4" } }, { "id": "D_kwDOAQkWPc4AOC_d", "number": 2789, "title": "Encoding of request bodies as x-www-form-urlencoded, and handling of arrays/explode", "body": "Hi,\r\nA, hopefully, straightforward question on the correct interpretation of the OpenAPI spec.\r\n\r\nRegarding the ```x-www-form-urlencoded``` encoding of request bodies, such as this example:\r\n\r\n```\r\n requestBody:\r\n content:\r\n application/x-www-form-urlencoded:\r\n schema:\r\n type: object\r\n properties:\r\n foo:\r\n type: array\r\n items:\r\n type: object\r\n properties:\r\n a:\r\n type: integer\r\n b:\r\n type: integer\r\n```\r\n\r\nHow is the ```foo``` array supposed to be encoded in the request body? As an exploded array?, such as:\r\n\r\n```\r\nfoo={\"a\":1,\"b\":2}&foo={\"a\":3,\"b\":4}\r\n```\r\n\r\nor not exploded? such as:\r\n\r\n```\r\nfoo={\"a\":1,\"b\":2},{\"a\":3,\"b\":4}\r\n```\r\n\r\nI'm aware that the explode behavior can be explicitly indicated by adding an ```encoding``` section with ```style: form``` and ```explode: true/false```, but I cannot find in the OpenAPI spec a clear indication of what is the expected behavior **when the encoding section is NOT provided**.\r\n\r\nOut of curiosity, I have tried with Swagger UI and it follows the non-exploded approach (2nd example), but please note that this is not a question about Swagger UI or any other tool. I'm interested in the correct interpretation of the OpenAPI spec.\r\n\r\nThanks in advance!\r\n", "created_at": "2021-11-12T11:28:01Z", "updated_at": "2024-05-01T17:52:39Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "jdegre", "avatar_url": "https://avatars.githubusercontent.com/u/31138976?u=a7d528eadbd6399971e64002ffa96ffa3555e561&v=4" } }, { "id": "D_kwDOAQkWPc4ANoUJ", "number": 2713, "title": "Working to Bring More Women and People of Color Into the API Specification Conversation", "body": "I wanted to start a conversation around the troubling fact that there are too few women and people of color involved at all levels of this community. AsyncAPI’s Senior Technical Writer Alejandra Quetzall brought it up in the SIG call today, but it is something that continues to get brought up, yet continues to be a problem for us—that the API specification conversation is largely dominated by white men. I know that many of us dread having this conversation, but trust me, it is no fun being the person to bring it up (or be affected by it), and I’d rather do the work than require women and people of color to keep doing the hard work here. So I wanted to kick off this conversation around what we can do to address this issue—I am looking for discussion around two things:\r\n\r\n- What obstacles currently keep women from participating in conversations within this community?\r\n- What can we do to attract more women to these communities and empower them to participate?\r\n\r\nIf you aren’t comfortable having this discussion here on the forum, ~~feel free to email your ideas at kinlane@gmail.com~~ _[**EDIT:** Please reach out to a [TSC member](https://github.com/OAI/OpenAPI-Specification/blob/main/MAINTAINERS.md) directly such as through DM on Slack]_, but I would prefer that we have this conversation out in the open, no matter how uncomfortable it makes us. I’d also like to make sure we keep this conversation friendly, inclusive, and supportive, but also make sure it is an honest and straightforward one. I look forward to hear your ideas and thoughts, and if you are someone from any of the underrepresented communities that are regularly absent from technology and the world of APIs, feel free to ping me directly for help learning about how you can get more involved.", "created_at": "2021-09-14T19:52:55Z", "updated_at": "2024-09-03T13:25:57Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "kinlane", "avatar_url": "https://avatars.githubusercontent.com/u/56100?u=34aa84ce72e1d75a7eb7c6852b23638d1c4a98c0&v=4" } }, { "id": "D_kwDOAQkWPc4AN3jO", "number": 2751, "title": "Nested form data", "body": "In `multipart/form-data` requests each field has it's own `content-type`.\r\nSo (I think) you can have nested `multipart/form-data` fields, or at least `multipart/form-data` -> `multipart x-www-form-urlencoded`.\r\nDoes the spec support this sort of request body?\r\n\r\nThanks!", "created_at": "2021-10-19T04:14:57Z", "updated_at": "2024-04-23T01:11:47Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "adriangb", "avatar_url": "https://avatars.githubusercontent.com/u/1755071?u=612704256e38d6ac9cbed24f10e4b6ac2da74ecb&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTY0NjI5", "number": 2707, "title": "how to define json-lines response?", "body": "Is there a way to describe a [json-lines](https://jsonlines.org/) with OpenAPI?\r\n\r\nBesides the fact that there seems to be no mimetype for it yet, I'm wondering if it's possible to describe such a response.\r\n\r\nIn theory my response could be an array of objects, but I received the question whether or not I could deliver as json-lines, meaning: Just the objects, one per line.\r\n\r\nSince I'm using OpenAPI to describe my API I'm puzzled as how to describe this response. I could simply define the response as being of type \"string\", but this is not very helpful for readers of my Api-spec.\r\n\r\nP.S. I already asked at [stackoverflow](https://stackoverflow.com/questions/69123769/openapi-how-to-define-json-lines-response) and was pointed to here.", "created_at": "2021-09-10T04:52:58Z", "updated_at": "2024-04-20T23:06:27Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Ai-_J", "body": "Not automatically. There would need to be a mapping defined to the JSON lines media type, and tools would need to support it. There's no reason you _can't_ just treat it as an array of objects and just document that it's a series of lines rather than a JSON array, but that would only work for human-readable documentation.\r\n\r\nIt's not clear to me what advantage JSON Lines has over [RFC 7464 JSON Text Sequences](https://www.rfc-editor.org/rfc/rfc7464.html)." }, "user": { "login": "Skeeve", "avatar_url": "https://avatars.githubusercontent.com/u/725404?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTUyNjkw", "number": 2693, "title": "How should we determine the prioritization of work?", "body": "## Problem statement\r\n\r\nThe community don't have a clear understanding of how to communicate what is important to them in a way that we can easily aggregate that information.\r\nThe TSC has no defined way to determine what to work on next.\r\n\r\n## Questions\r\nCan we use reactions counts to determine priority?\r\nHow do we guide people to put reactions in the right place?\r\n\r\nOptions for identifying work items that have been prioritized by the working group:\r\n- Milestones\r\n- Labels\r\n\r\nCan we provide a way for the community to add labels?\r\n\r\nIs the community desire for features aligned with tooling desire for features?\r\n\r\n## \r\nTSC need to determine a process and present something that is clear to the community. If you have suggestions, feel free to comment on this thread.\r\n", "created_at": "2021-09-02T16:58:12Z", "updated_at": "2024-04-19T21:28:20Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "darrelmiller", "avatar_url": "https://avatars.githubusercontent.com/u/447694?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTUyODQ4", "number": 2695, "title": "Special Interest Groups (SIGs)", "body": "Following the launch of OpenAPI version 3.1.0, there were so many interesting topics for the community to explore that we created specific Special Interest Groups (SIGs) to help move forward on specific topics. Early SIGs include:\r\n- Security\r\n- Workflows\r\n- Overlays\r\n- Codegen\r\n- Lifecycle\r\n- Travel\r\n\r\nThe groups are self-organizing now, establishing their meeting cadence and on-boarding processes, so it is a great time to get involved. One easy way is to join the OpenAPI Initiative Slack channel. If you aren’t already a member, please go to https://communityinviter.com/apps/open-api/openapi to get onboarded. Make sure to mention which SIG(s) you are interested in, and we look forward to having you as part of the discussion.", "created_at": "2021-09-02T18:43:52Z", "updated_at": "2024-04-19T21:23:26Z", "category": { "name": "Announcements", "emoji": ":mega:" }, "answer": null, "user": { "login": "earth2marsh", "avatar_url": "https://avatars.githubusercontent.com/u/54582?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzcxNDA3", "number": 2579, "title": "Is is possible to have multiple Operation Object for single callback event URL and can a single callback event have multiple URLs ? Does it make sense ?", "body": "Case1:\r\nCan a single callback event have multiple operations - ex POST, PUT, PATCH etc...\r\n\r\n![image](https://user-images.githubusercontent.com/34859630/118691459-baf7c480-b826-11eb-9798-519b6c63f7cb.png)\r\n\r\n\r\n\r\nCase2:\r\nCan a single callback event have multiple URLs as denoted below?\r\n\r\n![image](https://user-images.githubusercontent.com/34859630/118691252-8421ae80-b826-11eb-8733-c34aa120b94f.png)\r\n\r\n\r\nMy understanding is that an event should be causing callback request invocation, \r\nand usually a request is configured with a particular URL and a particular operation.\r\nSo looks one to one mapping between \r\nEvent ==> URL and\r\nURL ==> Operation\r\n\r\nBut is it possible\r\n\r\none to many for both below\r\nEvent ==> URL and\r\nURL ==> Operation\r\n\r\n\r\nThanks!", "created_at": "2021-05-18T16:47:15Z", "updated_at": "2024-04-19T21:21:33Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "mma5997", "avatar_url": "https://avatars.githubusercontent.com/u/34859630?u=64b17a11db4481c1c2fbe70d765aa651d14caa24&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTY5MjY2", "number": 2712, "title": "Meaning of the string keys in maps inside the Components object", "body": "Hi! I noticed that in the [componentsObject](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsObject) section of the spec each field is a `Map[string, Object]`. While debugging some code I realized that this key was used as the name of each parameter declared in `parameters`. The spec does not make clear what this string means. \r\n\r\nIts an identifier? how should be used? What takes precedence in naming a parameter, this string, or the field `name` inside the parameter object? what happens if both are present?\r\n\r\nA little explanation should be added to avoid confusion with key names and actual object names.\r\n\r\nThanks!", "created_at": "2021-09-13T15:48:12Z", "updated_at": "2024-04-19T21:09:14Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "arielmirra", "avatar_url": "https://avatars.githubusercontent.com/u/8195364?u=5042b22f4245ffac34ea0921791f2e73b977302e&v=4" } }, { "id": "D_kwDOAQkWPc4AOodQ", "number": 2866, "title": "Clarify response description", "body": "It is currently unclear whether the `paths...responses..description` field describes the status code or the response body and if it's the status code where to describe the response body and vice versa.\r\n\r\nFor example both of these seem to be reasonable definitions:\r\n\r\n```yaml\r\npaths:\r\n /foo:\r\n post:\r\n summary: Create a new foo\r\n responses:\r\n 202:\r\n description: The foo has been received and will be processed within one minute\r\n content:\r\n text/plain: {}\r\n```\r\n\r\n```yaml\r\npaths:\r\n /foo:\r\n post:\r\n summary: Create a new foo\r\n responses:\r\n 202:\r\n description: A job token to inquire about the status of the processing of the foo\r\n content:\r\n text/plain: {}\r\n```\r\n\r\nIn the OpenAPI Guide on swagger.io the [Describing Responses](https://swagger.io/docs/specification/describing-responses/) page uses `description` to describe the response body, **except** in the section \"HTTP Status Codes\" where it is used to give a reason for the status code. (Unless I'm missing something and those are actually different `description` fields.)", "created_at": "2022-01-25T04:06:39Z", "updated_at": "2024-04-19T21:08:07Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "AndreKR", "avatar_url": "https://avatars.githubusercontent.com/u/1188538?v=4" } }, { "id": "D_kwDOAQkWPc4AXcak", "number": 3532, "title": "Why doesn't the \"paths\" object support description/summary", "body": "This seems like an obvious gap to me, but I want to see what were the philosophical reasons for it. Perhaps because the webhooks object is newer, it just wasn't as obvious at first that the info object can be awkward? The issue is there may be very different global(esque) descriptive text for all the paths vs. all the webhooks.", "created_at": "2024-01-29T04:29:29Z", "updated_at": "2024-04-19T21:06:20Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "kentbulza", "avatar_url": "https://avatars.githubusercontent.com/u/41305590?v=4" } }, { "id": "D_kwDOAQkWPc4ANttK", "number": 2730, "title": "Support for custom formats as defined in the specification", "body": "The specification says about format as follows\r\n`format – OpenAPI has its own predefined formats and also allows custom formats.`\r\n\r\nBut how exactly a custom format can be used? I don't find any features in the tooling of OpenAPI to extend support for custom formats that we use in a spec.", "created_at": "2021-09-27T08:15:13Z", "updated_at": "2024-04-19T20:48:15Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AFTtF", "body": "That's more of a tooling question than a spec one. Glad to hear you have usage for such a feature though. My recommendation is to reach out to the maintainers of the tools you use and ask them to support it.\r\n\r\nAs a side note - we recently created a [Special Interest Group for Formats](https://github.com/OAI/sig-formats) where we'll be discussing how to create some sort of a format registry to help OpenAPI users." }, "user": { "login": "gayanper", "avatar_url": "https://avatars.githubusercontent.com/u/7471994?u=87f27a620347049abafbd3f8138cce4d27ccbac5&v=4" } }, { "id": "D_kwDOAQkWPc4AN9NJ", "number": 2774, "title": "Can I Specify a Flexible Properties of Any Type on a Schema?", "body": "Hi OpenAPI-Specification team,\r\nWe are on OpenAPI Specification 3.0.1. We have a highly customizable platform that allows users to create custom fields on a schema. For example, let's say we provide a schema called \"Order\" out of the box:\r\n```\r\nOrder:\r\n type: object\r\n properties:\r\n id:\r\n type: integer\r\n format: int64\r\n shipDate:\r\n type: string\r\n format: date-time\r\n status:\r\n type: string\r\n description: Order Status\r\n enum:\r\n - placed\r\n - approved\r\n - delivered\r\n complete:\r\n type: boolean\r\n default: false\r\n xml:\r\n name: Order\r\n```\r\n\r\nLet's say the customer retrieve an OpenAPI specification (OAS) that contains the above schema. They generate a client library using the OAS and can use it in code to populate the field value like following:\r\n```\r\norder.setShipDate(\"10/29/2021\");\r\n```\r\n\r\nNow let's say they add a new custom field call \"quantity\" to the order schema:\r\n```\r\nquantity:\r\n type: integer\r\n format: int32\r\n```\r\n**But they don't regenerate client library using the updated OAS.** , so they can't do `order.setQuantity(2);` in their code.\r\n\r\nIf possible, we would like to reduce the number of times that customers need to regenerate OAS and client library. We are thinking about defining a flexible field on the schema that can support any number of properties of any type. For example, something like\r\n```\r\nproperties:\r\n anyPropertyName:\r\n type: anyType\r\n```\r\nAnd by doing so, we hope to enable following capability in client code:\r\n```\r\norder.setShipDate(\"10/29/2021\"); // \"ShipDate\" is a property provided out of the box, so customers can directly do setShipDate\r\norder.setField(\"quantity\", 2); // \"quantity\" is a customer-defined field, not a property provided out of the box, so customers need to use setField(fieldName, fieldValue) to populate the object\r\norder.setField(\"shippingCity\", \"San Francisco\"); // \"shippingCity\" is a customer-defined field, not a property provided out of the box, so customers need to use setField(fieldName, fieldValue) to populate the object\r\n```\r\n\r\nSo, my question: Is there anything in OpenAPI specification 3.0.1 that allow us to specify a flexible property under schema that allow us to do object.setField(fieldName, fieldValue) ? \r\n\r\nThanks!", "created_at": "2021-10-29T21:51:17Z", "updated_at": "2024-04-19T20:47:44Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "jake-xie-sfdc", "avatar_url": "https://avatars.githubusercontent.com/u/42158334?v=4" } }, { "id": "D_kwDOAQkWPc4ASLf3", "number": 3141, "title": "Confusions about OpenAPI, AsyncAPI and Websockets for client SDK", "body": " I have been reading up on people asking about websocket proposals for OpenAPI, and I am confused on if OpenAPI or AsyncAPI can actually accomplish what I'm looking for. \r\n\r\nI have a client SDK I am trying to autogenerate via one of these API specifications, but our SDK uses both websockets and HTTP Rest calls. The SDK default uses websockets with callbacks to act as a request-response. If the socket connection is lost, then the SDK falls back to the REST calls. From what I understand OpenAPI doesn't support websockets, but AsyncAPI doesn't have as robust of HTTP Rest support or the variety of language client generators. \r\n\r\nCurious what people are doing in situations like this? I know I have seen a few people in issues with similar situations. My initial thought was to use OpenAPI specification and generators to make client SDKs then modify the generated files for socket support. Any help would be appreciated and sorry if my understanding of either specification is not accurate.", "created_at": "2023-01-17T17:44:32Z", "updated_at": "2024-04-19T20:32:41Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4ATYUI", "body": "You can write a specification in your own proprietary format and then convert it to both OpenAPI and AsyncAPI specifications using some script. It should be kinda trivial task since both specs are just large JSONs and they pretty similar. Just pick common things from both specs and then create your own specification format. You may also write your own JSON Schema and define it in `$schema` keyword which will be nice for IDE autocompletion, and for validation you too — with help of [Ajv JSON Schema validator](https://ajv.js.org) or something similar. It would be useful at least for documentation purposes (rendering a spec as HTML).\r\n\r\nYou can also create your own proprietary code generation solution. It's not that hard to implement a code generator (using AST-based generation, not templates which will break your brain!), especially if you are not setting a goal to cover 100% features available in JSON Schema and OpenAPI/AsyncAPI (there are no generators that support advanced features of all these specs). And it would be much easier to generate a code from your proprietary spec I mentioned in previous paragraph. All these specs weren't designed to provide first-class support for code generating use-cases, that's why it's mostly impossible to accomplish 100% feature coverage. That's how our team fulfilled our specific code generation needs — we just wrote our own generator using our proprietary spec format (which uses JSON Schema for describing data)." }, "user": { "login": "ChristianVaughn", "avatar_url": "https://avatars.githubusercontent.com/u/4643028?u=2c2fed37d3803fde2fc3a68241f7b2262bfd3616&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMjIwODE3", "number": 2460, "title": "OpenAPI in function docstring? - YAML verbatim vs JavaDoc", "body": "Writing bidirectional code-generators for a number of languages, that take the language and generate Swagger/OpenAPI, and take Swagger/OpenAPI and update—or insert—the target language.\r\n\r\nMy question is what to put in the docstring, for example this pseudocode route:\r\n```javascript\r\n/* */\r\nasync function create_user(request, response) {\r\n try {\r\n const created_user = await db.create(User, request.json);\r\n } catch (e: ValidationError | DatabaseError) {\r\n response.status = 400;\r\n return e.json();\r\n }\r\n response.status = 201;\r\n return created_user.json();\r\n}\r\n```\r\n\r\nWhat should the docstring say? - I've seen some approaches which just put YAML verbatim inside, like:\r\n```yaml\r\ndescription: user to add to the system\r\ncontent: \r\n 'application/json':\r\n schema:\r\n $ref: '#/components/schemas/User'\r\n examples:\r\n user:\r\n summary: User Example\r\n externalValue: 'http://foo.bar/examples/user-example.json'\r\n```\r\n\r\nBut that seems rather nonstandard for maintainers. They need to think about the OpenAPI specification rather than JavaDoc (or whatever docstring format their language recommends).\r\n\r\nIs there a compromise, a way of specifying inside the docstring? - Or would you suggest just to use your YAML?\r\n", "created_at": "2021-02-13T07:21:49Z", "updated_at": "2024-04-19T20:29:39Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "SamuelMarks", "avatar_url": "https://avatars.githubusercontent.com/u/807580?u=163debc9c32e7086f42128064501f6075a5c771e&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzkzMTg4", "number": 2599, "title": "Mime Part Headers for multipart/mixed payload when using arrays", "body": "I would like to add body content with multipart/mixed payload, like this\r\n```\r\n\"requestBody\": {\r\n \"content\": {\r\n \"multipart/mixed\": {\r\n \"schema\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"payloads\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"string\",\r\n \"format\": \"binary\"\r\n }\r\n }\r\n }\r\n }\r\n },\r\n```\r\n\r\nAnd I would also like define header \"**_Part-Signature-Header_**\" for each part in array\r\nso that request body looks like this \r\n\r\n```\r\n-----------------------------37993639233119846881484177537\r\nContent-Disposition: form-data; name=\"payloads\"; filename=\"text-example1.txt\"\r\nContent-Type: text/plain\r\nPart-Signature-Header: asdfsdf3223fsdfw...\r\n\r\nHello world text example 1. \r\n\r\n-----------------------------37993639233119846881484177537\r\nContent-Disposition: form-data; name=\"payloads\"; filename=\"text-example2.txt\"\r\nContent-Type: text/plain\r\nPart-Signature-Header: asdfsd3345343fsdfw...\r\n \r\nHello world text example2. \r\n\r\n-----------------------------37993639233119846881484177537--\r\n```\r\nIs the correct encoding for this \r\n```\r\n\"multipart/mixed\": {\r\n \"schema\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"**payloads**\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"string\",\r\n \"format\": \"binary\"\r\n }\r\n }\r\n }\r\n },\r\n \"encoding\": {\r\n \"**payloads**\": {\r\n \"headers\": {\r\n \"Part-Signature-Header\": {\r\n \"$ref\": \"#/components/headers/Part-Signature-Header\",\r\n \"required\": true,\r\n \"style\": \"simple\"\r\n }\r\n }\r\n }\r\n }\r\n },\r\n```\r\n\r\n\r\nor should i use asterix or some other char to mark that this header must be on every part of Multipart/mixed\r\nas example: \r\n```\r\n\"multipart/mixed\": {\r\n \"schema\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"payloads\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"string\",\r\n \"format\": \"binary\"\r\n }\r\n }\r\n }\r\n },\r\n \"encoding\": {\r\n \"*\": {\r\n \"headers\": {\r\n \"Part-Signature-Header\": {\r\n \"$ref\": \"#/components/headers/Part-Signature-Header\",\r\n \"required\": true,\r\n \"style\": \"simple\"\r\n }\r\n }\r\n }\r\n }\r\n },\r\n```\r\n", "created_at": "2021-06-02T11:52:11Z", "updated_at": "2024-04-19T20:28:15Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "jrihtarsic", "avatar_url": "https://avatars.githubusercontent.com/u/10476027?u=3c70efd46e7c4eb0a2b1cd11285b87e6a7e33376&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNDcwNTIz", "number": 2654, "title": "Parameters behavior", "body": "Hello!\r\nSpecification [says](https://github.com/OAI/OpenAPI-Specification/blob/d9ac75b00c8bf405c2c90cfa9f20370564371dec/versions/3.0.3.md#parameter-object) `A unique parameter is defined by a combination of a name and location.`\r\n\r\nIn [`PathItem`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-item-object) specification says `PathItem parameters can be overridden at the operation level, but cannot be removed there.`\r\n\r\nIn [`Operation`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object) specification says `If a parameter is already defined at the PathItem, the new definition will override it but can never remove it.`\r\n\r\nI defined following OpenAPI\r\n```yaml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: Parameters example\r\n version: 0.1.0\r\nservers:\r\n - url: 'https://127.0.0.1/api/rest'\r\npaths:\r\n '/foo/{bar}':\r\n post:\r\n parameters:\r\n - name: bar\r\n in: header\r\n schema:\r\n type: string\r\n requestBody:\r\n content:\r\n application/json:\r\n schema:\r\n type: string\r\n responses:\r\n '200':\r\n description: Example\r\n content:\r\n application/json:\r\n schema:\r\n type: string\r\n delete:\r\n responses:\r\n '200':\r\n description: OK\r\n parameters:\r\n - required: true\r\n name: bar\r\n in: path\r\n schema:\r\n type: string\r\n```\r\nI defined `foo` parameter in path at `PathItem` and I defined parameter with same name `foo`, in header at `Operation`. I expect two parameters in my post. But `swaggerhub` UI says that parameter `foo` is overriden in my post and I've got only in header `foo` parameter. How it should work?", "created_at": "2021-07-21T09:07:35Z", "updated_at": "2024-04-19T20:19:40Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "MDE3OkRpc2N1c3Npb25Db21tZW50MTAzMTYzMg==", "body": "Your API definition is correct - it's OK to have parameters with the same `name` as long as they have different location (i.e. path vs header).\r\n\r\nThe issue you're seeing is a bug in Swagger UI. Please submit a bug report here:\r\nhttps://github.com/swagger-api/swagger-ui/issues" }, "user": { "login": "mtovts", "avatar_url": "https://avatars.githubusercontent.com/u/38750524?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMjQ3MTky", "number": 2491, "title": "Using jsonschema version other than 2020-12 with 3.1.0", "body": "Hi, \r\nIs it possible to use jsonschema version other than `2020-12` with `3.1.0`.", "created_at": "2021-03-03T08:28:51Z", "updated_at": "2024-04-19T20:19:01Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "gk12277", "avatar_url": "https://avatars.githubusercontent.com/u/41449598?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzc0NDMx", "number": 2584, "title": "json validation String is not a URI: URI with a scheme is expected.", "body": "hello,\r\n\r\nI try to validate my oas 3.1.0 and I get a error on internal $ref values **String is not a URI: URI with a scheme is expected** \r\n\r\nI define like that \r\n```json\r\n\"400\":\t{\r\n \"$ref\":\t\"#/components/responses/rsp400\"\r\n}\r\n```\r\n\r\n/components/responses/rsp400 is correctly defined (jump to with editor works good)\r\n\r\nTo validate the json semantic, I use the \"$schema\": \"https://spec.openapis.org/oas/3.1/schema/2021-03-02\".\r\n\r\nwhere $ref is defined as a #/$def/uri and uri is format 'uri' which request a uri **scheme** \r\n```json\r\n \"uri\": {\r\n \"type\": \"string\",\r\n \"format\": \"uri\"\r\n }\r\n```\r\n\r\nwhat to do to solve the error ?\r\nthanks\r\n", "created_at": "2021-05-20T13:16:57Z", "updated_at": "2024-04-19T20:17:54Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "MDE3OkRpc2N1c3Npb25Db21tZW50NzY0NDM1", "body": "The format should be `uri-reference`, not `uri`. I'll make a PR to fix it.\r\n\r\nHowever, `format` should be annotation-only and not cause validation failures." }, "user": { "login": "manufv", "avatar_url": "https://avatars.githubusercontent.com/u/4491759?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24xNzAzMTk4", "number": 2439, "title": "Why does the JSON schema for 3.0 specify patternProperties for component names but allows additional properties?", "body": "I've been working on some functionality that uses the JSON schema to help validate OpenAPI schemas, and recently noticed that the 3.0 schema allows any value for `{name}` in `/components/{component}/{name}`, while the [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-6) states that \"All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\\.\\-_]+$.`\" It seems like this could have been validated automatically by simply adding `additionalProperties: false` to the JSON schema.\r\n\r\nMy question is: Was not including `additionalProperties: false` in the JSON schema for 3.0 just an accidental omission, or was there some rationale behind not doing it?\r\n\r\nThanks for clarifying!", "created_at": "2021-01-11T15:43:07Z", "updated_at": "2024-08-08T13:43:41Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Ai-7b", "body": "Migrated to issue #3720 as there's a clear potential action. Closing this discussion in favor of the issue." }, "user": { "login": "ryankinderman", "avatar_url": "https://avatars.githubusercontent.com/u/7658?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzAzMjM3", "number": 2518, "title": "What is the relationship between OAS extensions and overlays?", "body": "As TSC is jumpstarting the overlay conversation again, I'd like to hear the communities thoughts about the relationship between OAS extensions and overlays. I have my own view of this, and have learned from others in the community about some of the top overlay use cases might, and think more about how the current OAS extension world might influence or inform the overlay conversation. \r\n\r\nAfter looking through the [extension of 16 different API service providers](https://github.com/api-specification-toolbox/toolbox/labels/new-extensions) I identified the following ways in which folks are extending the spec:\r\n\r\n- Documentation - Expanding on the spec for publishing documentation.\r\n- Examples - Enriching the examples for each API for use across the API lifecycle.\r\n- Parameters - Providing more details about each of the path, header, or question parameters.\r\n- Parameter Groups - Helping group parameters to help make them more organized.\r\n- Defaults - Offering up a set of default values for different layers of an OpenAPI.\r\n- Enumerators - Adding more information about enumeration for properties and parameters.\r\n- Versioning - Allowing there to be more details about the versioning of each API or schema.\r\n- Role Based Access Control (RBAC) - Adding a layer for RBAC across an API and their surface area.\r\n- TLS - Providing details about the transport level security being applied to each API.\r\n- Compression - Outlining the type of compression that is available as part of each API.\r\n- Validation - Describing the validation that occurs when an API is consumed or tested.\r\n- Authentication - Expanding on the overall authentication and access management.\r\n- Basic Auth - Providing more detail about Basic Auth that OpenAPI doesn’t provide.\r\n- API Key - Providing more detail about an API key that OpenAPI doesn’t provide.\r\n- OAuth - Providing more detail about oAuth that OpenAPI doesn’t provide.\r\n- JWT - Providing more detail about JWT that OpenAPI doesn’t provide.\r\n- Environments - Adding additional details about development, production or other environment.\r\n- Management - Defining the management layer that is in place for each API.\r\n- Policy - Allowing policies to be applied to each API being defined by OpenAPI\r\n- Rate Limit - Defining what levels of consumption are available for each API\r\n- Throttling Tier - Further defining the overall access or throttling tiers available.\r\n- Configuration - Providing configuration for how an API should be operating.\r\n- Gateway Request - Additional information regarding the request surface of an API.\r\n- Gateway Response - Additional information regarding the response surface of an API.\r\n- Integrations - Detailed information about the integration with another API behind an API.\r\n- Backend - Further details about backend integrations and connections behind each API.\r\n- Dependencies - Machine readability details about all of the dependencies an API has.\r\n- Languages - Machine readable information about the language available for an API.\r\n- CORS - Details about how cross origin resource sharing is addressed for an API.\r\n- Code Samples - Providing samples or snippets for all available API paths.\r\n- Client Code Generation - Information regarding what client side code generation.\r\n- Server Code Generation - Information regarding what server side code generation.\r\n- Requests Scripts - Defining scripts that are executed with each API request made.\r\n- Responses Scripts - Defining scripts that are executed after each API response.\r\n- Translation - Details about what translation occurs as part of each API request or response. \r\n- Filtering - Information regarding what filtering is available or applied to each API request or response.\r\n- Aliases - Providing details regarding aliases for different elements of each API.\r\n- Pagination - Offering more structure regarding the pagination of API resources.\r\n- Triggers - Defining what triggers are available or executed as part of API operations.\r\n- Notifications - Outlining available notifications that are made when an API is executed.\r\n- URL Encoding - Providing more details about how a URL is encoded as part of each API resource.\r\n- Data Store - Associating a data store with each API being defined as an OpenAPI.\r\n- Caching - Adding information regarding how each API is being cached as part of operations.\r\n- Security - Further expanding on how security is handled when it comes to each API operations. \r\n- Import - Providing additional information that needs to be considered or applied upon OpenAPI import.\r\n- Export - Providing additional information that needs to be considered or applied upon OpenAPI export.\r\n- Audiences - Offering more detail about the audience an API is intended for as part of each OpenAPI.\r\n- Capabilities - Having a machine readable defining of what each API is capable of doing.\r\n- Traits - Further outlining the traits of each of the APIs, helping further flesh out what each one does.\r\n- Tags - Adding more rich detail beyond the base tagging provided by OpenAPI.\r\n- Tag Groups - Helping group tags, adding another layer of organization to each API.\r\n\r\nI am just curious to more clearly define what use cases are best addressed through extensions, and which might be better suited for overlays. Then work to define a whole catalog of use cases to help drive the overlays conversation.", "created_at": "2021-04-01T23:12:15Z", "updated_at": "2024-04-19T20:07:08Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "kinlane", "avatar_url": "https://avatars.githubusercontent.com/u/56100?u=34aa84ce72e1d75a7eb7c6852b23638d1c4a98c0&v=4" } }, { "id": "D_kwDOAQkWPc4AOKGY", "number": 2807, "title": "Clarify how to handle default value on non-nullable optional properties when \"default\" keyword is not specified", "body": "Related https://github.com/OpenAPITools/openapi-generator/issues/10972\r\n\r\nSpec version: 3.0.3\r\nthe spec doesn't indicate how to handle model properties in the following case:\r\n```yaml\r\nrequired: false\r\nnullable: false\r\ntype: xxxxx\r\n```\r\n- `required: false` means that the property might not exist in the json\r\n- `nullable: false` means that the property doesn't accept null as a value\r\n\r\nso what to do when the spec document doesn't specify the `default` keyword ?\r\n\r\n1. assume default is null (works only for properties where `nullable: true`, [otherwise it will break the spec](https://swagger.io/specification/#:~:text=default%20%2D%20The%20default,cannot%20be%201.))\r\n\r\n2. assume default to be of same type as type, so for non-nullable types that would be\r\n \"boolean\" => false\r\n \"object\" => { }\r\n \"array\" => [ ]\r\n \"number\"/\"integer\" => 0\r\n \"string\" => \"\"\r\n\r\n3. make it required to specify the `default` keyword when `required: false` and `nullable: false`\r\n4. ignore the provided `required: false` and assume instead `required: true`\n5. ignore the provided `nullable: false` and assume `nullable: true`\n", "created_at": "2021-11-29T04:53:04Z", "updated_at": "2024-04-19T20:04:44Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "ahmednfwela", "avatar_url": "https://avatars.githubusercontent.com/u/63286031?v=4" } }, { "id": "D_kwDOAQkWPc4AONLr", "number": 2817, "title": "\"Domain Data Liberation\" - Enhancements needed?", "body": "Hi everyone,\r\n\r\nWe are working on \"Domain Data Liberation\" these days. Most of our core domains (that handles business processes) are wrapped in REST API's, but we do not support event driven and analytical patterns well enough (nor file transfer for that matter). I will start with the questions, and then explain the background for those that are interested:\r\n\r\n1. Query interface specification: Are there plans to crate a specifications similar to OpenAPI and AsyncAPI for typical \"query interfaces\"? By that I mean SQL (query databases and files), GraphQL (query graphs), SPARQL (query RDF graphs), MDX (OLAP cubes), LDAP (Active Directory) etc. I have found SwaggerQL that is \"sort of\" OpenAPI for SQL, but it is not maintained, and it is also lacking a lot of features that OpenAPI of today has: https://github.com/swaggerql/swaggerql\r\n2. File transfer / storage interface specification: Like the previous question, just for file transfer and files. Thinking of SFTP, NFS, OneDrive and any other storage / transfer mechanism for files. If we had a specification that describes the interface and the schema for file stores, that would be neat. I have found no such specifications.\r\n3. AsyncAPI links: You recently added this to OpenAPI. To give an example, the accountOwnerId in our (bank) accounts schema can now be linked to the customerId in our customer schema using this. Will this concept also be transferred to AsyncAPI? (so we can link events to each other the same way) Alternatively, should this be part of the JSON Schema instead of / in addition to?\r\n4. Primary key, foreign key and business key(s) in OpenAPI / JSON Schema: While path parameter and similar can be said to the the primary key you need to \"get a specific account\", for customer this is typically a generated UUID. What we would like is the ability to specify the \"primary key\" attribute (say, customerId), the foreign key attributes (say, homeAddressId is a foreign key pointer to the address schema) and the business key(s) attributes (say, the uniqueness behind the generated customerId is actually a combination of customerType, publicId and customerCountry). This unmaintained JSON Table Schema has the primary key and foreign key concepts at least: http://dataprotocols.org/json-table-schema/#primary-key\r\n\r\n**Background**\r\nThe idea is to do \"Domain Data Liberation\" as follows:\r\n\r\n- REST API's are the main interfaces for our core domains. We document the interfaces with OpenAPI and the data with JSON Schema. These will be the basis for interface documentation and schema definition for our 3 other integration patterns (message / event interfaces, query interfaces and file interfaces).\r\n- Whenever domain data change (POST, PUT, DELETE), an event containing the JSON Schema is sent to our EventHub (Kafka). We document the interfaces with AsyncAPI (generated from the OpenAPI) and the same JSON Schema (likely wrapped with CloudEvents to add some required attributes for describing source, id etc.).\r\n- Events can then be landed in data stores fit for operational query patterns (GraphQL for instance) to support Command Query Responsibility Segregation (CQRS). The GraphQL graph would then be generated based on the OpenAPI and JSON Schema. Need something similar to OpenAPI to describe query interfaces (see question 1 at the top).\r\n- Events can also be landed in data stores fit for analytical query patterns (Data Lake, Cloud Data Warehouse etc.). The table schema would then be created based on the JSON Schema. Need something similar to OpenAPI to describe query interfaces (see question 1 at the top).\r\n- Events can also be landed in files stores for archiving and transfers. Need something similar to OpenAPI to describe file interfaces (see question 2 at the top).\r\n\r\nThe concept above should enable us to do polyglot data modelling (model once, reuse across multiple interfaces / data stores) and enable us to generate interface documentation for the 3 other integration styles based on the initial OpenAPI documentation.\r\n\r\nSo, to summarize, we would have the following:\r\n\r\n- Domain data interfaces are described with similar open specifications (OpenAPI, AsyncAPI, , .\r\n- Domain data is documented and modeled once (JSON Schema) and reused across all 4 integration styles and various data stores. We do a lot of double work with domain data to support operational and analytical workloads today.\r\n- Interfaces documentation can be imported into one or more catalogs to enable humans to discover them (search, browse etc.) and machines to find each other (service discovery).\r\n\r\nI will split this up later based on initial feedback, and probably take some of it other places, but thought I would start in the OpenAPI community since OpenAPI will be our \"master\" in the setup suggested above.\r\n\r\nRegards,\r\nOlav", "created_at": "2021-12-05T15:40:01Z", "updated_at": "2024-04-19T20:01:45Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "iolalog", "avatar_url": "https://avatars.githubusercontent.com/u/26845866?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMjgwMTk1", "number": 2504, "title": "Looking for a community driven GH home for unofficial OpenAPI projects", "body": "I'm looking for a home for an OpenAPI project that has many users, stars, and GH forks but has not seen active maintainership recently and has no system of governance.\r\n\r\nWhile the OAS spec advances, many tools that users have come to depend on are left in less than ideal states. There may be competing interests for each of these projects to adapt to the latest standards or continue to support their implementation discrepancies. The user and developer community behind these projects should have some say in this and largely do. Each of these projects takes on or shirks responsibility whenever OAS changes are introduced. A common body of similarly concerned projects could benefit from each other based on similar languages, users, developers, or ideas.\r\n\r\nIt is understandable that the OAI organization does not want to show favoritism to any single implementation and should want to avoid the situation where an implementation discrepancy with the spec becomes authoritative.\r\n\r\nMany of the OAS tools available today are associated with commercial organizations:\r\n\r\n* https://github.com/swagger-api (SmartBear)\r\n* https://github.com/mermade\r\n\r\nAre these or similar organizations open to adopting existing projects? Would they be able to provide a fair community view that fosters project independence, growth, and health?\r\n\r\nSome community-run GH orgs actively maintain community projects or registries:\r\n * https://github.com/openapitools\r\n * https://github.com/openapi-contrib\r\n * https://github.com/apisyouwonthate\r\n * https://github.com/APIs-guru\r\n\r\nThese orgs may not be open to adopting competing projects or engineering heavy projects.\r\n\r\n1\\. Does @OAI have recommendations for projects looking for community governance and maintainership?\r\n\r\n2\\. Does @OAI have recommendations for community-led initiatives to provide this function?\r\n\r\n---\r\n\r\nAuthors that have expressed interest in having their tools moved to a central org:\r\n\r\n* @fotinakis (https://github.com/fotinakis/swagger-blocks)\r\n* @dorthu (https://github.com/Dorthu/openapi3)\r\n\r\nOrgs that have expressed interest in hosting disparate projects and hosting community and governance:\r\n\r\n* https://github.com/openapi (@sergeysova)\r\n", "created_at": "2021-03-18T16:52:19Z", "updated_at": "2024-04-19T19:51:47Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "displague", "avatar_url": "https://avatars.githubusercontent.com/u/317653?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMjgxMDY4", "number": 2505, "title": "Does OAS3 callbacks also relate about the Service implementation part, because if at all this callback endpoint might be a part of different Swagger as well ?", "body": "Hi folks,\r\nSo my query is, lets say I have OAS3 based Swagger101.json that has a subscription endpoint operation which is configured with a callbacks operation for callbacks URL.\r\n\r\nSo apart from invocation of callback, does the callbacks definition for this mean that the callbacks URL belongs to some other Service Swagger spec or basically another Swagger JSON. There might be a possibility that this callbacks endpoint operation might be part of whole different Swagger spec that has a lot of operations and endpoints to offer.\r\n\r\nDoes this make sense ?\r\n\r\nHi @webron , @hkosova ,\r\nany views over this will be much appreciated Thanks :)", "created_at": "2021-03-19T04:25:03Z", "updated_at": "2024-04-19T19:46:41Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "mma5997", "avatar_url": "https://avatars.githubusercontent.com/u/34859630?u=64b17a11db4481c1c2fbe70d765aa651d14caa24&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzM5MDQ0", "number": 2556, "title": "JMESPath and JSONPath", "body": "[MIGRATING THIS CONVERSATION TO OFFICIAL OVERLAYS REPO](https://github.com/OAI/Overlay-Specification/discussions/2)\r\nI wanted to showcase the conversation and thinking that has already occurred around the usage of JSONPath and / or JMESPath as part of the overlays specification. I will pull highlights from the TDC conversation a couple weeks back, but if anyone wanted to share why we are consider one over the other, as well as possibly allowing for both i have several API providers and API service providers interested in learning from the conversation. Thanks everyone for helping me grow the discussion here. \r\n\r\nJMESPath: https://jmespath.org/\r\nJSONPath: https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html", "created_at": "2021-04-26T19:55:43Z", "updated_at": "2024-04-19T19:46:10Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "kinlane", "avatar_url": "https://avatars.githubusercontent.com/u/56100?u=34aa84ce72e1d75a7eb7c6852b23638d1c4a98c0&v=4" } }, { "id": "D_kwDOAQkWPc4AOMtn", "number": 2815, "title": "How to refer response header in client generate api", "body": "I have defined the swagger in order to get the authorization token from the response header which can be used for next api call. However when I generate the client code out of swagger, it return only response body and not the header. I Have tried all the search but nothing was helpful. \r\n\r\n**Part of the swagger definition,**\r\n\r\n```yaml\r\n/token':\r\n post:\r\n tags:\r\n - Token\r\n parameters:\r\n - $ref: '#/components/parameters/Authorization'\r\n description: Used to generate token to call other api \r\n operationId: generateToken\r\nresponses:\r\n '200':\r\n description: OK\r\n content:\r\n Application/Json:\r\n schema:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/XYZ'\r\n headers:\r\n authorization:\r\n schema:\r\n type: string\r\n\r\ncomponents:\r\n parameters:\r\n Authorization:\r\n in: header\r\n name: Authorization\r\n description: Bearer token to access the one view API's.\r\n schema:\r\n type: string\r\n required: true\r\n```\r\n \r\n**Client Api generate:** ( the method body doesnt have any code for response header\"\r\n```java\r\npublic CompletableFuture> generateToken (String authorization) throws ApiException {\r\n....\r\n...}\r\n```\r\nIf you could provide any insight that would be more helpfull", "created_at": "2021-12-03T22:54:25Z", "updated_at": "2024-04-19T19:45:39Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Radha-rog", "avatar_url": "https://avatars.githubusercontent.com/u/77983380?v=4" } }, { "id": "D_kwDOAQkWPc4AYSam", "number": 3630, "title": "Where should openIdConnectUrl point to?", "body": "I'm trying to use the `openIdConnect` security scheme as defined in OpenAPI 3.1 and I think `openIdConnectUrl` is lacking some information.\r\n\r\nWhat is expected to be provided for `openIdConnectUrl`?\r\n- The issuer URL, e.g. https://openapi.example (so tooling would append need to append `/.well-known/openid-configuration`)\r\n- The well-known document directly, e.g. https://openapi.example/.well-known/openid-configuration\r\n\r\nOnce answered, happy to create a PR to clarify this.\r\n", "created_at": "2024-03-13T10:06:09Z", "updated_at": "2024-04-19T19:18:21Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AhwmB", "body": "Of your two examples it should be the latter i.e. the URL is expected to point to the discovery document for a given OpenID Provider. \r\n\r\n[This section](https://spec.openapis.org/oas/v3.1.0#security-scheme-object) of the OpenAPI specification points to the [OpenID Discovery specification](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06), hence it should be the discovery document not the issuer URL. \r\n\r\nLooking at the wording of the OpenAPI specification it could indeed be more explicit (in my opinion) although it does say:\r\n\r\n> OpenId Connect URL to discover OAuth2 configuration values\r\n\r\nSo there is some reference to discovery in there." }, "user": { "login": "m-mohr", "avatar_url": "https://avatars.githubusercontent.com/u/8262166?u=203eb9ae80303607f8adf8ff2b988433f85d64a8&v=4" } }, { "id": "D_kwDOAQkWPc4ANw8i", "number": 2739, "title": "Resolution rules of following OAS documents", "body": "Hello all,\r\n\r\nI was wondering if authors of the spec could help me verify the resolution behavior of following use-cases. `foo` and `bar` are pointing to future values of `SharedResponse` schema. I'm interested if this is correct or incorrect usage of the spec.\r\n\r\nIn OAS 3.0.0 JSON Reference spec is used to resolve the values. JSON Reference delegates the identifier fragment resolution to JSON Pointer spec.\r\n\r\n```yaml\r\nopenapi: 3.0.0\r\ninfo:\r\n description: \r\n version: 1.0.0\r\n title: Whatever\r\ncomponents:\r\n schemas:\r\n PartOfMySharedResponse:\r\n type: \"object\"\r\n properties:\r\n foo:\r\n $ref: '#/components/schemas/SharedResponse/properties/foo' \r\n bar:\r\n $ref: '#/components/schemas/SharedResponse/properties/bar' \r\n SharedResponse:\r\n $ref: '//example.com/shared.yaml#components/schemas/MyResponseDefinitionWithFooAndBarProperties'\r\n``` \r\n\r\nIn OAS 3.1.0 we have special Reference Object driven by RFC3986 and JSON Pointer. Then we have JSON Schema 2020-12 `$ref` keyword with it's [own rules of resolution](https://github.com/json-schema-org/community/discussions/61).\r\n\r\n```yaml\r\nopenapi: 3.1.0\r\ninfo:\r\n description: \r\n version: 1.0.0\r\n title: Whatever\r\ncomponents:\r\n schemas:\r\n PartOfMySharedResponse:\r\n type: \"object\"\r\n properties:\r\n foo:\r\n $ref: '#/components/schemas/SharedResponse/properties/foo' \r\n bar:\r\n $ref: '#/components/schemas/SharedResponse/properties/bar' \r\n SharedResponse:\r\n $ref: '//example.com/shared.yaml#components/schemas/MyResponseDefinitionWithFooAndBarProperties'\r\n``` \r\n\r\nThanks for help! ", "created_at": "2021-10-05T09:21:58Z", "updated_at": "2024-04-19T18:24:05Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "char0n", "avatar_url": "https://avatars.githubusercontent.com/u/193286?u=c89f3c6595b483483d3f7d66cb8287e744bb52f4&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zMzk0NTgw", "number": 2602, "title": "minItems and maxItems not present in 3.1 docs?", "body": "Hi, \r\n\r\nI've noticed that when ⌘F thorugh 3.0.3 spec I can see `minItems` and `maxItems` mentioned in the documentation, but not in 3.1. I assume this has to do with 3.1 being aligned with JSON Schema and maxItems being part of JSON Schema. Thus I assume it is available still, only it's not mentioned in the OpenAPI documentation? If that's so, I'd like this confirmed. \r\n\r\nAlso, I'd like to say that for people not deeply familiar with JSON Schema abilities, those who are writing OpenAPI mainly — we now have to resort to finding good documentation for JSON Schema and looking for what they define as available there, losing the convenience of looking through OpenAPI specification only. That makes it a bit harder to work with. Just mentioning in case it's something that hasn't been thought of, e.g. because for the insiders JSON Schema may be more obvious than for outsiders.", "created_at": "2021-06-03T08:44:40Z", "updated_at": "2024-04-19T18:20:03Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "MDE3OkRpc2N1c3Npb25Db21tZW50ODE5Njg0", "body": "Yes, this is the reason, `minItems` and `maxItems` (and all JSON Schema keywords unaltered by OAS) are now defined solely by the JSON Schema specification. This allows us to reduce the length of the OAS, avoid repetition and inadvertent mistakes/differences. We appreciate having to read two specs is more work, but realistically it has always been the case that a working knowledge of the JSON Schema draft which the OAS references is necessary to fully utilitise OAS.\r\n\r\nBoth projects are working on more narrative documentation, so consumers who prefer not to read things written in specification language have an alternative, more instructional route available to them; for example: https://oai.github.io/Documentation/" }, "user": { "login": "mimkorn", "avatar_url": "https://avatars.githubusercontent.com/u/5420435?u=5b1634771270e21ec4d121fefc46328898ca6e3f&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNDM4Mzk3", "number": 2636, "title": "How should a basePath \"/\" be interpreted by tooling in OAS2?", "body": "When constructing a URL from a document with a basePath `/` it's unclear what the expected outcome is.\r\n\r\nIn the [Swagger 2 spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#pathItemObject) it says that \r\n1. basePath is optional\r\n2. if provided, basePath must begin with /\r\n3. Paths Object keys must begin with / and the path is appended to the basePath in order to construct the full URL.\r\n\r\nThis suggests the following structure (ignoring scheme for now):\r\n``\r\n\r\nWithout a basePath:\r\n```\r\n\"host\": \"host.com\",\r\n\"paths\": {\r\n \"/user\": {}\r\n}\r\n```\r\nresults in **`host.com/user`**\r\n\r\nWith a basePath:\r\n```\r\n\"host\": \"host.com\",\r\n\"basePath\": \"/api\"\r\n\"paths\": {\r\n \"/user\": {}\r\n}\r\n```\r\nresults in **`host.com/api/user`**\r\n\r\nFinally, following the same logic:\r\n```\r\n\"host\": \"host.com\",\r\n\"basePath\": \"/\"\r\n\"paths\": {\r\n \"/user\": {}\r\n}\r\n```\r\nresults in **`host.com//user`**\r\n\r\nNow, I realise that this isn't the offical spec, but it seems that the expectation isn't 100% clear. swagger.io documentation suggests something else:\r\nhttps://swagger.io/docs/specification/2-0/api-host-and-base-path/\r\n\r\nSee\r\n> If basePath is not specified, it defaults to /, that is, all paths start at the host root.\r\n\r\nThis is considering `/` to be the same as not providing the value which isn't in the original spec.\r\n\r\nA number of other tools such as Stoplight are also interpreting `/` to be the root rather than an explicit basePath, which I think is wrong, and resulting in a lot of bad swaggers in the wild. It's not too bad when you're reading the swagger as documentation and interpreting it yourself, but if you're writing a tool, you need to follow the spec as correctly as possible. In this case it could end up with not calling the correct API, or not showing the correct path as was indended.\r\n\r\nThe question I have:\r\n1. When concatenating host, basePath and paths, should duplicated slashes be stripped (assuming the document was written haphazardly), or should all slashes be kept literally?\r\n\r\nThis should probably be clarified so it's not up to interpretation.", "created_at": "2021-06-30T13:55:20Z", "updated_at": "2024-04-19T18:19:46Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "alasdairhurst", "avatar_url": "https://avatars.githubusercontent.com/u/8441810?u=8b70e9c4142ea18c02703f53db6a196e85ea705e&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNDQ0MzY5", "number": 2640, "title": "`scheme` value", "body": "Is the value of the `scheme` field in [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/v3.1.1-dev/versions/3.1.0.md#security-scheme-object) supposed to be lower case ?\r\n\r\nThe values in the examples are all lower case but the names in the [IANA registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml) are not.", "created_at": "2021-07-03T15:53:55Z", "updated_at": "2024-04-19T18:18:39Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "aowss", "avatar_url": "https://avatars.githubusercontent.com/u/6297886?u=2a20a402f9d5bf182c0e8af3412595f8d9b23e08&v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNDUwMzA0", "number": 2645, "title": "Version parts", "body": "Are all parts of the [`openapi`](https://github.com/OAI/OpenAPI-Specification/blob/v3.1.1-dev/versions/3.1.1.md#versions) field mandatory or can i have a value that is just `3.1`?", "created_at": "2021-07-07T22:13:51Z", "updated_at": "2024-04-19T18:18:11Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "aowss", "avatar_url": "https://avatars.githubusercontent.com/u/6297886?u=2a20a402f9d5bf182c0e8af3412595f8d9b23e08&v=4" } }, { "id": "D_kwDOAQkWPc4AOKHU", "number": 2809, "title": "[Swagger specification] skip the reference object property [OPENAPI 3.+]", "body": "Swagger specification : \r\n\r\nConsider in the case of \"**allOf**\" , i don't want to use one of the properties from my reference object , how should I achieve that?\r\n\r\n**example :** \r\n\r\n```yaml\r\nrecipientAddress:\r\n allOf:\r\n - $ref: '#/components/schemas/Addresses'\r\nAddresses:\r\n properties:\r\n addressCategory:\r\n type: string\r\n maxLength: 10\r\n description: Type of Address \r\n enum: \r\n - PERMANENT \r\n - COMMUNICATON\r\n example: PERMANENT\r\n addressLine1:\r\n type: string\r\n maxLength: 40\r\n description: First line of the Address\r\n example: host tower\r\n```\r\nhere i don't want property \"**addressCategory**\" in my object \"**recipientAddress**\".\r\n", "created_at": "2021-11-29T16:46:23Z", "updated_at": "2024-04-19T18:16:01Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "bmmule", "avatar_url": "https://avatars.githubusercontent.com/u/46214740?v=4" } }, { "id": "D_kwDOAQkWPc4AOR7u", "number": 2826, "title": "Warning while using operation ref", "body": "I want ref a single operation of path, but it waring \"Missing required property 'responses'\"", "created_at": "2021-12-08T05:44:48Z", "updated_at": "2024-04-19T18:15:54Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "conanguyw", "avatar_url": "https://avatars.githubusercontent.com/u/29424657?u=f5f9ac41b5ff53e2b364e65d55ec529c58fa7f1e&v=4" } }, { "id": "D_kwDOAQkWPc4ANxYp", "number": 2740, "title": "Defining Constants for Schemas / Open Enum", "body": "Hey everyone 👋 \r\n\r\nI was wondering if anyone ever faced a similar challenge like I am currently, and was able to solve it in a good way also supported by the tooling. \r\n\r\nAssume an API which accepts web hooks. You have one endpoint with a schema where one property defines the type of event that happened. This event is a string. \r\n\r\n```yaml\r\ncomponents:\r\n schemas:\r\n WebHook:\r\n type: object\r\n properties:\r\n eventId:\r\n type: string\r\n```\r\n\r\nNow here comes the tricky aspects: not all `eventId` values are treated the same way. The API understands some special values, while others might be accepted but not treated in any special way. I want to be able to document in a good way some known values for this property like an enum, but not limit the property to this values. In best case these defined values, are also generated then as constants by the code generator so that the client implementing the API might have these special values available instead of duplicating it manually:\r\n\r\n\r\n```yaml\r\ncomponents:\r\n schemas:\r\n WebHook:\r\n type: object\r\n properties:\r\n eventId:\r\n type: string\r\n knownValues: # like an enum definition (would then also support description once this is extended by OAS)\r\n - Special.Event01\r\n - Special.Event02\r\n - Group02.Event01\r\n```\r\nAn output could look like this: \r\n```cs\r\nclass WebHook\r\n{\r\n public class KnownValues\r\n {\r\n public const string SpecialEvent01 = \"Special.Event01\";\r\n public const string SpecialEvent02 = \"Special.Event01\";\r\n public const string Group02Event01 = \"Group02Event01\";\r\n }\r\n}\r\n```\r\n\r\nI thought of using `examples` for this case but would also need to extend the code generators for this purpose and it is not really a standard practice. \r\n\r\n**Different explanation:**\r\n\r\nHas anybody ever tried to represent \"open enums\" in Open API Specification? I want to define properties which have predefined enum values, but are not limited to these. Some example use cases:\r\n\r\n- An enum listing known webhook event ids which actually trigger a special logic within the API. Once enum values support descriptions this would even make more sense. \r\n- Like in the [documentation ](https://swagger.io/docs/specification/data-models/enums/) the colors: you might list some predefined ones, but you might not prevent the client to provide other values like `#FF0000`\r\n\r\nCode generators would behave like: \r\n- The property of the schema would have the plain underlying data type like string or enum. \r\n- The enum would be generated as some type defining the constants so the generated client/server can use them. \r\n\r\n", "created_at": "2021-10-06T07:01:13Z", "updated_at": "2024-04-19T18:14:48Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Danielku15", "avatar_url": "https://avatars.githubusercontent.com/u/674916?u=7b199be729f9f1795a2bc63e4de896a4a5e93360&v=4" } }, { "id": "D_kwDOAQkWPc4AOcV4", "number": 2852, "title": "Seeing \"Unable to render this definition\" on ec2 instance not in local", "body": "Hi there, \r\n\r\nWe are trying to migrate from spring fox to spring doc as the former is no longer compatible with the latest spring boot version ( 2.6.x) and spring doc internally used open API specification ( 3.0.1). So I thought this might be the correct forum to raise the issue.\r\n\r\nWe have made all the migration changes and everything is working perfectly in my local but when we try to deploy to one of our ec2 instances we are facing the below issue.\r\n\r\n\"image\"\r\n\r\nAnd on clicking the Invalid Json symbol we are getting the below error message, \r\n\r\n\"image\"\r\n\r\n\r\nI have fetched my swagger YAML file and checked in swagger editor it is not having any parsing errors, can anyone point me to the reason we are getting it? \r\n\r\nThanks\r\n", "created_at": "2022-01-07T07:55:31Z", "updated_at": "2024-04-19T18:13:18Z", "category": { "name": "Tooling", "emoji": ":hammer_and_wrench:" }, "answer": null, "user": { "login": "RaviTejaMaddhini", "avatar_url": "https://avatars.githubusercontent.com/u/28302282?v=4" } }, { "id": "D_kwDOAQkWPc4APla4", "number": 2929, "title": "How to document required privilege levels on endpoints?", "body": "Please tell me the recommended OpenAPI way of documenting endpoint privileges (such as roles) that are enforced by a back-end implementation. For example, an endpoint \"GET /version\" is open to every authenticated and authorized user, but an endpoint \"POST /user\" is only open to an authenticated and authorized user with additional privileges that are managed in the back end. This need doesn't seem to fit in the securitySchema feature. I have seen people mention \"extensions\" but I'm not sure which is right or where to find those extensions, and I definitely don't want to add items that might break the toolchain that generates (Python) clients and other features. Thanks in advance!", "created_at": "2022-05-19T14:44:07Z", "updated_at": "2024-04-19T18:12:32Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "chrisinmtown", "avatar_url": "https://avatars.githubusercontent.com/u/10234212?u=14e73f48f48300e2a056164fc095cda8c6fb45d3&v=4" } }, { "id": "D_kwDOAQkWPc4AOrjv", "number": 2874, "title": "What is the meaning of a Media Type Object with no schema defined?", "body": "The spec for a Media Type Object does not say that the \"schema\" property is required. Therefore, it is valid to leave the schema undefined. But what does this mean? That any kind of content data is acceptable?", "created_at": "2022-02-01T22:58:25Z", "updated_at": "2024-04-19T18:07:30Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AH-4N", "body": "Not exactly. When you define the media type, you're telling the user what is expected to go over the wire. The `schema` is there to help validate the actual content. However, in many cases, a schema doesn't make sense - PDFs, audio files, binary files and so on, so specifying the schema is pointless. \r\n\r\nAt the moment, we only support JSON Schema for the Schema Object, meaning you can only describe JSON payloads (and to some limited extent XMLs). Had we supported things like XSD (which we may in the future), that would allow you to define schemas (or something similar) for additional media types." }, "user": { "login": "kerrykimbrough", "avatar_url": "https://avatars.githubusercontent.com/u/6577913?u=d013ab8a076390303f38eacbb375b27f36a80942&v=4" } }, { "id": "D_kwDOAQkWPc4APy9G", "number": 2943, "title": "Appending to referenced enum", "body": "Would love to be able to append to an existing enum. Not all values are applickable in all cases, this means that i need to redefine the enum. Especially when used together with deepmap's oapi-gen this would be nice.\r\n\r\n**Example:**\r\nSensorType.yaml:\r\n```yaml\r\ntype: string\r\nenum: [Motion, Push, Voice]\r\n```\r\nDoorbell.yaml:\r\n```yaml\r\n schema:\r\n $ref: \"#/shared/components/schemas/SensorType.yaml\"\r\n description: Sensor to trigger doorbell\r\n```\r\nAlarm.yaml:\r\n```yaml\r\n schema:\r\n $ref: \"#/shared/components/schemas/SensorType.yaml\"\r\n append: [ Temp, Vibration, SignalLoss ]\r\n description: Sensor to trigger alarm\r\n```", "created_at": "2022-06-13T09:06:13Z", "updated_at": "2024-04-19T17:55:30Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4ALNkc", "body": "This is more of a JSON Schema request than an OpenAPI one. You can achieve what you're looking for using `oneOf` or `anyOf` depending on the content of the different enums.\r\n\r\n```yaml\r\n schema:\r\n oneOf:\r\n - $ref: \"#/shared/components/schemas/SensorType.yaml\"\r\n - enum: [ Temp, Vibration, SignalLoss ]\r\n description: Sensor to trigger alarm\r\n```" }, "user": { "login": "martinwangen", "avatar_url": "https://avatars.githubusercontent.com/u/26923578?u=7e8d3d6c842c89d6efab16968b3c3531ecf9c6c0&v=4" } }, { "id": "D_kwDOAQkWPc4AN-QR", "number": 2778, "title": "warning:Body property 'CollectingDate' not defined in body schema (Though CollectingDate is defined in schema) what could be the possible reason for this warning?", "body": "I have defined CollectingDate property in my swagger.yaml file, but whenever I make put request I get **Body property 'CollectingDate' not defined in body schema** What could be the possible reason?", "created_at": "2021-11-02T11:25:48Z", "updated_at": "2024-04-19T17:55:07Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Ragzz1995", "avatar_url": "https://avatars.githubusercontent.com/u/16513966?v=4" } }, { "id": "D_kwDOAQkWPc4AP0g5", "number": 2944, "title": "Supporting custom types", "body": "Hi,\r\n\r\nI'm new to OpenAPI and we're using for a project where we have our custom data types. \r\n\r\nI would like to know if it would be possible to use an UI implementation of the OpenAPI and\r\nhave it render the custom data type. For example, I could use this json,\r\n\r\n`{\r\n \"varName\":{\r\n \"type\": \"customDataType\"\r\n }\r\n}`\r\n\r\nand have it rendered as it it were a string or number or any of the other supported types by OA.\r\n\r\nP.S.: We could use objects but we would still have to fall back to the OpenAPI data types, which is something we want to avoid.\r\n\r\nThanks", "created_at": "2022-06-15T14:49:58Z", "updated_at": "2024-04-19T17:53:56Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "WoobaWooba", "avatar_url": "https://avatars.githubusercontent.com/u/106334468?v=4" } }, { "id": "D_kwDOAQkWPc4AQCJg", "number": 2967, "title": "OAS 3 : allOf specification missing ?", "body": "Hello Everyone,\r\n\r\nI was wondering why the allOf at array level with items was not documented, because it is working perfectly :\r\n\r\n(in the screenshot the swagger has been simplified for clarity purposes)\r\n\r\n![image](https://user-images.githubusercontent.com/65857453/177994486-726fac6c-03a5-45c2-8905-d01fa61f9ae3.png)\r\n\r\n![image](https://user-images.githubusercontent.com/65857453/177994599-5b1063b5-3412-4642-a232-a384fa6e80b9.png)\r\n\r\nBut because of the spec mentionned at https://spec.openapis.org/oas/latest.html :\r\n\r\n4.8.24.2.1 Composition and Inheritance (Polymorphism) [§](https://spec.openapis.org/oas/latest.html#composition-and-inheritance-polymorphism)\r\nThe OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.\r\n\r\nWhile composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the discriminator field. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. As such, the discriminator field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance.\r\n\r\nMy company is using those specs to validate swaggers, and because of that my AllOf is refused.", "created_at": "2022-07-08T14:00:48Z", "updated_at": "2024-04-19T17:52:15Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "jonathan-vandebosch", "avatar_url": "https://avatars.githubusercontent.com/u/65857453?v=4" } }, { "id": "D_kwDOAQkWPc4AQKGx", "number": 2977, "title": "Is a fractional part of \".0\" allowed for integers?", "body": "Please clarify: Are values like `1.0` valid for the `integer` data type?\r\n\r\nJSON schema allows values like `1.0` for integers. But the OpenAPI specification contains this sentence:\r\n> Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.\r\n\r\n\"without a fraction or exponent part\" - does that mean that the number is not allowed to have a fraction part at all, e.g. `1` is valid but `1.0` is invalid? Or does it mean that a fraction of 0 is allowed, so `1` is valid and `1.0` is also valid?\r\n\r\nAre the rules the same for JSON parameters and for query parameters?\r\n\r\nFor example, consider this OpenAPI specification:\r\n```\r\n{\r\n \"openapi\": \"3.0.0\",\r\n \"info\": {\r\n \"title\": \"Integers\",\r\n \"version\": \"1.0\"\r\n },\r\n \"paths\": {\r\n \"/path1\": {\r\n \"post\": {\r\n \"requestBody\": {\r\n \"content\": {\r\n \"application/json\": {\r\n \"schema\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"value\": {\r\n \"type\": \"integer\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n },\r\n \"responses\": {\r\n \"default\": {\r\n \"description\": \"test\"\r\n }\r\n }\r\n }\r\n },\r\n \"/path2\": {\r\n \"get\": {\r\n \"parameters\": [\r\n {\r\n \"in\": \"query\",\r\n \"name\": \"a\",\r\n \"schema\": {\r\n \"type\": \"integer\"\r\n }\r\n }\r\n ],\r\n \"responses\": {\r\n \"default\": {\r\n \"description\": \"test\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nAre these requests valid?\r\n* Request 1:\r\n```\r\ncurl -H \"Content-Type: application/json\" --data '{ \"value\": 1.0 }' 'http://localhost/path1'\r\n```\r\n\r\n* Request 2:\r\n```\r\ncurl 'http://localhost/path2?a=1.0'\r\n```", "created_at": "2022-07-21T15:29:44Z", "updated_at": "2024-04-19T17:51:37Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AMNNp", "body": "It looks like you're referencing OpenAPI 3.0 which uses JSON Schema draft-6/draft-0. That version of JSON Schema does not have an `integer` data type. The definition was added since we moved from draft 4, which did have an [integer definition](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04#section-3.5), though otherwise the draft versions are pretty much identical. \r\n\r\nDraft 06 does have some [additional information](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-6.3) about mathematical integers, and suggest not using a decimal point for integer values, even though it is technically supported.\r\n\r\nLong story short, the fractional part is not allowed." }, "user": { "login": "mkauf", "avatar_url": "https://avatars.githubusercontent.com/u/12849992?v=4" } }, { "id": "D_kwDOAQkWPc4AUp_B", "number": 3329, "title": "How do I structure a large API where using namespaces in generated client code would be ideal?", "body": "We have a large API defined in Python using Pydantic/FastAPI. On the Python side the schemas/paths are neatly structure into separate python modules (e.g. `users.py` for `/users` and all its schemas). We'd like to generate an OpenAPI client* (e.g. for TypeScript) that is similarly well organized but it doesn't seem possible to preserve enough information in the OpenAPI spec such that a client that uses namespaces can be generated.\r\n\r\n- Is it possible to generate clients using namespaces?\r\n - What approach would be suitable? Relying on tags? Parsing the path and generating namespaces from e.g. the last path component?\r\n- How do people manage large APIs and clients generated for such?\r\n\r\n\\* I'm fine writing my own client generator. The issue is more whether OpenAPI is too lossy to be able to do so.", "created_at": "2023-07-18T13:19:10Z", "updated_at": "2024-04-19T17:49:35Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "tibbe", "avatar_url": "https://avatars.githubusercontent.com/u/17277?v=4" } }, { "id": "D_kwDOAQkWPc4AOo5b", "number": 2867, "title": "When using OAuth 2.0, how do you describe the exact mechanism that should be used to authorize requests to a resource server?", "body": "OpenAPI allows you to specify an OAuth security scheme type and a list of scopes required to request an endpoint (resource server). It might look like this:\r\n\r\n```\r\ncomponents:\r\n securitySchemes:\r\n oAuthSample:\r\n type: oauth2\r\n flows:\r\n implicit:\r\n authorizationUrl: https://api.example.com/oauth2/authorize\r\n scopes:\r\n read_pets: read pets in your account\r\n write_pets: modify pets in your account\r\n```\r\n\r\n```\r\npaths:\r\n /pets/{petId}:\r\n patch:\r\n summary: Updates a pet in the store\r\n security: \r\n - oAuthSample: [write_pets]\r\n ...\r\n```\r\n\r\nSource: https://swagger.io/docs/specification/authentication/oauth2/.\r\n\r\nHow, from such a specification, you can understand how exactly a client should be authorized on a resource server on behalf of an user? Should it just be stated in a text documentation, or is there a standardized way provided by OpenAPI?\r\n\r\nOr maybe it's better to formulate the question as follows - how in OpenAPI to specify the type of an access token from the options defined here https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-types, that is issued by an authorization server and, as a result, explain how the token is used for authorization on a resource server?\r\n\r\nP.S. This question was originally asked on [Stackoverflow](https://stackoverflow.com/questions/70867784/in-openapi-when-using-oauth-2-0-how-do-you-describe-the-exact-mechanism-that-s).", "created_at": "2022-01-27T11:57:46Z", "updated_at": "2024-04-19T17:45:30Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "alex-feel", "avatar_url": "https://avatars.githubusercontent.com/u/71711753?u=f80539f3cb83cac40fffaf2b48aca6b655078db1&v=4" } }, { "id": "D_kwDOAQkWPc4ARAXs", "number": 3047, "title": "OAS3 Array query params example", "body": "Hi all\r\n\r\nI have some doubts about the examples in 4.7.12.4 - serialization styles.\r\n\r\n\r\n\r\nField Name | Type | Description\r\n-- | -- | --\r\nexplode | boolean | When this is true, parameter values of type array or object generate separate parameters for each value of the array [...]\r\n\r\n\r\n\r\n\r\nThe input array data for array is \r\n`color := [\"blue\",\"black\",\"brown\"]`\r\n\r\nI'd expect it to serialize as:\r\nexploded: `'color=blue&color=black&color=brown'`\r\nnon-exploded: `'color=blue,black,brown'`\r\n\r\nYet both examples are simply `'blue,black,brown'`\r\n\r\nIs this correct?\r\n", "created_at": "2022-10-09T14:35:05Z", "updated_at": "2024-04-19T17:42:42Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AiABn", "body": "Yes it does, I asked a similar question before, and got pointed to the same rfc [(You may find it useful to read the answers I received)](https://github.com/OAI/OpenAPI-Specification/issues/3481)\r\n\r\n[RFC6570-2.4.2](https://www.rfc-editor.org/rfc/rfc6570#section-2.4.2) will give you a good idea of why someone might want explode.\r\n\r\nThe example you've given is for the **simple** style which can **only be used in paths and headers**:\r\n\r\nIn a path: parameters MUST appear in the same order specified in the template, so the name isn't required i.e.\r\n\r\n`/paint/{colors}/{type}` and you get `/paint/red,green,blue/silk` you still know which part the color parameter is because each parameter is delimited by a forward slash.\r\n\r\nIn a header: each header has a name, so the name of the parameter is already given.\r\n\r\n`color: red,green,blue` is clear.\r\n`color: color=red,green,blue` would be redundant.\r\n" }, "user": { "login": "rafalkrupinski", "avatar_url": "https://avatars.githubusercontent.com/u/3732079?u=4b647b396cd54c57e11b5c73fc09e7cf83acf786&v=4" } }, { "id": "D_kwDOAQkWPc4AQMTn", "number": 2984, "title": "swagger-cli validate ./openapi.yaml fails while adding examples in request body with $ref for content", "body": "openapi: 3.0.2\r\n\r\n**API example:** \r\n```yaml\r\nrequestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n $ref: ./api/rosetta/rosetta-account-balance-request.schema.json\r\n examples:\r\n network_identifier:\r\n value: [mainnet]\r\n account_identifier: \r\n value: [SPZ5DJGRVZHXEEEYYGWEX84KQB8P69GC715ZRNW1]\r\n```\r\n \r\n **Output**: \r\n```\r\nSwagger schema validation failed.\r\n #/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/application~1json/schema must NOT have additional properties\r\n #/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/application~1json/schema must have required property '$ref'\r\n #/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/application~1json/schema must match exactly one schema in oneOf\r\n #/paths/~1rosetta~1v1~1account~1balance/post/requestBody must have required property '$ref'\r\n #/paths/~1rosetta~1v1~1account~1balance/post/requestBody must match exactly one schema in oneOf\r\n```\r\n\r\n\r\nhttps://github.com/hirosystems/stacks-blockchain-api/runs/7506454511?check_suite_focus=true", "created_at": "2022-07-25T18:30:51Z", "updated_at": "2024-04-19T17:42:02Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "LakshmiLavanyaKasturi", "avatar_url": "https://avatars.githubusercontent.com/u/55154433?u=ad3b8ac224f8215df52e44291b07a1dc0a04d4e0&v=4" } }, { "id": "D_kwDOAQkWPc4AQSqh", "number": 2990, "title": "Expert Opinions Please - Data Centric (Generic) API", "body": "Hello,\r\n\r\nI'd like to elicit some opinions from the experts on how I'm approaching API design and how OAI might be applicable.\r\nFirst off, I have a framework and middle-tier components that allow me to push all user resource (code & data, including unstructured) into a database (Oracle...get your arrows and slings out..!!!). There's nothing in the middle-tier in my design other than a protocol adapter between HTTP and SQL.\r\n\r\nSo...what that means is I can build an API, expressed as a package in the database, that only exposes a single entry point. Remember, all of the logic is in the DB. That means all of your routing is there too. That's what allows you to expose a single entry point. The logic in the database looks at your 'message' and figures out what to do.\r\n\r\nThis is what I call a Data Centric (Generic) API.\r\n\r\nHere's my package header which is essentially the API signature:\r\n\r\n`create or replace package db_twig as\r\n\r\n function call_rest_api\r\n (\r\n p_json_parameters clob\r\n )\r\n return clob;\r\n\r\nend db_twig;\r\n`\r\nAs you can see, not much to expose.\r\nSo, my questions are:\r\n\r\n- How would OAI deal with API components that are embedded within p_json_parameters, which is a JSON string sent into the function in the DB?\r\n- It seems as though OAI is geared towards APIs that expose their components as entry-points and parameters. Would it even be possible to use OAI to test APIs developed in the manner above?\r\n\r\nThanks for your time and opinions on this matter.", "created_at": "2022-08-02T00:01:07Z", "updated_at": "2024-04-19T17:41:41Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "JumpinJackFlash", "avatar_url": "https://avatars.githubusercontent.com/u/1429769?u=ba1f7114969b5ea894f4a3a9789f1d205f9a3a9e&v=4" } }, { "id": "D_kwDOAQkWPc4AQguY", "number": 3007, "title": "Header and Parameter in header ambiguity", "body": "The `Components` object has:\r\n* `parameters` - collection of `Parameter` objects\r\n* `headers` - collection of `Header` objects\r\n\r\nHowever, a `Parameter` can be a header (when `in == \"header\"`). \r\nThis inherent **ambiguity creates confusion** when one tries to create a global/group customization. \r\n\r\nCan the ambiguity be removed (maybe deprecating the `Header` object or the `\"header\"` location of `Parameter`)? \r\nIf not, when should I declare a header as a `Parameter` and when should I declare it as a `Header`? The answer to this last question is direly needed in the documentation. ", "created_at": "2022-08-23T21:02:54Z", "updated_at": "2024-04-19T17:24:00Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "pmerson", "avatar_url": "https://avatars.githubusercontent.com/u/6674738?u=05eba14157a61f7167d345acba455181258e8b80&v=4" } }, { "id": "D_kwDOAQkWPc4AQr7C", "number": 3025, "title": "Behavior of the allOf and discriminator", "body": "Hello! I have a few pieces of questions related to a combination of `allOf` and `discriminator` usage. \r\n\r\nI have following OpenAPI spec\r\n\r\n```yml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: 'Example'\r\n version: 0.1.0\r\nservers:\r\n - url: 'http://example.com'\r\npaths:\r\n ‘/users’:\r\n get:\r\n responses:\r\n '200':\r\n description: OK\r\n content: \r\n application/json:\r\n schema:\r\n type: array\r\n items: \r\n $ref: \"#/components/schemas/User\"\r\ncomponents:\r\n schemas:\r\n User:\r\n type: object\r\n properties:\r\n $type:\r\n type: string\r\n shared_property:\r\n type: string\r\n discriminator:\r\n propertyName: \"$type\"\r\n\r\n UserA:\r\n allOf: [\r\n $ref: \"#/components/schemas/User\"\r\n ]\r\n type: object\r\n properties:\r\n foo:\r\n type: string\r\n\r\n\r\n UserB:\r\n allOf: [\r\n $ref: \"#/components/schemas/User\"\r\n ]\r\n type: object\r\n properties:\r\n bar:\r\n type: string\r\n```\r\n\r\nIn case of GET request to `/users` server must return an array of `User`s and their subtypes (`UserA`, `UserB`). \r\n\r\n1. Is that right or `User` do not includes their subtypes (UserA, UserB) in this context? Seems I should define response as `oneOf: [User, UserA, UserB]` for correctness?\r\n\r\nI have doubts because I use this spec to generate python client using [openapi-generator](https://openapi-generator.tech/). And in generated `User` model I see following code\r\n\r\n```python3\r\n…\r\n\r\ndef discriminator():\r\n lazy_import()\r\n val = {\r\n 'UserA': UserA,\r\n 'UserB': UserB,\r\n }\r\n\r\n…\r\n```\r\n\r\nSeems like `User` knows about `UserA` and `UserB` and tries to parse data into them if eg `$type=UserA`. But no `User` model himself here. So parsing fails when I get an object with `$type=User`. That seems strange.\r\n\r\nIt may be fixed in 2 ways\r\n- `oneOf: [User, UserA, UserB]` in endpoint response.\r\n- add discriminator/mapping field, where explicitly add `User` schema into discriminator mapping.\r\n\r\n\r\n2. Is [openapi generator](https://openapi-generator.tech/) implement this in the correct way?\r\n3. What is the convenient way to specify that server returns an array, that may contain types: `User`, `UserA`, `UserB`?", "created_at": "2022-09-08T12:53:12Z", "updated_at": "2024-04-19T17:20:37Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AON0h", "body": "allOf makes it an inheritance. Superclass should neither know of nor include its subclasses.\r\n\r\nThe specification you've attached says your endpoint returns only a list of `User`. Since `additionalProperties` is true by default, it may return objects that happen to validate against `UserA` and/or `UserB` but that's not declared explicitly.\r\n\r\n```yaml\r\nresponses:\r\n default:\r\n content:\r\n application/json:\r\n schema:\r\n type: array\r\n items:\r\n oneOf:\r\n - $ref: '#/components/schemas/UserA'\r\n - $ref: '#/components/schemas/UserB'\r\n - $ref: '#/components/schemas/User'\r\n```\r\n\r\nNot sure about discriminator, but you can try adding `additionalProperties: false` to User schema, so that UserA&B don't validate against it.\r\n" }, "user": { "login": "mtovt", "avatar_url": "https://avatars.githubusercontent.com/u/96553816?v=4" } }, { "id": "D_kwDOAQkWPc4AOoc2", "number": 2865, "title": "Parameter only for POST", "body": "I have a schema that I would like to use for both POST and PUT methods but a target parameter is allowed only for the POST request.\r\n\r\nTo make it clear let's imagine that there is a possibility to **create** and **update** a *user*.\r\nAt the POST it's required the name and the inviteCode, then for the PUT just the name and don't allow to edit the inviteCode anymore\r\n\r\n```yaml\r\ncomponents:\r\n schemas:\r\n user:\r\n type: object\r\n properties:\r\n name:\r\n type: string\r\n inviteCode:\r\n type: string\r\npaths:\r\n \"/user\":\r\n post:\r\n requestBody:\r\n content:\r\n application/json:\r\n schema:\r\n \"$ref\": \"#/components/schemas/user\"\r\n \"/user/{id}\":\r\n put:\r\n parameters:\r\n - name: id\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n requestBody:\r\n content:\r\n application/json:\r\n schema:\r\n \"$ref\": \"#/components/schemas/user\"\r\n```\r\n\r\nIs there a way to do it by just adding a parameter to the ```inviteCode```? ", "created_at": "2022-01-26T16:56:23Z", "updated_at": "2024-04-19T17:20:02Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AH1I_", "body": "JSON Schema doesn't quite allow you to pick and choose which properties you want to use from a given schema definition.\r\nYou have two options:\r\n- split `user` into two schemas, where one uses `allOf` the other and adds the `inviteCode`\r\n- use the `user` schema for both, but in the case of put make it a combination of `allOf` and `not` to remove support for `inviteCode`" }, "user": { "login": "DenisFerrero", "avatar_url": "https://avatars.githubusercontent.com/u/61707512?u=71886d23e185ee6aa7b345265740cabe3866f38d&v=4" } }, { "id": "D_kwDOAQkWPc4AQnVU", "number": 3014, "title": "Invalid request for route publish_po_message: OpenAPI spec contains no such operation", "body": "Hi ,\r\n\r\nAnyone have idea why i am getting this error .\r\n\r\nThanks\r\nShubhangi", "created_at": "2022-09-02T06:38:10Z", "updated_at": "2024-04-19T17:18:54Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "shubhangicatch", "avatar_url": "https://avatars.githubusercontent.com/u/110524798?v=4" } }, { "id": "MDEwOkRpc2N1c3Npb24zNTI0NzU5", "number": 2676, "title": "Why OpenAPI 3.1.0 does not allow schema references in Parameter & Media Type objects?", "body": "It feels very strange for me that [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) (`schema` field) and [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject) (`schema` field) do not allow Reference Object to be passed. Maybe I am blind, but I can't find places in spec where schemas defined in `#/components/schemas/*` may be reused because there are no definitions of something like `Schema Object | Reference Object` in the spec. As I see currently component schemas may be reused only within another schemas (e.g. via `allOf`, `oneOf`, `items`, `properties`, etc).\r\n\r\nIsn't it a good idea to add `Schema Object | Reference Object` to Parameter Object and Media Type Object?", "created_at": "2021-08-17T09:51:10Z", "updated_at": "2024-03-26T18:56:08Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "MDE3OkRpc2N1c3Npb25Db21tZW50MTE5NDg4Mw==", "body": "@flaksp your example\r\n```yaml\r\napplication/json: \r\n schema:\r\n $ref: \"#/components/schemas/Pet\"\r\n description: \"Description goes here\"\r\n summary: \"Summary goes here\"\r\n```\r\nis perfectly valid in OAS 3.1.0.\r\n\r\nSchemas support $ref siblings as part of JSON Schema 2019-09 and later. (OAS 3.1 uses JSON Schema 2020-12 by default.) Schema $refs are a bit different from OpenAPI Reference Objects (used for parameter $refs, response $refs, etc.) in that schema $refs support _any_ sibling keywords, whereas OAS Reference Objects only support sibling `summary` and `description`.\r\n\r\nNote that JSON Schema doesn't have the `summary` keyword so it will be handled as an _annotation_." }, "user": { "login": "flaksp", "avatar_url": "https://avatars.githubusercontent.com/u/12474739?u=11f1f84a1962b729023cdf2f4dad17cffdd271ee&v=4" } }, { "id": "D_kwDOAQkWPc4AN-Ob", "number": 2777, "title": "Accept/Content-Type/Authorization Ignored", "body": "Hi all,\r\n\r\nI work at a company that requires Swagger/OpenAPI specs for every API, so we have about 1500+ specs right now; probably 85% are using Swagger 2. I'm going to start requiring everyone to use OpenAPI 3.x going forward, primarily because it's waaay past time we did this. I'm also trying to make it easier for specs to be downloaded and imported into Insomnia or Postman and not have duplicate params that will cause confusion.\r\n\r\nI've got a couple of issues, however, that are holding me up.\r\n\r\n1. We have more than a couple APIs that, for whatever reason, have required Accept or Content-Type header params. Is there a way to still have these using the OpenAPI 3.x rules/structure? Do we just flat-out tell teams not to add these header params?\r\n2. For years we have told teams that `key` is a required query param (or `x-api-key` header), and `Authorization` is a required header param if auth is being used. I understand these move into the `security/securityScheme` sections. Has anyone run into issues with people being confused about the new location of these values? Like I said, previously these were easy to see in the param list in Swagger-UI, but going forward, they are behind the padlock icon, which is a bit different. \r\n\r\nSorry for the long note. I'm just hung up on #1, and worried about #2 (especially since we've made a big deal about \"keys are for tracking, not security\" and now they are in the security section). I'm curious if others have had to deal with this and what has worked for them.\r\n\r\nThanks!", "created_at": "2021-11-02T15:20:10Z", "updated_at": "2024-03-26T18:55:00Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AGBF7", "body": "1. That was indeed one of the stricter changes from 2.0 to 3.0. You simply cannot have those as defined headers anymore as those are exclusively defined under `content` now. If you're using any conversion tools, they may be able to support it (or extended to support it). Adding those headers in 3+ is a no-go and should fail validation.\r\n\r\n2. `key` or `x-api-key` could have been defined in 2.0 as well under the security sections. I don't believe there's any requirement for you to move them to become security definitions rather than parameters in 3.0. The benefit of moving them to the security section is that that you're not going to have to add them to each and every operation. `authorization` is strictly prohibited as a header parameter name and that has to move to the security section. " }, "user": { "login": "jaydreyer", "avatar_url": "https://avatars.githubusercontent.com/u/1815281?v=4" } }, { "id": "D_kwDOAQkWPc4APdQB", "number": 2924, "title": "Java OpenApi format date", "body": "Hello, I am using OpenApi in my Java project. In my yaml file I used type string and format date. But I am facing one issue with the year.\r\nMy request should come like this 2022-01-30 if I give wrong day or month validation is working and I am getting error message but for the year this is not happening. For example if I sent wrong year like this 20223131-01-30 I am not getting error message that year has to be 4 digits or there is no such year. How can I fix this?\r\n\r\nThank you.", "created_at": "2022-05-04T14:41:33Z", "updated_at": "2024-03-26T18:54:10Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AKVrC", "body": "20223131 is a valid year, albeit not very likely to be the correct value in your application.\r\n\r\nYou could add an extra check like `\"maxLength\": 10\"` or `\"pattern\": \"^\\d{4}-\\d{2}-\\d{2}$\"` to ensure that you get four-digit years." }, "user": { "login": "danosavraam", "avatar_url": "https://avatars.githubusercontent.com/u/98758983?v=4" } }, { "id": "D_kwDOAQkWPc4AP6ac", "number": 2954, "title": "Clarification about path template uri that may or not clash with other paths", "body": "Hi!. This is related to: #2753\r\n\r\nContext: we have an OAS 3.0 api with two path objects: `/v2` and `/v2{param}`. \"Param\" is a required parameter so in practice the second endpoint should always result in a different uri than the first one f.e: `/v2` vs `/v2test` (\"param\" is parameterized with \"test\").\r\n\r\nThe question is: do these paths clash with each other or are they valid according to the spec? The only thing I found but that doesn't apply to this case completely is:\r\n\r\n> When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical\r\n\r\nWhat would happen if instead of only two path objects, there were three:\r\n- `/v2`\r\n- `/v2another`\r\n- `/v2{param}` (clashes with `/v2another` if param == another)\r\n\r\nThis is all without taking into account the different styles the template parameter could have.\r\n\r\nHow should API processors handle all these variations? It seems to me that this might be really error-prone for processors.\r\n\r\nHere an API showcasing this:\r\n```yaml\r\nopenapi: \"3.0.0\"\r\ninfo:\r\n version: 1.0.0\r\n title: mytest\r\npaths: \r\n /v2:\r\n get:\r\n responses:\r\n \"200\":\r\n description: \"___\"\r\n /v2{params}:\r\n parameters:\r\n - in: path\r\n name: params\r\n required: true\r\n schema:\r\n type: string\r\n post:\r\n responses:\r\n \"200\":\r\n description: \"_______\"\r\n```", "created_at": "2022-06-24T21:37:57Z", "updated_at": "2024-03-26T18:52:21Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4ALhYp", "body": "I don't see any problem with the described definition. With the case of `/v2another` and `/v2{param}` (clashes with `/v2another` if param == another), the definition of `/v2another` will take precedence because it's a specific case definition." }, "user": { "login": "tomsfernandez", "avatar_url": "https://avatars.githubusercontent.com/u/15634976?u=9d60a0b4af3156b37522b30b86229bb0855a673d&v=4" } }, { "id": "D_kwDOAQkWPc4AN_oG", "number": 2782, "title": "download workflow form responses from my slack by API", "body": "Hello,\r\n\r\nI am trying to download workflow form responses from my slack by API but there is no info in API about it.\r\n\r\nIs that possible ?\r\nif Yes can You please put example how to do it ?\r\n\r\nBR", "created_at": "2021-11-05T08:37:52Z", "updated_at": "2024-03-26T18:51:32Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "enimath", "avatar_url": "https://avatars.githubusercontent.com/u/85619615?v=4" } }, { "id": "D_kwDOAQkWPc4AQJ2P", "number": 2974, "title": "How to manage multiple requestBody in a single endpoint", "body": "Is it possible to have more than one requestBody for the same endpoint post;\r\n`\r\n \"Entete\": {\r\n \"operationid\": 7701,\r\n },\r\n\"contentParams\":{\r\n\"user\":\"username\",\r\n\"password\":\"passworduser\"\r\n}\r\n`\r\nThis a piece of my request body and depending of the operationid execute a method , \r\nNote: operation code are unique for every method;\r\nMore info: contentParams depend of the operationid,\r\nevery operationid have its unique id, but the content params might be same with other methods but the output is always different;\r\nIf i am not clear enough i can explain more, and ask me question when need be;", "created_at": "2022-07-21T09:57:37Z", "updated_at": "2024-03-26T18:50:53Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "ydevmob", "avatar_url": "https://avatars.githubusercontent.com/u/109730381?v=4" } }, { "id": "D_kwDOAQkWPc4AQb41", "number": 3001, "title": "Scopes: Logical OR and AND", "body": "According to [the Swagger documentation](https://swagger.io/docs/specification/authentication/#multiple), it's already possible to use multiple authentication types:\r\n\r\n```\r\nsecurity: # (A AND B) OR (C AND D)\r\n - A\r\n B\r\n - C\r\n D\r\n```\r\n\r\nIs this concept also extensible to scopes? E.g.\r\n\r\n```\r\nsecurity: \r\n - oauth2: # user needs scope \"A\" or \"B\"\r\n - A\r\n - B\r\n\r\nsecurity:\r\n - oauth2: # user needs scope \"A\" and \"B\"\r\n - A\r\n B\r\n```\r\n\r\nI already tested this in the Swagger Editor and it doesn't seem to make a difference. So, is my assumption correct that scopes always use Logical AND?", "created_at": "2022-08-16T11:44:19Z", "updated_at": "2024-03-26T18:49:26Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4ANL0T", "body": "Logical \"AND\" and \"OR\" for scopes can be expressed as follows:\r\n\r\n```yaml\r\n# User needs scopes A AND B\r\nsecurity:\r\n - oauth2:\r\n - A\r\n - B\r\n\r\n# User needs scope A OR B\r\nsecurity:\r\n - oauth2:\r\n - A\r\n - oauth2:\r\n - B\r\n\r\n# User needs scope (A AND B) OR C\r\nsecurity:\r\n - oauth2:\r\n - A\r\n - B\r\n - oauth2:\r\n - C\r\n```" }, "user": { "login": "mrksbnch", "avatar_url": "https://avatars.githubusercontent.com/u/15638734?v=4" } }, { "id": "D_kwDOAQkWPc4AQT7D", "number": 2993, "title": "Is \"on\" reserved? \"on\" field converts to String true in java", "body": "The following yaml:\r\n\r\n by:\r\n type: string\r\n description: Email Address of User.\r\n on:\r\n type: string\r\n description: Timestamp of creation.\r\n example: 2018-07-10T11:44:00Z\r\n\r\nUsing org.openapitools 5.3.0 creates this:\r\n\r\n @JsonProperty(\"by\")\r\n private String by;\r\n\r\n @JsonProperty(\"true\")\r\n private String true;\r\n", "created_at": "2022-08-03T14:29:43Z", "updated_at": "2024-03-26T18:49:09Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "jkoorts", "avatar_url": "https://avatars.githubusercontent.com/u/10402021?v=4" } }, { "id": "D_kwDOAQkWPc4ASv-c", "number": 3177, "title": "Referencing Response Headers in Generated Response Schema", "body": "I'm working on an API where we're using JWS and we're intending to return a `Replay-Nonce` header in each response that we want to be able to be referenced in the generated code. Right now, we're only generating a Go client and the generated code is not providing anyway to access the header. \r\n\r\nThe OpenAPI YAML we are using looks like:\r\n\r\n```yaml\r\nopenapi: 3.0.0\r\ninfo:\r\n title: Example\r\n version: 1.0.0\r\n\r\nservers:\r\n- url: https://example.net\r\n\r\npaths:\r\n /new-nonce:\r\n head:\r\n operationId: RetrieveNewNonce\r\n responses:\r\n '200':\r\n headers:\r\n Replay-Nonce:\r\n $ref: '#/components/headers/ReplayNonce'\r\n /order:\r\n post:\r\n operationId: OrderItem\r\n requestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n nonce:\r\n type: string\r\n title:\r\n type: string\r\n responses:\r\n '201':\r\n headers:\r\n Replay-Nonce:\r\n $ref: '#/components/headers/ReplayNonce'\r\n content:\r\n application/json:\r\n schema:\r\n $ref: '#/components/schemas/OrderResponse'\r\n\r\ncomponents:\r\n headers:\r\n ReplayNonce:\r\n schema:\r\n type: string\r\n schemas:\r\n OrderResponse:\r\n type: object\r\n properties:\r\n id:\r\n type: integer\r\n title:\r\n type: string\r\n```\r\n\r\nWe've also tried having separate request schema that we add additional code to generate a JWS that would look like:\r\n\r\n```\r\nrequestBody:\r\n required: true\r\n content:\r\n application/json: # application/jose+json doesn't work despite being a registered IANA media type\r\n properties:\r\n protected:\r\n type: string\r\n payload:\r\n type: string\r\n signature:\r\n type: string\r\n required: ['protected', 'payload', 'signature']\r\n```\r\n\r\nBut that naturally doesn't change anything. The generated code from this has a client struct with\r\n\r\n```go\r\nfunc (client *Client) RetrieveNewNonce(\r\n\tctx context.Context,\r\n) error {\r\n// ...\r\n}\r\n```\r\n\r\n(In other words, it's not returning anything other than an error)\r\n\r\nAre we missing something? Is there syntax we're missing that would allow us to extract the value to the response struct?\r\n\r\n", "created_at": "2023-03-01T16:40:44Z", "updated_at": "2024-03-13T18:46:59Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "sigmavirus24", "avatar_url": "https://avatars.githubusercontent.com/u/240830?u=cfe7ddccc58238bedb4176ff2a8dbc200c6a314d&v=4" } }, { "id": "D_kwDOAQkWPc4AURfd", "number": 3300, "title": "How do I reuse a set of parameters between POST and PATCH request?", "body": "I have two endpoints. One for POST, one for PATCH. Both take 20+ params, PATCH taking one extra (the ID to update). How do I share a set of 20 params between POST and PATCH? The docs don't indicate that this is possible, which means I'm looking at having to duplicate the set of 20+ params in both the POST and PATCH definitions. The params component only takes individual params, which means I'd still need to duplicate some code (duplicate arrays of param references). What I'm hoping to be able to do is something like:\r\n\r\n\r\n```yaml\r\npaths:\r\n /api/v2/users:\r\n post:\r\n parameters:\r\n $ref: \"#/components/parameterSet/User\"\r\n /api/v2/users:\r\n patch:\r\n parameters:\r\n $ref: \"#/components/parameterSet/User\"\r\n\r\ncomponents:\r\n parameterSet:\r\n User:\r\n - name: first_name\r\n in: query\r\n description: \"Must not contain numbers or any of the following special characters !@#$%^&*()\"\r\n required: true\r\n schema:\r\n type: string\r\n explode: false\r\n example: \"John\"\r\n - name: last_name\r\n in: query\r\n description: \"Must not contain numbers or any of the following special characters !@#$%^&*()\"\r\n required: true\r\n schema:\r\n type: string\r\n explode: false\r\n example: \"Smith\"\r\n```\r\n\r\nIs this possible at all using Schemas? It doesn't appear so but I could be missing something.", "created_at": "2023-06-19T04:03:34Z", "updated_at": "2024-03-13T18:25:00Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AXuJn", "body": "Just to clarify - are these parameters query parameters, or are they request body fields?\r\n\r\nI'm asking because your example looks like CRUD, and the typical CRUD design is\r\n\r\n```\r\nPOST /users\r\n\r\n{\r\n \"field1\": value1,\r\n ...\r\n}\r\n```\r\n```\r\nPATCH /users/:id\r\n\r\n{\r\n \"field1\": value1,\r\n ...\r\n}\r\n```\r\n\r\nrather than `POST /users?field1=value1&...`." }, "user": { "login": "KieranP", "avatar_url": "https://avatars.githubusercontent.com/u/16620?v=4" } }, { "id": "D_kwDOAQkWPc4ARADG", "number": 3045, "title": "Path Item Object $ref - how does it work?", "body": "I understand that Reference Object is for reusability of parts of the schema. Everywhere where reference is allowed is written that type can be either Reference Object or the other object type.\r\n\r\nExcept in Path Item Object. In Path Item Object are allowed the standard fields and $ref which references another Path Item Object? It also has type string instead of Reference Object and I found description really confusing.\r\n\r\nIs it just inconsistency or does $ref in Path Item Object work differently? I would expect that Callback Object and Paths Object would both accept list of Path Item Object | Reference Object.\r\n\r\nThank you", "created_at": "2022-10-08T19:34:25Z", "updated_at": "2024-03-13T18:24:14Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AOycY", "body": "For now I just merge data from original and referenced Path Item and throw an exception in case field exists in both, because behavior is undefined by specification" }, "user": { "login": "mabar", "avatar_url": "https://avatars.githubusercontent.com/u/20974277?u=3d1ca7b25c91464326767b478b07da70e8563512&v=4" } }, { "id": "D_kwDOAQkWPc4ARA_a", "number": 3049, "title": "Include HTTP version (1.1/2/3) in the spec", "body": "The servers are typically backwards compatible so any API client could connect using the lowest version,\r\nbut including HTTP versions in the spec would tell a client developer that they can use a special library and connect via the higher version.\r\n\r\nI propose something like this:\r\n```yaml\r\nopenapi:\r\n http-versions:\r\n - '1.0'\r\n - '1.1'\r\n - '2.0'\r\n - '3.0'\r\n```", "created_at": "2022-10-10T15:37:33Z", "updated_at": "2024-03-13T18:19:07Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "rafalkrupinski", "avatar_url": "https://avatars.githubusercontent.com/u/3732079?u=4b647b396cd54c57e11b5c73fc09e7cf83acf786&v=4" } }, { "id": "D_kwDOAQkWPc4ARKX_", "number": 3062, "title": "How to define multiple objects to the definitions or components", "body": "Hi , \r\n\r\nI have a definition (swagger-2.0)\r\n```\r\n ErrorCode:\r\n type: object\r\n properties:\r\n code:\r\n type: integer\r\n field: \r\n type: string \r\n```\r\n\r\nI would like to add possible value for this structure into openapi documentation. Practically, code and field corresponds to the same thing (one in numerical and the other in English). I would like all the possible objects be part of the openAPI document, so the client can translate them into multiple languages if needed.\r\nFor example \r\n```\r\n{\r\n\t{\r\n\t\tcode: 1001\r\n\t\tfield: \"missing_file\"\r\n\t},\r\n\t{\r\n\t\tcode: 1002\r\n\t\tfield: \"invalid_file\"\r\n\t},\r\n\t{\r\n\t\tcode: 1003\r\n\t\tfield: \"large_file\"\r\n\t},\r\n\t...\r\n}\r\n```\r\n\r\nHow to specify all the ErrorCode in the openapi document", "created_at": "2022-10-24T11:00:40Z", "updated_at": "2024-03-13T18:15:08Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4APGhS", "body": "```yaml\r\nErrorCode:\r\n type: object\r\n properties:\r\n code:\r\n type: integer\r\n field: \r\n type: string \r\n enum:\r\n - code: 1001\r\n field: missing_file\r\n - code: 1002\r\n field: invalid_file\r\n...\r\n```" }, "user": { "login": "BhanuKiranChaluvadi", "avatar_url": "https://avatars.githubusercontent.com/u/19394175?u=3b0405f0a65a7be9e22da0c06b9738923df394ca&v=4" } }, { "id": "D_kwDOAQkWPc4AReIg", "number": 3079, "title": "How to have examples for an object which has an array of objects", "body": "https://swagger.io/docs/specification/adding-examples/ seems to suggest it cant be done: Note that arrays and array items support single example but not multiple examples.\r\n\r\nI would like to reference several examples.", "created_at": "2022-11-18T17:04:34Z", "updated_at": "2024-03-13T18:13:54Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AP94S", "body": "Multiple schema-level `examples` are supported in OpenAPI 3.1. They must be inline example values and cannot be $refs.\r\n\r\n```yaml\r\nopenapi: 3.1.0\r\n...\r\n\r\ncomponents:\r\n schemas:\r\n MyObject:\r\n type: object\r\n properties:\r\n foo:\r\n type: string\r\n # Multiple property-level examples\r\n examples:\r\n - Hello, world!\r\n - quick brown fox\r\n # Multiple object-level examples\r\n examples:\r\n - foo: Hello, world!\r\n - foo: quick brown fox\r\n \r\n MyArray:\r\n type: array\r\n items:\r\n $ref: '#/components/schemas/MyObject'\r\n # Multiple array-level examples\r\n examples: \r\n -\r\n # The 1st example\r\n - foo: Hello, world!\r\n - foo: quick brown fox\r\n - \r\n # The 2nd example\r\n - foo: Something else\r\n```" }, "user": { "login": "mcrobbj", "avatar_url": "https://avatars.githubusercontent.com/u/10534160?v=4" } }, { "id": "D_kwDOAQkWPc4AOR9G", "number": 2827, "title": "Question: Is it possible define minimum and maximum limits for date/datetime", "body": "Hi,\r\n\r\nI have been trying to figure out how I could add limits to datetime / date based properties / values in open api 3 schema.\r\n\r\nhttps://swagger.io/docs/specification/data-models/data-types/\r\n\r\ndescribes that string can have min length and max length properties but I would like to provide minimum and maximum value for the date\r\n\r\n```\r\ntype: string\r\nminLength: 3\r\nmaxLength: 20\r\n```\r\n\r\nSomething similar what integer has:\r\n\r\n```\r\ntype: integer\r\nminimum: 1\r\nmaximum: 20\r\n```\r\n\r\n\r\nSomething like this?\r\n\r\n```\r\ntype: string\r\nformat: date\r\nminimum: 1996-12-19\r\nmaximum: 2021-12-19\r\n```", "created_at": "2021-12-13T11:38:19Z", "updated_at": "2024-03-13T16:51:30Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AWue_", "body": "As webron said it's not possible to add such constraints using OpenAPI or JSON Schema as-is. Only with hacks like using `pattern` keyword, or you should redesign your API to use UNIX timestamps so you will be able to use `minimum` and `maximum` keywords.\r\n\r\nHowever JSON Schema specification says it's pretty valid to add custom keywords like this:\r\n\r\n```yaml\r\ntype: string\r\nformat: date\r\nminimumDate: 1996-12-19\r\nmaximumDate: 2021-12-19\r\n```\r\n\r\nCustom keywords `minimumDate` and `maximumDate` will be ignored (treated as annotations) by most tools. But if tools you are using support some kind of extensions or plugins you may \"tune\" them to recognise these keywords and you may write your own logic around this. If your tools don't have such API for extensions you may just fork them if these keywords worth this 😁" }, "user": { "login": "Havunen", "avatar_url": "https://avatars.githubusercontent.com/u/2021355?u=19cf8e5fded24b44633b755f9edc10108cf6b3aa&v=4" } }, { "id": "D_kwDOAQkWPc4ARCiZ", "number": 3052, "title": "how should be specified and represent a nested array of a query parameter ?", "body": "- As long as I understand, the query parameter type can define as a nested array.\r\n\r\n `{\r\n \"name\": \"petName\",\r\n \"in\": \"query\",\r\n \"description\": \"Status of pet that needs to be updated\",\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"integer\"\r\n }\r\n }\r\n }\r\n }\r\n }`\r\n\r\n![Capture1](https://user-images.githubusercontent.com/56576410/195317322-bd742c0b-6311-4941-a8e6-327a55edef48.PNG)\r\n\r\n- But this will represent a flat array in the request URL of the swaggers. \r\n\r\n`https://petstore.swagger.io/v2/pet/19?status=available&petName=5&petName=5&petName=66&petName=77`\r\n\r\n![Capture3](https://user-images.githubusercontent.com/56576410/195317007-09ca1cf6-4acc-4370-adb3-e0eba0df0c60.PNG)\r\n![Capture4](https://user-images.githubusercontent.com/56576410/195317278-f05042e7-4f6d-4560-999a-6505969068e7.PNG)\r\n\r\nI was wondering if this scenario is valid or if could you please give me a brief introduction about how to specify and represent a nested array of a query parameter.\r\n\r\nBest regards", "created_at": "2022-10-12T10:19:48Z", "updated_at": "2024-03-13T16:50:36Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AP94q", "body": "As of OpenAPI 3.1, nested arrays and nested objects are **not** actually supported in query parameters because the serialization rules are not defined for nested structures. More info here:\r\n\r\n* #1706\r\n* [OpenAPI path/query parameters nested structure serialization](https://stackoverflow.com/questions/67745944/openapi-path-query-parameters-nested-structure-serialization) on Stack Overflow" }, "user": { "login": "RSH17", "avatar_url": "https://avatars.githubusercontent.com/u/56576410?u=51f132710d3b977a0bf3f775a144601a4d229f80&v=4" } }, { "id": "D_kwDOAQkWPc4AQyLV", "number": 3031, "title": "How should be specified a query/header parameter thats allow duplication", "body": "As long as I understand in HTTP is possible to send duplicated query and header parameters, how the server handle this is out of the scope of the specification but I have observed that the combination of \"name\" and location (expressed by field \"in\") in parameters in Open API should be unique so what is the correct way to specify that an API allow multiple query/headers, for example:\r\n\r\n```\r\nHTTP://myapi.com?id=123&id=345\r\n```\r\nBest regards", "created_at": "2022-09-17T11:25:36Z", "updated_at": "2024-03-13T16:50:14Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AOJkv", "body": "\"[4.8.12.3 Style Values](https://spec.openapis.org/oas/latest.html#style-values)\" section covers how parameters may be represented with different data types (also check out table with examples in \"[4.8.12.4 Style Examples](https://spec.openapis.org/oas/latest.html#style-examples)\" section below). It is possible to represent array of query-parameters as you wish with `style: form`, `explode: true` and using schema of type `array` in `schema` keyword. \r\n\r\nExample:\r\n\r\n```yaml\r\nname: color\r\nin: query\r\nstyle: form\r\nexplode: true\r\nschema:\r\n type: array\r\n uniqueItems: true\r\n items:\r\n enum: [blue, black, brown]\r\n```\r\n```\r\ncolor=blue&color=black&color=brown\r\n```\r\n\r\nHowever, OpenAPI specification does not cover multiple headers with same name, so behaviour is undefined 😔 But it's nice idea to visit \"[Big thoughts for 4.0](https://github.com/OAI/OpenAPI-Specification/discussions/2930)\" discussion where we gather ideas for the next major update of the spec and suggest yours about headers with attached references to HTTP spec, existing issues and discussions if they exist." }, "user": { "login": "joolfe", "avatar_url": "https://avatars.githubusercontent.com/u/1319632?u=ef14a0c73c81bfae9308ecbcb427ac142571e9c7&v=4" } }, { "id": "D_kwDOAQkWPc4ARKKN", "number": 3060, "title": "how could we define the mutualTLS ?", "body": "> Under Open API specification 3.1.0 version, there is a defined Security Scheme type called mutualTLS. how could we define this type using code? \r\ncould you please give an example of this type? ", "created_at": "2022-10-24T04:06:12Z", "updated_at": "2024-03-13T16:49:30Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "RSH17", "avatar_url": "https://avatars.githubusercontent.com/u/56576410?u=51f132710d3b977a0bf3f775a144601a4d229f80&v=4" } }, { "id": "D_kwDOAQkWPc4AU-0i", "number": 3344, "title": "Documenting an API with all operations under a single path", "body": "I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:\r\n```\r\n/api?action=action1&some-param=1\r\n/api?action=action2&other-aparam=2\r\n```\r\nIf I would put all parameters under a single path, that would force all parameters under that path, too and would mix a lot of parameters that are only valid on certain actions.\r\n\r\nThe Swagger editor doesn't let me create multiple entries for the same path, even if the action parameter is required with a different value on each. and doesn't accept `/api?action=action1` as a separate path either.\r\n\r\nIs the unique path a requirement from Swagger or from the OpenAPI spec ?\r\n\r\nIs there a good workaround how to handle this ?\r\n\r\nThanks!", "created_at": "2023-08-08T16:33:22Z", "updated_at": "2024-03-13T16:44:48Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AaKSL", "body": "Swagger is a tooling vendor for the OpenAPI specification. The OAS specification requires each path is unique up to the point of the `?`, the query separator. \r\n\r\nThe way your api is designed makes it very difficult to construct a human readable OpenAPI description. OAS does not have any \"scenario\" type of description available. This means all possible query parameters of a single endpoint should be described. But there is no way to distinguish which sets of parameters will provide a different response payload. You can use `examples` to provide different representations of the payload and you can also provide multiple payloads using composition keywords such as `oneOf` or `anyOf` to describe the possible data instances. \r\n\r\n```yaml\r\nopenapi: 3.0.3\r\ninfo:\r\n title: test\r\n version: 1.0.0\r\npaths:\r\n /api:\r\n get:\r\n summary: summary of api\r\n parameters:\r\n - name: action\r\n in: query\r\n required: true\r\n schema:\r\n type: string\r\n - name: some-pararm\r\n in: query\r\n schema:\r\n type: string\r\n - name: other-pararm\r\n in: query\r\n schema:\r\n type: string\r\n responses:\r\n 200:\r\n description: OK\r\n content:\r\n application/json:\r\n schema: \r\n anyOf:\r\n - $ref: \"#/components/schemas/action_some-param\"\r\n - $ref: \"#/components/schemas/action_other-param\"\r\n examples:\r\n action_some-param:\r\n value: {}\r\n action_other-param:\r\n value: {}\r\ncomponents:\r\n schemas:\r\n action_some-param:\r\n type: object\r\n properties:\r\n some-param-payload:\r\n type: string\r\n action_other-param:\r\n type: object\r\n properties:\r\n other-param-payload:\r\n type: string\r\n\r\n\r\n```\r\n" }, "user": { "login": "willamowius", "avatar_url": "https://avatars.githubusercontent.com/u/6840544?u=196e57c8b7ef87b3b5997a657f93fb0abf4e2f4b&v=4" } }, { "id": "D_kwDOAQkWPc4AVLlQ", "number": 3358, "title": "Is Query parameters need to encode when parameter type is array and items are define as objects?", "body": "when the query parameter is defined as type=array and its item as object. when executing, values get encoded. is that the behavior?\r\n\r\n`\"parameters\": [\r\n {\r\n \"name\": \"tags\",\r\n \"in\": \"query\",\r\n \"description\": \"Tags to filter by\",\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"object\"\r\n }\r\n }\r\n }\r\n ]`\r\n\r\nresult curl: curl -X 'GET' \\\r\n 'https://raw.githubusercontent.com/api/v3/pet/findByTags?tags=%7B%20%22R%22%3A%20100%2C%20%22G%22%3A%20200%2C%20%22B%22%3A%20150%20%7D&tags=%7B%20%22R%22%3A%20%22FF%22%2C%20%22G%22%3A%20%22GG%22%2C%20%22B%22%3A%20%22yu%22%20%7D' \\\r\n -H 'accept: application/xml'", "created_at": "2023-08-24T02:27:39Z", "updated_at": "2024-03-13T16:42:49Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AfarH", "body": "The Parameter Object does not say anything about encoding, so this behavior is surprising. You should file an issue with whatever tool you are using, as we cannot help debug tooling problems here in the specification repo." }, "user": { "login": "RSH17", "avatar_url": "https://avatars.githubusercontent.com/u/56576410?u=51f132710d3b977a0bf3f775a144601a4d229f80&v=4" } }, { "id": "D_kwDOAQkWPc4AURgG", "number": 3301, "title": "Authority/specification governing `$ref` in Schema Object", "body": "Which specification is responsible for describing the processing of `$ref` in Schema Objects?\r\n\r\n- OpenAPI 3.1 (ultimate authority)\r\n- JSON Schema 2020-12 (any authority?)\r\n\r\nIf you believe that `$ref` in Schema Objects is processed according to the JSON Schema specification, could you tell me why [examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) like this are guaranteed to work:\r\n\r\n```json\r\n\"$ref\": \"#/components/schemas/Address\"\r\n```\r\n\r\nNote that I can see how I *can* make such a reference work. The question is *which rules mandate and guarantee the behavior* assumed/intended by the author of this example (and many similar examples). If an implementation did not support this behavior, which rules would it break? How would we argue in a hypothetical court case where good will and common sense are weak arguments?\r\n\r\nIf you believe that `$ref` in Schema Objects is not processed according to the JSON Schema specification, where is the JSON Schema behavior overruled (why would `$ref` not be subject to: \"Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics.\")? Also, if you believe that `$ref` is not processed according to the JSON Schema specification, please explain this examples [from the OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) specification (notice `type` as sibling of `$ref`):\r\n\r\n```yaml\r\nitems:\r\n type: object\r\n $ref: '#/components/schemas/Address'\r\n```\r\n", "created_at": "2023-06-19T04:27:26Z", "updated_at": "2024-03-13T16:42:03Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AXvA5", "body": "> Which specification is responsible for describing the processing of `$ref` in Schema Objects?\r\n> * OpenAPI 3.1 (ultimate authority)\r\n> * JSON Schema 2020-12 (any authority?)\r\n\r\n(This answer is specifically about OAS 3.1. Earlier versions are slightly different in this regard.)\r\n\r\nThere are two types of $refs:\r\n\r\n1. Within _schemas_ (aka [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object)), the $refs are processed according to the JSON Schema rules. For example, given a schema definition based JSON Schema 2020-12 (the default version used by OAS 3.1), [this is the relevant section](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.3.1) of the JSON Schema spec.\r\n\r\n2. Everywhere else (e.g. $refs to parameter/response/requestBody definitions) the $refs are the so-called \"Reference Objects\" and are processed according to [this section](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object) of the OpenAPI 3.1 Spec.\r\n" }, "user": { "login": "watuwo", "avatar_url": "https://avatars.githubusercontent.com/u/83006066?v=4" } }, { "id": "D_kwDOAQkWPc4AU2kI", "number": 3341, "title": "Refactor of Server url and path", "body": "Hi all,\r\n\r\nMy question is related to the server URL and path. Let's assume we have the following specification (I will omit some parameters):\r\n``` yaml\r\nservers: \r\n - url: https://fake-environment.com\r\npaths:\r\n - /cars: # POST - GET\r\n $ref: paths/cars.yaml \r\n - /cars/test1: # GET\r\n $ref: paths/cars-test1.yaml \r\n - /cars/test2: # GET \r\n $ref: paths/cars-test2.yaml \r\n .... (All paths start with `/cars`)\r\n```\r\n\r\nIn a refactor, I decide to move `/cars` to the server URL and it looks like this: \r\n\r\n``` yaml\r\nservers: \r\n - url: https://fake-environment.com/cars\r\npaths:\r\n - /: # POST - GET\r\n $ref: paths/cars.yaml \r\n - /test1 : # GET\r\n $ref: paths/cars-test1.yaml \r\n - /test2: # GET\r\n $ref: paths/cars-test2.yaml \r\n ```\r\n\r\nHowever this is a little bit weird, because if I do a POST in the original one, it was POST https://fake-environment.com/cars, but in the new one it will be POST https://fake-environment.com/cars/ . So my question here is: \r\n\r\n- Does it make sense this refactor? \r\n- Should I rename the first path to `/create` or something like that? This is related to the restriction where all paths must start with `/`.\r\n- Is there any way to avoid that `/` at the end of the path? \r\n\r\nIf you need more explanation, please let me know. \r\n\r\nThanks in advance!!! ", "created_at": "2023-08-02T07:54:12Z", "updated_at": "2024-03-13T16:39:02Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AfnqG", "body": "You can't avoid the `/` at the end of the path because you can't define a Path Item under the empty string- it has to at least be `\"/\"`. So no, you can't do this refactor I'm afraid." }, "user": { "login": "JRamonMC", "avatar_url": "https://avatars.githubusercontent.com/u/20944056?u=94abf4c8a0369a74e19c745ddd60e917d3adf57a&v=4" } }, { "id": "D_kwDOAQkWPc4AVgA7", "number": 3371, "title": "Proposal to add 'archetype' field to path specifications", "body": "I would like to propose the addition of an 'archetype' field to path specifications to allow for the declaration of the architectural pattern that a path implements. There are two major reasons for this that I lay out in my proposal.\r\n\r\n1. It is vital information for automated testing tools to allow tools to scan APIs and ensure that they meet architectural standards. This allows architectural or design constraints to be tested and applied across a larger API set.\r\n2. It is very useful information for code generators and or dynamic clients that want to create interop code or other means of automatically building communication mechanisms with an api.\r\n\r\nhttps://github.com/OAI/OpenAPI-Specification/pull/3369\r\n", "created_at": "2023-09-16T12:32:18Z", "updated_at": "2024-02-22T18:25:45Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "myronww", "avatar_url": "https://avatars.githubusercontent.com/u/239715?v=4" } }, { "id": "D_kwDOAQkWPc4ARIhK", "number": 3058, "title": "Hide Schemas below but not routes?", "body": "Hi, \r\n\r\ni tried to get rid of the fastapi-users (python) schemas in the bottom dropdown in swagger without breaking swagger:\r\n\r\n```\r\nfrom fastapi.openapi.utils import get_openapi\r\n\r\napp = FastAPI(redoc_url=None)\r\n\r\ndef custom_openapi():\r\n if app.openapi_schema:\r\n return app.openapi_schema\r\n\r\n openapi_schema = get_openapi(\r\n title=\"Api\",\r\n version=\"1.0.0\",\r\n routes=app.routes,\r\n description=\"This is the API documentation\",\r\n tags=tags_metadata\r\n )\r\n\r\n for model in (\r\n 'BearerResponse', 'Body_auth_jwt_login_auth_jwt_login_post', 'ErrorModel', 'HTTPValidationError',\r\n 'ValidationError',\r\n 'UserCreate', 'UserRead', 'UserUpdate'):\r\n openapi_schema[\"components\"][\"schemas\"].pop\r\n\r\n app.openapi_schema = openapi_schema\r\n return app.openapi_schema\r\n\r\n\r\napp.openapi = custom_openapi\r\n```\r\n\r\nBut i get this errors when i click onevery route to dropdown it:\r\n\r\n```\r\nErrors\r\n\r\nResolver error at paths./auth/jwt/login.post.requestBody.content.application/x-www-form-urlencoded.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/Body_auth_jwt_login_auth_jwt_login_post does not exist in document\r\nResolver error at paths./auth/jwt/login.post.responses.200.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/BearerResponse does not exist in document\r\nResolver error at paths./auth/jwt/login.post.responses.400.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/ErrorModel does not exist in document\r\nResolver error at paths./auth/jwt/login.post.responses.422.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/HTTPValidationError does not exist in document\r\nResolver error at paths./admin/register.post.requestBody.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/UserCreate does not exist in document\r\nResolver error at paths./admin/register.post.responses.201.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/UserRead does not exist in document\r\nResolver error at paths./admin/register.post.responses.400.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/ErrorModel does not exist in document\r\nResolver error at paths./admin/register.post.responses.422.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/HTTPValidationError does not exist in document\r\nResolver error at paths./admin/users/{id}.get.responses.200.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/UserRead does not exist in document\r\nResolver error at paths./admin/users/{id}.get.responses.422.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/HTTPValidationError does not exist in document\r\nResolver error at paths./admin/users/{id}.delete.responses.422.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/HTTPValidationError does not exist in document\r\nResolver error at paths./admin/users/{id}.patch.requestBody.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/UserUpdate does not exist in document\r\nResolver error at paths./admin/users/{id}.patch.responses.200.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/UserRead does not exist in document\r\nResolver error at paths./admin/users/{id}.patch.responses.400.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/ErrorModel does not exist in document\r\nResolver error at paths./admin/users/{id}.patch.responses.422.content.application/json.schema.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/HTTPValidationError does not exist in document\r\nResolver error at paths./admin/list-users.get.responses.200.content.application/json.schema.items.$ref\r\nCould not resolve reference: Could not resolve pointer: /components/schemas/UserRead does not exist in document\r\n\r\n```\r\n\r\nIs there a other way to disable the displaying in Swagger, without breaking the schema? The \"include_in_schema = False\" removes routes with schemas on the bottom dropdown of the site. I only want to stop displaying the schema in the bottom dropdown in swagger. Or is there a way to change the order of the schemas there so i can move the important ones up to the list?\r\n\r\nThank you for helping.", "created_at": "2022-10-20T23:43:37Z", "updated_at": "2024-03-18T11:24:14Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Afnup", "body": "This repository is for the specification, not individual tools. Please raise your issue with your tooling vendor." }, "user": { "login": "hsul-git", "avatar_url": "https://avatars.githubusercontent.com/u/103585823?v=4" } }, { "id": "D_kwDOAQkWPc4ARB79", "number": 3050, "title": "What licenses would you recommend for openapi schema?", "body": "What license would you recommend for API schema that would free the client code generated from any legal burden?\r\n\r\nSome might argue that a generated client is a translation or other derivative work. distributing the schema under CC SA for example, might impose the license on the generated client.\r\n\r\nAny recommendations?", "created_at": "2022-10-11T15:28:20Z", "updated_at": "2024-01-29T19:21:51Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "rafalkrupinski", "avatar_url": "https://avatars.githubusercontent.com/u/3732079?u=4b647b396cd54c57e11b5c73fc09e7cf83acf786&v=4" } }, { "id": "D_kwDOAQkWPc4AR31U", "number": 3103, "title": "Different types of properties behavior in schemas with `allOf`", "body": "Hi there! I have a question about different types of properties in schemas with `allOf`. Faced that different toolings interpret this case in another way. And I want to be sure what is the correct way to implement this is and why. \r\n\r\nPlease, see the example below.\r\n\r\nIt seems, there are 3 possible scenarios with different tools I've met: \r\n1. `Bar.property1` infers as `object`\r\n2. `Bar.property1` infers as `array`\r\n3. Validation error\r\n\r\n```yml\r\nopenapi: 3.0.1\r\ninfo:\r\n title: example\r\n description: allOf example\r\n version: 0.1.0\r\nservers:\r\n - url: 'https://example.com'\r\npaths:\r\n '/foo':\r\n delete:\r\n responses:\r\n '200':\r\n description: OK\r\ncomponents:\r\n schemas:\r\n Foo:\r\n type: object\r\n properties: \r\n property1: \r\n type: object\r\n Bar:\r\n type: object\r\n properties:\r\n property1:\r\n type: array\r\n items:\r\n type: string\r\n allOf:\r\n - $ref: '#/components/schemas/Foo'\r\n```\r\n\r\nI've tried to look for the answer in [OpenAPI v3.0.1 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#schema-object)\r\n\r\n> This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/).\r\n\r\n> properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).\r\nThe following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.\r\n\r\n> type - Value MUST be a string. Multiple types via an array are not supported.\r\n\r\n> The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.\r\n\r\nShould we validate the object separately against `object` and separately against `array` in that case? Or is another behavior here expected?\r\n\r\nRelated:\r\nhttps://github.com/swagger-api/swagger-editor/issues/3732\r\n\r\n\r\n\r\n", "created_at": "2022-12-22T09:30:01Z", "updated_at": "2024-01-29T19:20:36Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AS4y0", "body": "The `Bar` schema is valid. But it won't work as you expect.\r\n\r\nSchema instance (a value you are validating against a schema) is valid only when it was successfully validated agains all keywords in a schema.\r\n\r\nLet's say this is a value you are validating against `Bar` schema:\r\n\r\n```json\r\n{\r\n \"property1\": []\r\n}\r\n```\r\n\r\nThis is how validator will validate the value against your schemas:\r\n\r\n- Evaluating `/components/schemas/Bar/type` keyword: is passed value has type `object`? Yes.\r\n- Evaluating `/components/schemas/Bar/properties`:\r\n - Evaluating `/components/schemas/Bar/properties/property1/type` keyword: is passed value has type `array`? Yes.\r\n- Evaluating `/components/schemas/Bar/allOf` keyword:\r\n 1. Evaluating `/components/schemas/Bar/allOf/0/$ref` keyword: \r\n - Evaluating `/components/schemas/Foo/type` keyword: is passed value has type `object`? Yes.\r\n - Evaluating `/components/schemas/Foo/properties`:\r\n - Evaluating `/components/schemas/Foo/properties/property1/type` keyword: is passed value has type `object`? No.\r\n\r\nAs you can see, validation will fail because passed JSON is not valid against the single keyword. Because `property1` can't hold a value of types `array` and `object` at the same time.\r\n\r\nIt's important to note that `allOf` keyword is not an *inheritance* or *merge* solution. It's like an intersection. A value should be valid against all schemas defined in `allOf` keyword.\r\n\r\nThis repository is mostly about OpenAPI spec. You are welcome to ask questions about JSON Schema in [official repository discussions on GitHub](https://github.com/json-schema-org/community/discussions) 🙂" }, "user": { "login": "mtovt", "avatar_url": "https://avatars.githubusercontent.com/u/96553816?v=4" } }, { "id": "D_kwDOAQkWPc4AUTjD", "number": 3302, "title": "Meta-Defining JSON Schema inside of an openAPI spec (Version 3.0.2)", "body": "The following definition of a json_schema is found in an openAPI specification I'm currently working with:\r\n\r\n```\r\n \"json_schema\": {\r\n \"type\": \"object\",\r\n \"title\": \"JSON Schema\",\r\n \"description\": \"A JSON Schema compliant to [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or later.\\n\\nJSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved).\\nThis allows clients to consume the schemas much better.\\nClients are not expected to support dereferencing `$refs`.\\n\\nNote: The specified schema in the OpenAPI document is only a common subset of JSON Schema.\\nAdditional keywords from the JSON Schema specification MAY be used.\",\r\n \"properties\": {\r\n \"$schema\": {\r\n \"description\": \"The JSON Schema version. If not given in the context of openEO,\\ndefaults to `draft-07`.\\n\\nYou may need to add the default value for `$schema` property explicitly to the JSON Schema\\nobject before passing it to a JSON Schema validator.\",\r\n \"type\": \"string\",\r\n \"format\": \"uri\",\r\n \"default\": \"http://json-schema.org/draft-07/schema#\"\r\n },\r\n \"$id\": {\r\n \"description\": \"ID of your JSON Schema.\",\r\n \"type\": \"string\",\r\n \"format\": \"uri\"\r\n },\r\n \"type\": {\r\n \"description\": \"The allowed basic data type(s) for a value.\\n\\nIf this property is not present, all data types are allowed.\",\r\n \"oneOf\": [\r\n {\r\n \"$ref\": \"#/components/schemas/json_schema_type\"\r\n },\r\n {\r\n \"type\": \"array\",\r\n \"minItems\": 1,\r\n \"uniqueItems\": true,\r\n \"items\": {\r\n \"$ref\": \"#/components/schemas/json_schema_type\"\r\n }\r\n }\r\n ]\r\n },\r\n \"pattern\": {\r\n \"type\": \"string\",\r\n \"format\": \"regex\",\r\n \"description\": \"The regular expression a string value must match against.\"\r\n },\r\n \"enum\": {\r\n \"type\": \"array\",\r\n \"items\": {},\r\n \"description\": \"An exclusive list of allowed values.\"\r\n },\r\n \"minimum\": {\r\n \"type\": \"number\",\r\n \"description\": \"The minimum value (inclusive) allowed for a numerical value.\"\r\n },\r\n \"maximum\": {\r\n \"type\": \"number\",\r\n \"description\": \"The maximum value (inclusive) allowed for a numerical value.\"\r\n },\r\n \"minItems\": {\r\n \"type\": \"number\",\r\n \"minimum\": 0,\r\n \"default\": 0,\r\n \"description\": \"The minimum number of items required in an array.\"\r\n },\r\n \"maxItems\": {\r\n \"type\": \"number\",\r\n \"minimum\": 0,\r\n \"description\": \"The maximum number of items required in an array.\"\r\n },\r\n \"items\": {\r\n \"description\": \"Specifies schemas for the items in an array.\",\r\n \"anyOf\": [\r\n {\r\n \"type\": \"array\",\r\n \"minItems\": 1,\r\n \"items\": {\r\n \"$ref\": \"#/components/schemas/json_schema\"\r\n }\r\n },\r\n {\r\n \"$ref\": \"#/components/schemas/json_schema\"\r\n }\r\n ]\r\n }\r\n },\r\n \"additionalProperties\": {\r\n \"description\": \"You can add any other property supported by the JSON Schema version that is given through the property `$schema`, so either [draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or any later version.\"\r\n }\r\n },\r\n```\r\n\r\nThis is then being referenced to be used in multiple parts of the document to describe the JSON responses of the API. (Here's a link to the entire document https://api.openeo.org/)\r\n\r\nTo my understanding this was done in an attempt to mimic JSON Schema dialects introduced in 3.1.0.\r\n\r\nI believe this to not only be superfluous, as all the functionality that is needed is already covered by the inherent existence of the openAPI version of the JSON Schema (https://spec.openapis.org/oas/v3.0.2#schema-object), but also strictly unsupported because of the use of $id and $schema, which are covered by JSON Schema (https://json-schema.org/), hence their inclusion in this meta-implementation of it, but not supported in the context of a openAPI document (openapi-core library fails at validating this spec because of the inclusion of the $id property).\r\n\r\nI was discussing this with the person who made this specific specification and he told me that I was wrong in thinking this and I should ask the openAPI community itself. (https://github.com/Open-EO/openeo-api/issues/499)", "created_at": "2023-06-21T12:16:00Z", "updated_at": "2024-01-29T19:18:25Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AX07J", "body": "> Firstly, is the json_schema object not a schema object and therefore has to follow the guidelines outlined here https://spec.openapis.org/oas/v3.0.2#schema-object disallowing certain properties (such as $id)?\r\n\r\nThat schema doesn't use `$id` or `$schema` as a keyword. Those are property names.\r\n\r\n```json\r\n{\r\n \"$id\": \"...\" // <= This is a keyword and would not be allowed\r\n \"properties\": {\r\n \"$id\": { // <= This is just a property name. It just happens to be spelled the same as the keyword.\r\n } \r\n }\r\n}\r\n```\r\n\r\n> Secondly, the \"/collections/{collection_id}/queryables\" is the only endpoint with application/schema+json mimetype, but the json_schema is referenced in way more endpoints than that one.\r\n\r\nYes, other resources seem to include schemas embedded in their responses. That's similar to how OpenAPI has schemas embedded in them. The schemas being part of a response is no different than a schema being the whole response.\r\n\r\n> Lastly, why then is the spec-validation failing due to the existence of $id fields if they would be fine to have in a openAPI document in the places that they are in. (specifically openapi-core python library)\r\n\r\nSounds like a bug in that library. I'd suggest opening an issue with them." }, "user": { "login": "rtmiz", "avatar_url": "https://avatars.githubusercontent.com/u/14345617?u=9b820193fd4b6c4ecd6a97a536a4280b2abf339b&v=4" } }, { "id": "D_kwDOAQkWPc4APYgQ", "number": 2918, "title": "Should required properties in a component be allowed if not included in properties?", "body": "What a title.\r\n\r\nI noticed today that we are sending data in our responses that is not described in the component spec. In the example schema I'll post below I have a `created_at` entry that has no description inside properties. This seems to validate in most validation tools. Should it be valid?\r\n\r\n```\r\n{\r\n \"openapi\": \"3.0.3\",\r\n \"info\": {\r\n \"title\": \"Hello\",\r\n \"version\": \"1.0.1\"\r\n },\r\n \"paths\": {\r\n \"/objects\": {\r\n \"get\": {\r\n \"summary\": \"Get all objects\",\r\n \"description\": \"Returns an array of TestObject that is visible to the user role\",\r\n \"operationId\": \"fetchObjects\",\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"A list of objects\",\r\n \"content\": {\r\n \"application/json\": {\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"$ref\": \"#/components/schemas/Object\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n },\r\n \"components\": {\r\n \"schemas\": {\r\n \"Object\": {\r\n \"required\": [\"id\", \"title\", \"created_at\"],\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"id\": {\r\n \"type\": \"integer\"\r\n },\r\n \"title\": {\r\n \"description\": \"Title for the new object.\",\r\n \"type\": \"string\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n```", "created_at": "2022-04-25T13:41:49Z", "updated_at": "2024-01-29T19:17:21Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AKCH8", "body": "Your example is valid and is equivalent to this (YAML version for readability):\r\n```yaml\r\nObject:\r\n required: [id, title, created_at]\r\n type: object\r\n properties:\r\n id:\r\n type: integer\r\n title:\r\n description: Title for the new object.\r\n type: string\r\n created_at: {} # The value can be of any type\r\n```\r\n\r\nExtra properties not explicitly defined under `properties` **are allowed** unless the schema has `additionalProperties: false` / `unevaluatedProperties: false`.\r\n\r\nYou can use a linter to enforce that the properties listed in the `required` list are explicitly defined in `properties`." }, "user": { "login": "mull", "avatar_url": "https://avatars.githubusercontent.com/u/646665?v=4" } }, { "id": "D_kwDOAQkWPc4ARh1F", "number": 3081, "title": "Extra fields in the presence of `$ref`", "body": "I recently started to implement an OAI parser in D, and immediately hit an issue with my first test case, the [Gitlab openapi.yml](https://gitlab.com/gitlab-org/gitlab/-/raw/51e15dfa26a9f36e68cc9276b96c59a866dd8bd2/doc/api/openapi/openapi.yaml).\r\n\r\nAs it turns out, it has ref to the root of the document, outside of components (https://github.com/OAI/OpenAPI-Specification/issues/2038):\r\n\r\n```yaml\r\n# Other OpenAPI Object fields... \r\npaths:\r\n # METADATA\r\n /v4/metadata:\r\n $ref: '#/metadata'\r\n\r\n # VERSION\r\n /v4/version:\r\n $ref: '#/version'\r\n\r\n # More...\r\nmetadata:\r\n get:\r\n tags:\r\n - metadata\r\n summary: 'Retrieve metadata information for this GitLab instance.'\r\n operationId: 'getMetadata'\r\n # More stuff...\r\n\r\nversion:\r\n get:\r\n tags:\r\n - version\r\n summary: 'Retrieve version information for this GitLab instance.'\r\n # More stuff...\r\n```\r\n\r\nThis works with the [swagger inspector](https://inspector.swagger.io/builder) but not with the ruby library, for example:\r\n```\r\nirb(main):008:0> document = Openapi3Parser.load_url(\"https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/api/openapi/openapi.yaml\")\r\n=> Openapi3Parser::Document(openapi_version: 3.0, root_source: Openapi3Parser::Source(input: https://gitlab.com/gitlab-org/gitlab/-/raw/m...\r\nirb(main):009:0> document.valid?\r\n=> false\r\nirb(main):010:0> document.errors\r\n=> Openapi3Parser::Validation::ErrorCollection(errors: {\"#/\"=>[\"Unexpected fields: metadata, version, accessRequestsProjects, accessRequestsProjectsApprove, accessRequestsProjectsDeny, accessRequestsGroups, accessRequestsGroupsApprove, accessRequestsGroupsDeny, accessTokens and accessTokensRevoke\"], \"#/paths/%2Fv4%2Fprojects%2F%7Bid%7D%2Faccess_tokens/%24ref\"=>[\"#/accessTokens does not resolve to a valid object\"]})\r\n```\r\n\r\nFrom reading the specs, this should not be allowed: the fields do not match the [Specification Extensions](https://swagger.io/specification/#specification-extensions) and do not match the name of field in the `OpenAPI Object`.\r\n\r\nCould someone confirm that this is indeed a bug ?", "created_at": "2022-11-23T16:45:52Z", "updated_at": "2024-01-29T19:14:45Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Geod24", "avatar_url": "https://avatars.githubusercontent.com/u/2180215?v=4" } }, { "id": "D_kwDOAQkWPc4ASBLX", "number": 3113, "title": "Can you set required fields in a request body of fields in a \"oneOf\" or \"anyOf\"", "body": "Hi,\r\n\r\nI have been trying to work out how to set fields as required for a specific method requestBody when I am using a \"oneOf\" in a schema object.\r\n\r\nI know how to set required fields of a referenced object, but when you try set the required properties of oneOf objects the same way, it does not work.\r\n\r\nI also know that I can set the required fields in the schema object itself, however I do not want to do this as the required fields differ on each method (i.e all fields required for a post, but only some required for a patch).\r\n\r\nSo essentially, how do I set the required fields in a request body of a schema used in oneOf?\r\n\r\nI have created an example below, in it, I want to:\r\n\r\n- Set the fields Bird - wingSpan and beakLength as required in the Post method \r\n- Set the fields Cat - tailLength as required in the Post method\r\n- Not have any required fields for Bird and Cat in the Patch method.\r\n\r\n```\r\nopenapi: 3.0.3\r\nservers:\r\n - description: SwaggerHub API Auto Mocking\r\n url: https://virtserver.swaggerhub.com/Enable-Networks/TroubleTicket/1.0.0\r\n\r\ninfo:\r\n title: Pet API\r\n version: 1.0.0\r\n\r\npaths:\r\n /pet:\r\n patch:\r\n summary: Update a pet\r\n requestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n allOf:\r\n - $ref: \"#/components/schemas/Pet\"\r\n - type: object\r\n required:\r\n - age\r\n responses:\r\n \"204\":\r\n description: The request was a success and the pet was successfully created.\r\n\r\n post:\r\n summary: Create a pet\r\n requestBody:\r\n required: true\r\n content:\r\n application/json:\r\n schema:\r\n allOf:\r\n - $ref: \"#/components/schemas/Pet\"\r\n - type: object\r\n required:\r\n - name\r\n - age\r\n - species\r\n properties:\r\n species:\r\n type: object\r\n required:\r\n - ???\r\n responses:\r\n \"204\":\r\n description: The request was a success and the pet was successfully created.\r\n\r\ncomponents:\r\n schemas:\r\n Cat:\r\n type: object\r\n properties:\r\n tailLength: \r\n type: integer\r\n whiskerLength:\r\n type: integer\r\n Bird:\r\n type: object \r\n properties:\r\n wingSpan:\r\n type: integer\r\n beakLength:\r\n type: integer\r\n highestAltitude:\r\n type: integer\r\n\r\n Pet:\r\n type: object\r\n properties:\r\n name:\r\n type: string\r\n age:\r\n type: string\r\n species:\r\n oneOf:\r\n - $ref: '#/components/schemas/Cat'\r\n - $ref: '#/components/schemas/Bird'\r\n```\r\n\r\nAny help on this would be appreciated!", "created_at": "2023-01-04T20:15:08Z", "updated_at": "2024-01-29T19:13:21Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "JordanGardiner-enable", "avatar_url": "https://avatars.githubusercontent.com/u/54789317?v=4" } }, { "id": "D_kwDOAQkWPc4ATxSW", "number": 3272, "title": "How to generate the openapi.json spec file", "body": "I am completely new to open api. Is there a tool that one can use to generate this file, perhaps against a RESTFULL API service repo or does it need to be manually edited? If so, is there an editor that can be used for that purpose?\r\n\r\nCan yaml be used instead of json? I am trying to figure out what I need to feed to the zap_api_scan.py -target argument.", "created_at": "2023-05-10T18:28:09Z", "updated_at": "2024-01-29T19:10:28Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "denismp", "avatar_url": "https://avatars.githubusercontent.com/u/2000960?u=1239efcdf8ceda676e4948e052629d4678993243&v=4" } }, { "id": "D_kwDOAQkWPc4AUgf7", "number": 3323, "title": "OpenAPI spec to HTTP request", "body": "OpenAPI specification describes URL path, the HTTP method, the body of the request (if needed), the parameters (if needed), the properties (if needed), etc.\r\n\r\nFor instance, for the OpenAPI specification below\r\n\r\n```yaml\r\npaths:\r\n \"/stub\":\r\n patch:\r\n requestBody:\r\n content:\r\n application/json:\r\n schema:\r\n type: object\r\n properties:\r\n name:\r\n type: string\r\n description: The name of the stub.\r\n```\r\n\r\nThe corresponding HTTP request is for the `/stub` path, using `PATCH` HTTP method and the request body is a JSON `{\"name\":\"some name\"}`.\r\n\r\nIs there any tool that reads OpenAPI specification file and issue a request per the specification or returns an HTTP request object (of some sort)?", "created_at": "2023-07-06T21:02:21Z", "updated_at": "2024-01-29T19:06:36Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "electriquo", "avatar_url": "https://avatars.githubusercontent.com/u/28758375?v=4" } }, { "id": "D_kwDOAQkWPc4ARn9x", "number": 3087, "title": "Why \"all other properties in a \"$ref\" object are ignored\"?", "body": "I was curious about why this is the case - I'm building an API from the ground up using Open API 3.0, and in some of my schemas I'm using compositional references to build the schemas, for example:\r\n\r\n```\r\n UserId:\r\n description: The unique identifier of a user\r\n type: integer\r\n example: 751\r\n\r\n Quote:\r\n type: object\r\n properties:\r\n id:\r\n $ref: \"#/components/schemas/QuoteId\"\r\n example: 1000\r\n company:\r\n type: string\r\n description: Company name at the time of the quote\r\n example: Dunder Mifflin\r\n maxLength: 140\r\n prepared_by:\r\n $ref: \"#/components/schemas/UserId\"\r\n example: 751\r\n description: ID of the user who created the quote\r\n approved_by:\r\n $ref: \"#/components/schemas/UserId\"\r\n example: 751\r\n description: ID of the user who approved the quote\r\n```\r\n\r\nHowever, when editting using https://editor-next.swagger.io/, I'm getting errors on the lines such as `prepared_by` and `approved_by`, stating `All other properties in a \"$ref\" object are ignored`. In this case, it would seem to me that these fields would or could have different descriptions than the schema they are referring to, because they represent something else.\r\n\r\nIs there any other way of doing this, or does someone have an explanation as to why this is a feature of the spec?", "created_at": "2022-12-02T00:16:41Z", "updated_at": "2024-01-29T19:00:05Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "geoff-maddock", "avatar_url": "https://avatars.githubusercontent.com/u/55493?u=e455d661bd0987e03f8ce707ff01488b4342e814&v=4" } }, { "id": "D_kwDOAQkWPc4AXaGS", "number": 3526, "title": "allow any property as sibling of $ref", "body": "it's nice to see that openapi spec 3.1.0 allows that one can use description alongside of `$ref`. However, why the restriction to `description` and `summary` only? I would like to define `maxLength` and other validations for $ref which are normally not included in the reference. \r\n\r\nI now found a fitting issue (closed though): \r\nhttps://github.com/OAI/OpenAPI-Specification/issues/1514\r\n\r\n", "created_at": "2024-01-26T15:44:57Z", "updated_at": "2024-01-26T22:29:29Z", "category": { "name": "Enhancements", "emoji": ":bulb:" }, "answer": null, "user": { "login": "robstoll", "avatar_url": "https://avatars.githubusercontent.com/u/5557885?v=4" } }, { "id": "D_kwDOAQkWPc4AXVyj", "number": 3512, "title": "Treatment of trailing forward slash on Server Object \"url\".", "body": "If you had something like this:\r\n```yaml\r\n# rest of api...\r\nservers:\r\n - url: http://petstore.swagger.io/\r\npaths:\r\n /pets:\r\n get:\r\n# rest of api...\r\n```\r\n\r\nAssuming no other servers are specified at any level; what would the expected url be for a `get` request to `/pets`?\r\n\r\n`https://petstore.swagger.io/pets`\r\nor\r\n`https://petstore.swagger.io//pets`\r\n\r\n", "created_at": "2024-01-22T12:23:20Z", "updated_at": "2024-01-25T14:18:12Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AfabB", "body": "The specification requires that the URL template be **appended** (bolded in the spec), so the result would be `https://petstore.swagger.io//pets`. Of course, a tool can then choose to normalize URLs in accordance with RFC 3986, but that's outside of the scope of the OpenAPI Specification. Many web servers are configured to normalize such URLs internally (e.g. https://github.com/OAI//OpenAPI-Specification/discussions/3512 brings up this discussion, but still shows the `//` between `OAI` and `OpenAPI-Specification` in the address bar for me)." }, "user": { "login": "charjr", "avatar_url": "https://avatars.githubusercontent.com/u/102669158?u=55733dff67ac7c915ad26913f9791ac2b58e79f1&v=4" } }, { "id": "D_kwDOAQkWPc4AUq8C", "number": 3330, "title": "Is it possible to reference the pattern of a string", "body": "If you need a pattern multiple times, I would like to reduce duplication. Is it possible to reference a pattern for a string?", "created_at": "2023-07-19T15:22:01Z", "updated_at": "2024-01-24T17:17:41Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AYw_n", "body": "You can just have a schema that only has `{\"pattern\": \"the pattern\"}` and use `\"$ref\"` to include it." }, "user": { "login": "robp94", "avatar_url": "https://avatars.githubusercontent.com/u/42009775?v=4" } }, { "id": "D_kwDOAQkWPc4AQe2J", "number": 3004, "title": "Can you define placeholders to replace in component schemas?", "body": "I'm interested in creating an OpenAPI specification for my Rest API, but one thing that bothers me is the defining of responses for the API.\r\n\r\nMy API has 2 specific JSON replies based on HTTP response codes:\r\n\r\n- `200`\r\n ```json\r\n {\r\n \"error\": false,\r\n \"link\": \"https://example.com/img/animals/cat/cat_001.jpg\",\r\n \"time\": 0\r\n }\r\n ```\r\n- `403` or `404`\r\n The info is mostly the same, with the exception of the `message` being different. Example with an invalid path (403) is shown here.\r\n ```json\r\n {\r\n \"details\": {\r\n \"path\": \"/api/invalid/path\",\r\n \"content-type\": \"application/json\",\r\n \"user-agent\": \"Some-UA/1.0\"\r\n },\r\n \"error\": true,\r\n \"message\": \"The provided path is not valid.\",\r\n \"time\": 0\r\n }\r\n ```\r\n\r\nWhile I can, for the most part, create two components to cover the 403 and 404 cases, would I like to have an example scheme that depicts an example link matching the provided URL path for the successful request.\r\nIf f.e. the path defined is `/api/img/cat/` should the example JSON have a URL pointing to a random cat image (As shown above).\r\n\r\nThis, to my knowledge, requires me to create a separate scheme for each API endpoint I have if I want to have this.\r\n\r\nSo my question now is, can I define some kind of placeholder in the scheme, to then be replaced with whatever value I provide?\r\n\r\nLike f.e.\r\n```yaml\r\ncomponents:\r\n schemas:\r\n image-response-200:\r\n type: object\r\n properties:\r\n error:\r\n type: boolean\r\n example: false\r\n link:\r\n type: string\r\n example: \"https://example.com/img/{type}/{type}_001.jpg\"\r\n time:\r\n type: integer\r\n format: int32\r\n example: 0\r\n```\r\nwould then allow me to provide \"cat\" as type somewhere and the example shown would have `{type}` replaced with `cat`\r\n\r\nI hope such a feature exists, as it would reduce the copy-paste jobs I have by a lot in the end...", "created_at": "2022-08-20T20:10:26Z", "updated_at": "2024-01-24T17:15:23Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AeJbT", "body": "@MelleD it is possible in 3.1 using JSON Schema draft 2020-12's [`$dynamicAnchor` and `$dynamicRef`](https://json-schema.org/blog/posts/dynamicref-and-generics). It is not possible in 3.0 or earlier." }, "user": { "login": "Andre601", "avatar_url": "https://avatars.githubusercontent.com/u/11576465?u=b608c1e5d40b7bb195c1a06c77d837799a8c9c05&v=4" } }, { "id": "D_kwDOAQkWPc4AUiQ0", "number": 3324, "title": "Is an empty string valid or invalid if Data Type is string and format is specified?", "body": "An empty string is valid as a string, but if a format is specified, would an empty string be considered an invalid value?\r\nI would like to check, is it valid if an empty string comes to `something_date` with the following definition? I would like to ask this question, especially since [it is not explicitly stated](https://spec.openapis.org/oas/v3.0.3#data-types).\r\n\r\n```yaml\r\npaths:.\r\n '/foo/v1/bar':: ``post:''\r\n post:: ``post:''\r\n requestBody:: content\r\n content: application/json:: post\r\n application/json:: schema\r\n schema: object\r\n type: object\r\n properties: properties\r\n something_date: string\r\n type: string\r\n format: date\r\n```", "created_at": "2023-07-09T13:38:16Z", "updated_at": "2024-01-24T17:14:47Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4AekX0", "body": "Looking at the RFC definition they reference: [full-date = date-fullyear \"-\" date-month \"-\" date-mday](https://www.rfc-editor.org/rfc/rfc3339.html#page-8)\r\n\r\nSo the definition of a \"full-date\" would not allow an empty string. So according to the \"date\" format an empty string would be invalid.\r\n\r\n**However** it is explicitly stated that [Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.](https://spec.openapis.org/oas/v3.0.3#data-types).\r\n\r\nSo I think the answer is: \"it depends on the tool you use\" as it is the tool that decides whether `format: date` means anything." }, "user": { "login": "ydah", "avatar_url": "https://avatars.githubusercontent.com/u/13041216?u=01da03508c39ff279c1e23e236a8c5f878fe04b4&v=4" } }, { "id": "D_kwDOAQkWPc4AWuYw", "number": 3471, "title": "NRF installation without docker query", "body": "I am only installing NRF using https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-nrf/-/wikis/Installation this without docker.\r\nMy question is that does this installation also install mysql DB also with it ? if yes then where does it get installed ?", "created_at": "2023-12-13T15:16:24Z", "updated_at": "2024-01-24T17:14:25Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Deblina96", "avatar_url": "https://avatars.githubusercontent.com/u/116576465?u=263e6304458204a62c88831ad3e0972899cbc54f&v=4" } }, { "id": "D_kwDOAQkWPc4AV7vH", "number": 3406, "title": "Is there any plan to add Generic, Pick, Omit and other TypeScript like features?", "body": "In TS if you want to $ref specific properties from a Schema, it's a pain, at least from what I understood.\r\nFor example:\r\n\r\n```\r\n//permission\r\n{\r\n id: string;\r\n key: string;\r\n info: string;\r\n metadata: Metadata;\r\n}\r\n// role\r\n{\r\n id: string;\r\n title: string;\r\n permissions: {\r\n id: Permissions.id;\r\n key: Permissions.key;\r\n // notice that info shouldn't be here.\r\n }\r\n}\r\n```\r\n\r\nAs you can see, there is a relation between Permission and Role. But Role shouldn't include all of the Permission properties, just part of them. Imagine if Permission or other embedded Schemas had 50 properties, this could lead to big issue.\r\n\r\n**\r\n\r\nMoreover, if we want to make it even more tricky, in a real life production API, we have different kinds of the same Schema, for example: when creating a new Permission we should never provide id. If someone provides id we want to deny the request. When updating a Permission, we can only update the info, but never the key. \r\nWhen returning a Permission in a GET request, we would like to return the entire Permission, but without the metadata (which is basically some system info).\r\n\r\nAny advices here?", "created_at": "2023-10-18T12:57:57Z", "updated_at": "2024-01-24T15:52:45Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "razb-viola", "avatar_url": "https://avatars.githubusercontent.com/u/142972451?v=4" } }, { "id": "D_kwDOAQkWPc4ATp-g", "number": 3265, "title": "about running this project", "body": "Sir,can i get how to run these code .\r\ncan you explain in detail", "created_at": "2023-05-02T12:34:10Z", "updated_at": "2024-01-17T09:33:18Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "Shrishashank", "avatar_url": "https://avatars.githubusercontent.com/u/72358619?v=4" } }, { "id": "D_kwDOAQkWPc4AXJtf", "number": 3498, "title": "Error while using UERANSIM || UE does not have an emergency", "body": "I am trying to build my UE and ran using UERANSIM. I am following the below document:\r\nhttps://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed/-/blob/master/docs/DEPLOY_SA5G_WITH_UERANSIM.md\r\n\r\nBut in the document is mentioned that, ##### IMPORTANT: Add following parameters in oai-amf service of docker-compose, before deploying core network.\r\n\r\n```shell\r\n - INT_ALGO_LIST=[\"NIA1\" , \"NIA2\"]\r\n - CIPH_ALGO_LIST=[\"NEA1\" , \"NEA2\"]\r\n```\r\nMy question is it, in which section of aoi-amf should I add it ?\r\n\r\nI have tried to add it like in below mention SS, but did not work:\r\n![image](https://github.com/OAI/OpenAPI-Specification/assets/116576465/5d32182e-3537-4f3e-815f-9164b7647107)\r\n\r\nError:\r\n![image](https://github.com/OAI/OpenAPI-Specification/assets/116576465/82f7c34a-ca35-49d1-9e07-e9e95e52910d)\r\n\r\nPlease suggest on this.\r\n\r\n", "created_at": "2024-01-13T12:01:57Z", "updated_at": "2024-01-17T09:29:44Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "Deblina96", "avatar_url": "https://avatars.githubusercontent.com/u/116576465?u=263e6304458204a62c88831ad3e0972899cbc54f&v=4" } }, { "id": "D_kwDOAQkWPc4AXBjP", "number": 3490, "title": "Not able to find NRF configuration script in wiki", "body": "I am following the below repo to install NRF. I have successfully build NRF. But after building I am unable to find nrf_conf.sh script to generate nrf.conf.\r\n\r\nhttps://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-nrf/-/wikis/Installation\r\nPlease, let me know where nrf_conf.sh exist.\r\n\r\n", "created_at": "2024-01-06T19:28:14Z", "updated_at": "2024-01-08T15:20:14Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "Deblina96", "avatar_url": "https://avatars.githubusercontent.com/u/116576465?u=263e6304458204a62c88831ad3e0972899cbc54f&v=4" } }, { "id": "D_kwDOAQkWPc4ATMtv", "number": 3224, "title": "Documentation of openApi", "body": "Please can I have solutions of this exercise?\n\n![Screenshot_2023-03-31-13-13-31-841_com.google.android.apps.docs.jpg](https://user-images.githubusercontent.com/117768938/229232541-5b737b79-bb27-4f16-99a2-a97e9dbe0df8.jpg)", "created_at": "2023-03-31T21:14:34Z", "updated_at": "2024-01-05T09:05:52Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "cynthiatoussi", "avatar_url": "https://avatars.githubusercontent.com/u/117768938?v=4" } }, { "id": "D_kwDOAQkWPc4AWzFs", "number": 3474, "title": "Error while launching UERANSIM", "body": "I am trying to deploy UERANSIM and getting the following error:-\r\nPlease explain how this can be solved.\r\n![image](https://github.com/OAI/OpenAPI-Specification/assets/116576465/19a873c0-a35e-4055-b646-5e4fd8670235)\r\n", "created_at": "2023-12-18T20:41:22Z", "updated_at": "2024-01-05T09:03:49Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "Deblina96", "avatar_url": "https://avatars.githubusercontent.com/u/116576465?u=263e6304458204a62c88831ad3e0972899cbc54f&v=4" } }, { "id": "D_kwDOAQkWPc4AV7vT", "number": 3407, "title": "Where can I edit oas but Swagger?", "body": "I saw that Swagger is a tool to build my oas, but Swagger is a private company, while oas is a public standard and open source. How can I use oas without any intervention of a private company?\r\n\r\nI need code autocompletion and the ability to produce docs.\r\n\r\nIf this is something that is not included within the oas, just say. \r\n\r\nThanks.", "created_at": "2023-10-18T13:02:23Z", "updated_at": "2024-01-24T17:15:45Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": { "id": "DC_kwDOAQkWPc4Ab-Nk", "body": "There are many open-source tools for editing OAS descriptions listed at https://tools.openapis.org/" }, "user": { "login": "razb-viola", "avatar_url": "https://avatars.githubusercontent.com/u/142972451?v=4" } }, { "id": "D_kwDOAQkWPc4ATY-m", "number": 3241, "title": "Specification website improvements", "body": "Hi,\r\n\r\nI'm finding the [online specification](https://swagger.io/specification) a little frustrating. A few things:\r\n\r\n1. It has lots of anchor tags, which is great, but ECMAScript is being used when you click on them which means that the browser's URL doesn't update and the back button doesn't work. As the browser will handle anchor tags out of the box ECMAScript is purely making things worse here.\r\n\r\n2. When you click on an anchor tag the floating top nav bar obscures the Heading that you navigated to, so you are unsure whether you are in the right place\r\n\r\n3. If you disable ECMAScript then the yaml/json snippets become white text on a white background\r\n\r\nWhat's the right place to raise these?\r\n\r\nThanks!", "created_at": "2023-04-13T14:08:21Z", "updated_at": "2023-04-14T10:55:17Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "Mahoney", "avatar_url": "https://avatars.githubusercontent.com/u/168448?u=8af9f09897d7af9c9ad4b9b7c390543257ed3694&v=4" } }, { "id": "D_kwDOAQkWPc4ATZTo", "number": 3245, "title": "type-mappings question", "body": "I want integer types without a format to be treated as bigint in a typescript generator. If I run the command with `--type-mappings integer=BigInt` it works, but I want to constrain it to only integers in the schema without an explicit format. Any ideas?", "created_at": "2023-04-13T20:56:06Z", "updated_at": "2023-04-13T20:56:24Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": { "login": "dansimpson", "avatar_url": "https://avatars.githubusercontent.com/u/23339?u=fef7a0315c24d0d47132652554f741afcd0753b5&v=4" } }, { "id": "D_kwDOAQkWPc4AOVvQ", "number": 2835, "title": "How OpenAPI or any spec related can help on contract/schema testing?", "body": "## Context\r\nA lot of companies uses microservices, and have HTTP or async/event communication between them. It´s a common problem when server changes a thing, that something breaks on the client microservice. An we have tools like https://docs.pact.io/ and https://www.postman.com/ that help on that, and pact is relying on OAS for some automation on contract/schema testing.\r\n\r\n## Problem\r\nOpenAPI spec, AFAIK just describes the server part of http communications, and contract testing is all about checking the \"match\" between a **client** and a **server**, or a **producer** and a **consumer**. We researched and didn't find out a \"contract/spec\" that describes the **client** \"behavior\" or the way the client uses/sends data to the API. Pact is trying to do that with https://docs.pactflow.io/docs/workshops/bi-directional/ and using mock samples and other \"client evidences\" as way to extract this data to a file called PACT (their format). \r\n\r\nOther thing to mention is that we are using the https://martinfowler.com/bliki/TolerantReader.html approach. So we don't export/generate http clients from open api spec. This approach reduces the probability of a \"breaking change\", because the client does not need to know/use all fields/structure that the server produces.\r\n\r\n## Proposal/discussion\r\nWhat if we had a \"open spec\" that describes, the client part of the communication? That could be very similar to the OpenAPI spec and could be used for contract/schema checks.\r\n\r\nOne of the challenges on that is how can we generate this spec. some options:\r\n1)from mocked samples (wiremock)\r\n2)recording runtime behavior on integration tests or even on production/sandbox enviroments\r\n3) support some specific stacks, and parse that info from http client or any kind of \"structured\" code that tell us , how the request is going to be like. That could be done through static analysis or even evaluating some \"runtime\" http components.\r\n\r\nBut the main thing is not about how to get this files/spec, is about having a open spec for http clients.\r\n\r\nIf this is not the right place to start a discussion on that, please, we are open to all kind of suggestions.", "created_at": "2021-12-21T13:41:53Z", "updated_at": "2022-06-30T18:58:25Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "lednubr", "avatar_url": "https://avatars.githubusercontent.com/u/89259678?u=2b5f54de79cd5b4c4efcaef4d178913187aefe36&v=4" } }, { "id": "D_kwDOAQkWPc4ANswb", "number": 2724, "title": "apply `allowReserved: true` globally", "body": "I need to apply `allowReserved: true` to many of my parameters. \r\n\r\nIsn't there any way to set `allowReserved: true` globally?", "created_at": "2021-09-24T06:12:59Z", "updated_at": "2023-01-31T11:43:03Z", "category": { "name": "Q&A", "emoji": ":question:" }, "answer": null, "user": {} }, { "id": "MDEwOkRpc2N1c3Npb24zNTYxMzU3", "number": 2702, "title": "How to start demo", "body": "How to pratice in my laptop. please share details", "created_at": "2021-09-08T11:59:51Z", "updated_at": "2024-03-26T18:56:25Z", "category": { "name": "General", "emoji": ":speech_balloon:" }, "answer": null, "user": { "login": "umakanta1987", "avatar_url": "https://avatars.githubusercontent.com/u/90271045?u=50f934f1474d38b2fb2f6f5b69b02c768c2db002&v=4" } } ], "details": { "id": 17372733, "node_id": "MDEwOlJlcG9zaXRvcnkxNzM3MjczMw==", "name": "OpenAPI-Specification", "full_name": "OAI/OpenAPI-Specification", "private": false, "owner": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "description": "The OpenAPI Specification Repository", "fork": false, "url": "https://api.github.com/repos/OAI/OpenAPI-Specification", "created_at": "2014-03-03T16:53:36Z", "updated_at": "2026-03-04T19:04:24Z", "pushed_at": "2026-03-02T07:43:55Z", "homepage": "https://openapis.org", "size": 9502, "stargazers_count": 30936, "watchers_count": 30936, "language": "Markdown", "has_issues": true, "has_projects": true, "has_downloads": true, "has_wiki": true, "has_pages": false, "has_discussions": true, "forks_count": 9164, "archived": false, "disabled": false, "open_issues_count": 112, "license": { "key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0", "url": "https://api.github.com/licenses/apache-2.0", "node_id": "MDc6TGljZW5zZTI=" }, "allow_forking": true, "is_template": false, "web_commit_signoff_required": false, "has_pull_requests": true, "pull_request_creation_policy": "all", "topics": { "0": "apis", "1": "oas", "2": "openapi", "3": "openapi-specification", "4": "rest", "5": "webapi" }, "visibility": "public", "forks": 9164, "open_issues": 112, "watchers": 30936, "default_branch": "main", "permissions": { "admin": false, "maintain": false, "push": false, "triage": false, "pull": true }, "temp_clone_token": "", "custom_properties": {}, "organization": { "login": "OAI", "id": 16343502, "node_id": "MDEyOk9yZ2FuaXphdGlvbjE2MzQzNTAy", "avatar_url": "https://avatars.githubusercontent.com/u/16343502?v=4", "gravatar_id": "", "url": "https://api.github.com/users/OAI", "type": "Organization", "user_view_type": "public", "site_admin": false }, "network_count": 9164, "subscribers_count": 841 }, "lastFetched": 1772671224857 }