├── .gitattributes ├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── config.yml │ ├── registry_feature_request.md │ └── spec_bug_report.md ├── dependabot.yml ├── pull_request_template.md ├── templates │ └── agenda.md └── workflows │ ├── agenda.yaml │ ├── check-restricted-files.yaml │ ├── inactive-issues.yml │ ├── respec.yaml │ ├── schema-publish.yaml │ ├── schema-tests.yaml │ ├── sync-dev-to-vX.Y-dev.yaml │ ├── sync-main-to-dev.yaml │ └── validate-markdown.yaml ├── .gitignore ├── .gitmodules ├── .markdownlint.yaml ├── CONTRIBUTING.md ├── EDITORS.md ├── GOVERNANCE.md ├── IMPLEMENTATIONS.md ├── LICENSE ├── MAINTAINERS.md ├── README.md ├── SECURITY_CONSIDERATIONS.md ├── SPECIAL_INTEREST_GROUPS.md ├── TOB.md ├── _archive_ ├── README.md └── schemas │ ├── README.md │ ├── v1.2 │ ├── README.md │ ├── apiDeclaration.json │ ├── authorizationObject.json │ ├── dataType.json │ ├── dataTypeBase.json │ ├── infoObject.json │ ├── modelsObject.json │ ├── oauth2GrantType.json │ ├── operationObject.json │ ├── parameterObject.json │ ├── resourceListing.json │ └── resourceObject.json │ ├── v2.0 │ ├── README.md │ └── schema.json │ └── v3.0 │ ├── README.md │ ├── pass │ ├── api-with-examples.yaml │ ├── callback-example.yaml │ ├── link-example.yaml │ ├── petstore-expanded.yaml │ ├── petstore.yaml │ └── uspto.yaml │ ├── schema.test.mjs │ └── schema.yaml ├── package-lock.json ├── package.json ├── proposals ├── 2019-01-01-Proposal-Template.md ├── 2019-03-15-Alternative-Schema.md ├── 2019-07-17-Webhooks.md ├── 2019-10-31-Clarify-Nullable.md ├── 2019-12-24-Overlays.md ├── 2020-10-28-Experimental.md ├── 2024-08-01-Self-Identification.md ├── 2024-09-01-Tags-Improvement.md ├── 2025-03-20-URIs-for-Tags.md ├── Alternative-Schema │ ├── CONTRIBUTORS.md │ ├── alternative_schema_object.md │ ├── examples.md │ ├── implementations.md │ └── schema_object.md └── Overlays │ ├── Changes.yml │ └── MergePatch.yml ├── scripts ├── adjust-release-branch.sh ├── close-no-recent.ps1 ├── fwdabort.sh ├── fwdport.sh ├── label-no-recent.ps1 ├── md2html │ ├── .gitignore │ ├── analytics │ │ └── google.html │ ├── build.sh │ ├── gist.css │ ├── main.css │ ├── md2html.js │ ├── style-finish.html │ ├── style-start.html │ └── syntax-github.css ├── schema-publish.sh ├── schema-test-coverage.mjs ├── schema-test-coverage.sh └── validate.mjs ├── spec.markdownlint.yaml ├── style-guide.md ├── tests └── md2html │ ├── README.md │ ├── fixtures │ ├── .gitattributes │ ├── basic-new.html │ ├── basic-new.maintainers │ ├── basic-new.md │ ├── basic-old.html │ ├── basic-old.maintainers │ └── basic-old.md │ └── md2html.test.mjs ├── versions ├── 1.2.md ├── 2.0-editors.md ├── 2.0.md ├── 3.0.0-editors.md ├── 3.0.0.md ├── 3.0.1-editors.md ├── 3.0.1.md ├── 3.0.2-editors.md ├── 3.0.2.md ├── 3.0.3-editors.md ├── 3.0.3.md ├── 3.0.4-editors.md ├── 3.0.4.md ├── 3.1.0-editors.md ├── 3.1.0.md ├── 3.1.1-editors.md └── 3.1.1.md └── vitest.config.mjs /.gitattributes: -------------------------------------------------------------------------------- 1 | *.md linguist-detectable 2 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Global Repo Owners 2 | * @oai/openapi-maintainers @oai/tsc 3 | 4 | # Specification Versions 5 | /versions/ @oai/tsc 6 | 7 | # Protect specific top level files 8 | /MAINTAINERS.md @oai/tsc 9 | /TOB.md @oai/tsc 10 | /GOVERNANCE.md @oai/tsc 11 | /LICENSE @oai/tsc -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | 3 | contact_links: 4 | - name: Have a question about using OpenAPI? 5 | url: https://communityinviter.com/apps/open-api/openapi 6 | about: Ask us on our Slack! 7 | - name: Have a question about OpenAPI Tooling? 8 | url: https://tools.openapis.org/ 9 | about: Please ask your tooling vendor! 10 | - name: Want to add to our list of OpenAPI Tools? 11 | url: https://tools.openapis.org/ 12 | about: Please take a look at our tooling site's instructions! 13 | - name: Want to suggest more how-to documentation and examples? 14 | url: https://github.com/OAI/learn.openapis.org/issues/new 15 | about: Please open an issue on our learning site! 16 | - name: Want to request a new feature in the specification? 17 | url: https://github.com/OAI/OpenAPI-Specification/discussions/new?category=enhancements 18 | about: Please start a discussion in this repository! 19 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/registry_feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Contribute to the registries at spec.openapis.org/registry 3 | about: Add a new registry entry, or edit an existing one 4 | title: 'Registry: ...' 5 | labels: registries 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Which registry do you want to contribute to** 11 | - [ ] [Alternative Schema Type Registry](https://spec.openapis.org/registry/alternative-schema) 12 | - [ ] [Draft Features Registry](https://spec.openapis.org/registry/draft-feature) 13 | - [ ] [Specification Extension Registry](https://spec.openapis.org/registry/extension) 14 | - [ ] [Format Registry](https://spec.openapis.org/registry/format) 15 | - [ ] [Extension Namespace Registry](https://spec.openapis.org/registry/namespace) 16 | - [ ] [Tag Kind Registry](https://spec.openapis.org/registry/tag-kind) 17 | 18 | **Describe your contribution** 19 | A clear and concise description of what you want to add or change. 20 | 21 | **Describe alternatives you've considered** 22 | A clear and concise description of any alternative solutions or features you've considered. 23 | 24 | **Additional context** 25 | Add any other context or screenshots about the feature request here. 26 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/spec_bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report an error in the specification 3 | about: Create a report to help us improve the specification 4 | title: 'vX.Y: ...' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the error in the specification** 11 | A clear and concise description of 12 | - what the error is, 13 | - which specification versions are affected, 14 | - what you would expect the specification to say instead, and 15 | - a link to the corresponding specification section in the "oldest" affected version. 16 | 17 | **Additional context** 18 | Add any other context about the problem here. 19 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: github-actions 4 | directory: "/" 5 | schedule: 6 | interval: daily 7 | open-pull-requests-limit: 10 8 | - package-ecosystem: npm 9 | directory: "/" 10 | schedule: 11 | interval: daily 12 | open-pull-requests-limit: 10 13 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | - [ ] schema changes are included in this pull request 20 | - [ ] schema changes are needed for this pull request but not done yet 21 | - [ ] no schema changes are needed for this pull request 22 | -------------------------------------------------------------------------------- /.github/templates/agenda.md: -------------------------------------------------------------------------------- 1 | ## Weekly meetings happen on Thursdays at 9am - 10am Pacific 2 | 3 | This 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. 4 | 5 | Whether 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**. 6 | 7 | Meetings take place over Zoom: [https://zoom.us/j/975841675](https://zoom.us/j/975841675?pwd=SUh4MjRLaEFKNlI3RElpWTdhRDVVUT09), dial-in passcode: 763054 8 | 9 | ### Accessibility & Etiquette 10 | * Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file). 11 | 12 | * Meetings are recorded for future reference, and for those who are not able to attend in-person. 13 | 14 | * We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting. 15 | 16 | * We look forward to your participation, but please consider these acts of etiquette: 17 | * Remain on mute when not speaking to prevent interruptions. 18 | * Blur your background to reduce visual distractions. 19 | * Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak. 20 | 21 | | Blur My Background | Raise Hand | 22 | |-|-| 23 | | Screenshot of Zoom UI showing the 'Stop Video' and 'Blur My Background' control | Screenshot of Zoom UI showing the 'Reaction' and 'Raise Hand' control | 24 | 25 | ### Agenda Structure 26 | 27 | | Topic | Owner | Decision/NextStep | 28 | |-|-|-| 29 | Intros and governance meta-topics (5 mins) | TDC | | 30 | Reports from Special Interest Groups (5 mins) | SIG members | | 31 | Any other business (add comments below to suggest topics) | TDC | | 32 | [Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | | 33 | [Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | | 34 | [New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage | | 35 | 36 | /cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion. 37 | -------------------------------------------------------------------------------- /.github/workflows/agenda.yaml: -------------------------------------------------------------------------------- 1 | name: agenda 2 | 3 | # author: @MikeRalphson 4 | # issue: various 5 | 6 | # 7 | # This workflow creates the agenda issue each week. It runs on a cron every 8 | # Monday morning, raising an issue for the following Thursday. 9 | # It can also be run manually, in case GitHub Actions has a failure. 10 | # 11 | 12 | on: 13 | schedule: 14 | - cron: '0 16 * * 4' 15 | workflow_dispatch: {} 16 | 17 | permissions: 18 | issues: write 19 | contents: read 20 | 21 | jobs: 22 | agenda: 23 | if: github.repository == 'OAI/OpenAPI-Specification' 24 | env: 25 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 26 | TITLE_PREFIX: "Open Community (TDC) Meeting, " 27 | LABEL: "Housekeeping" 28 | POST_MEETING_CLOSE_DURATION_IN_DAYS: 10 29 | 30 | runs-on: ubuntu-latest 31 | 32 | steps: 33 | - uses: actions/checkout@v4 # checkout repo content 34 | 35 | # we want to close old agenda issues before creating a new one because there's a limit of 3 pinned items on a repo 36 | - name: Close old agenda issues 37 | run: gh issue list -l ${{ env.LABEL }} --author "app/github-actions" --json number,title | ConvertFrom-Json | Where-Object { $_.title -like "${{ env.TITLE_PREFIX }}*" -and ([datetime]::UtcNow - [datetime]::Parse([regex]::Replace($_.title.Replace("${{ env.TITLE_PREFIX }}", ""), "\([^)]+\)", ""))) -ge [timespan]::FromDays([int]::Parse("${{ env.POST_MEETING_CLOSE_DURATION_IN_DAYS }}"))} | ForEach-Object { gh issue close $_.number && gh issue unpin $_.number } 38 | shell: pwsh 39 | 40 | - name: Create agenda issue 41 | run: | 42 | $nextThursday = @(@(1..8) | % {$(Get-Date).AddDays($_)} | ? {$_.DayOfWeek -ieq "Thursday"})[0].ToString("dddd dd MMMM yyyy", [CultureInfo]::InvariantCulture) 43 | $result = gh issue create -l ${{ env.LABEL }} -t "${{ env.TITLE_PREFIX }}$nextThursday" -F .github/templates/agenda.md 44 | gh issue pin $result 45 | shell: pwsh 46 | 47 | 48 | -------------------------------------------------------------------------------- /.github/workflows/check-restricted-files.yaml: -------------------------------------------------------------------------------- 1 | name: check-restricted-files 2 | 3 | # Author: @ralfhandl 4 | # Issue: https://github.com/OAI/OpenAPI-Specification/issues/3432 5 | 6 | # This workflow fails if restricted files are changed in a pull request 7 | 8 | on: 9 | pull_request: 10 | paths: 11 | - 'schemas/**/*.yaml' 12 | - 'versions/*.md' 13 | 14 | jobs: 15 | check-files: 16 | runs-on: ubuntu-latest 17 | steps: 18 | - name: Check changed files 19 | shell: bash 20 | run: | 21 | if [[ "${{ github.event.pull_request.head.repo.full_name }}" == "OAI/OpenAPI-Specification" ]] && \ 22 | [[ "${{ github.event.pull_request.base.repo.full_name }}" == "OAI/OpenAPI-Specification" ]]; then 23 | 24 | if [[ "${{ github.event.pull_request.head.ref }}" == "main" ]] && \ 25 | [[ "${{ github.event.pull_request.base.ref }}" == "dev" ]]; then 26 | echo Sync from main to dev 27 | exit 0 28 | fi 29 | 30 | if [[ "${{ github.event.pull_request.head.ref }}" == "dev" ]] && \ 31 | [[ "${{ github.event.pull_request.base.ref }}" =~ ^v[0-9]+\.[0-9]+-dev$ ]]; then 32 | echo Sync from dev to ${{ github.event.pull_request.base.ref }} 33 | exit 0 34 | fi 35 | 36 | if [[ "${{ github.event.pull_request.head.ref }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]] && \ 37 | [[ "${{ github.event.pull_request.base.ref }}" == "main" ]]; then 38 | echo Release from ${{ github.event.pull_request.head.ref }} to main 39 | exit 0 40 | fi 41 | fi 42 | 43 | echo This PR contains changes to files that should not be changed 44 | exit 1 45 | -------------------------------------------------------------------------------- /.github/workflows/inactive-issues.yml: -------------------------------------------------------------------------------- 1 | on: 2 | issues: 3 | types: labeled 4 | workflow_dispatch: 5 | schedule: 6 | - cron: '*/5 * * * *' 7 | 8 | permissions: 9 | issues: write 10 | contents: read 11 | 12 | name: Label and close issues with no recent activity 13 | 14 | env: 15 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 16 | NEEDS_ATTENTION_LABEL: "Needs attention" 17 | NEEDS_AUTHOR_FEEDBACK_LABEL: "Needs author feedback" 18 | NO_RECENT_ACTIVITY_LABEL: "No recent activity" 19 | NO_RECENT_ACTIVITY_DURATION_IN_DAYS: 7 20 | NO_RECENT_ACTIVITY_DURATION_CLOSE_IN_DAYS: 28 21 | ORG_NAME: ${{ github.repository_owner }} 22 | REPO_NAME: ${{ github.event.repository.name }} 23 | NO_RECENT_ACTIVITY_COMMENT: "This issue has been labeled with `No recent activity` because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to." 24 | 25 | 26 | jobs: 27 | run: 28 | if: github.repository == 'OAI/OpenAPI-Specification' 29 | runs-on: ubuntu-latest 30 | name: Label issues with no recent activity 31 | steps: 32 | - uses: actions/checkout@v4 33 | - run: scripts/label-no-recent.ps1 34 | shell: pwsh 35 | - run: scripts/close-no-recent.ps1 36 | shell: pwsh 37 | -------------------------------------------------------------------------------- /.github/workflows/respec.yaml: -------------------------------------------------------------------------------- 1 | name: respec 2 | 3 | # author: @MikeRalphson 4 | # issue: https://github.com/OAI/OpenAPI-Specification/issues/1564 5 | 6 | # 7 | # This workflow updates the respec 'pretty' rendered versions of the spec 8 | # on the gh-pages branch when the corresponding markdown files change. 9 | # 10 | 11 | # run this manually from main 12 | on: 13 | workflow_dispatch: {} 14 | 15 | jobs: 16 | respec: 17 | if: github.ref == 'refs/heads/main' 18 | 19 | runs-on: ubuntu-latest 20 | 21 | steps: 22 | - uses: actions/checkout@v4 # checkout main branch 23 | with: 24 | fetch-depth: 0 25 | 26 | - uses: actions/setup-node@v4 # setup Node.js 27 | with: 28 | node-version: '20.x' 29 | 30 | - name: Install dependencies 31 | run: npm ci 32 | 33 | - uses: actions/checkout@v4 # checkout gh-pages branch 34 | with: 35 | ref: gh-pages 36 | path: deploy 37 | 38 | - name: run main script 39 | run: scripts/md2html/build.sh 40 | 41 | - name: Create Pull Request 42 | uses: peter-evans/create-pull-request@v6 43 | with: 44 | token: ${{ secrets.GITHUB_TOKEN }} 45 | branch: update-respec-version 46 | base: gh-pages 47 | delete-branch: true 48 | path: deploy 49 | labels: Housekeeping 50 | reviewers: darrelmiller,webron,earth2marsh,webron,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge 51 | title: Update ReSpec-rendered specification versions 52 | commit-message: Update ReSpec-rendered specification versions 53 | signoff: true 54 | body: | 55 | This pull request is automatically triggered by GitHub action `respec`. 56 | 57 | The `versions/*.md` files have changed, so the HTML files are automatically being regenerated. 58 | 59 | 60 | -------------------------------------------------------------------------------- /.github/workflows/schema-publish.yaml: -------------------------------------------------------------------------------- 1 | name: schema-publish 2 | 3 | # author: @ralfhandl 4 | # issue: https://github.com/OAI/OpenAPI-Specification/issues/3715 5 | 6 | # 7 | # This workflow creates a pull request for publishing schema iterations to the gh-pages branch 8 | # 9 | 10 | # run this on push to vX.Y-dev branches or manually 11 | on: 12 | push: 13 | branches: 14 | - 'v[0-9].[0-9]-dev' 15 | paths: 16 | - 'src/schemas/validation/*.yaml' 17 | - 'scripts/schema-publish.sh' 18 | - '.github/workflows/schema-publish.yaml' 19 | workflow_dispatch: {} 20 | 21 | jobs: 22 | publish: 23 | 24 | runs-on: ubuntu-latest 25 | 26 | steps: 27 | - uses: actions/checkout@v4 # checkout main branch 28 | with: 29 | fetch-depth: 0 30 | 31 | - uses: actions/setup-node@v4 # setup Node.js 32 | with: 33 | node-version: '22.x' 34 | 35 | - name: Install dependencies 36 | run: npm ci 37 | 38 | - uses: actions/checkout@v4 # checkout gh-pages branch 39 | with: 40 | ref: gh-pages 41 | path: deploy 42 | 43 | - name: run main script 44 | run: scripts/schema-publish.sh 45 | 46 | - name: Create Pull Request 47 | uses: peter-evans/create-pull-request@v6 48 | with: 49 | token: ${{ secrets.GITHUB_TOKEN }} 50 | branch: ${{ github.ref_name }}-publish-schema-iteration 51 | base: gh-pages 52 | delete-branch: true 53 | path: deploy 54 | labels: Housekeeping,Schema 55 | reviewers: darrelmiller,webron,earth2marsh,webron,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge 56 | title: '${{ github.ref_name }}: publish OpenAPI schema iterations' 57 | commit-message: New OpenAPI schema iterations 58 | signoff: true 59 | body: | 60 | This pull request is automatically generated by GitHub action `schema-publish`. 61 | The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated. 62 | -------------------------------------------------------------------------------- /.github/workflows/schema-tests.yaml: -------------------------------------------------------------------------------- 1 | name: schema-test 2 | 3 | # Author: @MikeRalphson / runs @jdesrosiers tests 4 | # Issue: https://github.com/OAI/OpenAPI-Specification/pull/2489 5 | 6 | # 7 | # This workflow runs the npm test script to validate passing and failing 8 | # testcases for the metaschemas 9 | # 10 | 11 | # run this on push to any branch and creation of pull-requests 12 | on: 13 | push: {} 14 | pull_request: {} 15 | workflow_dispatch: {} 16 | 17 | jobs: 18 | test: 19 | 20 | runs-on: ubuntu-latest 21 | 22 | steps: 23 | - uses: actions/checkout@v4 # checkout repo content 24 | with: 25 | fetch-depth: 0 26 | 27 | - uses: actions/setup-node@v4 # setup Node.js 28 | with: 29 | node-version: '20.x' 30 | 31 | - name: Install dependencies 32 | run: npm ci 33 | 34 | - name: Run tests 35 | run: npm run test 36 | -------------------------------------------------------------------------------- /.github/workflows/sync-dev-to-vX.Y-dev.yaml: -------------------------------------------------------------------------------- 1 | name: sync-dev-to-vX.Y-dev 2 | 3 | # author: @ralfhandl 4 | 5 | # 6 | # This workflow creates PRs to update the vX.Y-dev branch with the latest changes from dev 7 | # 8 | 9 | # run this on push to dev 10 | on: 11 | push: 12 | branches: 13 | - dev 14 | 15 | jobs: 16 | sync-branches: 17 | runs-on: ubuntu-latest 18 | steps: 19 | - name: Checkout repository 20 | uses: actions/checkout@v4 21 | with: 22 | fetch-depth: 0 23 | 24 | - name: Create pull requests 25 | id: pull_requests 26 | shell: bash 27 | run: | 28 | DEV_BRANCHES=$(git branch -r --list origin/v?.?-dev) 29 | for DEV_BRANCH in $DEV_BRANCHES; do 30 | BASE=${DEV_BRANCH:7} 31 | EXISTS=$(gh pr list --base $BASE --head $HEAD \ 32 | --json number --jq '.[] | .number') 33 | if [ ! -z "$EXISTS" ]; then 34 | echo "PR #$EXISTS already wants to merge $HEAD into $BASE" 35 | continue 36 | fi 37 | 38 | gh pr create --base $BASE --head $HEAD \ 39 | --label "Housekeeping" \ 40 | --title "$BASE: update from $HEAD" \ 41 | --body "Merge \`$HEAD\` into \`$BASE\`." 42 | done 43 | env: 44 | GH_TOKEN: ${{ github.token }} 45 | HEAD: dev 46 | -------------------------------------------------------------------------------- /.github/workflows/sync-main-to-dev.yaml: -------------------------------------------------------------------------------- 1 | name: sync-main-to-dev 2 | 3 | # author: @ralfhandl 4 | 5 | # 6 | # This workflow creates PRs to update the dev branch with the latest changes from main 7 | # 8 | 9 | # run this on push to main 10 | on: 11 | push: 12 | branches: 13 | - main 14 | 15 | jobs: 16 | sync-branch: 17 | runs-on: ubuntu-latest 18 | steps: 19 | - name: Checkout repository 20 | uses: actions/checkout@v4 21 | 22 | - name: Create pull request 23 | id: pull_request 24 | shell: bash 25 | run: | 26 | EXISTS=$(gh pr list --base $BASE --head $HEAD \ 27 | --json number --jq '.[] | .number') 28 | if [ ! -z "$EXISTS" ]; then 29 | echo "PR #$EXISTS already wants to merge $HEAD into $BASE" 30 | exit 0 31 | fi 32 | 33 | gh pr create --base $BASE --head $HEAD \ 34 | --label "Housekeeping" \ 35 | --title "$BASE: update from $HEAD" \ 36 | --body "Merge \`$HEAD\` into \`$BASE\`." 37 | env: 38 | GH_TOKEN: ${{ github.token }} 39 | HEAD: main 40 | BASE: dev 41 | -------------------------------------------------------------------------------- /.github/workflows/validate-markdown.yaml: -------------------------------------------------------------------------------- 1 | name: validate-markdown 2 | 3 | # Author: @MikeRalphson 4 | # Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130 5 | 6 | # 7 | # This workflow validates markdown files in the project root. 8 | # It also validates the work-in-progress specification file src/oas.md with slightly different rules. 9 | # 10 | 11 | # run this on push to any branch and creation of pull-requests 12 | on: [push, pull_request] 13 | 14 | jobs: 15 | lint: 16 | 17 | runs-on: ubuntu-latest 18 | 19 | steps: 20 | 21 | - uses: actions/checkout@v4 # checkout repo content 22 | with: 23 | fetch-depth: 0 24 | 25 | - uses: actions/setup-node@v4 # setup Node.js 26 | with: 27 | node-version: '20.x' 28 | 29 | - name: Lint work-in-progress spec 30 | run: npx --yes markdownlint-cli2 --config spec.markdownlint.yaml src/oas.md 31 | 32 | - name: Lint other files 33 | run: npx --yes markdownlint-cli2 *.md 34 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | *.iml 3 | *.ipr 4 | *.iws 5 | target 6 | atlassian-ide-plugin.xml 7 | node_modules/ 8 | deploy/ 9 | deploy-preview/ 10 | coverage/ 11 | _site/ 12 | Gemfile.lock 13 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OAI/OpenAPI-Specification/69723dda32a9888100a277399278c7759402541c/.gitmodules -------------------------------------------------------------------------------- /.markdownlint.yaml: -------------------------------------------------------------------------------- 1 | # First heading is a top-level heading 2 | MD002: true 3 | 4 | # Heading style (ATX is leading # symbols) 5 | MD003: 6 | style: atx 7 | 8 | # Unordered list symbol can be anything 9 | MD004: false 10 | 11 | # Unordered list indentation size 12 | MD007: 13 | indent: 2 14 | 15 | # Allow additional blank lines 16 | MD012: false 17 | 18 | # Maximum line length 19 | MD013: 20 | line_length: 800 21 | tables: false 22 | 23 | # Headings need blank lines before and after 24 | MD022: true 25 | 26 | # Duplicate headings are allowed 27 | MD024: false 28 | 29 | # Surround lists with blank lines 30 | MD032: true 31 | 32 | # Allow inline HTML 33 | MD033: false 34 | -------------------------------------------------------------------------------- /EDITORS.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Specification Editors 2 | 3 | ## Active 4 | 5 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 6 | * Henry Andrews [@handrews](https://github.com/handrews) 7 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 8 | * Lorna Mitchell [@lornajane](https://github.com/lornajane) 9 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 10 | * Miguel Quintero [@miqui](https://github.com/miqui) 11 | * Mike Kistler [@mikekistler](https://github.com/mikekistler) 12 | * Ralf Handl [@ralfhandl](https://github.com/ralfhandl) 13 | * Ron Ratovsky [@webron](https://github.com/webron) 14 | 15 | ## Emeritus 16 | 17 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 18 | * Uri Sarid [@usarid](https://github.com/usarid) 19 | * Jason Harmon [@jharmn](https://github.com/jharmn) 20 | * Tony Tam [@fehguy](https://github.com/fehguy) 21 | -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Governance 2 | 3 | The OpenAPI Specification is a project of the OpenAPI Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance). 4 | 5 | ## Processes and procedures of the Technical Steering Committee (TSC) 6 | 7 | The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines. 8 | 9 | ### 1. The establishment of roles and the responsibilities for each role 10 | 11 | Roles: 12 | 13 | * [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the OAI's Business Governing Board (BGB) at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC. 14 | 15 | * [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. 16 | 17 | * [Community Manager](https://en.wikipedia.org/wiki/Online_community_manager) — responsible for onboarding of new contributors, dealing with antisocial behaviour before it becomes a code of conduct violation, and managing the issue triage team. 18 | 19 | * [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members. 20 | 21 | ### 2. Adding members to the TSC 22 | 23 | A call-for-nominations period may be agreed upon by the TSC voting members and announced in a timely manner on a weekly TDC call (and documented on the agenda issue), assuming the TSC membership is not already at its maximum. 24 | A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting. 25 | A nominee must not receive opposition votes of more than 25% of the TSC voting membership via a confidential vote held electronically within a week following the nomination meeting. 26 | Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 6 months. 27 | The provisional period is concluded by a second, confidential vote similar to the nomination period's vote, after which newly confirmed members gain their voting rights. 28 | At most there are four voting periods per year (no more than one every three months), with a minimum of one per year. 29 | 30 | ### 3. Removal of membership from the TSC 31 | 32 | Occasionally it may be necessary to remove a TSC member, such as behavior that violates the code of conduct or prolonged absenteeism. A 66% vote (confidential, electronic) of the other TSC members is required to remove a member. Otherwise, TSC members are removed when they renounce their position by informing the TSC of their effective resignation date via email. 33 | 34 | ### 4. Criteria for decisions 35 | 36 | The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the OAI's Technical Oversight Board (TOB). 37 | 38 | The TSC will maintain a publicly available document specifying the process in the contributor guidelines for how proposed changes are merged into the specification. The TSC will document and publicize the schedule of merge parties and release parties for the benefit of the developer community. 39 | -------------------------------------------------------------------------------- /IMPLEMENTATIONS.md: -------------------------------------------------------------------------------- 1 | # Implementations 2 | 3 | The list of implementations formerly in this file is no-longer maintained here. 4 | 5 | You may find a more comprehensive list at 6 | 7 | Instructions on listing your projects are contained in 8 | 9 | These tools are not endorsed by the OAI. 10 | -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Initiative Technical Steering Committee Members 2 | 3 | ## Active 4 | 5 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 6 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 7 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 8 | * Ron Ratovsky [@webron](https://github.com/webron) 9 | * Lorna Mitchell [@lornajane](https://github.com/lornajane) 10 | * Mike Kistler [@mikekistler](https://github.com/mikekistler) 11 | * Miguel Quintero [@miqui](https://github.com/miqui) 12 | * Ralf Handl [@ralfhandl](https://github.com/ralfhandl) 13 | 14 | ## Emeritus 15 | 16 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 17 | * Uri Sarid [@usarid](https://github.com/usarid) 18 | * Jason Harmon [@jharmn](https://github.com/jharmn) 19 | * Tony Tam [@fehguy](https://github.com/fehguy) 20 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The OpenAPI Specification 2 | 3 | ![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/badge.svg) [![Issue triagers](https://www.codetriage.com/oai/openapi-specification/badges/users.svg)](https://www.codetriage.com/oai/openapi-specification) 4 | 5 | ![OpenAPI logo](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) 6 | 7 | 8 | The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. 9 | 10 | The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. 11 | 12 | Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe API services and are represented in YAML or JSON formats. These documents may be produced and served statically or generated dynamically from an application. 13 | 14 | The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the described service may not even be owned by the creator of its description. It does, however, require that the service's capabilities be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with an HTTP API. 15 | 16 | This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project. 17 | 18 | ## Versions 19 | 20 | This repository contains [the Markdown sources](versions) for [all published OpenAPI Specification versions](https://spec.openapis.org/). For release notes and release candidate versions, refer to the [releases page](releases). 21 | 22 | ## See It in Action 23 | 24 | If you just want to see it work, check out the [list of current examples](https://learn.openapis.org/examples/). 25 | 26 | ## Tools and Libraries 27 | 28 | Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing 29 | [list of implementations](IMPLEMENTATIONS.md). 30 | 31 | ## Participation 32 | 33 | The current process for developing the OpenAPI Specification is described in 34 | the [Contributing Guidelines](CONTRIBUTING.md). 35 | 36 | Developing the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to `main`. 37 | 38 | The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the entire OpenAPI [technical meeting calendar](https://calendar.google.com/calendar/u/0/embed?src=c_fue82vsncog6ahhjvuokjo8qsk@group.calendar.google.com) online. 39 | 40 | The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: 41 | 42 | * Review the specification [markdown sources](versions) and [authoritative _source-of-truth_ HTML renderings](https://spec.openapis.org/), including full credits and citations. 43 | * Review the [contributing](CONTRIBUTING.md) process so you understand how the spec is evolving. 44 | * Check the [discussions](https://github.com/OAI/OpenAPI-Specification/discussions), [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR. 45 | * Subscribe to an open issue a day (or a week) in your inbox via [CodeTriage.com](https://www.codetriage.com/oai/openapi-specification). 46 | * Create a discussion to describe a new concern, ideally with clear explanations of related use cases. 47 | 48 | Not all feedback can be accommodated, and there may be solid arguments for or against a change being appropriate for the specification. 49 | 50 | ## Licensing 51 | 52 | See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE) 53 | 54 | 55 | -------------------------------------------------------------------------------- /SECURITY_CONSIDERATIONS.md: -------------------------------------------------------------------------------- 1 | # Security Considerations 2 | 3 | ## OpenAPI Document Formats 4 | 5 | OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations: 6 | 7 | - [JSON](https://www.iana.org/assignments/media-types/application/json) 8 | - [YAML](https://www.iana.org/assignments/media-types/application/yaml) 9 | - [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13) 10 | - [JSON Schema Validation](https://json-schema.org/draft/2020-12/json-schema-validation#name-security-considerations) 11 | 12 | ## Tooling and Usage Scenarios 13 | 14 | In addition, OpenAPI documents are processed by a wide variety of tooling for numerous different purposes, such as client code generation, documentation generation, server side routing, and API testing. OpenAPI document authors must consider the risks of the scenarios where the OpenAPI document may be used. 15 | 16 | ## Security Schemes 17 | 18 | An OpenAPI document describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations. 19 | 20 | ## Handling External Resources 21 | 22 | OpenAPI documents may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted. References in an OpenAPI document, or across OpenAPI documents may cause a cycle. Tooling must detect and handle cycles to prevent resource exhaustion. 23 | 24 | ## Markdown and HTML Sanitization 25 | 26 | Certain properties allow the use of Markdown which can contain HTML including script. It is the responsibility of tooling to appropriately sanitize the Markdown. 27 | -------------------------------------------------------------------------------- /SPECIAL_INTEREST_GROUPS.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Special Interest Groups (SIGs) 2 | 3 | OpenAPI Special Interest Groups, or "SIGs", are the OpenAPI Initiative's way of focusing work in particular areas. SIGs may start with just a Slack channel to gauge interest. SIGs with enough traction to produce work may have their own GitHub repositories and regular Zoom calls, and ultimately produce work that becomes part of, or a companion to, the OpenAPI Specification. 4 | 5 | See the [OAS community repository](https://github.com/OAI/community/blob/main/SPECIAL_INTEREST_GROUPS.md) for a complete list of SIGs, and for more information about forming a SIG. 6 | -------------------------------------------------------------------------------- /TOB.md: -------------------------------------------------------------------------------- 1 | # Technical Oversight Board ("TOB") 2 | 3 | ## Description 4 | 5 | > The TOB is responsible for managing conflicts, violations of procedures or guidelines or other issues that cannot be resolved in the TSC for the OAS. For further details please consult the OpenAPI Project Charter. 6 | 7 | ## TSC Elected - terms through May 2023 8 | 9 | Isabelle Mauny @isamauny 10 | 11 | Uri Sarid @usarid 12 | 13 | Marsh Gardiner @earth2marsh 14 | 15 | Ron Ratovsky @webron 16 | 17 | ## BGB Elected - terms through May 2022 18 | 19 | Darrel Miller @darrelmiller 20 | 21 | Jerome Louvel @jlouvel 22 | 23 | Jeremy Whitlock @whitlockjc 24 | -------------------------------------------------------------------------------- /_archive_/README.md: -------------------------------------------------------------------------------- 1 | # Archive 2 | 3 | This folder contains files that are no longer actively maintained. 4 | -------------------------------------------------------------------------------- /_archive_/schemas/README.md: -------------------------------------------------------------------------------- 1 | # Archive of outdated JSON Schema Files 2 | 3 | > [!TIP] 4 | > JSON Schema files for validating OpenAPI descriptions using current OpenAPI versions are available on https://spec.openapis.org/#openapi-specification-schemas. 5 | > 6 | > These schema files are maintained in the `src/schemas` folder of the corresponding `vX.Y-dev` branch in this repository. 7 | 8 | > [!CAUTION] 9 | > Schema files in this folder are not maintained any more and are not intended for productive use. 10 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/README.md: -------------------------------------------------------------------------------- 1 | # Swagger Specification JSON Schemas 2 | 3 | The work on the JSON Schema for the Swagger Specification was donated to the community by [Francis Galiegue](https://github.com/fge)! 4 | 5 | Keep in mind that due to some JSON Schema limitations, not all constraints can be described. The missing constraints will be listed here in the future. 6 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/apiDeclaration.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/apiDeclaration.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "swaggerVersion", "basePath", "apis" ], 6 | "properties": { 7 | "swaggerVersion": { "enum": [ "1.2" ] }, 8 | "apiVersion": { "type": "string" }, 9 | "basePath": { 10 | "type": "string", 11 | "format": "uri", 12 | "pattern": "^https?://" 13 | }, 14 | "resourcePath": { 15 | "type": "string", 16 | "format": "uri", 17 | "pattern": "^/" 18 | }, 19 | "apis": { 20 | "type": "array", 21 | "items": { "$ref": "#/definitions/apiObject" } 22 | }, 23 | "models": { 24 | "type": "object", 25 | "additionalProperties": { 26 | "$ref": "modelsObject.json#" 27 | } 28 | }, 29 | "produces": { "$ref": "#/definitions/mimeTypeArray" }, 30 | "consumes": { "$ref": "#/definitions/mimeTypeArray" }, 31 | "authorizations": { "$ref": "authorizationObject.json#" } 32 | }, 33 | "additionalProperties": false, 34 | "definitions": { 35 | "apiObject": { 36 | "type": "object", 37 | "required": [ "path", "operations" ], 38 | "properties": { 39 | "path": { 40 | "type": "string", 41 | "format": "uri-template", 42 | "pattern": "^/" 43 | }, 44 | "description": { "type": "string" }, 45 | "operations": { 46 | "type": "array", 47 | "items": { "$ref": "operationObject.json#" } 48 | } 49 | }, 50 | "additionalProperties": false 51 | }, 52 | "mimeTypeArray": { 53 | "type": "array", 54 | "items": { 55 | "type": "string", 56 | "format": "mime-type" 57 | }, 58 | "uniqueItems": true 59 | } 60 | } 61 | } 62 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/authorizationObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/authorizationObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "additionalProperties": { 6 | "oneOf": [ 7 | { 8 | "$ref": "#/definitions/basicAuth" 9 | }, 10 | { 11 | "$ref": "#/definitions/apiKey" 12 | }, 13 | { 14 | "$ref": "#/definitions/oauth2" 15 | } 16 | ] 17 | }, 18 | "definitions": { 19 | "basicAuth": { 20 | "required": [ "type" ], 21 | "properties": { 22 | "type": { "enum": [ "basicAuth" ] } 23 | }, 24 | "additionalProperties": false 25 | }, 26 | "apiKey": { 27 | "required": [ "type", "passAs", "keyname" ], 28 | "properties": { 29 | "type": { "enum": [ "apiKey" ] }, 30 | "passAs": { "enum": [ "header", "query" ] }, 31 | "keyname": { "type": "string" } 32 | }, 33 | "additionalProperties": false 34 | }, 35 | "oauth2": { 36 | "type": "object", 37 | "required": [ "type", "grantTypes" ], 38 | "properties": { 39 | "type": { "enum": [ "oauth2" ] }, 40 | "scopes": { 41 | "type": "array", 42 | "items": { "$ref": "#/definitions/oauth2Scope" } 43 | }, 44 | "grantTypes": { "$ref": "oauth2GrantType.json#" } 45 | }, 46 | "additionalProperties": false 47 | }, 48 | "oauth2Scope": { 49 | "type": "object", 50 | "required": [ "scope" ], 51 | "properties": { 52 | "scope": { "type": "string" }, 53 | "description": { "type": "string" } 54 | }, 55 | "additionalProperties": false 56 | } 57 | } 58 | } 59 | 60 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/dataType.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataType.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "description": "Data type as described by the specification (version 1.2)", 5 | "type": "object", 6 | "oneOf": [ 7 | { "$ref": "#/definitions/refType" }, 8 | { "$ref": "#/definitions/voidType" }, 9 | { "$ref": "#/definitions/primitiveType" }, 10 | { "$ref": "#/definitions/modelType" }, 11 | { "$ref": "#/definitions/arrayType" } 12 | ], 13 | "definitions": { 14 | "refType": { 15 | "required": [ "$ref" ], 16 | "properties": { 17 | "$ref": { "type": "string" } 18 | }, 19 | "additionalProperties": false 20 | }, 21 | "voidType": { 22 | "enum": [ { "type": "void" } ] 23 | }, 24 | "modelType": { 25 | "required": [ "type" ], 26 | "properties": { 27 | "type": { 28 | "type": "string", 29 | "not": { 30 | "enum": [ "boolean", "integer", "number", "string", "array" ] 31 | } 32 | } 33 | }, 34 | "additionalProperties": false 35 | }, 36 | "primitiveType": { 37 | "required": [ "type" ], 38 | "properties": { 39 | "type": { 40 | "enum": [ "boolean", "integer", "number", "string" ] 41 | }, 42 | "format": { "type": "string" }, 43 | "defaultValue": { 44 | "not": { "type": [ "array", "object", "null" ] } 45 | }, 46 | "enum": { 47 | "type": "array", 48 | "items": { "type": "string" }, 49 | "minItems": 1, 50 | "uniqueItems": true 51 | }, 52 | "minimum": { "type": "string" }, 53 | "maximum": { "type": "string" } 54 | }, 55 | "additionalProperties": false, 56 | "dependencies": { 57 | "format": { 58 | "oneOf": [ 59 | { 60 | "properties": { 61 | "type": { "enum": [ "integer" ] }, 62 | "format": { "enum": [ "int32", "int64" ] } 63 | } 64 | }, 65 | { 66 | "properties": { 67 | "type": { "enum": [ "number" ] }, 68 | "format": { "enum": [ "float", "double" ] } 69 | } 70 | }, 71 | { 72 | "properties": { 73 | "type": { "enum": [ "string" ] }, 74 | "format": { 75 | "enum": [ "byte", "date", "date-time" ] 76 | } 77 | } 78 | } 79 | ] 80 | }, 81 | "enum": { 82 | "properties": { 83 | "type": { "enum": [ "string" ] } 84 | } 85 | }, 86 | "minimum": { 87 | "properties": { 88 | "type": { "enum": [ "integer", "number" ] } 89 | } 90 | }, 91 | "maximum": { 92 | "properties": { 93 | "type": { "enum": [ "integer", "number" ] } 94 | } 95 | } 96 | } 97 | }, 98 | "arrayType": { 99 | "required": [ "type", "items" ], 100 | "properties": { 101 | "type": { "enum": [ "array" ] }, 102 | "items": { 103 | "type": "array", 104 | "items": { "$ref": "#/definitions/itemsObject" } 105 | }, 106 | "uniqueItems": { "type": "boolean" } 107 | }, 108 | "additionalProperties": false 109 | }, 110 | "itemsObject": { 111 | "oneOf": [ 112 | { 113 | "$ref": "#/definitions/refType" 114 | }, 115 | { 116 | "allOf": [ 117 | { 118 | "$ref": "#/definitions/primitiveType" 119 | }, 120 | { 121 | "properties": { 122 | "type": {}, 123 | "format": {} 124 | }, 125 | "additionalProperties": false 126 | } 127 | ] 128 | } 129 | ] 130 | } 131 | } 132 | } -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/dataTypeBase.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataTypeBase.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "description": "Data type fields (section 4.3.3)", 5 | "type": "object", 6 | "oneOf": [ 7 | { "required": [ "type" ] }, 8 | { "required": [ "$ref" ] } 9 | ], 10 | "properties": { 11 | "type": { "type": "string" }, 12 | "$ref": { "type": "string" }, 13 | "format": { "type": "string" }, 14 | "defaultValue": { 15 | "not": { "type": [ "array", "object", "null" ] } 16 | }, 17 | "enum": { 18 | "type": "array", 19 | "items": { "type": "string" }, 20 | "uniqueItems": true, 21 | "minItems": 1 22 | }, 23 | "minimum": { "type": "string" }, 24 | "maximum": { "type": "string" }, 25 | "items": { "$ref": "#/definitions/itemsObject" }, 26 | "uniqueItems": { "type": "boolean" } 27 | }, 28 | "dependencies": { 29 | "format": { 30 | "oneOf": [ 31 | { 32 | "properties": { 33 | "type": { "enum": [ "integer" ] }, 34 | "format": { "enum": [ "int32", "int64" ] } 35 | } 36 | }, 37 | { 38 | "properties": { 39 | "type": { "enum": [ "number" ] }, 40 | "format": { "enum": [ "float", "double" ] } 41 | } 42 | }, 43 | { 44 | "properties": { 45 | "type": { "enum": [ "string" ] }, 46 | "format": { 47 | "enum": [ "byte", "date", "date-time" ] 48 | } 49 | } 50 | } 51 | ] 52 | } 53 | }, 54 | "definitions": { 55 | "itemsObject": { 56 | "oneOf": [ 57 | { 58 | "type": "object", 59 | "required": [ "$ref" ], 60 | "properties": { 61 | "$ref": { "type": "string" } 62 | }, 63 | "additionalProperties": false 64 | }, 65 | { 66 | "allOf": [ 67 | { "$ref": "#" }, 68 | { 69 | "required": [ "type" ], 70 | "properties": { 71 | "type": {}, 72 | "format": {} 73 | }, 74 | "additionalProperties": false 75 | } 76 | ] 77 | } 78 | ] 79 | } 80 | } 81 | } 82 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/infoObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/infoObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "description": "info object (section 5.1.3)", 5 | "type": "object", 6 | "required": [ "title", "description" ], 7 | "properties": { 8 | "title": { "type": "string" }, 9 | "description": { "type": "string" }, 10 | "termsOfServiceUrl": { "type": "string", "format": "uri" }, 11 | "contact": { "type": "string", "format": "email" }, 12 | "license": { "type": "string" }, 13 | "licenseUrl": { "type": "string", "format": "uri" } 14 | }, 15 | "additionalProperties": false 16 | } -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/modelsObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/modelsObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "id", "properties" ], 6 | "properties": { 7 | "id": { "type": "string" }, 8 | "description": { "type": "string" }, 9 | "properties": { 10 | "type": "object", 11 | "additionalProperties": { "$ref": "#/definitions/propertyObject" } 12 | }, 13 | "subTypes": { 14 | "type": "array", 15 | "items": { "type": "string" }, 16 | "uniqueItems": true 17 | }, 18 | "discriminator": { "type": "string" } 19 | }, 20 | "dependencies": { 21 | "subTypes": [ "discriminator" ] 22 | }, 23 | "definitions": { 24 | "propertyObject": { 25 | "allOf": [ 26 | { 27 | "not": { "$ref": "#" } 28 | }, 29 | { 30 | "$ref": "dataTypeBase.json#" 31 | } 32 | ] 33 | } 34 | } 35 | } 36 | 37 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/oauth2GrantType.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/oauth2GrantType.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "minProperties": 1, 6 | "properties": { 7 | "implicit": { "$ref": "#/definitions/implicit" }, 8 | "authorization_code": { "$ref": "#/definitions/authorizationCode" } 9 | }, 10 | "definitions": { 11 | "implicit": { 12 | "type": "object", 13 | "required": [ "loginEndpoint" ], 14 | "properties": { 15 | "loginEndpoint": { "$ref": "#/definitions/loginEndpoint" }, 16 | "tokenName": { "type": "string" } 17 | }, 18 | "additionalProperties": false 19 | }, 20 | "authorizationCode": { 21 | "type": "object", 22 | "required": [ "tokenEndpoint", "tokenRequestEndpoint" ], 23 | "properties": { 24 | "tokenEndpoint": { "$ref": "#/definitions/tokenEndpoint" }, 25 | "tokenRequestEndpoint": { "$ref": "#/definitions/tokenRequestEndpoint" } 26 | }, 27 | "additionalProperties": false 28 | }, 29 | "loginEndpoint": { 30 | "type": "object", 31 | "required": [ "url" ], 32 | "properties": { 33 | "url": { "type": "string", "format": "uri" } 34 | }, 35 | "additionalProperties": false 36 | }, 37 | "tokenEndpoint": { 38 | "type": "object", 39 | "required": [ "url" ], 40 | "properties": { 41 | "url": { "type": "string", "format": "uri" }, 42 | "tokenName": { "type": "string" } 43 | }, 44 | "additionalProperties": false 45 | }, 46 | "tokenRequestEndpoint": { 47 | "type": "object", 48 | "required": [ "url" ], 49 | "properties": { 50 | "url": { "type": "string", "format": "uri" }, 51 | "clientIdName": { "type": "string" }, 52 | "clientSecretName": { "type": "string" } 53 | }, 54 | "additionalProperties": false 55 | } 56 | } 57 | } -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/operationObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/operationObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "allOf": [ 6 | { "$ref": "dataTypeBase.json#" }, 7 | { 8 | "required": [ "method", "nickname", "parameters" ], 9 | "properties": { 10 | "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" ] }, 11 | "summary": { "type": "string" }, 12 | "notes": { "type": "string" }, 13 | "nickname": { 14 | "type": "string", 15 | "pattern": "^[a-zA-Z0-9_]+$" 16 | }, 17 | "authorizations": { 18 | "type": "object", 19 | "additionalProperties": { 20 | "type": "array", 21 | "items": { 22 | "$ref": "authorizationObject.json#/definitions/oauth2Scope" 23 | } 24 | } 25 | }, 26 | "parameters": { 27 | "type": "array", 28 | "items": { "$ref": "parameterObject.json#" } 29 | }, 30 | "responseMessages": { 31 | "type": "array", 32 | "items": { "$ref": "#/definitions/responseMessageObject"} 33 | }, 34 | "produces": { "$ref": "#/definitions/mimeTypeArray" }, 35 | "consumes": { "$ref": "#/definitions/mimeTypeArray" }, 36 | "deprecated": { "enum": [ "true", "false" ] } 37 | } 38 | } 39 | ], 40 | "definitions": { 41 | "responseMessageObject": { 42 | "type": "object", 43 | "required": [ "code", "message" ], 44 | "properties": { 45 | "code": { "$ref": "#/definitions/rfc2616section10" }, 46 | "message": { "type": "string" }, 47 | "responseModel": { "type": "string" } 48 | } 49 | }, 50 | "rfc2616section10": { 51 | "type": "integer", 52 | "minimum": 100, 53 | "maximum": 600, 54 | "exclusiveMaximum": true 55 | }, 56 | "mimeTypeArray": { 57 | "type": "array", 58 | "items": { 59 | "type": "string", 60 | "format": "mime-type" 61 | }, 62 | "uniqueItems": true 63 | } 64 | } 65 | } 66 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/parameterObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/parameterObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "allOf": [ 6 | { "$ref": "dataTypeBase.json#" }, 7 | { 8 | "required": [ "paramType", "name" ], 9 | "properties": { 10 | "paramType": { 11 | "enum": [ "path", "query", "body", "header", "form" ] 12 | }, 13 | "name": { "type": "string" }, 14 | "description": { "type": "string" }, 15 | "required": { "type": "boolean" }, 16 | "allowMultiple": { "type": "boolean" } 17 | } 18 | }, 19 | { 20 | "description": "type File requires special paramType and consumes", 21 | "oneOf": [ 22 | { 23 | "properties": { 24 | "type": { "not": { "enum": [ "File" ] } } 25 | } 26 | }, 27 | { 28 | "properties": { 29 | "type": { "enum": [ "File" ] }, 30 | "paramType": { "enum": [ "form" ] }, 31 | "consumes": { "enum": [ "multipart/form-data" ] } 32 | } 33 | } 34 | ] 35 | } 36 | ] 37 | } 38 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/resourceListing.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceListing.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "swaggerVersion", "apis" ], 6 | "properties": { 7 | "swaggerVersion": { "enum": [ "1.2" ] }, 8 | "apis": { 9 | "type": "array", 10 | "items": { "$ref": "resourceObject.json#" } 11 | }, 12 | "apiVersion": { "type": "string" }, 13 | "info": { "$ref": "infoObject.json#" }, 14 | "authorizations": { "$ref": "authorizationObject.json#" } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /_archive_/schemas/v1.2/resourceObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "path" ], 6 | "properties": { 7 | "path": { "type": "string", "format": "uri" }, 8 | "description": { "type": "string" } 9 | }, 10 | "additionalProperties": false 11 | } -------------------------------------------------------------------------------- /_archive_/schemas/v2.0/README.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Specification v2.0 JSON Schema 2 | 3 | This is the JSON Schema file for the OpenAPI Specification version 2.0. Download and install it via NPM. 4 | 5 | ## Install via NPM 6 | 7 | ```shell 8 | npm install --save swagger-schema-official 9 | ``` 10 | 11 | ## License 12 | 13 | Apache-2.0 14 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/README.md: -------------------------------------------------------------------------------- 1 | # OpenAPI 3.0.X JSON Schema 2 | 3 | This directory contains the YAML source for generating the JSON Schema for validating OpenAPI definitions of versions 3.0.X, which is published on [https://spec.openapis.org](https://spec.openapis.org). 4 | 5 | Due to limitations of GitHub pages, the schemas on the spec site are served with `Content-Type: application/octet-stream`, but should be interpreted as `application/schema+json`. 6 | 7 | The source in this directory, which has `WORK-IN-PROGRESS` in its `id`, is _not intended for direct use_. 8 | 9 | ## Schema `id` dates 10 | 11 | The published schemas on the spec site have an _iteration date_ in their `id`s. 12 | This allows the schemas for a release line (in this case 3.0) to be updated independent of the spec patch release cycle. 13 | 14 | The iteration version of the JSON Schema can be found in the `id` field. 15 | For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. 16 | 17 | We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) how to best provide programmatic access for determining the latest date for each schema. 18 | 19 | ## Improving the schema 20 | 21 | As a reminder, the JSON Schema is not the source of truth for the Specification. 22 | In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. 23 | Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance. 24 | 25 | The schema only validates the mandatory aspects of the OAS. 26 | Validating requirements that are optional, or field usage that has undefined or ignored behavior are not within the scope of this schema. 27 | Schemas to perform additional optional validation are [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4141). 28 | 29 | Improvements can be submitted by opening a PR against the `main` branch. 30 | 31 | Modify the `schema.yaml` file and add test cases for your changes. 32 | 33 | The TSC will then: 34 | - Run tests on the updated schema 35 | - Update the iteration version 36 | - Publish the new version 37 | 38 | The [test suite](../../tests/v3.0) is part of this package. 39 | 40 | ```bash 41 | npm install 42 | npm test 43 | ``` 44 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/pass/api-with-examples.yaml: -------------------------------------------------------------------------------- 1 | openapi: "3.0.0" 2 | info: 3 | title: Simple API overview 4 | version: 2.0.0 5 | paths: 6 | /: 7 | get: 8 | operationId: listVersionsv2 9 | summary: List API versions 10 | responses: 11 | '200': 12 | description: |- 13 | 200 response 14 | content: 15 | application/json: 16 | examples: 17 | foo: 18 | value: 19 | { 20 | "versions": [ 21 | { 22 | "status": "CURRENT", 23 | "updated": "2011-01-21T11:33:21Z", 24 | "id": "v2.0", 25 | "links": [ 26 | { 27 | "href": "http://127.0.0.1:8774/v2/", 28 | "rel": "self" 29 | } 30 | ] 31 | }, 32 | { 33 | "status": "EXPERIMENTAL", 34 | "updated": "2013-07-23T11:33:21Z", 35 | "id": "v3.0", 36 | "links": [ 37 | { 38 | "href": "http://127.0.0.1:8774/v3/", 39 | "rel": "self" 40 | } 41 | ] 42 | } 43 | ] 44 | } 45 | '300': 46 | description: |- 47 | 300 response 48 | content: 49 | application/json: 50 | examples: 51 | foo: 52 | value: | 53 | { 54 | "versions": [ 55 | { 56 | "status": "CURRENT", 57 | "updated": "2011-01-21T11:33:21Z", 58 | "id": "v2.0", 59 | "links": [ 60 | { 61 | "href": "http://127.0.0.1:8774/v2/", 62 | "rel": "self" 63 | } 64 | ] 65 | }, 66 | { 67 | "status": "EXPERIMENTAL", 68 | "updated": "2013-07-23T11:33:21Z", 69 | "id": "v3.0", 70 | "links": [ 71 | { 72 | "href": "http://127.0.0.1:8774/v3/", 73 | "rel": "self" 74 | } 75 | ] 76 | } 77 | ] 78 | } 79 | /v2: 80 | get: 81 | operationId: getVersionDetailsv2 82 | summary: Show API version details 83 | responses: 84 | '200': 85 | description: |- 86 | 200 response 87 | content: 88 | application/json: 89 | examples: 90 | foo: 91 | value: 92 | { 93 | "version": { 94 | "status": "CURRENT", 95 | "updated": "2011-01-21T11:33:21Z", 96 | "media-types": [ 97 | { 98 | "base": "application/xml", 99 | "type": "application/vnd.openstack.compute+xml;version=2" 100 | }, 101 | { 102 | "base": "application/json", 103 | "type": "application/vnd.openstack.compute+json;version=2" 104 | } 105 | ], 106 | "id": "v2.0", 107 | "links": [ 108 | { 109 | "href": "http://127.0.0.1:8774/v2/", 110 | "rel": "self" 111 | }, 112 | { 113 | "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", 114 | "type": "application/pdf", 115 | "rel": "describedby" 116 | }, 117 | { 118 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 119 | "type": "application/vnd.sun.wadl+xml", 120 | "rel": "describedby" 121 | }, 122 | { 123 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 124 | "type": "application/vnd.sun.wadl+xml", 125 | "rel": "describedby" 126 | } 127 | ] 128 | } 129 | } 130 | '203': 131 | description: |- 132 | 203 response 133 | content: 134 | application/json: 135 | examples: 136 | foo: 137 | value: 138 | { 139 | "version": { 140 | "status": "CURRENT", 141 | "updated": "2011-01-21T11:33:21Z", 142 | "media-types": [ 143 | { 144 | "base": "application/xml", 145 | "type": "application/vnd.openstack.compute+xml;version=2" 146 | }, 147 | { 148 | "base": "application/json", 149 | "type": "application/vnd.openstack.compute+json;version=2" 150 | } 151 | ], 152 | "id": "v2.0", 153 | "links": [ 154 | { 155 | "href": "http://23.253.228.211:8774/v2/", 156 | "rel": "self" 157 | }, 158 | { 159 | "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", 160 | "type": "application/pdf", 161 | "rel": "describedby" 162 | }, 163 | { 164 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 165 | "type": "application/vnd.sun.wadl+xml", 166 | "rel": "describedby" 167 | } 168 | ] 169 | } 170 | } 171 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/pass/callback-example.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: Callback Example 4 | version: 1.0.0 5 | paths: 6 | /streams: 7 | post: 8 | description: subscribes a client to receive out-of-band data 9 | parameters: 10 | - name: callbackUrl 11 | in: query 12 | required: true 13 | description: | 14 | the location where data will be sent. Must be network accessible 15 | by the source server 16 | schema: 17 | type: string 18 | format: uri 19 | example: https://tonys-server.com 20 | responses: 21 | '201': 22 | description: subscription successfully created 23 | content: 24 | application/json: 25 | schema: 26 | description: subscription information 27 | required: 28 | - subscriptionId 29 | properties: 30 | subscriptionId: 31 | description: this unique identifier allows management of the subscription 32 | type: string 33 | example: 2531329f-fb09-4ef7-887e-84e648214436 34 | callbacks: 35 | # the name `onData` is a convenience locator 36 | onData: 37 | # when data is sent, it will be sent to the `callbackUrl` provided 38 | # when making the subscription PLUS the suffix `/data` 39 | '{$request.query.callbackUrl}/data': 40 | post: 41 | requestBody: 42 | description: subscription payload 43 | content: 44 | application/json: 45 | schema: 46 | type: object 47 | properties: 48 | timestamp: 49 | type: string 50 | format: date-time 51 | userData: 52 | type: string 53 | responses: 54 | '202': 55 | description: | 56 | Your server implementation should return this HTTP status code 57 | if the data was received successfully 58 | '204': 59 | description: | 60 | Your server should return this HTTP status code if no longer interested 61 | in further updates 62 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/pass/link-example.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: Link Example 4 | version: 1.0.0 5 | paths: 6 | /2.0/users/{username}: 7 | get: 8 | operationId: getUserByName 9 | parameters: 10 | - name: username 11 | in: path 12 | required: true 13 | schema: 14 | type: string 15 | responses: 16 | '200': 17 | description: The User 18 | content: 19 | application/json: 20 | schema: 21 | $ref: '#/components/schemas/user' 22 | links: 23 | userRepositories: 24 | $ref: '#/components/links/UserRepositories' 25 | /2.0/repositories/{username}: 26 | get: 27 | operationId: getRepositoriesByOwner 28 | parameters: 29 | - name: username 30 | in: path 31 | required: true 32 | schema: 33 | type: string 34 | responses: 35 | '200': 36 | description: repositories owned by the supplied user 37 | content: 38 | application/json: 39 | schema: 40 | type: array 41 | items: 42 | $ref: '#/components/schemas/repository' 43 | links: 44 | userRepository: 45 | $ref: '#/components/links/UserRepository' 46 | /2.0/repositories/{username}/{slug}: 47 | get: 48 | operationId: getRepository 49 | parameters: 50 | - name: username 51 | in: path 52 | required: true 53 | schema: 54 | type: string 55 | - name: slug 56 | in: path 57 | required: true 58 | schema: 59 | type: string 60 | responses: 61 | '200': 62 | description: The repository 63 | content: 64 | application/json: 65 | schema: 66 | $ref: '#/components/schemas/repository' 67 | links: 68 | repositoryPullRequests: 69 | $ref: '#/components/links/RepositoryPullRequests' 70 | /2.0/repositories/{username}/{slug}/pullrequests: 71 | get: 72 | operationId: getPullRequestsByRepository 73 | parameters: 74 | - name: username 75 | in: path 76 | required: true 77 | schema: 78 | type: string 79 | - name: slug 80 | in: path 81 | required: true 82 | schema: 83 | type: string 84 | - name: state 85 | in: query 86 | schema: 87 | type: string 88 | enum: 89 | - open 90 | - merged 91 | - declined 92 | responses: 93 | '200': 94 | description: an array of pull request objects 95 | content: 96 | application/json: 97 | schema: 98 | type: array 99 | items: 100 | $ref: '#/components/schemas/pullrequest' 101 | /2.0/repositories/{username}/{slug}/pullrequests/{pid}: 102 | get: 103 | operationId: getPullRequestsById 104 | parameters: 105 | - name: username 106 | in: path 107 | required: true 108 | schema: 109 | type: string 110 | - name: slug 111 | in: path 112 | required: true 113 | schema: 114 | type: string 115 | - name: pid 116 | in: path 117 | required: true 118 | schema: 119 | type: string 120 | responses: 121 | '200': 122 | description: a pull request object 123 | content: 124 | application/json: 125 | schema: 126 | $ref: '#/components/schemas/pullrequest' 127 | links: 128 | pullRequestMerge: 129 | $ref: '#/components/links/PullRequestMerge' 130 | /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: 131 | post: 132 | operationId: mergePullRequest 133 | parameters: 134 | - name: username 135 | in: path 136 | required: true 137 | schema: 138 | type: string 139 | - name: slug 140 | in: path 141 | required: true 142 | schema: 143 | type: string 144 | - name: pid 145 | in: path 146 | required: true 147 | schema: 148 | type: string 149 | responses: 150 | '204': 151 | description: the PR was successfully merged 152 | components: 153 | links: 154 | UserRepositories: 155 | # returns array of '#/components/schemas/repository' 156 | operationId: getRepositoriesByOwner 157 | parameters: 158 | username: $response.body#/username 159 | UserRepository: 160 | # returns '#/components/schemas/repository' 161 | operationId: getRepository 162 | parameters: 163 | username: $response.body#/owner/username 164 | slug: $response.body#/slug 165 | RepositoryPullRequests: 166 | # returns '#/components/schemas/pullrequest' 167 | operationId: getPullRequestsByRepository 168 | parameters: 169 | username: $response.body#/owner/username 170 | slug: $response.body#/slug 171 | PullRequestMerge: 172 | # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge 173 | operationId: mergePullRequest 174 | parameters: 175 | username: $response.body#/author/username 176 | slug: $response.body#/repository/slug 177 | pid: $response.body#/id 178 | schemas: 179 | user: 180 | type: object 181 | properties: 182 | username: 183 | type: string 184 | uuid: 185 | type: string 186 | repository: 187 | type: object 188 | properties: 189 | slug: 190 | type: string 191 | owner: 192 | $ref: '#/components/schemas/user' 193 | pullrequest: 194 | type: object 195 | properties: 196 | id: 197 | type: integer 198 | title: 199 | type: string 200 | repository: 201 | $ref: '#/components/schemas/repository' 202 | author: 203 | $ref: '#/components/schemas/user' 204 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/pass/petstore-expanded.yaml: -------------------------------------------------------------------------------- 1 | openapi: "3.0.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification 6 | termsOfService: http://swagger.io/terms/ 7 | contact: 8 | name: Swagger API Team 9 | email: apiteam@swagger.io 10 | url: http://swagger.io 11 | license: 12 | name: Apache 2.0 13 | url: https://www.apache.org/licenses/LICENSE-2.0.html 14 | servers: 15 | - url: https://petstore.swagger.io/v2 16 | paths: 17 | /pets: 18 | get: 19 | description: | 20 | Returns all pets from the system that the user has access to 21 | Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia. 22 | 23 | Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien. 24 | operationId: findPets 25 | parameters: 26 | - name: tags 27 | in: query 28 | description: tags to filter by 29 | required: false 30 | style: form 31 | schema: 32 | type: array 33 | items: 34 | type: string 35 | - name: limit 36 | in: query 37 | description: maximum number of results to return 38 | required: false 39 | schema: 40 | type: integer 41 | format: int32 42 | responses: 43 | '200': 44 | description: pet response 45 | content: 46 | application/json: 47 | schema: 48 | type: array 49 | items: 50 | $ref: '#/components/schemas/Pet' 51 | default: 52 | description: unexpected error 53 | content: 54 | application/json: 55 | schema: 56 | $ref: '#/components/schemas/Error' 57 | post: 58 | description: Creates a new pet in the store. Duplicates are allowed 59 | operationId: addPet 60 | requestBody: 61 | description: Pet to add to the store 62 | required: true 63 | content: 64 | application/json: 65 | schema: 66 | $ref: '#/components/schemas/NewPet' 67 | responses: 68 | '200': 69 | description: pet response 70 | content: 71 | application/json: 72 | schema: 73 | $ref: '#/components/schemas/Pet' 74 | default: 75 | description: unexpected error 76 | content: 77 | application/json: 78 | schema: 79 | $ref: '#/components/schemas/Error' 80 | /pets/{id}: 81 | get: 82 | description: Returns a user based on a single ID, if the user does not have access to the pet 83 | operationId: find pet by id 84 | parameters: 85 | - name: id 86 | in: path 87 | description: ID of pet to fetch 88 | required: true 89 | schema: 90 | type: integer 91 | format: int64 92 | responses: 93 | '200': 94 | description: pet response 95 | content: 96 | application/json: 97 | schema: 98 | $ref: '#/components/schemas/Pet' 99 | default: 100 | description: unexpected error 101 | content: 102 | application/json: 103 | schema: 104 | $ref: '#/components/schemas/Error' 105 | delete: 106 | description: deletes a single pet based on the ID supplied 107 | operationId: deletePet 108 | parameters: 109 | - name: id 110 | in: path 111 | description: ID of pet to delete 112 | required: true 113 | schema: 114 | type: integer 115 | format: int64 116 | responses: 117 | '204': 118 | description: pet deleted 119 | default: 120 | description: unexpected error 121 | content: 122 | application/json: 123 | schema: 124 | $ref: '#/components/schemas/Error' 125 | components: 126 | schemas: 127 | Pet: 128 | allOf: 129 | - $ref: '#/components/schemas/NewPet' 130 | - type: object 131 | required: 132 | - id 133 | properties: 134 | id: 135 | type: integer 136 | format: int64 137 | 138 | NewPet: 139 | type: object 140 | required: 141 | - name 142 | properties: 143 | name: 144 | type: string 145 | tag: 146 | type: string 147 | 148 | Error: 149 | type: object 150 | required: 151 | - code 152 | - message 153 | properties: 154 | code: 155 | type: integer 156 | format: int32 157 | message: 158 | type: string 159 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/pass/petstore.yaml: -------------------------------------------------------------------------------- 1 | openapi: "3.0.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | license: 6 | name: MIT 7 | servers: 8 | - url: http://petstore.swagger.io/v1 9 | paths: 10 | /pets: 11 | get: 12 | summary: List all pets 13 | operationId: listPets 14 | tags: 15 | - pets 16 | parameters: 17 | - name: limit 18 | in: query 19 | description: How many items to return at one time (max 100) 20 | required: false 21 | schema: 22 | type: integer 23 | maximum: 100 24 | format: int32 25 | responses: 26 | '200': 27 | description: A paged array of pets 28 | headers: 29 | x-next: 30 | description: A link to the next page of responses 31 | schema: 32 | type: string 33 | content: 34 | application/json: 35 | schema: 36 | $ref: "#/components/schemas/Pets" 37 | default: 38 | description: unexpected error 39 | content: 40 | application/json: 41 | schema: 42 | $ref: "#/components/schemas/Error" 43 | post: 44 | summary: Create a pet 45 | operationId: createPets 46 | tags: 47 | - pets 48 | requestBody: 49 | content: 50 | application/json: 51 | schema: 52 | $ref: '#/components/schemas/Pet' 53 | required: true 54 | responses: 55 | '201': 56 | description: Null response 57 | default: 58 | description: unexpected error 59 | content: 60 | application/json: 61 | schema: 62 | $ref: "#/components/schemas/Error" 63 | /pets/{petId}: 64 | get: 65 | summary: Info for a specific pet 66 | operationId: showPetById 67 | tags: 68 | - pets 69 | parameters: 70 | - name: petId 71 | in: path 72 | required: true 73 | description: The id of the pet to retrieve 74 | schema: 75 | type: string 76 | responses: 77 | '200': 78 | description: Expected response to a valid request 79 | content: 80 | application/json: 81 | schema: 82 | $ref: "#/components/schemas/Pet" 83 | default: 84 | description: unexpected error 85 | content: 86 | application/json: 87 | schema: 88 | $ref: "#/components/schemas/Error" 89 | components: 90 | schemas: 91 | Pet: 92 | type: object 93 | required: 94 | - id 95 | - name 96 | properties: 97 | id: 98 | type: integer 99 | format: int64 100 | name: 101 | type: string 102 | tag: 103 | type: string 104 | Pets: 105 | type: array 106 | maxItems: 100 107 | items: 108 | $ref: "#/components/schemas/Pet" 109 | Error: 110 | type: object 111 | required: 112 | - code 113 | - message 114 | properties: 115 | code: 116 | type: integer 117 | format: int32 118 | message: 119 | type: string 120 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/pass/uspto.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.1 2 | servers: 3 | - url: '{scheme}://developer.uspto.gov/ds-api' 4 | variables: 5 | scheme: 6 | description: 'The Data Set API is accessible via https and http' 7 | enum: 8 | - 'https' 9 | - 'http' 10 | default: 'https' 11 | info: 12 | description: >- 13 | The Data Set API (DSAPI) allows the public users to discover and search 14 | USPTO exported data sets. This is a generic API that allows USPTO users to 15 | make any CSV based data files searchable through API. With the help of GET 16 | call, it returns the list of data fields that are searchable. With the help 17 | of POST call, data can be fetched based on the filters on the field names. 18 | Please note that POST call is used to search the actual data. The reason for 19 | the POST call is that it allows users to specify any complex search criteria 20 | without worry about the GET size limitations as well as encoding of the 21 | input parameters. 22 | version: 1.0.0 23 | title: USPTO Data Set API 24 | contact: 25 | name: Open Data Portal 26 | url: 'https://developer.uspto.gov' 27 | email: developer@uspto.gov 28 | tags: 29 | - name: metadata 30 | description: Find out about the data sets 31 | - name: search 32 | description: Search a data set 33 | paths: 34 | /: 35 | get: 36 | tags: 37 | - metadata 38 | operationId: list-data-sets 39 | summary: List available data sets 40 | responses: 41 | '200': 42 | description: Returns a list of data sets 43 | content: 44 | application/json: 45 | schema: 46 | $ref: '#/components/schemas/dataSetList' 47 | example: 48 | { 49 | "total": 2, 50 | "apis": [ 51 | { 52 | "apiKey": "oa_citations", 53 | "apiVersionNumber": "v1", 54 | "apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields", 55 | "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json" 56 | }, 57 | { 58 | "apiKey": "cancer_moonshot", 59 | "apiVersionNumber": "v1", 60 | "apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields", 61 | "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json" 62 | } 63 | ] 64 | } 65 | /{dataset}/{version}/fields: 66 | get: 67 | tags: 68 | - metadata 69 | summary: >- 70 | Provides the general information about the API and the list of fields 71 | that can be used to query the dataset. 72 | description: >- 73 | This GET API returns the list of all the searchable field names that are 74 | in the oa_citations. Please see the 'fields' attribute which returns an 75 | array of field names. Each field or a combination of fields can be 76 | searched using the syntax options shown below. 77 | operationId: list-searchable-fields 78 | parameters: 79 | - name: dataset 80 | in: path 81 | description: 'Name of the dataset.' 82 | required: true 83 | example: "oa_citations" 84 | schema: 85 | type: string 86 | - name: version 87 | in: path 88 | description: Version of the dataset. 89 | required: true 90 | example: "v1" 91 | schema: 92 | type: string 93 | responses: 94 | '200': 95 | description: >- 96 | The dataset API for the given version is found and it is accessible 97 | to consume. 98 | content: 99 | application/json: 100 | schema: 101 | type: string 102 | '404': 103 | description: >- 104 | The combination of dataset name and version is not found in the 105 | system or it is not published yet to be consumed by public. 106 | content: 107 | application/json: 108 | schema: 109 | type: string 110 | /{dataset}/{version}/records: 111 | post: 112 | tags: 113 | - search 114 | summary: >- 115 | Provides search capability for the data set with the given search 116 | criteria. 117 | description: >- 118 | This API is based on Solr/Lucene Search. The data is indexed using 119 | SOLR. This GET API returns the list of all the searchable field names 120 | that are in the Solr Index. Please see the 'fields' attribute which 121 | returns an array of field names. Each field or a combination of fields 122 | can be searched using the Solr/Lucene Syntax. Please refer 123 | https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for 124 | the query syntax. List of field names that are searchable can be 125 | determined using above GET api. 126 | operationId: perform-search 127 | parameters: 128 | - name: version 129 | in: path 130 | description: Version of the dataset. 131 | required: true 132 | schema: 133 | type: string 134 | default: v1 135 | - name: dataset 136 | in: path 137 | description: 'Name of the dataset. In this case, the default value is oa_citations' 138 | required: true 139 | schema: 140 | type: string 141 | default: oa_citations 142 | responses: 143 | '200': 144 | description: successful operation 145 | content: 146 | application/json: 147 | schema: 148 | type: array 149 | items: 150 | type: object 151 | additionalProperties: 152 | type: object 153 | '404': 154 | description: No matching record found for the given criteria. 155 | requestBody: 156 | content: 157 | application/x-www-form-urlencoded: 158 | schema: 159 | type: object 160 | properties: 161 | criteria: 162 | description: >- 163 | Uses Lucene Query Syntax in the format of 164 | propertyName:value, propertyName:[num1 TO num2] and date 165 | range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the 166 | response please see the 'docs' element which has the list of 167 | record objects. Each record structure would consist of all 168 | the fields and their corresponding values. 169 | type: string 170 | default: '*:*' 171 | start: 172 | description: Starting record number. Default value is 0. 173 | type: integer 174 | default: 0 175 | rows: 176 | description: >- 177 | Specify number of rows to be returned. If you run the search 178 | with default values, in the response you will see 'numFound' 179 | attribute which will tell the number of records available in 180 | the dataset. 181 | type: integer 182 | default: 100 183 | required: 184 | - criteria 185 | components: 186 | schemas: 187 | dataSetList: 188 | type: object 189 | properties: 190 | total: 191 | type: integer 192 | apis: 193 | type: array 194 | items: 195 | type: object 196 | properties: 197 | apiKey: 198 | type: string 199 | description: To be used as a dataset parameter value 200 | apiVersionNumber: 201 | type: string 202 | description: To be used as a version parameter value 203 | apiUrl: 204 | type: string 205 | format: uriref 206 | description: "The URL describing the dataset's fields" 207 | apiDocumentationUrl: 208 | type: string 209 | format: uriref 210 | description: A URL to the API console for each API 211 | -------------------------------------------------------------------------------- /_archive_/schemas/v3.0/schema.test.mjs: -------------------------------------------------------------------------------- 1 | import { readdirSync, readFileSync } from "node:fs"; 2 | import YAML from "yaml"; 3 | import { validate, setMetaSchemaOutputFormat } from "@hyperjump/json-schema/openapi-3-0"; 4 | import { BASIC } from "@hyperjump/json-schema/experimental"; 5 | import { describe, test, expect } from "vitest"; 6 | 7 | import contentTypeParser from "content-type"; 8 | import { addMediaTypePlugin } from "@hyperjump/browser"; 9 | import { buildSchemaDocument } from "@hyperjump/json-schema/experimental"; 10 | 11 | addMediaTypePlugin("application/schema+yaml", { 12 | parse: async (response) => { 13 | const contentType = contentTypeParser.parse(response.headers.get("content-type") ?? ""); 14 | const contextDialectId = contentType.parameters.schema ?? contentType.parameters.profile; 15 | 16 | const foo = YAML.parse(await response.text()); 17 | return buildSchemaDocument(foo, response.url, contextDialectId); 18 | }, 19 | fileMatcher: (path) => path.endsWith(".yaml") 20 | }); 21 | 22 | const parseYamlFromFile = (filePath) => { 23 | const schemaYaml = readFileSync(filePath, "utf8"); 24 | return YAML.parse(schemaYaml, { prettyErrors: true }); 25 | }; 26 | 27 | setMetaSchemaOutputFormat(BASIC); 28 | 29 | const validateOpenApi = await validate("./_archive_/schemas/v3.0/schema.yaml"); 30 | const folder = './_archive_/schemas/v3.0/pass/'; 31 | 32 | describe("pass", async () => { 33 | readdirSync(folder, { withFileTypes: true }) 34 | .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) 35 | .forEach((entry) => { 36 | test(entry.name, () => { 37 | const instance = parseYamlFromFile(folder + entry.name); 38 | const output = validateOpenApi(instance, BASIC); 39 | expect(output.valid).to.equal(true); 40 | }); 41 | }); 42 | }); 43 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "oas-infra", 3 | "version": "0.0.0", 4 | "description": "OpenAPI Specification Automation & Infrastructure", 5 | "author": { 6 | "name": "OpenAPI Initiative TSC", 7 | "email": "tsc@openapis.org", 8 | "url": "https://openapis.org/" 9 | }, 10 | "repository": { 11 | "type": "git", 12 | "url": "https://github.com/OAI/OpenAPI-Specification.git" 13 | }, 14 | "license": "Apache-2.0", 15 | "scripts": { 16 | "build": "bash ./scripts/md2html/build.sh", 17 | "build-src": "npm run validate-markdown && bash ./scripts/md2html/build.sh src && bash ./scripts/schema-publish.sh src", 18 | "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh", 19 | "format-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml --fix src/oas.md && npx markdownlint-cli2 --fix *.md", 20 | "validate-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml src/oas.md && npx markdownlint-cli2 *.md" 21 | }, 22 | "dependencies": { 23 | "cheerio": "^1.0.0-rc.5", 24 | "highlight.js": "^11.11.1", 25 | "markdown-it": "^14.1.0", 26 | "respec": "35.3.1", 27 | "yargs": "^17.7.2" 28 | }, 29 | "devDependencies": { 30 | "@hyperjump/json-schema": "^1.13.0", 31 | "c8": "^10.1.3", 32 | "markdownlint-cli2": "^0.17.2", 33 | "vitest": "^3.1.2", 34 | "yaml": "^2.7.1" 35 | }, 36 | "keywords": [ 37 | "OpenAPI", 38 | "OAS", 39 | "Swagger", 40 | "schema", 41 | "API" 42 | ] 43 | } 44 | -------------------------------------------------------------------------------- /proposals/2019-01-01-Proposal-Template.md: -------------------------------------------------------------------------------- 1 | # Feature name 2 | 3 | 4 | ## Metadata 5 | 6 | |Tag |Value | 7 | |---- | ---------------- | 8 | |Proposal |[YYYY-MM-DD-Short-Name](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name.md})| 9 | |Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| 10 | |Review Manager | TBD | 11 | |Status |Proposal, Draft, Promoted, or Abandoned| 12 | |Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name}/implementations.md)| 13 | |Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{IssueId})| 14 | |Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | 15 | 16 | ## Change Log 17 | 18 | |Date |Responsible Party |Description | 19 | |---- | ---------------- | ---------- | 20 | 21 | ## Introduction 22 | 23 | A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. 24 | 25 | ## Motivation 26 | 27 | Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code. 28 | 29 | ## Proposed solution 30 | 31 | Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? 32 | 33 | ## Detailed design 34 | 35 | Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section. 36 | 37 | ## Backwards compatibility 38 | 39 | Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed. 40 | 41 | ## Alternatives considered 42 | 43 | Describe alternative approaches to addressing the same problem, and why you chose this approach instead. 44 | 45 | -------------------------------------------------------------------------------- /proposals/2019-03-15-Alternative-Schema.md: -------------------------------------------------------------------------------- 1 | # Alternative Schema 2 | 3 | ## Metadata 4 | 5 | |Tag |Value | 6 | |---- | ---------------- | 7 | |Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/2019-03-15-Alternative-Schema.md)| 8 | |Authors|[Chuck Heazel](https://github.com/cmheazel)| 9 | |Review Manager |TBD | 10 | |Status |**Draft** | 11 | |Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative-Schema/implementations.md) 12 | |Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)| 13 | |Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) | 14 | 15 | .Change Log 16 | 17 | |Date |Responsible Party |Description | 18 | |---- | ---------------- | ---------- | 19 | |2019-03-15 |C. Heazel|Initial Markup Draft | 20 | |2019-04-17 |C. Heazel|Re-structured based on Apple Swift| 21 | 22 | ## Introduction 23 | 24 | This a proposal to add a new field called ``alternativeSchema`` to the OAS. 25 | 26 | ## Motivation 27 | 28 | OpenAPI allows APIs to describe the syntax of their request and response messaged using a JSON Schema-like syntax. However, not all messages will be in JSON. The ability to refer to one or more external schema will allow an API to describe the syntax of a message regardless of the format used. 29 | 30 | For example: Some XML payloads are defined by an XML schema (the syntax) and a suite of Schematron rules (valid values). JSON Schema cannot effectively represent their content. By providing access to the appropriate appropriate XML Schema and Schematron files, the payload can be validated the way it was intended to be. 31 | 32 | ## Proposed solution 33 | 34 | This proposal makes the following changes to the OAS 3.0 specification: 35 | 36 | 1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field. 37 | 1. Addition of the Alternative Schema Object. 38 | 1. Addition of Alternative Schema examples. 39 | 1. Addition of a preliminary discussion of the Alternative Schema registry. 40 | 41 | ## Detailed design 42 | 43 | ### Extend the Schema Object 44 | 45 | The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/schema_object.md) 46 | 47 | ### Add the Alternative Schema Object 48 | 49 | The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/alternative_schema_object.md) 50 | 51 | ### Provide Alternative Schema Examples 52 | Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/Alternative%20Schema/alternative_schema_examples.md) 53 | 54 | ### Alternative Schema Registry 55 | 56 | Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located at . 57 | 58 | *** Note this is a placeholder registry. Don't take the values seriously. *** 59 | 60 | Initial contents of the registry will include: 61 | 62 | |Name |Link |Description | 63 | |--- | --- | --- | 64 | |jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema | 65 | 66 | ## Backwards compatibility 67 | 68 | This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly. 69 | 70 | ## Alternatives considered 71 | 72 | Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an external link was preferred. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language. 73 | 74 | -------------------------------------------------------------------------------- /proposals/2019-12-24-Overlays.md: -------------------------------------------------------------------------------- 1 | # Overlays 2 | 3 | ## Metadata 4 | 5 | |Tag |Value | 6 | |---- | ---------------- | 7 | |Proposal |[2019-12-24-Overlays](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/2019-12-24-Overlays.md)| 8 | |Authors|[Darrel Miller](https://github.com/darrelmiller)| 9 | |Status |Proposal| 10 | |Issues |[1442](https://github.com/OAI/OpenAPI-Specification/issues/1442) [1722](https://github.com/OAI/OpenAPI-Specification/issues/1722)| 11 | 12 | ## Change Log 13 | 14 | |Date |Responsible Party |Description | 15 | |---- | ---------------- | ---------- | 16 | | 24th December 2019 | Darrel Miller | Initial draft | 17 | | 2nd January 2019 | Darrel Miller | Update to wording around removing items from arrays. Added section on backward compatibility. Clarified process around applying a set of updates. Started to add supported scenarios.| 18 | | 29th July 2020 | Darrel Miller | Updated to be explicit about update operations | 19 | 20 | ## Introduction 21 | 22 | In recent months we have been discussing various use cases for overlays and various solutions. The following proposal takes a somewhat more radical approach to the problem. It is a more ambitious proposal than the others we have seen before but the additional complexity does allow for supporting many of the scenarios that have been discussed to date. 23 | 24 | #### Overlay Document 25 | 26 | An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid. 27 | 28 | 29 | #### Overlay Object 30 | 31 | This is the root object of the [OpenAPI Overlay document](#oasDocument). 32 | 33 | ##### Fixed Fields 34 | 35 | Field Name | Type | Description 36 | ---|:---:|--- 37 | overlay | `string` | Version of the Overlay specification that this document conforms to. 38 | info | [[Info Object](#overlayInfoObject)] | Identifying information about the overlay. 39 | extends | `url` | URL to an OpenAPI document this overlay applies to. 40 | updates | [[Update Object](#updateObject)] | A list of update objects to be applied to the target document. 41 | 42 | The list of update objects MUST be applied in sequential order to ensure a consistent outcome. Updates are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update. 43 | 44 | The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. This is an optional property. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description. 45 | 46 | #### Info Object 47 | 48 | This object contains identifying information about the [OpenAPI Overlay document](#oasDocument). 49 | 50 | ##### Fixed Fields 51 | 52 | Field Name | Type | Description 53 | ---|:---:|--- 54 | title | `string` | A human readable description of the purpose of the overlay. 55 | version | `string` | A version identifier for indicating changes to an overlay document. 56 | 57 | #### Update Object 58 | 59 | This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath. 60 | 61 | ##### Fixed Fields 62 | 63 | Field Name | Type | Description 64 | ---|:---:|--- 65 | target | `string` | A JMESPath expression referencing the target objects in the target document. 66 | add | [Any](#addObject) | An object to be added as a child of the object(s) referenced by the target. Property has no impact if `remove` property is `true`. 67 | merge | [Any](#mergeObject) | An object with the properties and values to be merged with the object(s) referenced by the target. Property has no impact if `remove` property is `true`. 68 | remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false. 69 | 70 | The properties of the merge object MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object. 71 | 72 | ##### Structured Overlays Example 73 | 74 | When updating properties throughout the target document it may be more efficient to create a single `Update Object` that mirrors the structure of the target document. e.g. 75 | 76 | ```yaml 77 | overlay: 1.0.0 78 | info: 79 | title: Structured Overlay 80 | version: 1.0.0 81 | updates: 82 | - target: "@" 83 | merge: 84 | info: 85 | x-overlay-applied: structured-overlay 86 | paths: 87 | "/": 88 | summary: "The root resource" 89 | get: 90 | summary: "Retrieve the root resource" 91 | x-rate-limit: 100 92 | "/pets": 93 | get: 94 | summary: "Retrieve a list of pets" 95 | x-rate-limit: 100 96 | components: 97 | tags: 98 | ``` 99 | 100 | ##### Targeted Overlays 101 | 102 | Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) can be more targeted. 103 | 104 | ```yaml 105 | overlay: 1.0.0 106 | info: 107 | title: Targeted Overlays 108 | version: 1.0.0 109 | updates: 110 | - target: paths."/foo".get 111 | merge: 112 | description: This is the new description 113 | - target: paths."/bar".get 114 | merge: 115 | description: This is the updated description 116 | - target: paths."/bar" 117 | merge: 118 | post: 119 | description: This is an updated description of a child object 120 | x-safe: false 121 | ``` 122 | 123 | ##### Wildcard Overlays Examples 124 | 125 | One significant advantage of using the JMESPath syntax that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards. 126 | 127 | ```yaml 128 | overlay: 1.0.0 129 | info: 130 | title: Update many objects at once 131 | version: 1.0.0 132 | updates: 133 | - target: paths.*.get 134 | merge: 135 | x-safe: true 136 | - target: paths.*.get.parameters[?name=='filter' && in=='query'] 137 | merge: 138 | schema: 139 | $ref: "/components/schemas/filterSchema" 140 | ``` 141 | 142 | ##### Array Modification Examples 143 | 144 | Due to the fact that we can now reference specific elements of the parameter array, it allows adding parameters. Parameters can be deleted using the `remove` property. Use of indexes to remove array items should be avoided where possible as indexes will change when items are removed. 145 | 146 | ```yaml 147 | overlay: 1.0.0 148 | info: 149 | title: Add an array element 150 | version: 1.0.0 151 | updates: 152 | - target: paths.*.get.parameters 153 | add: 154 | name: newParam 155 | in: query 156 | ``` 157 | 158 | ```yaml 159 | overlay: 1.0.0 160 | info: 161 | title: Remove a array element 162 | version: 1.0.0 163 | updates: 164 | - target: paths[*].get.parameters[? name == 'dummy'] 165 | remove: true 166 | ``` 167 | 168 | ##### Traits Examples 169 | 170 | By annotating an OpenAPI description using extension such as `x-oai-traits` an author of OpenAPI description can identify where overlay updates should be applied. 171 | 172 | ```yaml 173 | openapi: 3.1.0 174 | info: 175 | title: Api with a paged collection 176 | version: 1.0.0 177 | paths: 178 | /items: 179 | get: 180 | x-oai-traits: ["paged"] 181 | responses: 182 | 200: 183 | description: OK 184 | ``` 185 | 186 | With the above OpenAPI description, following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied. 187 | 188 | ```yaml 189 | overlay: 1.0.0 190 | info: 191 | title: Apply Traits 192 | version: 1.0.0 193 | updates: 194 | - target: $.paths[*].get[?contains(x-traits,'paged')] 195 | merge: 196 | parameters: 197 | - name: top 198 | in: query 199 | - name: skip 200 | in: query 201 | ``` 202 | 203 | This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself. 204 | 205 | ## Proposal Summary 206 | 207 | ### Benefits 208 | 209 | - This approach addresses the two distinct approaches of structured overlay vs targeted overlay which suits distinct but equally valid scenarios. 210 | - Addresses the problem of modifying the parameters array and removes the need to replace the entire array when a small change is required. 211 | - Allows sets of related overlays to be stored in a same file. 212 | - Enables updating a set of objects based on a pattern. This might be an effective way of apply common behaviour across many operations in an API. 213 | 214 | ### Challenges 215 | 216 | - Tooling will need a JMESPath implementation. 217 | - Large overlays may be slow to process. 218 | - Multiple complex pattern based overlays may cause overlapping updates causing confusing outcomes. 219 | 220 | ## Alternatives considered 221 | 222 | JMESPath was chosen over JSONPath due to the fact that JMESPath has a [specification](http://jmespath.org/specification.html) and a set of test cases. This will help to ensure compatibility between implementations. 223 | 224 | ## Backwards compatibility 225 | 226 | Overlays will be described in a new specification that can be used alongside an OpenAPI Description, therefore there will be no compatibility issues for the initial release. Overlay documents can be used against OpenAPI v2 and v3 descriptions. 227 | 228 | ## Scenarios Considered 229 | 230 | - Multi-language support. An Overlay document for each language is used to target a specific OpenAPI description. The Overlay document will likely use a duplicate structure to the original OpenAPI description and replace all `description` properties. 231 | - Applying API wide standards. An Overlay document contains update objects that describe standard headers, parameters, responses. These documents would use JMESPath queries to target the appropriate objects in the OpenAPI description. Tooling could be used to target the OpenAPI description rather than using extends. 232 | - Add tool specific OpenAPI metadata. Overlay adds additional metadata such as SLA information, client codegen hints or middleware policies. Using Overlays to manage this data separately is valuable when there is a different audience for the data and/or there the information has different sensitivity levels. 233 | -------------------------------------------------------------------------------- /proposals/2020-10-28-Experimental.md: -------------------------------------------------------------------------------- 1 | # Experimental marker 2 | 3 | ## Metadata 4 | 5 | |Tag |Value | 6 | |---- | ---------------- | 7 | |Proposal |[Experimental](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2020-10-28-Experimental.md)| 8 | |Authors|[David Goss](https://github.com/davidjgoss)| 9 | |Review Manager |TBD | 10 | |Status |Proposal| 11 | |Implementations || 12 | |Issues || 13 | |Previous Revisions || 14 | 15 | ## Change Log 16 | 17 | |Date |Responsible Party |Description | 18 | |---- | ---------------- | ---------- | 19 | 20 | ## Introduction 21 | 22 | A way to mark an aspect of the API as "experimental", indicating that it is not yet a fully stable and supported part of the API. 23 | 24 | ## Motivation 25 | 26 | Consider an API with two categories of thing in it: 27 | 28 | - Core, stable things, where we are committed to the ongoing stability and have no intention of making breaking changes. 29 | - New, experimental things, where we are getting them out there for feedback and early adopters, but they may change before we consider them to be in the first category, or even just get removed. 30 | 31 | These sit together fine in principle, but cause friction when trying to apply something like semver to the API as a whole. How do we make changes to the experimental stuff - without bumping the major version several times a year and scaring consumers - while also ensuring we can't make breaking changes to the core stuff we never _want_ to break. 32 | 33 | ## Proposed solution 34 | 35 | Add an "experimental" field which specifies that an items in the API is not yet fully stable and supported, may change or be removed without a major version bump, and as such should be used with caution. 36 | 37 | _(I don't have a strong opinion about the naming - "beta" is another idea, though I think "experimental" does the job better in terms of being the most noncommital.)_ 38 | 39 | Downstream tools could then make use of this metadata: 40 | 41 | - Tools like swagger-ui could surface this in the documentation they generate so consumers are made aware. Experimental items could also be filtered out of the documentation and stubs if desired. 42 | - Tools for detecting and preventing breaking changes could take this into consideration when deciding whether a change is breaking. 43 | 44 | ## Detailed design 45 | 46 | A new boolean field named `experimental`, defaulting to `false`, is added to: 47 | 48 | - Operation 49 | - Parameter 50 | - Schema 51 | 52 | This specifies that the operation, parameter or schema is not yet stable and SHOULD be used with caution. 53 | 54 | ### Operation Object 55 | 56 | ... 57 | 58 | ##### Fixed Fields 59 | 60 | Field Name | Type | Description 61 | ---|:---:|--- 62 | ... | ... | ... 63 | experimental | `boolean` | Specifies that an operation is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. 64 | 65 | ### Parameter Object 66 | 67 | ... 68 | 69 | ##### Fixed Fields 70 | 71 | Field Name | Type | Description 72 | ---|:---:|--- 73 | ... | ... | ... 74 | experimental | `boolean` | Specifies that a parameter is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. Cannot be `true` when the parameter is `required`. 75 | 76 | ### Schema Object 77 | 78 | ... 79 | 80 | ##### Fixed Fields 81 | 82 | Field Name | Type | Description 83 | ---|:---:|--- 84 | ... | ... | ... 85 | experimental | `boolean` | Specifies that a schema is in experimental status, meaning it may change outside of the normal breaking change process. Consumers SHOULD use with caution. Default value is `false`. 86 | 87 | ### Example Spec 88 | 89 | ```yaml 90 | /asset/constraints: 91 | get: 92 | tags: 93 | - Asset 94 | - Constraints 95 | summary: Get a set of asset constraints 96 | operationId: constraints 97 | parameters: 98 | - name: siteToken 99 | in: query 100 | description: Site token obtained from Site API 101 | required: true 102 | schema: 103 | type: string 104 | experimental: true 105 | ``` 106 | ### Prior Art 107 | 108 | This kind of requirement is handled for TypeScript libraries by [api-extractor](https://api-extractor.com/pages/tsdoc/doc_comment_syntax/#release-tags) - they have both "alpha" and "beta" markers with a somewhat opinionated flow attached - I'm not sure that level of granularity is necessary. But the "beta" and "public" ones map well to the motivations described here: 109 | 110 | > - **beta**: Indicates that an API item has been released as a preview or for experimental purposes. Third parties are encouraged to try it and provide feedback. However, a “beta” API should NOT be used in production, because it may be changed or removed in a future version. 111 | > - **public**: Indicates that an API item has been officially released, and is now part of the supported contract for a package. If the SemVer versioning scheme is used, then the API signature cannot be changed without a MAJOR version increment. 112 | 113 | ### Unanswered Questions 114 | 115 | - If an operation is not marked as experimental, but it is using a schema which is (i.e. as its request object), then it is implicitly also unstable. Would this usage be considered invalid? 116 | 117 | ## Backwards compatibility 118 | 119 | The `experimental` field would default to false, meaning existing behaviour is preserved, and the new field is only used on an opt-in basis. 120 | 121 | `experimental` can coexist with `deprecated` - an operation, parameter or schema can be both experimental and deprecated, having never gotten to a stable point before being deprecated. 122 | 123 | ## Alternatives considered 124 | 125 | - _Specification extensions_ - publishers could add an extension in their own domain, but the benefit of the metadata being available to downstream tools (including those used by consumers, not just publishers) would be lost. 126 | - _Tags_ - as above, but this also gets to mixing other kinds of metadata in with resource taxonomy, which seems wrong. 127 | - _Overlays_ - The [Overlays proposal](https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2019-12-24-Overlays.md) is sufficiently powerful to be able to implement this, with a canonical spec representing the stable API and an overlay used to apply experimental additions. Downsides: not as ergonomic for authors, the OpenAPI specification would still not have "experimental" as a first-class concept so there'd be reliance on conventions being observed across the ecosystem for how it's done with overlays. 128 | - _Different API_ - this would be the least messy from a technical perspective - maintain a completely separate API for experimental items, and then "promote" them to the main API once they are considered stable. This has increased overhead for publishers and consumers, and could also reduce the likelihood of getting feedback on, and early uptake of, experimental items if they are segregated in a different place altogether. 129 | 130 | -------------------------------------------------------------------------------- /proposals/2024-08-01-Self-Identification.md: -------------------------------------------------------------------------------- 1 | # Self-Identification 2 | 3 | ## Metadata 4 | 5 | |Tag |Value | 6 | |---- | ---------------- | 7 | |Proposal |[2024-08-01 Self-Identification](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{2024-08-01-Self-Identification-and-Bundling.md})| 8 | |Relevant Specification(s)|OpenAPI Specification (OAS), Arazzo Specification| 9 | |Authors|[Henry Andrews](https://github.com/handrews)| 10 | |Review Manager | TBD | 11 | |Status |Proposal| 12 | |Implementations |n/a| 13 | |Issues | | 14 | |Previous Revisions | | 15 | 16 | ## Change Log 17 | 18 | |Date |Responsible Party |Description | 19 | |---- | ---------------- | ---------- | 20 | |2024-08-01 | @handrews | Initial submission 21 | 22 | ## Introduction 23 | 24 | OpenAPI 3.1 references are treated as identifiers rather than locators. This behavior is inherited from JSON Schema 2020-12, and is made more explicit in the forthcoming OAS 3.1.1 patch release. This separation can support stable, self-assigned identifiers which allow certain sorts of OpenAPI Description refactoring _without_ having to re-write the values of `"$ref"` and similar keywords. However, OAS lacks a mechanism to fully define such identifiers within each document, which substantially limits the benefits of this separation. 25 | 26 | ## Motivation 27 | 28 | One of the main motivations for separating identity (URIs/IRIs) and location (URLs) is to have stable, persistent identifiers regardless of the resource's location. Such identifiers are typically assigned within the resource. There are two varieties: 29 | 30 | * Setting the complete resource's absolute URI, which is also used as the resource's base URI per [RFC3986 §5.1.1](https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1.1) (example: [the Schema Object's `$id`](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#name-the-id-keyword)) 31 | * Setting a ["plain name" URI fragment](https://www.w3.org/TR/2012/WD-fragid-best-practices-20121025/#dfn-plain-name-fragid) that does not rely on the JSON/YAML structure of the document (example: [the Schema Object's `$anchor`](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#name-defining-location-independe), and technically also `$dynamicAnchor` although this proposal will not mention `$dynamicAnchor` further as its additional complexities are not relevant here). 32 | 33 | As suggested by the above examples, in OAS 3.1 only the Schema Object can set stable, location-independent identifiers. OpenAPI Description documents as a whole cannot do so, nor can other Objects within the document. 34 | 35 | Note also that due to the recursive structure of schemas, resolving the Schema Object's `$id` keyword can be complex, as each can itself be a relative URI-reference that is resolved against the `$id` in parent schemas. There is no clear use case for such complexity within other parts of an OpenAPI Description. 36 | 37 | ### Use Cases 38 | 39 | There are several use cases for separating identity and location, including: 40 | 41 | * Working around network challenges: 42 | * Restrictive network security policies 43 | * Intermittent connectivity 44 | * High latency / low bandwidth 45 | * Document hosts that [require authentication](https://github.com/OAI/OpenAPI-Specification/issues/3270) 46 | * Abstracting development vs testing vs deployment details 47 | * Allowing `.json` and `.yaml` file extensions during development, as is preferred by most IDEs 48 | * Using extensions in development and HTTP content negotiation in production 49 | * Differing source control repository structure (particularly of shared documents) vs deployment directory and server layouts 50 | * This separation is necessary (although not, on its own, sufficient) to implement [bundling](https://www.openapis.org/blog/2021/08/23/json-schema-bundling-finally-formalised). 51 | 52 | For a more detailed real-world example, see the [OGC example](https://github.com/OAI/sig-moonwalk/discussions/72#user-content-ogc) in the Moonwalk discussion on imports. 53 | 54 | Many of these use cases can be worked around, but only by restricting deployment options or performing error-prone reference target rewriting. Many tools that perform reference rewriting do not take into account the added complexities of referencing in OAS 3.1 compared to 3.0 and earlier. 55 | 56 | ### Prior Art 57 | 58 | Self-identification of resources with identity independent of location is common in the JSON Schema world. This demonstrates that implementation is not just feasible but well-proven, particularly given that JSON Schema's `$id` is more complex to support than this proposal. 59 | 60 | The JSON Schema package used by the [OASComply](https://github.com/OAI/oascomply) project includes a [schema catalog](https://jschon.readthedocs.io/en/latest/tutorial/catalog.html) with [configurable file and network sources](https://jschon.readthedocs.io/en/latest/examples/file_based_schemas.html) to manage the URI-to-URL mapping (local files can be considered `file:` URLs). 61 | 62 | Self-identification is common in other formats as well. Notably, the Atom format pioneered the use of [web links with `rel="self"`](https://www.rfc-editor.org/rfc/rfc4287.html#section-4.2.7.2) for this purpose. 63 | 64 | ## Proposed solution 65 | 66 | The proposal is a simplified analog of JSON Schema's `$id` that appears in exactly one place: a new `self` field in the root OpenAPI Object (OAS) and Arazzo Object (Arazzo). When referencing a document that has a `self` field, the `self` field SHOULD be used in reference values so that reference values remain the same even if the document is moved. 67 | 68 | Placing the `self` field only in the OpenAPI Object or Arazzo Object makes it align with the existing bootstrapping process for parsing: 69 | 70 | 1. Check the `openapi` or `arazzo` field in the root OpenAPI or Arazzo Object to determine the specification version 71 | 1. Check the `jsonSchemaDialect` field for the default Schema Object dialect 72 | 1. Determine the base URI per RFC3986 §5.1.2-5.1.4 (in most cases, use the retrieval URL per §5.1.3) 73 | 1. ***NEW*** Check the `self` field for a base URI per RFC3986 §5.1.1; if it exists, resolve it against the base URI from the previous step and use the result as the document's actual base URI 74 | 1. Continue parsing the remainder of the document as usual 75 | 76 | As [OAS 3.1.1 clarifies](https://github.com/OAI/OpenAPI-Specification/pull/3758), it is already mandatory to separate location and identity for Schema Object support. 77 | 78 | Currently, associating a URI other than the current URL with a document to meet this requirement has to be done externally. Many tools effectively support this by allowing the retrieval URL to be set manually, without verifying that the document actually lives at the given URL. However, this relies on users to make use of a non-standard implementation feature rather than offering well-defined behavior based on the document author's intent. 79 | 80 | With the new `self` field, tools need to be configured to know how to locate documents whose `self` values do not match their locations. The JSON Schema implementation linked under [Prior Art](#prior-art) above demonstrates several ways to accomplish this. 81 | 82 | ## Detailed design 83 | 84 | This is written for the structure of the OAS, but it should be clear how it would be adapted for Arazzo. Some amount of guidance around how to configure tools to resolve `self`-references that do not match locations probably also needs to be added in the sections on reference resolution and base URIs. 85 | 86 | ```MARKDOWN 87 | ## OpenAPI Object 88 | 89 | ### Fixed Fields 90 | 91 | Field Name | Type | Description 92 | ---|:---|:--- 93 | self | `URI-reference` (without a fragment) | Sets the URI of this document, which also serves as its base URI in accordance with [RFC 3986 §5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1); the value MUST NOT be the empty string and MUST NOT contain a fragment 94 | ``` 95 | 96 | ## Backwards compatibility 97 | 98 | OAS 3.2 and Arazzo 1.1 documents that do not use the `self` field will behave exactly the same as OAS 3.1 and Arazzo 1.0 documents. The change in minor version is sufficient to manage the compatibility issues, as no software that only supports up to 3.1/1.0 should attempt to parse 3.2/1.1 documents. 99 | 100 | ## Alternatives considered 101 | 102 | ### Plain name fragments in every Object 103 | 104 | While including `self` in every Object would produce the same complexity as JSON Schema's nested `$id`, we could just adopt an equivalent of JSON Schema's `$anchor` keyword, which (like HTML/XML's `id` attribute) creates a plain name fragment that is not tied to the location of the Object in the JSON/YAML structure. 105 | 106 | Handling a fragment declaration keyword would require scanning all Objects for the keyword prior to declaring that a reference target with a plain name fragment cannot be resolved. This would likely be done on document load, but could be deferred and done incrementally as-needed when unknown fragments are encountered. 107 | 108 | Support for `$anchor` in JSON Schema demonstrates that this is feasible, and the mental model is familiar to most from HTML. But it would be a bit more work to support. 109 | 110 | While it would be a significant advantage to have completely location-independent referencing support, this is given as an alternative because the `self` field is a pre-requisite, and can be added whether we later support plain name fragments or not. 111 | -------------------------------------------------------------------------------- /proposals/2024-09-01-Tags-Improvement.md: -------------------------------------------------------------------------------- 1 | # Tags Improvement 2 | 3 | 4 | ## Metadata 5 | 6 | |Tag |Value | 7 | |---- | ---------------- | 8 | |Proposal |[2024-09-01-Tags-Improvement](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{2024-09-01-Tags-Improvement.md})| 9 | |Authors|[Lorna Mitchell](https://github.com/lornajane)| 10 | |Review Manager | TBD | 11 | |Status |Proposal| 12 | |Implementations | | 13 | |Issues | [1367](https://github.com/OAI/OpenAPI-Specification/issues/1367), [2843](https://github.com/OAI/OpenAPI-Specification/issues/2843), | 14 | |Previous Revisions | None, but see [Moonwalk discussion](https://github.com/OAI/sig-moonwalk/discussions/67) 15 | 16 | ## Change Log 17 | 18 | |Date |Responsible Party |Description | 19 | |---- | ---------------- | ---------- | 20 | | 2024-09-01 | @lornajane | Initial draft | 21 | 22 | ## Introduction 23 | 24 | Evolve the existing `tags` implementation to (optionally) support more use cases, such as giving the tags some grouping/relationships and adding more metadata. 25 | 26 | ## Motivation 27 | 28 | The tags feature hasn't changed since the spec was still called Swagger, but it's one of the most-extended aspects of OpenAPI with most tools supporting some sort of grouping or additional metadata. One motivation for this proposal is to "pave the cowpath" and formalise some of the patterns from those extensions as part of the specification. 29 | 30 | The existing tags implementation is also quite limiting, so users/tools feel they "cannot" use tags, because they are so widely implemented for documentation navigation and required exactly one tag per operation, to be used only for this single purpose or to be opted out using extensions such as `x-traitTag`. The result is that we see lots of extensions that add arbitrary metadata to operations, some of them even become part of the specification officially (looking at you, `deprecated: true`) or being so widely used that we should probably adopt them (`x-internal`, `x-experimental`). The specification does have a way of tagging operations, but it's too limited and the result is that everything has to be added as an extension field. 31 | 32 | On a personal note, I work for a tool vendor and was proposing these changes internally; but the problems affect all OpenAPI users so I brought it to the main project. 33 | 34 | ### Supporting evidence 35 | 36 | There are several examples "in the wild" of where a better tags implementation would have helped. Here is a selection of publicly-accessible examples to illustrate some of the problems this proposal could help with: 37 | 38 | - Grouping of tags is a very common use case, almost everyone uses some sort of extra hierarchy to group the tags themselves, which makes sense as our APIs are only getting more complex, something like [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) is a good example - and there's a [very active open issue on OpenAPI specification itself](https://github.com/OAI/OpenAPI-Specification/issues/1367) 39 | - Various tag-alike additions exist, sometimes called "badges" or similar; I'd include extensions such as [`x-internal`](https://redocly.com/docs/cli/guides/hide-apis/#step-1-add-x-internal-to-the-api-description) as a tag-alike since they could be tags if more than one tag (or tag type) could be applied. 40 | - Additional display metadata is also in active use in the wild, see [`x-displayName`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-display-name) and this [OpenAPI specification issue](https://github.com/OAI/OpenAPI-Specification/issues/2843) 41 | 42 | ## Proposed solution 43 | 44 | Originally proposed in a [Moonwalk discussion](https://github.com/OAI/sig-moonwalk/discussions/67), I am proposing three backwards-compatible additions to the existing tags feature: 45 | 46 | * Tags get a `summary` alongside `name` and `description`. In keeping with our existing practices: name is the identifier, summary is the short display content, and description is available in contexts where more information is appropriate. 47 | * A `parent` field is added to support a hierarchy without adding either separators or a new data type. Your tag can belong to another tag. 48 | * A `kind` field to explain which family of tags this tag belongs to (previously proposed as `type`). We'd expecting these to be `nav`, `badge`, `internal` and probably some other things that other tooling types would find useful. 49 | 50 | An example could look something like this: 51 | 52 | ```yaml 53 | tags: 54 | - name: deprecated 55 | kind: internal 56 | summary: Deprecated 57 | description: This operation has been deprecated and will be removed in the future. Avoid using items with this tag. 58 | - name: shop 59 | kind: nav 60 | summary: Order Online 61 | description: Operations relating to the retail operations behind the [online shopping site](https://example.com/shopping). 62 | - name: products 63 | kind: nav 64 | parent: shop 65 | summary: Products 66 | description: View and manage the product catalog. 67 | - name: orders 68 | kind: nav 69 | parent: shop 70 | summary: Online Orders 71 | description: Place, fulfil and invoice orders for the online shop. 72 | 73 | ``` 74 | 75 | Rather than making an allowed list of kinds, we will instead leave that open for user extension and keep a list of the recommended/expected types in a registry and evolve that as conventions emerge. 76 | 77 | ## Detailed design 78 | 79 | The following section is an updated specification section, for the top-level tags object only (no other changes are needed): 80 | 81 | --- 82 | 83 | #### Tag Object 84 | 85 | Adds metadata to a single tag that is used by the [Operation Object](#operation-object). 86 | Each tag used in the Operation Object instances MAY have a Tag Object defined. 87 | 88 | ##### Fixed Fields 89 | 90 | Field Name | Type | Description 91 | ---|:---:|--- 92 | name | `string` | **REQUIRED**. The name of the tag. Use this value in the `tags` array of an Operation. 93 | summary | `string` | A short summary of the tag, used for display purposes. 94 | description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 95 | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. 96 | parent | `string` | The `name` of a tag that this tags is nested under. The named tag MUST exist in the API description, and circular references between parent and child tags MUST NOT be used. 97 | kind | `string` | A machine-readable string to categorize what sort of tag it is. Common uses are `nav` for Navigation, `badge` for badges, `internal` for internal APIs, but any string value can be used. A registry of known values is available. 98 | 99 | This object MAY be extended with [Specification Extensions](#specification-extensions). 100 | 101 | ##### Tag Object Example 102 | 103 | ```json 104 | { 105 | "name": "account-updates", 106 | "summary": "Account Updates", 107 | "description": "Account update operations", 108 | "kind": "nav" 109 | }, 110 | { 111 | "name": "partner", 112 | "summary": "Partner", 113 | "description": "Operations available to the partners network", 114 | "parent": "external", 115 | "kind": "audience" 116 | }, 117 | { 118 | "name": "external", 119 | "summary": "External", 120 | "description": "Operations available to external consumers", 121 | "kind": "audience" 122 | } 123 | ``` 124 | 125 | ```yaml 126 | - name: account-updates 127 | summary: Account Updates 128 | description: Account update operations 129 | kind: nav 130 | 131 | - name: partner 132 | summary: Partner 133 | description: Operations available to the partners network 134 | parent: external 135 | kind: audience 136 | 137 | - name: external 138 | summary: External 139 | description: Operations available to external consumers 140 | kind: audience 141 | ``` 142 | 143 | --- 144 | 145 | ## Backwards compatibility 146 | 147 | All new fields are optional, so existing API descriptions will remain valid and useful. 148 | Some users may wish to adopt some of the following steps on upgrade: 149 | 150 | - Set `kind: nav` if their existing tags are currently used for navigation entries in documentation tooling. 151 | - Change `x-displayName` in `tag` objects to `summary` instead. 152 | - Add a tag to replace each `x-tagGroups` entry, and set the `parent` field for each of the tags in the groups. 153 | - Change `x-badges` extensions to instead be a tag with `kind: badge`. 154 | - Change features like `x-internal` to be a tag with a specific `kind` set. Similarly some lifecycle use cases such as `x-beta` could be replaced with tags. 155 | 156 | ## Alternatives considered 157 | 158 | - Continue to use tags as-is, and extend the spec for each use case that users need rather than providing an open metadata implementation. 159 | We've been slow to iterate and I would rather "open" the options than try to control them. 160 | The API space evolves quite quickly. 161 | 162 | - Set `children` rather than `parent` on the tags and operate a top-down relationship. 163 | The suggestion of allowing multiple links or a graph approach was also mentioned. 164 | In both cases, there are good ideas in every direction, but our responsibility is to implement a structure that users can easily understand and maintain. 165 | 166 | -------------------------------------------------------------------------------- /proposals/2025-03-20-URIs-for-Tags.md: -------------------------------------------------------------------------------- 1 | # URIs for Tags 2 | 3 | 4 | ## Metadata 5 | 6 | |Tag |Value | 7 | |---- | ---------------- | 8 | |Proposal |[2025-03-20-URIs-for-Tags](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{2025-03-20-URIs-for-Tags.md})| 9 | |Authors|[Henry Andrews](https://github.com/handrews)| 10 | |Review Manager | [Lorna Mitchell](https://github.com/lornajane) | 11 | |Status | rejected | 12 | |Implementations | n/a | 13 | |Issues |[#2905 Allow the use of $ref and json pointer in tags](https://github.com/OAI/OpenAPI-Specification/issues/2905), consolidated into [#3853 Consolidated $ref-to-Some Object feature request](https://github.com/OAI/OpenAPI-Specification/issues/3853)| 14 | |Previous Revisions |n/a| 15 | 16 | ## Change Log 17 | 18 | |Date |Responsible Party |Description | 19 | |---- | ---------------- | ---------- | 20 | |2025-03-20 | @handrews | Initial publication | 21 | |2025-03-26 | @handrews | Document rejection | 22 | 23 | ## Introduction 24 | 25 | Tags are the last remaining [implicit connection](https://spec.openapis.org/oas/v3.1.1#resolving-implicit-connections) that do not have a URI-based alternative for deterministic, universal referencing (Security Requirement Objects are fixed in [PR #4388](https://github.com/OAI/OpenAPI-Specification/pull/4388), currently awaiting re-approval after review feedback changes). 26 | This proposal adds such an alternative, giving tags the same capabilities as all other similar mechanisms within the OAS. 27 | 28 | ## Motivation 29 | 30 | ### A user request and proposal 31 | 32 | From @SandroG in issue #2905 (which is only closed because it was consolidated into #3853), which got two further thumbs-ups: 33 | 34 | _**[NOTE:** The mechanism proposed here is **not** the one favored by this proposal, which is explained further down]_ 35 | 36 | > I have a large specification, which I need to break down in different files. I use an approach where each file is like a sub-specification that lists all endpoints regarding the same subject and then I include these endpoints in the main openapi file. 37 | > The documentation of a tag is in the same file as the endpoint that uses it. 38 | > 39 | > I'm not able to reuse that tag declaration in the main file, so I'm not able to include the description of the tag. 40 | > 41 | > For example, I have a separate file for customer's endpoints 42 | 43 | `customers.yaml` 44 | ```YAML 45 | info: 46 | ... 47 | tags: 48 | - name: Customer 49 | description: APIs to manage customers. A customer is a representation of ... 50 | 51 | paths: 52 | /customers/{id}/: 53 | parameters: 54 | - name: id 55 | . . . 56 | get: 57 | . . . 58 | /customers/: 59 | . . . 60 | ``` 61 | > I need to do this: 62 | 63 | `openapi.yaml` 64 | ```YAML 65 | info: 66 | ... 67 | tags: 68 | - $ref: "./customers.yaml#/tags/0" 69 | 70 | paths: 71 | /customers/{id}/: 72 | $ref: "./customers.yaml#/paths/~customers~1{id}~1" 73 | /customers/: 74 | $ref: "./customers.yaml#/paths/~customers~1" 75 | ``` 76 | 77 | ### Proof of confusion over tag to Tag Object resolution 78 | 79 | In the above example, @SandroG proposes using `$ref` for Tag Objects to pull Tag Objects from one [OpenAPI Document](https://spec.openapis.org/oas/v3.1.1#openapi-document) into another, where they can be used by the `tags` field in Operation Objects. 80 | This makes clear that they expect tags to be resolved from the _current document_, which may be a [referenced document rather than the entry document](https://spec.openapis.org/oas/v3.1.1#openapi-description). 81 | 82 | However, in [3.0.4](https://spec.openapis.org/oas/v3.0.4#resolving-implicit-connections) and [3.1.1](https://spec.openapis.org/oas/v3.1.1#resolving-implicit-connections) we RECOMMEND (== SHOULD) that tag names are resolved to Tag Objects in the _entry document_. 83 | This means that there is no way to resolve them from the current document, which is the mirror image of the problem as that encountered by @SandroG. 84 | 85 | In today's TDC call, @lornajane stated that she expects tag names to be resolved from the entry document, and @kevinswiber expressed doubt that anyone implements anything else (sadly @SandroG does not mention their tool, which presumably resolves from the current document or else they would not have explained the issue in this way). 86 | 87 | ### Fragility of JSON Pointers with arrays 88 | 89 | Tag Objects are ordered, and tools MAY treat the ordering as significant for presentation purposes. JSON Pointers include the array index, which will change whenever someone decides to re-order the tag display, breaking any URI references that include a JSON Pointer. 90 | However, the use of the `name` field and the requirement that all Tag Objects in a list have a unique name mean that it is only necessary to identify the OpenAPI Object (or as a simpler proxy, the OpenAPI Document) in which to find the list of Tag Objects. 91 | Once the correct OpenAPI Document is identified, the list can be searched by name as it is now. 92 | 93 | ### Additional scenarios 94 | 95 | Another scenario to consider is a standards group that is publishing OpenAPI Documents that are intended to be used by multiple API providers. 96 | Such standards groups have no control over the entry documents used, so if they wish to provide Tag Objects, they MUST place them in the shared, referenced document. 97 | If the API provider wishes to use those Tag Objects in their entry document, or in their own referenced documents, then they currently cannot do. 98 | 99 | ## Proposed solution 100 | 101 | A new field or fields would be added to identify, with a URI, the OpenAPI Document from which a tag MUST be resolved. 102 | This would bring tags into alignment with other implicitly resolved names (e.g. Schema names in the Discriminator Object and Security Scheme names in the Security Requirement Object), with the variation that only the Document rather than the exact Object is identified. 103 | 104 | ## Detailed design 105 | 106 | In the Tag Object, a `parentDocument` field would be an optional URI qualifier to the `parent` field, and only allowed if `parent` is present. 107 | 108 | In the Operation Object, a `tagRefs` field would be added alongside the `tags` field. 109 | This new field would be a map with a Document URI as the keys, and an array of tags (as in the `tags` field) as the values. 110 | Tags under `tagRefs` would be resolved within the document identified by the key, while tags within `tags` would continue to be RECOMMENDED to resolve from the entry document. 111 | 112 | ## Backwards compatibility 113 | 114 | The proposal is fully backwards compatible. 115 | 116 | ## Alternatives considered 117 | 118 | The option proposed by @SandroG would require the Operation Object's `tags` field to resolve from the current document, which would be a breaking change and therefore not possible in 3.2. 119 | 120 | @baywet proposed a top-level (per-document) association of URIs and tags, to reduce the number of places where it is necessary to look for URIs. 121 | However, this requires duplicating tags that would otherwise only appear in Operation Objects in the top-level field, and does not fully solve the namespacing issue as each tag could only resolve from one place, rather than allowing the same tag name to have different meanings by resolving it to a different Tag Object in a different document. 122 | 123 | @karenetheridge proposed treating tags like `operationId` and resolving within the entire description (a PR to this proposal with more details of this alternative would be welcome). 124 | To me, `operationId` is not a good precedent to follow, as we already have to provide numerous disclaimers regarding collisions in the specification text, and the results are not well-defined. 125 | While we could make collisions an error for this new mechanism, @baywet noted that trying to prevent such collisions is highly burdensome in large organizations (although @karenetheridge similarly pointed to experience of it working). 126 | The fact that `operationRef` had to be included to provide a URI-based alternative to using `operationId` in the Link Object is a strong piece of evidence in favor of a URI-based solution for tags. 127 | 128 | ## Outcome 129 | 130 | Rejected per @lornajane, with concurrence by @ralfhandl: 131 | 132 | > I am not in favour of these additions for the 3.x branch. I wish that we'd implemented tags differently in the first place, and I'm sure that all the constructive discussion around the tags feature will help us a lot in future major releases. 133 | > 134 | > I believe that the limitations of the current tag situation can be overcome with helper tooling and that this change (while solving a narrow but valid use case) adds complexity to the specification that is unnecessary and does not benefit the majority of users. As custodians of a widely-used standard, we have a responsibility to maintain something that is appropriate for its audience, and we should be "reluctant" in all our changes unless we see that they are really needed. 135 | > 136 | > I propose that users would be equally well served by leaving the requirement to resolve tags from the entry document. Organisations can either maintain an extensive list of tags in all OpenAPI documents, and then remove any that aren't used before publishing (tooling exists for this use case), or alternatively if a tool wants to include tags found in the wider context of referenced OpenAPI documents by adding them to the top-level tags array during processing, that would work well too. 137 | > 138 | > The tags array is a list of strings. It isn't an ID like the Operation uses, and it's not a named entry like the security schemes, so it is appropriate to approach the limitations of it differently. My proposal is to offer some advice or documentation on approaching this problem, but not to bring it in scope of the specification for 3.x since other options are available. 139 | -------------------------------------------------------------------------------- /proposals/Alternative-Schema/CONTRIBUTORS.md: -------------------------------------------------------------------------------- 1 | * Chuck Heazel [@cmheazel](https://github.com/cmheazel) 2 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) -------------------------------------------------------------------------------- /proposals/Alternative-Schema/alternative_schema_object.md: -------------------------------------------------------------------------------- 1 | ## Change: Add the Alternative Schema Object 2 | 3 | The following text is to be inserted after the XML Object section 4 | 5 | ### Alternative Schema Object 6 | 7 | This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the _type_, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed. 8 | 9 | ## Fixed Fields 10 | 11 | |Field Name | Type | Description | 12 | |---|:---:|---| 13 | |type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. | 14 | |location | url | **REQUIRED**. This is a absolute or relative reference to an external resource containing a schema of a known type. This reference may contain a fragment identifier to reference only a subset of an external document. | 15 | 16 | This object MAY be extended with Specification Extensions. 17 | 18 | -------------------------------------------------------------------------------- /proposals/Alternative-Schema/examples.md: -------------------------------------------------------------------------------- 1 | ## Change: Add Alternative Schema Examples 2 | 3 | The following text is to be inserted after the Alternative Schema Object section. 4 | 5 | ### Alternative Schema Examples 6 | 7 | Minimalist usage of alternative schema: 8 | 9 | schema: 10 | x-oas-draft-alternativeSchema: 11 | type: jsonSchema 12 | location: ./real-jsonschema.json 13 | 14 | Combination of OAS schema and alternative: 15 | 16 | schema: 17 | type: object 18 | nullable: true 19 | x-oas-draft-alternativeSchema: 20 | type: jsonSchema 21 | location: ./real-jsonschema.json 22 | 23 | Multiple different versions of alternative schema: 24 | 25 | schema: 26 | anyOf: 27 | - x-oas-draft-alternativeSchema: 28 | type: jsonSchema 29 | location: ./real-jsonschema-08.json 30 | - x-oas-draft-alternativeSchema: 31 | type: jsonSchema 32 | location: ./real-jsonschema-07.json 33 | 34 | Combined alternative schemas: 35 | 36 | schema: 37 | allOf: 38 | - x-oas-draft-alternativeSchema: 39 | type: xmlSchema 40 | location: ./xmlSchema.xsd 41 | - x-oas-draft-alternativeSchema: 42 | type: schematron 43 | location: ./schema.sch 44 | 45 | Mixed OAS schema and alternative schema: 46 | 47 | schema: 48 | type: array 49 | items: 50 | x-oas-draft-alternativeSchema: 51 | type: jsonSchema 52 | location: ./real-jsonschema.json 53 | 54 | -------------------------------------------------------------------------------- /proposals/Alternative-Schema/implementations.md: -------------------------------------------------------------------------------- 1 | # Implementations 2 | 3 | ## Overview 4 | 5 | Below is a list of tooling that claims to implement the Alternative Schema proposal. While support for this feature matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the OpenAPI specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. 6 | 7 | These tools are not endorsed by the OAI 8 | 9 | ## Implementations: 10 | 11 | #### Low-Level tooling 12 | 13 | | Title | Project Link | Language | Description 14 | | ----------- | ----------- | ----------- | ----------- 15 | |TBD |TBD |TBD |TBD | 16 | 17 | #### Editors 18 | 19 | | Title | Project Link | Language |Description | 20 | |----------------|--------------|----------|---------------------| 21 | |TBD |TBD |TBD |TBD | 22 | 23 | #### User Interfaces 24 | 25 | | Title | Project Link | Language |Description | 26 | |----------------|--------------|----------|---------------------| 27 | |TBD |TBD |TBD |TBD | 28 | 29 | #### Mock Servers 30 | | Title | Project Link | Language | Description | 31 | | -------------- | ------------ | -------- | ----------- | 32 | |TBD |TBD |TBD |TBD | 33 | 34 | #### Server Implementations 35 | | Title | Project Link | Language |Description | 36 | |----------------|--------------|----------|---------------------| 37 | |TBD |TBD |TBD |TBD | 38 | 39 | #### Code Generators 40 | 41 | | Title | Project Link | Language |Description | 42 | |----------------|--------------|----------|---------------------| 43 | |TBD |TBD |TBD |TBD | 44 | 45 | 46 | 47 | -------------------------------------------------------------------------------- /proposals/Alternative-Schema/schema_object.md: -------------------------------------------------------------------------------- 1 | ## Change: Extend the Schema Object to support Alternative Schemas 2 | 3 | The following content shall be used to replace the Fixed Fields table in the Schema Object section 4 | 5 | #### Fixed Fields 6 | 7 | |Field Name | Type | Description | 8 | |---|:---:|---| 9 | | nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.| 10 | | discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#schemaComposition) for more details. | 11 | | readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | 12 | | writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | 13 | | xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | 14 | | externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema. 15 | | example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.| 16 | | deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.| 17 | |x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | 18 | -------------------------------------------------------------------------------- /proposals/Overlays/Changes.yml: -------------------------------------------------------------------------------- 1 | # Create update methods (add,replace,merge,delete)? Is merge necessary? 2 | # Multiple additions or updates to the same target is more efficient with merge 3 | 4 | # Different than JSON Patch because is works in JSON and YAML 5 | # Has info object and spec version 6 | # values 7 | 8 | overlay: 1.0.0 9 | info: 10 | title: An example of an overlay that captures changes to an API 11 | version: 1.0.0 12 | updates: 13 | # Add a property to a schema 14 | - target: components.schemas."todo".properties 15 | merge: 16 | createdBy: 17 | type: string 18 | # Add constraints to a schema 19 | - target: components.schemas."todo" 20 | merge: 21 | additionalProperties: false 22 | - target: components.schemas."todo" 23 | merge: 24 | type: ["object","null"] 25 | #Change a schema 26 | - target: components.schemas."todo" 27 | replace: 28 | type: integer 29 | # Add multiple constraints to a schema using merge 30 | - target: components.schemas."todo" 31 | merge: 32 | additionalProperties: false 33 | type: ["object","null"] 34 | # Add multiple constraints to a schema using merge 35 | - target: components.schemas."todo" 36 | merge: 37 | additionalProperties: false 38 | type: ["object","null"] 39 | properties: 40 | someprop: 41 | type: string 42 | # Add an operation 43 | - target: paths."/foo" 44 | add: 45 | delete: 46 | description: delete a foo 47 | responses: 48 | 200: 49 | description: ok 50 | # Add a path 51 | - target: paths 52 | add: 53 | "/items": 54 | get: 55 | responses: 56 | 200: 57 | description: ok 58 | # Add an optional query parameter 59 | - target: paths."/bar".parameters 60 | add: 61 | name: skip 62 | in: query 63 | type: string 64 | # Mark an operation as deprecated 65 | 66 | # Change the value of a JSON schema constraint 67 | # Update the version of the API 68 | # Change the license of an API 69 | # Add support for a new request media type 70 | # Add support for a new response media type 71 | -------------------------------------------------------------------------------- /proposals/Overlays/MergePatch.yml: -------------------------------------------------------------------------------- 1 | overlay: 1.0.0 2 | info: 3 | title: An example of an overlay that performs a Merge Patch 4 | version: 1.0.0 5 | updates: 6 | - target: "@" 7 | merge: 8 | openapi: 3.0.3 9 | paths: {} 10 | 11 | -------------------------------------------------------------------------------- /scripts/adjust-release-branch.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # Author: @ralfhandl 4 | 5 | # Run this script from the root of the repo. It is designed to be run manually in a release branch. 6 | 7 | branch=$(git branch --show-current) 8 | 9 | if [[ ! $branch =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]]; then 10 | echo "This script is intended to be run from a release branch, e.g. v3.1.2-rel" 11 | exit 1 12 | fi 13 | 14 | vVersion=$(basename "$branch" "-rel") 15 | version=${vVersion:1} 16 | echo Prepare release of $version 17 | 18 | cp EDITORS.md versions/$version-editors.md 19 | mv src/oas.md versions/$version.md 20 | rm -r src/schemas 21 | rm -r tests/schema 22 | -------------------------------------------------------------------------------- /scripts/close-no-recent.ps1: -------------------------------------------------------------------------------- 1 | $inactivityDelay = [timespan]::FromDays([int]::Parse($Env:NO_RECENT_ACTIVITY_DURATION_CLOSE_IN_DAYS)) 2 | $oldIssues = gh issue list --label "$Env:NO_RECENT_ACTIVITY_LABEL" --state open --limit 100 --json number,author,createdAt,labels | ConvertFrom-Json | Where-Object {$_.labels.name -notcontains $Env:NEEDS_ATTENTION_LABEL } 3 | foreach($oldIssue in $oldIssues) { 4 | $lastComment = gh issue view $oldIssue.number --json comments | ConvertFrom-Json | Select-Object -ExpandProperty comments | Where-Object {$_.author.login -eq $oldIssue.author.login} | Select-Object -Last 1 5 | if($null -eq $lastComment) { 6 | $lastCommentDate = [Nullable[datetime]]$null 7 | } else { 8 | $lastCommentDate = $lastComment.createdAt #powershell already parses the date for us with the json conversion 9 | } 10 | $lastLabelEvent = gh api -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "/repos/$($Env:ORG_NAME)/$($Env:REPO_NAME)/issues/$($oldIssue.number)/events?per_page=100" | ConvertFrom-Json | Where-Object {$_.event -eq "labeled" -and $_.label.name -eq "$Env:NO_RECENT_ACTIVITY_LABEL"} | Select-Object -Last 1 11 | $lastLabelEventDate = $lastLabelEvent.created_at 12 | if ($null -ne $lastCommentDate -and $lastCommentDate -gt $lastLabelEventDate) { 13 | gh issue edit $oldIssue.number --remove-label "$Env:NO_RECENT_ACTIVITY_LABEL" --remove-label "$Env:NEEDS_AUTHOR_FEEDBACK_LABEL" --add-label "$Env:NEEDS_ATTENTION_LABEL" 14 | } elseif (([datetime]::UtcNow - $lastLabelEventDate) -ge $inactivityDelay) { 15 | gh issue close $oldIssue.number -r "not planned" 16 | } 17 | } -------------------------------------------------------------------------------- /scripts/fwdabort.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Aborts a fwdport.sh run cleanly 4 | 5 | # Author: @MikeRalphson 6 | 7 | git am -i --abort 8 | rm -f *.mbox *.patch *.rej 9 | git checkout main 10 | 11 | -------------------------------------------------------------------------------- /scripts/fwdport.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Forward ports changes from the spec file of a source branch to the spec file of a target branch 4 | # For example: porting interim changes made in v3.1.x patch releases to the v3.2.0 branch 5 | 6 | # This script is designed to be run once per branch, when interim changes need merging in 7 | # before another branch is released. It is not intended to be run multiple times to keep 8 | # two branches in sync. 9 | 10 | # Author: @MikeRalphson 11 | # Issues: https://github.com/OAI/OpenAPI-Specification/pull/2163 12 | 13 | mainbranch=main 14 | myremote=origin 15 | upstream=upstream 16 | 17 | source=$1 18 | target=$2 19 | 20 | if [ -z "$source" ]; then 21 | echo You must specify a source and target branch 22 | exit 1 23 | fi 24 | if [ -z "$target" ]; then 25 | echo You must specify a source and target branch 26 | exit 1 27 | fi 28 | 29 | echo Checking working dir... 30 | status=`git ls-files -m` 31 | if [ -z "$status" ]; then 32 | echo All clear 33 | else 34 | echo You have a dirty working tree, aborting 35 | echo ${status} 36 | exit 1 37 | fi 38 | 39 | cruft=`ls -1 *.patch *.rej *.mbox 2>/dev/null` 40 | if [ -z "$cruft" ]; then 41 | echo No .patch, .rej or .mbox files found, continuing 42 | else 43 | echo .patch / .rej / .mbox files found, aborting 44 | exit 1 45 | fi 46 | 47 | tmpbranch=forward-port-${source} 48 | existing=`git branch | grep ${tmpbranch}` 49 | if [ -z "$existing" ]; then 50 | echo No matching temp branch found, continuing 51 | else 52 | echo Temp branch ${tmpbranch} already exists, aborting 53 | exit 1 54 | fi 55 | 56 | srcver=`echo $source | sed s/-dev//g | sed s/v//g`.md 57 | tgtver=`echo $target | sed s/-dev//g | sed s/v//g`.md 58 | 59 | echo Forward-porting changes from ${source}:versions/${srcver} to ${target}:${tgtver} 60 | echo You may use the commands \'git fwdskip\' and \'git fwdcont\' to skip patches, or to continue after manually fixing. 61 | echo Use `fwdabort.sh` to abort cleanly. 62 | echo 63 | echo Due to a bug in \`git am\`, git v2.22.1+ is required, you\'re running: 64 | git --version 65 | echo 66 | echo Press a key to continue... 67 | read 68 | 69 | git config --add rerere.enabled true 70 | git config alias.fwdskip '!git am -i --skip' 71 | git config alias.fwdcont '!git am -i --continue' 72 | 73 | git checkout ${source} 74 | git pull ${upstream} ${source} 75 | 76 | # look at using git merge-base as an alternative? say if we branched 3.1.0 part way through 3.0.2's life 77 | 78 | firstsrc=`git log --abbrev-commit --format=format:%H -n 1 --reverse -- versions/${srcver}` 79 | lastsrc=`git log --abbrev-commit --format=format:%H -- versions/${srcver} | tail -n 1` 80 | changes=`git log --format=format:%H --reverse versions/${srcver}` 81 | 82 | echo Applying changes from ${firstsrc} to ${lastsrc} 83 | 84 | # remove first (creation) commit and uniq without sorting 85 | oIFS="$IFS" 86 | IFS=' ' 87 | changes=`echo ${changes} | tail -n +2 | awk '!x[$0]++'` 88 | IFS="$oIFS" 89 | 90 | for c in ${changes}; do 91 | git format-patch --stdout -1 $c | sed s/${srcver}/${tgtver}/g > $c.patch 92 | done 93 | 94 | git checkout ${target} 95 | git pull ${upstream} ${target} 96 | git checkout -b ${tmpbranch} 97 | cat *.patch > fwdport.mbox 98 | rm -f *.patch 99 | git am -3 --interactive --ignore-whitespace -s fwdport.mbox 100 | 101 | -------------------------------------------------------------------------------- /scripts/label-no-recent.ps1: -------------------------------------------------------------------------------- 1 | $inactivityDelay = [timespan]::FromDays([int]::Parse($Env:NO_RECENT_ACTIVITY_DURATION_IN_DAYS)) 2 | $oldIssues = gh issue list --label "$Env:NEEDS_AUTHOR_FEEDBACK_LABEL" --state open --limit 100 --json number,author,createdAt,labels | ConvertFrom-Json | Where-Object {$_.labels.name -notcontains $Env:NO_RECENT_ACTIVITY_LABEL } 3 | foreach($oldIssue in $oldIssues) { 4 | $lastComment = gh issue view $oldIssue.number --json comments | ConvertFrom-Json | Select-Object -ExpandProperty comments | Where-Object {$_.author.login -eq $oldIssue.author.login} | Select-Object -Last 1 5 | if($null -eq $lastComment) { 6 | $lastCommentDate = [Nullable[datetime]]$null 7 | } else { 8 | $lastCommentDate = $lastComment.createdAt #powershell already parses the date for us with the json conversion 9 | } 10 | $lastLabelEvent = gh api -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "/repos/$($Env:ORG_NAME)/$($Env:REPO_NAME)/issues/$($oldIssue.number)/events?per_page=100" | ConvertFrom-Json | Where-Object {$_.event -eq "labeled" -and $_.label.name -eq "$Env:NEEDS_AUTHOR_FEEDBACK_LABEL"} | Select-Object -Last 1 11 | $lastLabelEventDate = $lastLabelEvent.created_at 12 | if ($null -ne $lastCommentDate -and $lastCommentDate -gt $lastLabelEventDate) { 13 | gh issue edit $oldIssue.number --remove-label "$Env:NO_RECENT_ACTIVITY_LABEL" --remove-label "$Env:NEEDS_AUTHOR_FEEDBACK_LABEL" --add-label "$Env:NEEDS_ATTENTION_LABEL" 14 | } elseif (([datetime]::UtcNow - $lastLabelEventDate) -ge $inactivityDelay) { 15 | gh issue edit $oldIssue.number --add-label "$Env:NO_RECENT_ACTIVITY_LABEL" --remove-label "$Env:NEEDS_ATTENTION_LABEL" 16 | gh issue comment $oldIssue.number -b "$Env:NO_RECENT_ACTIVITY_COMMENT" 17 | } 18 | } -------------------------------------------------------------------------------- /scripts/md2html/.gitignore: -------------------------------------------------------------------------------- 1 | *.err 2 | input.bs 3 | -------------------------------------------------------------------------------- /scripts/md2html/analytics/google.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 9 | -------------------------------------------------------------------------------- /scripts/md2html/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Author: @MikeRalphson 4 | 5 | # run this script from the root of the repo 6 | # It is designed to be run by a GitHub workflow 7 | 8 | # Usage: build.sh [version | "latest" | "src"] 9 | # When run with no arguments, it builds artifacts for all published specification versions. 10 | # It may also be run with a specific version argument, such as "3.1.1" or "latest" 11 | # Finally, it may be run with "src" to build "src/oas.md" 12 | # 13 | # It contains bashisms 14 | 15 | if [ "$1" = "src" ]; then 16 | deploydir="deploy-preview" 17 | else 18 | deploydir="deploy/oas" 19 | fi 20 | 21 | mkdir -p $deploydir/js 22 | mkdir -p $deploydir/temp 23 | cp -p node_modules/respec/builds/respec-w3c.* $deploydir/js/ 24 | 25 | latest=$(git describe --abbrev=0 --tags) 26 | 27 | allVersions=$(ls -1 versions/[23456789].*.md | grep -v -e "\-editors" | sort -r) 28 | 29 | if [ -z "$1" ]; then 30 | specifications=$allVersions 31 | elif [ "$1" = "latest" ]; then 32 | specifications=$(ls -1 versions/$latest.md) 33 | elif [ "$1" = "src" ]; then 34 | specifications="src/oas.md" 35 | else 36 | specifications=$(ls -1 versions/$1.md) 37 | fi 38 | 39 | latestCopied="none" 40 | lastMinor="-" 41 | 42 | for specification in $specifications; do 43 | version=$(basename $specification .md) 44 | 45 | if [ "$1" = "src" ]; then 46 | destination="$deploydir/$version.html" 47 | maintainers="EDITORS.md" 48 | else 49 | destination="$deploydir/v$version.html" 50 | maintainers="$(dirname $specification)/$version-editors.md" 51 | fi 52 | 53 | minorVersion=${version:0:3} 54 | tempfile="$deploydir/temp/$version.html" 55 | tempfile2="$deploydir/temp/$version-2.html" 56 | 57 | echo === Building $version to $destination 58 | 59 | node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile 60 | npx respec --no-sandbox --use-local --src $tempfile --out $tempfile2 61 | # remove unwanted Google Tag Manager and Google Analytics scripts 62 | sed -e 's/ 4 | 10 | 11 | OpenAPI Specification v30.0.1 | Introduction, Definitions, & More 12 | 13 | 14 |

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for this specification is the HTML file referenced above as This version.
15 |

Heading 1

16 |

Text for first chapter

17 |

Version 30.0.1

18 |

This is the conformance section

19 |

Heading 2

20 |

Text for first section

21 |

Broken anchor

22 |

Heading 3

23 |

Text for first subsection

24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 |
VersionDate
30.0.13001-04-01
38 | 39 | -------------------------------------------------------------------------------- /tests/md2html/fixtures/basic-old.maintainers: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Foo Bar [@foobar](https://github.com/foobar) 3 | -------------------------------------------------------------------------------- /tests/md2html/fixtures/basic-old.md: -------------------------------------------------------------------------------- 1 | # Heading 1 2 | 3 | Text for first chapter 4 | 5 | #### Version 30.0.1 6 | 7 | This is the conformance section 8 | 9 | ## Table of Contents 10 | 11 | Will be removed 12 | 13 | ## Heading 2 14 | 15 | Text for first section 16 | 17 | Broken anchor 18 | 19 | ### Heading 3 20 | 21 | Text for first subsection 22 | 23 | 24 | Version | Date 25 | --------|----------- 26 | 30.0.1 | 3001-04-01 27 | -------------------------------------------------------------------------------- /tests/md2html/md2html.test.mjs: -------------------------------------------------------------------------------- 1 | import { readdirSync, readFileSync } from "node:fs"; 2 | import { execFile } from "node:child_process"; 3 | import { resolve } from "node:path"; 4 | import { describe, test, expect } from "vitest"; 5 | import assert from "node:assert"; 6 | 7 | const folder = "./tests/md2html/fixtures/"; 8 | describe("md2html", async () => { 9 | readdirSync(folder, { withFileTypes: true }) 10 | .filter((entry) => entry.isFile() && /\.md$/.test(entry.name)) 11 | .forEach((entry) => { 12 | test(entry.name, async () => { 13 | const expected = readFileSync( 14 | folder + entry.name.replace(".md", ".html"), 15 | "utf8", 16 | ); 17 | const output = await md2html( 18 | [ 19 | "--maintainers", 20 | entry.name.replace(".md", ".maintainers"), 21 | entry.name, 22 | "path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md", 23 | ], 24 | folder, 25 | ); 26 | expect(output.stdout).to.equal(expected); 27 | }); 28 | }); 29 | }); 30 | 31 | function md2html(args, cwd) { 32 | return new Promise((res) => { 33 | execFile( 34 | "node", 35 | [`${resolve("./scripts/md2html/md2html.js")}`, ...args], 36 | { cwd }, 37 | (error, stdout, stderr) => { 38 | res({ 39 | code: error?.code || 0, 40 | error, 41 | stdout, 42 | stderr, 43 | }); 44 | }, 45 | ); 46 | }); 47 | } 48 | -------------------------------------------------------------------------------- /versions/2.0-editors.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 3 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 4 | * Ron Ratovsky [@webron](https://github.com/webron) 5 | * Tony Tam [@fehguy](https://github.com/fehguy) 6 | -------------------------------------------------------------------------------- /versions/3.0.0-editors.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 3 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 4 | * Ron Ratovsky [@webron](https://github.com/webron) 5 | * Tony Tam [@fehguy](https://github.com/fehguy) 6 | 7 | ## Emeritus 8 | * Jason Harmon [@jharmn](https://github.com/jharmn) 9 | -------------------------------------------------------------------------------- /versions/3.0.1-editors.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 3 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 4 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 5 | * Ron Ratovsky [@webron](https://github.com/webron) 6 | 7 | ## Emeritus 8 | * Jason Harmon [@jharmn](https://github.com/jharmn) 9 | * Tony Tam [@fehguy](https://github.com/fehguy) 10 | -------------------------------------------------------------------------------- /versions/3.0.2-editors.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 3 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 4 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 5 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 6 | * Ron Ratovsky [@webron](https://github.com/webron) 7 | * Uri Sarid [@usarid](https://github.com/usarid) 8 | 9 | ## Emeritus 10 | * Jason Harmon [@jharmn](https://github.com/jharmn) 11 | * Tony Tam [@fehguy](https://github.com/fehguy) 12 | -------------------------------------------------------------------------------- /versions/3.0.3-editors.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 3 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 4 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 5 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 6 | * Ron Ratovsky [@webron](https://github.com/webron) 7 | * Uri Sarid [@usarid](https://github.com/usarid) 8 | 9 | ## Emeritus 10 | * Jason Harmon [@jharmn](https://github.com/jharmn) 11 | * Tony Tam [@fehguy](https://github.com/fehguy) 12 | -------------------------------------------------------------------------------- /versions/3.0.4-editors.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Specification Editors 2 | 3 | ## Active 4 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 5 | * Henry Andrews [@handrews](https://github.com/handrews) 6 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 7 | * Lorna Mitchell [@lornajane](https://github.com/lornajane) 8 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 9 | * Miguel Quintero [@miqui](https://github.com/miqui) 10 | * Mike Kistler [@mikekistler](https://github.com/mikekistler) 11 | * Ralf Handl [@ralfhandl](https://github.com/ralfhandl) 12 | * Ron Ratovsky [@webron](https://github.com/webron) 13 | 14 | ## Emeritus 15 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 16 | * Uri Sarid [@usarid](https://github.com/usarid) 17 | * Jason Harmon [@jharmn](https://github.com/jharmn) 18 | * Tony Tam [@fehguy](https://github.com/fehguy) 19 | -------------------------------------------------------------------------------- /versions/3.1.0-editors.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 3 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 4 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 5 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 6 | * Ron Ratovsky [@webron](https://github.com/webron) 7 | * Uri Sarid [@usarid](https://github.com/usarid) 8 | 9 | ## Emeritus 10 | * Jason Harmon [@jharmn](https://github.com/jharmn) 11 | * Tony Tam [@fehguy](https://github.com/fehguy) 12 | -------------------------------------------------------------------------------- /versions/3.1.1-editors.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Specification Editors 2 | 3 | ## Active 4 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 5 | * Henry Andrews [@handrews](https://github.com/handrews) 6 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 7 | * Lorna Mitchell [@lornajane](https://github.com/lornajane) 8 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 9 | * Miguel Quintero [@miqui](https://github.com/miqui) 10 | * Mike Kistler [@mikekistler](https://github.com/mikekistler) 11 | * Ralf Handl [@ralfhandl](https://github.com/ralfhandl) 12 | * Ron Ratovsky [@webron](https://github.com/webron) 13 | 14 | ## Emeritus 15 | * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) 16 | * Uri Sarid [@usarid](https://github.com/usarid) 17 | * Jason Harmon [@jharmn](https://github.com/jharmn) 18 | * Tony Tam [@fehguy](https://github.com/fehguy) 19 | -------------------------------------------------------------------------------- /vitest.config.mjs: -------------------------------------------------------------------------------- 1 | import { defineConfig } from 'vitest/config' 2 | 3 | export default defineConfig({ 4 | test: { 5 | forceRerunTriggers: ['**/scripts/**', '**/tests/**'], 6 | }, 7 | }) --------------------------------------------------------------------------------