Showing preview only (2,072K chars total). Download the full file or copy to clipboard to get everything.
Repository: OAI/OpenAPI-Specification
Branch: main
Commit: 33d949476e00
Files: 124
Total size: 2.0 MB
Directory structure:
gitextract_xldvqxs9/
├── .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
├── .linkspector.yml
├── .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.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
│ ├── start-release.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
│ └── schema/
│ └── oas-schema.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
│ ├── 3.1.2-editors.md
│ ├── 3.1.2.md
│ ├── 3.2.0-editors.md
│ └── 3.2.0.md
└── vitest.config.mjs
================================================
FILE CONTENTS
================================================
================================================
FILE: .gitattributes
================================================
*.md linguist-detectable
================================================
FILE: .github/CODEOWNERS
================================================
# Global Repo Owners
* @oai/openapi-maintainers @oai/tsc
# Specification Versions
/versions/ @oai/tsc
# Protect specific top level files
/MAINTAINERS.md @oai/tsc
/TOB.md @oai/tsc
/GOVERNANCE.md @oai/tsc
/LICENSE @oai/tsc
================================================
FILE: .github/ISSUE_TEMPLATE/config.yml
================================================
blank_issues_enabled: false
contact_links:
- name: Have a question about using OpenAPI?
url: https://communityinviter.com/apps/open-api/openapi
about: Ask us on our Slack!
- name: Have a question about OpenAPI Tooling?
url: https://tools.openapis.org/
about: Please ask your tooling vendor!
- name: Want to add to our list of OpenAPI Tools?
url: https://tools.openapis.org/
about: Please take a look at our tooling site's instructions!
- name: Want to suggest more how-to documentation and examples?
url: https://github.com/OAI/learn.openapis.org/issues/new
about: Please open an issue on our learning site!
- name: Want to request a new feature in the specification?
url: https://github.com/OAI/OpenAPI-Specification/discussions/new?category=enhancements
about: Please start a discussion in this repository!
================================================
FILE: .github/ISSUE_TEMPLATE/registry_feature_request.md
================================================
---
name: Contribute to the registries at spec.openapis.org/registry
about: Add a new registry entry, or edit an existing one
title: 'Registry: ...'
labels: registries
assignees: ''
---
**Which registry do you want to contribute to**
- [ ] [Alternative Schema Type Registry](https://spec.openapis.org/registry/alternative-schema)
- [ ] [Draft Features Registry](https://spec.openapis.org/registry/draft-feature)
- [ ] [Specification Extension Registry](https://spec.openapis.org/registry/extension)
- [ ] [Format Registry](https://spec.openapis.org/registry/format)
- [ ] [Extension Namespace Registry](https://spec.openapis.org/registry/namespace)
- [ ] [Tag Kind Registry](https://spec.openapis.org/registry/tag-kind)
**Describe your contribution**
A clear and concise description of what you want to add or change.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context or screenshots about the feature request here.
================================================
FILE: .github/ISSUE_TEMPLATE/spec_bug_report.md
================================================
---
name: Report an error in the specification
about: Create a report to help us improve the specification
title: 'vX.Y: ...'
labels: ''
assignees: ''
---
**Describe the error in the specification**
A clear and concise description of
- what the error is,
- which specification versions are affected,
- what you would expect the specification to say instead, and
- a link to the corresponding specification section in the "oldest" affected version.
**Additional context**
Add any other context about the problem here.
================================================
FILE: .github/dependabot.yml
================================================
version: 2
updates:
- package-ecosystem: github-actions
directory: "/"
schedule:
interval: daily
open-pull-requests-limit: 10
- package-ecosystem: npm
directory: "/"
schedule:
interval: daily
open-pull-requests-limit: 10
groups:
vitest:
patterns:
- "*vitest*"
================================================
FILE: .github/pull_request_template.md
================================================
<!--
Thank you for contributing to the OpenAPI Specification!
Please make certain you are submitting your PR on the correct
branch, to the files under the "src/" directory (which is not
present on the main branch, only on the development branches).
* 3.1.x spec and schemas: v3.1-dev branch
* 3.2.x spec and schemas: v3.2-dev branch
* 3.3.x spec and schemas: v3.3-dev branch
* process documentation and build infrastructure: main
Note that we do not accept changes to published specifications.
-->
<!-- Tick one of the following options and remove the other two: -->
- [ ] schema changes are included in this pull request
- [ ] schema changes are needed for this pull request but not done yet
- [ ] no schema changes are needed for this pull request
================================================
FILE: .github/templates/agenda.md
================================================
## Weekly meetings happen on Thursdays at 9am - 10am Pacific
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.
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**.
Meetings take place over Zoom: https://zoom-lfx.platform.linuxfoundation.org/meeting/92028872923?password=9ddcd542-4f5b-484a-a254-e00d8a8b15d8
### Accessibility & Etiquette
* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file).
* Meetings are recorded for future reference, and for those who are not able to attend in-person.
* We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting.
* We look forward to your participation, but please consider these acts of etiquette:
* Remain on mute when not speaking to prevent interruptions.
* Blur your background to reduce visual distractions.
* Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak.
| Blur My Background | Raise Hand |
|-|-|
| <img width="323" alt="Screenshot of Zoom UI showing the 'Stop Video' and 'Blur My Background' control" src="https://github.com/OAI/OpenAPI-Specification/assets/7367/7e43dbbb-6529-46e6-8b04-4c1aa852d9dd"> | <img width="323" alt="Screenshot of Zoom UI showing the 'Reaction' and 'Raise Hand' control" src="https://github.com/user-attachments/assets/bf19ee70-59b1-410e-b893-645f26c2c96e"> |
### Agenda Structure
| Topic | Owner | Decision/NextStep |
|-|-|-|
Intros and governance meta-topics (5 mins) | TDC | |
Reports from Special Interest Groups (5 mins) | SIG members | |
Any other business (add comments below to suggest topics) | TDC | |
[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | |
[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | |
[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage | |
Identify next week's meeting host (2 mins) | All | Comment on next week's agenda |
/cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.
================================================
FILE: .github/workflows/agenda.yaml
================================================
name: agenda
# author: @MikeRalphson
# issue: various
#
# This workflow creates the agenda issue each week. It runs on a cron every
# Monday morning, raising an issue for the following Thursday.
# It can also be run manually, in case GitHub Actions has a failure.
#
on:
schedule:
- cron: '0 16 * * 4'
workflow_dispatch: {}
permissions:
issues: write
contents: read
jobs:
agenda:
if: github.repository == 'OAI/OpenAPI-Specification'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TITLE_PREFIX: "Open Community (TDC) Meeting, "
LABEL: "Housekeeping"
POST_MEETING_CLOSE_DURATION_IN_DAYS: 10
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6 # checkout repo content
# we want to close old agenda issues before creating a new one because there's a limit of 3 pinned items on a repo
- name: Close old agenda issues
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 }
shell: pwsh
- name: Unpin any issue that was closed manually
run: gh issue list -l ${{ env.LABEL }} --author "app/github-actions" --json "number,title,isPinned" -s closed | ConvertFrom-Json | Where-Object { $_.isPinned -eq $true -and $_.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 unpin $_.number }
shell: pwsh
- name: Create agenda issue
run: |
$nextThursday = @(@(1..8) | % {$(Get-Date).AddDays($_)} | ? {$_.DayOfWeek -ieq "Thursday"})[0].ToString("dddd dd MMMM yyyy", [CultureInfo]::InvariantCulture)
$result = gh issue create -l ${{ env.LABEL }} -t "${{ env.TITLE_PREFIX }}$nextThursday" -F .github/templates/agenda.md
gh issue pin $result
shell: pwsh
================================================
FILE: .github/workflows/check-restricted-files.yaml
================================================
name: check-restricted-files
# Author: @ralfhandl
# Issue: https://github.com/OAI/OpenAPI-Specification/issues/3432
# This workflow fails if restricted files are changed in a pull request
on:
pull_request:
paths:
- "versions/*.md"
jobs:
check-files:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6 # checkout repo content
with:
fetch-depth: 0
- name: Check changed files
shell: bash
run: |
if [[ "${{ github.event.pull_request.head.repo.full_name }}" == "OAI/OpenAPI-Specification" ]] && \
[[ "${{ github.event.pull_request.base.repo.full_name }}" == "OAI/OpenAPI-Specification" ]]; then
if [[ "${{ github.event.pull_request.head.ref }}" == "dev-sync-with-main" ]] && \
[[ "${{ github.event.pull_request.base.ref }}" == "dev" ]]; then
echo Sync from main to dev via ${{ github.event.pull_request.head.ref }}
exit 0
fi
if [[ "${{ github.event.pull_request.head.ref }}" =~ ^v[0-9]+\.[0-9]+-dev-sync-with-dev$ ]] && \
[[ "${{ github.event.pull_request.base.ref }}" =~ ^v[0-9]+\.[0-9]+-dev$ ]] && \
[[ ${{ github.event.pull_request.head.ref }} == ${{ github.event.pull_request.base.ref }}* ]]; then
echo Sync from dev to ${{ github.event.pull_request.base.ref }} via ${{ github.event.pull_request.head.ref }}
exit 0
fi
if [[ "${{ github.event.pull_request.head.ref }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]] && \
[[ "${{ github.event.pull_request.base.ref }}" == "main" ]]; then
echo Release from ${{ github.event.pull_request.head.ref }} to main
exit 0
fi
fi
echo This PR contains changes to files that should not be changed:
echo
git diff --compact-summary origin/${{ github.event.pull_request.base.ref }} -- versions/
exit 1
================================================
FILE: .github/workflows/inactive-issues.yml
================================================
on:
issues:
types: labeled
workflow_dispatch:
schedule:
- cron: '*/5 * * * *'
permissions:
issues: write
contents: read
name: Label and close issues with no recent activity
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NEEDS_ATTENTION_LABEL: "Needs attention"
NEEDS_AUTHOR_FEEDBACK_LABEL: "Needs author feedback"
NO_RECENT_ACTIVITY_LABEL: "No recent activity"
NO_RECENT_ACTIVITY_DURATION_IN_DAYS: 7
NO_RECENT_ACTIVITY_DURATION_CLOSE_IN_DAYS: 28
ORG_NAME: ${{ github.repository_owner }}
REPO_NAME: ${{ github.event.repository.name }}
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."
jobs:
run:
if: github.repository == 'OAI/OpenAPI-Specification'
runs-on: ubuntu-latest
name: Label issues with no recent activity
steps:
- uses: actions/checkout@v6
- run: scripts/label-no-recent.ps1
shell: pwsh
- run: scripts/close-no-recent.ps1
shell: pwsh
================================================
FILE: .github/workflows/respec.yaml
================================================
name: respec
# author: @MikeRalphson, @ralfhandl
# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564
#
# This workflow creates a pull request for publishing HTML spec versions to the spec.openapis.org site.
#
# run this manually from main
on:
workflow_dispatch: {}
jobs:
respec:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Generate access token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
owner: OAI
repositories: spec.openapis.org
- uses: actions/checkout@v6 # checkout main branch of this repo
with:
fetch-depth: 0
- uses: actions/setup-node@v6 # setup Node.js
with:
node-version: "22.x"
- name: Install dependencies
run: npm ci
- uses: actions/checkout@v6 # checkout main branch of website repo
with:
token: ${{ steps.generate-token.outputs.token }}
repository: OAI/spec.openapis.org
ref: main
path: deploy
- name: run main script
run: scripts/md2html/build.sh
- name: Create Pull Request
uses: peter-evans/create-pull-request@v8
with:
token: ${{ steps.generate-token.outputs.token }}
branch: openapi-spec-versions
base: main
delete-branch: true
path: deploy
labels: OpenAPI,Specification
reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,whitlockjc,handrews,karenetheridge
title: OpenAPI - update ReSpec-rendered specification versions
commit-message: Update ReSpec-rendered specification versions
signoff: true
body: |
This pull request is automatically generated by GitHub action `respec` in the OAI/OpenAPI-Specification repo.
The `versions/*.md` files of the OpenAPI Specification have changed and the corresponding HTML files are regenerated.
================================================
FILE: .github/workflows/schema-publish.yaml
================================================
name: schema-publish
# author: @ralfhandl
# issue: https://github.com/OAI/OpenAPI-Specification/issues/3715
#
# This workflow creates a pull request for publishing schema iterations to the spec.openapis.org site.
#
# run this on push to vX.Y-dev branches or manually
on:
push:
branches:
- "v[0-9].[0-9]-dev"
paths:
- "src/schemas/validation/*.yaml"
workflow_dispatch: {}
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Generate access token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
owner: OAI
repositories: spec.openapis.org
- uses: actions/checkout@v6 # checkout main branch of this repo
with:
fetch-depth: 0
- uses: actions/setup-node@v6 # setup Node.js
with:
node-version: "22.x"
- name: Install dependencies
run: npm ci
- uses: actions/checkout@v6 # checkout main branch of website repo
with:
token: ${{ steps.generate-token.outputs.token }}
repository: OAI/spec.openapis.org
ref: main
path: deploy
- name: run main script
run: scripts/schema-publish.sh
- name: Create Pull Request
uses: peter-evans/create-pull-request@v8
with:
token: ${{ steps.generate-token.outputs.token }}
branch: openapi-${{ github.ref_name }}-schema-iterations
base: main
delete-branch: true
path: deploy
labels: OpenAPI,Schema
reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,whitlockjc,handrews,karenetheridge
title: "OpenAPI - publish ${{ github.ref_name }} schema iterations"
commit-message: "New OpenAPI schema iterations published from ${{ github.ref_name }}"
signoff: true
body: |
This pull request is automatically generated by GitHub action `schema-publish` in the OAI/OpenAPI-Specification repo.
The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated.
================================================
FILE: .github/workflows/schema-tests.yaml
================================================
name: schema-test
# Author: @MikeRalphson / runs @jdesrosiers tests
# Issue: https://github.com/OAI/OpenAPI-Specification/pull/2489
#
# This workflow runs the npm test script to validate passing and failing
# testcases for the metaschemas
#
# run this on push to any branch and creation of pull-requests
on:
pull_request: {}
workflow_dispatch: {}
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6 # checkout repo content
with:
fetch-depth: 0
- uses: actions/setup-node@v6 # setup Node.js
with:
node-version: '20.x'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm run test
env:
BASE: ${{ github.event.pull_request.base.ref }}
================================================
FILE: .github/workflows/sync-dev-to-vX.Y-dev.yaml
================================================
name: sync-dev-to-vX.Y-dev
# author: @ralfhandl
#
# This workflow creates PRs to update the vX.Y-dev branch with the latest changes from dev
#
# run this on push to dev
on:
push:
branches:
- dev
workflow_dispatch: {}
jobs:
sync-branches:
if: github.repository == 'OAI/OpenAPI-Specification'
runs-on: ubuntu-latest
steps:
- name: Generate access token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 0
token: ${{ steps.generate-token.outputs.token }}
- name: Create pull requests
id: pull_requests
shell: bash
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
DEV_BRANCHES=$(git branch -r --list origin/v?.?-dev)
for DEV_BRANCH in $DEV_BRANCHES; do
BASE=${DEV_BRANCH:7}
SYNC="$BASE-sync-with-$HEAD"
git checkout -b $SYNC origin/$SYNC || git checkout -b $SYNC origin/$BASE
git merge origin/$HEAD -m "Merge $HEAD into $SYNC"
git checkout origin/$BASE src/
git checkout origin/$BASE tests/schema/
git commit -m "Restored src/ and tests/schema/" || echo ""
git push -u origin $SYNC
EXISTS=$(gh pr list --base $BASE --head $SYNC \
--json number --jq '.[] | .number')
if [ ! -z "$EXISTS" ]; then
echo "PR #$EXISTS already wants to merge $SYNC into $BASE"
continue
fi
PR=$(gh pr create --base $BASE --head $SYNC \
--label "Housekeeping" \
--title "$BASE: sync with $HEAD" \
--body "Merge relevant changes from \`$HEAD\` into \`$BASE\`.")
echo ""
echo "PR to sync $BASE with $HEAD: $PR"
sleep 60 # allow status checks to be triggered
gh pr checks $PR --watch --required || continue
gh pr merge $PR --merge --admin
done
env:
GH_TOKEN: ${{ steps.generate-token.outputs.token }}
HEAD: dev
================================================
FILE: .github/workflows/sync-main-to-dev.yaml
================================================
name: sync-main-to-dev
# author: @ralfhandl
#
# This workflow creates PRs to update the dev branch with the latest changes from main
#
# run this on push to main
on:
push:
branches:
- main
workflow_dispatch: {}
jobs:
sync-branch:
if: github.repository == 'OAI/OpenAPI-Specification'
runs-on: ubuntu-latest
steps:
- name: Generate access token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 0
token: ${{ steps.generate-token.outputs.token }}
- name: Create pull request
id: pull_request
shell: bash
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
SYNC="$BASE-sync-with-$HEAD"
git checkout -b $SYNC origin/$SYNC || git checkout -b $SYNC origin/$BASE
git merge origin/$HEAD -m "Merge $HEAD into $SYNC"
git checkout origin/$BASE src/
git checkout origin/$BASE tests/schema/
git commit -m "Restored src/ and tests/schema/" || echo ""
git push -u origin $SYNC
EXISTS=$(gh pr list --base $BASE --head $SYNC \
--json number --jq '.[] | .number')
if [ ! -z "$EXISTS" ]; then
echo "PR #$EXISTS already wants to merge $SYNC into $BASE"
exit 0
fi
gh pr create --base $BASE --head $SYNC \
--label "Housekeeping" \
--title "$BASE: sync with $HEAD" \
--body "Merge relevant changes from \`$HEAD\` into \`$BASE\`."
env:
GH_TOKEN: ${{ steps.generate-token.outputs.token }}
HEAD: main
BASE: dev
================================================
FILE: .github/workflows/validate-markdown.yaml
================================================
name: validate-markdown
# Author: @MikeRalphson
# Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130
# This workflow validates markdown files in the project root.
# It also validates the work-in-progress specification file src/oas.md with slightly different rules.
# run this on pull requests (which includes pushes to their head branch)
on:
- pull_request
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6 # checkout repo content
- uses: actions/setup-node@v6 # setup Node.js
with:
node-version: "20.x"
- name: Lint work-in-progress spec
run: npx --yes markdownlint-cli2 --config spec.markdownlint.yaml src/oas.md
- name: Lint other files
run: npx --yes markdownlint-cli2 *.md
- name: Check links in markdown files
uses: umbrelladocs/action-linkspector@v1
with:
reporter: github-check
fail_level: any
filter_mode: file
================================================
FILE: .gitignore
================================================
.idea
*.iml
*.ipr
*.iws
target
atlassian-ide-plugin.xml
node_modules/
deploy/
deploy-preview/
coverage/
_site/
Gemfile.lock
================================================
FILE: .gitmodules
================================================
================================================
FILE: .linkspector.yml
================================================
files:
- src/oas.md
- CONTRIBUTING.md
- EDITORS.md
- GOVERNANCE.md
- IMPLEMENTATIONS.md
- MAINTAINERS.md
- README.md
- SECURITY_CONSIDERATIONS.md
- SPECIAL_INTEREST_GROUPS.md
- style-guide.md
- TOB.md
ignorePatterns:
- pattern: 'clientdomain.com'
- pattern: 'example.org'
================================================
FILE: .markdownlint.yaml
================================================
# First heading is a top-level heading
MD002: true
# Heading style (ATX is leading # symbols)
MD003:
style: atx
# Unordered list symbol can be anything
MD004: false
# Unordered list indentation size
MD007:
indent: 2
# Allow additional blank lines
MD012: false
# Maximum line length
MD013:
line_length: 800
tables: false
# Headings need blank lines before and after
MD022: true
# Duplicate headings are allowed
MD024: false
# Surround lists with blank lines
MD032: true
# Allow inline HTML
MD033: false
================================================
FILE: CONTRIBUTING.md
================================================
# Contribute to the OpenAPI Specification
## Key information
This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme).
All participants are expected to read and follow this code.
No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder).
Exceptions may be made when links to external URLs have been changed by a 3rd party, in order to keep our documents accurate.
Published versions of the specification are in the `versions/` folder.
The under-development versions of the specification are in the file `src/oas.md` on the appropriately-versioned branch.
For example, work on the next patch release for 3.2 is on `v3.2-dev` in the file `src/oas.md`, and work on the next minor release with additional features for 3.3 is on `v3.3-dev`.
The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI specification as it contains all the citations and author credits (the markdown in this repository was previously the authoritative version until 2024).
The OpenAPI project is almost entirely staffed by volunteers.
Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world.
### Active branches
The current active specification releases are:
| Version | Branch | Notes |
| ------- | ------ | ----- |
| 3.1.3 | `v3.1-dev` | active patch release line |
| 3.2.1 | `v3.2-dev` | active patch release line |
| 3.3.0 | `v3.3-dev` | minor release in development |
| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) |
## How to contribute
We welcome new contributors to the project whether you have changes to suggest, problems to report, or some feedback for us.
Please jump to the most relevant section from the list below:
- Ask a question or offer feedback: use a [discussion](#discussions)
- Suggest a change or report a problem: open an [issue](#issues)
- Contribute a change to the repository: open a [pull request](#pull-requests)
- Or just [get in touch](#get-in-touch)
## Discussions
We use [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for anything that doesn't (yet) have a specific action associated with it.
Most ideas start as discussions.
Please do come and start a discussion to:
- ask questions
- make suggestions
- give feedback
Anyone can start a discussion and you're very welcome to do so! Write a message and pick a relevant discussion category.
### Discussion management
Participation in discussions and especially answering of questions is encouraged (and appreciated) by everyone.
Discussions are closed when:
- the question has been answered.
- no further action or conversation would be useful.
- there has been no engagement for a while, or a previously popular thread has been inactive for an extended period.
- activity is now taking place elsewhere, such as in an issue.
- the discussion is out of scope for the project.
## Issues
Issues are for planned tasks, problems to solve, or requests for (specific) changes.
Most issues should have a clear outcome; something will be fixed, improved or otherwise measurably different when the issue is complete.
We use [discussions](#discussions) for ideas and early-stage suggestions.
> [!NOTE]
> For larger or more extensive changes, we have a formal [proposal process](#propose-a-specification-change) to give more structure where it's needed.
The best issues give a clear and concise explanation of the problem at hand, and ideally some examples of what the problem is.
Suggested solutions are also welcome, but it is very important that the issue outlines the problem that is being solved as well as the solution.
Some issues may be a backlog of a task that needs to be done; other issues might be automatically created as part of the project processes.
### Issue management
We have some issue automation to close inactive issues and create/pin/archive the weekly meeting issues.
More information is in the [Appendix: Issue automation](#appendix-issue-automation) section.
Everyone is encouraged to open and comment on issues in the project.
If you want to tag/assign/close something and you don't have enough permissions, add a comment and someone will help.
Issues are managed by the [Triage](#triage), [Maintainers](#maintainers) and [TSC](#tsc) teams.
They may move issues to other repositories within the project as needed.
In order to keep the issues list manageable and realistic for a relatively small group of volunteers, issues are proactively closed when it's not clear that they can be completed.
Issues may be closed when:
- they have been inactive for a long time
- they are out of scope or no further constructive action can be taken
- they are complete (yay!)
- they are unclear and more details are not forthcoming
- as a group, there is agreement that no further action will be taken
When issues are closed, a comment is added about why.
Closing issues is a reversible action, and it is always acceptable to comment and explain (politely) why an issue should not have been closed.
### Labels
We make extensive use of labels.
The main categories are:
- [Housekeeping](https://github.com/OAI/OpenAPI-Specification/labels/Housekeeping) for meetings, project logistics, etc.
- [approved pr port](https://github.com/OAI/OpenAPI-Specification/labels/approved%20pr%20port) for pull requests that repeat a change from one version to another
- most other tags are used to group similar or related issues into topic areas; this list is ever-changing
Labels related to [issue automation](#appendix-issue-automation)
- [Needs attention](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20attention) automated tag when an issue is updated
- [Needs author feedback](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20author%20feedback) used to indicate that more information is needed from the issue creator
- [No recent activity](https://github.com/OAI/OpenAPI-Specification/labels/No%20recent%20activity) if no information is received, the issue is marked for closure (automatic after 30 days)
### Milestones
We use milestones in GitHub to plan what should be included in future releases.
Issues and pull requests should both be added to the earliest milestone we expect they will be released in.
Any changes that aren't ready in time for release should be moved to the next milestone or untagged.
The milestones and items assigned to them are under constant review and subject to change.
### Projects
The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects:
* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1)
* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1)
## Pull requests
> [!NOTE]
> Since the 3.0.4 and 3.1.1 releases (October 2024), the OAS is developed in the `src/oas.md` file.
> Check the [Appendix: Branch Strategy](#appendix-branch-strategy) for more information about the updated branching strategy.
Changes to the next version of the specification are welcome and can be proposed by anyone.
For large changes that will need discussion, please use the [Proposal process](#propose-a-specification-change).
For other changes, we recommend [opening an issue](#issues) first, so that you can get some feedback and any extra input you need before spending a lot of time on something.
Schema changes are made on the same branch, but can be released independently.
When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred.
Patch releases cannot contain changes that _require_ a schema update.
### Use a fork
All work **MUST be done on a fork** and be submitted as a pull request.
### Target the earliest active `*-dev` branch
Branch from and submit pull requests to the a branch from the _earliest relevant and [active](#active-branches)_ `vX.Y-dev` branch.
For example, if a change applies to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release.
All changes to the specification must conform to the [style guide](./style-guide.md).
Both specification and schema changes follow this approach.
For changes to repository files that affect all versions, use the `main` branch.
This might apply to, for example, Markdown files, automation, and scripts.
For all pull requests, if they should not be merged yet for any reason (they depend on something else, you would like feedback from a specific reviewer), mark them as draft and they will not be merged while in that state.
Draft pull requests can still be reviewed while in draft state.
### Preview specification HTML locally
> [!NOTE]
> `npm run build-src` calls bash scripts. Use [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL).
The markdown source files are converted to HTML before publishing.
To do this locally, please
1. Install [Node.js](https://nodejs.org/)
2. Check out this repo, go to the repo root, and switch to a development branch
3. Execute `npm install` (once, repeat after merging upstream changes)
4. Execute `npm run build-src` after changing `src/oas.md` (this first executes `npm run validate-markdown`, which can also be run separately)
5. Open output file `deploy-preview/oas.html` with a browser and check your changes
Please make sure the markdown validates and builds using the above steps before creating a pull request or marking a draft pull request as ready for review.
## Reviewers
> [!NOTE]
> See also the detailed team outlines in the [roles section](#roles).
All pull requests must be reviewed and approved by one member of the TSC or Maintainers teams.
Reviews from other contributors are always welcome.
Additionally, all pull requests that change the specification file `src/oas.md` must be approved by two TSC members.
Reviews requesting changes should have their changes addressed regardless of how many other approvers there are.
## Publishing
### Specification Versions
The specification versions are published to the [spec site](https://spec.openapis.org/oas) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`.
This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files).
The steps for creating a `vX.Y.Z-rel` branch are:
1. Update `EDITORS.md` on `main`
2. Merge `main` into `dev` and `dev` into `vX.Y-dev` via PRs
- sync PRs are automatically created by workflows `sync-main-to-dev` and `sync-dev-to-vX.Y-dev`
3. Prepare spec files in `vX.Y-dev`
- `npm run format-markdown`
- `npm run build-src`
- open `deploy-preview/oas.html` in browser and verify correct formatting
- adjust and repeat until done
- merge changes to `src/oas.md` back into `vX.Y-dev` via PR
4. Create `vX.Y.Z-rel` from `vX.Y-dev` and adjust it
- the bash script `scripts/adjust-release-branch.sh` does this:
- copy file `src/oas.md` to `versions/X.Y.Z.md` and replace the release date placeholder `| TBD |` in the history table of Appendix A with the current date
- copy file `EDITORS.md` to `versions/X.Y.Z-editors.md`
- delete folder `src`
- delete version-specific files and folders from `tests/schema`
- file `schema.test.mjs`
- folders `pass` and `fail`
5. Merge `vX.Y.Z-rel` into `main` via PR
- this PR should only add files `versions/X.Y.Z.md` and `versions/X.Y.Z-editors.md`
The HTML renderings of the specification versions are generated from the `versions` directory on `main` by manually triggering the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml), which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org).
#### Start Next Patch Version
Once the released specification version is [synced](#branch-sync-automation) back to the `vX.Y-dev` branch, the next patch version X.Y.(Z+1) can be started:
1. Run bash script `scripts/start-release.sh` in branch `vX.Y-dev` to
- create branch `vX.Y-dev-start-X.Y.(Z+1)`
- initialize `src/oas.md` with empty history and content from `versions/X.Y.Z.md`
- change version heading to X.Y.(Z+1) and add a new line to the version history table in Appendix A of `src/oas.md`
- commit and push changes
2. Merge `vX.Y-dev-start-X.Y.(Z+1)` into `vX.Y-dev` via pull request
Alternatively, if no patch version X.Y.(Z+1) is planned, delete file `src/oas.md` from branch `vX.Y-dev` via pull request.
#### Start New Minor or Major Version
A new minor version X.(Y+1).0 or major version (X+1).0.0 is started similarly:
1. Create branch `vX'.Y'-dev` from `vX.Y-dev`
2. Run bash script `scripts/start-release.sh` in the new branch to
- create branch `vX'.Y'-dev-start-X'.Y'.0`
- initialize `src/oas.md` with empty history and content from `versions/X.Y.Z.md`
- change version heading to X'.Y'.0 and add a new line to the version history table in Appendix A of `src/oas.md`
- change version in all schema files `src/schemas/validation/.yaml`
- change version in schema test script `tests/schema/schema.test.mjs`
- change version in schema test fixtures in folders `tests/schema/pass` and `tests/schema/fail`
- commit and push changes
3. Merge `vX'.Y'-dev-start-X'.Y'.0` into `vX'.Y'-dev` via pull request
### Schema Iterations
The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/oas).
Schemas are updated in and directly published from the `vX.Y-dev` branches.
As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the [`schema-publish` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/schema-publish.yaml) which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required.
#### Schemas and OAS Requirements
The schemas published by the OpenAPI Initiative _only_ validate mandatory
OAS requirements. This means that a field value or combination with another
field is only forbidden in a schema if there is a corresponding MUST / MUST NOT /
SHALL / SHALL NOT requirement that prevents it.
Schemas that apply further restrictions to enforce desired usage are outside
of the scope of the OpenAPI Initiative. When opening an issue or PR for
schema changes, please ensure that the changes are backed by clear OAS
requirements. Otherwise, the issue or PR will be closed with a note pointing
to this section.
## Release Process and Scope
This section relates to the 3.x versions only.
### Minor Releases
Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Propose a Specification Change](#propose-a-specification-change)), in addition to the issues already on the project backlog.
Changes in minor releases (such as 3.2, 3.3) meet the following criteria:
* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version.
For example, new optional fields can be added.
* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs.
For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification.
* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available.
* Make the specification document clearer or easier to understand.
A minor release is due when there are some meaningful features (including one or a small number of headline features).
### Patch Releases
Patch releases reflect a constant quest for improving the active minor versions of OpenAPI.
Since we do not edit specification documents after publication, even the smallest change has to be in a new release.
Changes in patch releases meet the following criteria:
* Editorial changes such as spelling or formatting fixes, including link updates.
* Clarifications or additions that do not change the meaning of the specification.
Patch releases are created as often as there are changes to the specification worth releasing.
### Release Process
A release requires a vote on the specification at a particular version and the associated release notes by TSC members within the voting period.
Major or minor release voting periods will be announced in the Slack channel and noted on the calendar at least 6 days in advance.
During this time, TSC members who have not yet voted must note their approval by leaving a comment on the GitHub pull request proposing the release; release notes should be included with the description.
TSC members are responsible for coordinating the information about the release to the outreach team as appropriate.
* Patch-level releases require majority approval by TSC members. (Max voting period 3 days)
* Minor: requires approval by 66% of TSC members. (Max voting period 7 days)
* Major: requires approval by 66% of TSC members. (Max voting period 14 days)
During the voting period, further changes should not be made to the specification being considered.
Once the threshold of approvals is met, the release can be performed by any TSC member.
## Propose a Specification Change
As an organisation, we're open to changes, and these can be proposed by anyone.
The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result.
We do not accept changes lightly (but we will consider any that we can).
Small changes are welcome as pull requests.
Bigger changes require a more formal process.
1. Start a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) of type "Enhancements".
The discussion entry must include some use cases, your proposed solution and the alternatives you have considered.
If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage.
2. It really helps to see the proposed change in action.
Start using it as a `x-*` extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted.
3. If you are adding support for something from another specification (such as OAuth), please point to implementations of that
specification so that we can understand how, and to what degree, it is being used.
4. If the suggested change has good support, you will be asked to create a formal proposal.
Use the [template in the proposals directory](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals), copy it to a new file, and complete it.
Once you the document is ready, open a pull request on the main branch.
5. The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted.
At that point, the proposal is merged into the `main` branch and a pull request is opened to add the feature to the appropriate `dev` version of the specification.
Questions are welcome on the process at any time. Use the discussions feature or find us in Slack.
## Roles
The OpenAPI project has some key roles that are played by multiple people.
### TSC
The Technical Steering Committee are listed in the [MAINTAINERS file](./MAINTAINERS.md).
They are the maintainers of the OpenAPI Specification itself and every other aspect of the project operation and direction.
TSC members can review changes to all parts of the repository and make decisions about the project.
### Maintainers
The maintainers have write access to the repository and play a key role in the project.
They review pull requests to non-specification parts of the repository, and take on other strategic tasks around project planning and maintenance.
### Triage
The triage team are active OpenAPI members who help with discussion and issue management.
They respond to new issues and discussions, direct people to our existing resources or raise conversations to a wider audience.
The triage team keeps an eye on the backlog and closes issues and discussions that are no longer active or needed.
## Get in touch
To get in touch with other people on the project, ask questions, or anything else:
- Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi).
- Start a [GitHub Discussion](https://github.com/OAI/OpenAPI-Specification/discussions/).
- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHousekeeping).
## Appendix: Branch strategy
For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and earlier, see the comments in [issue #3677](https://github.com/OAI/OpenAPI-Specification/issues/3677).
### Branch roles
* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed. The `src` tree is _**not**_ present on `main`.
* `dev` is the primary branch for working with the `src` tree. Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed.
Changes on `main` are automatically included in a pull request to `dev` (see the section on [branch sync](#branch-sync-automation)).
* `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions. All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document.
* `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location and removing schema-related files before merging back to `main`, and is deleted once merged into `main` via a pull request.
### Branching and merging (3.1.2, 3.2.0, and later)
Upon release:
* Pre-release steps:
* The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant
* If doing simultaneous releases on multiple lines, do them from the oldest to newest line
* For example, if releasing 3.1.3 and 3.2.0:
* release 3.1.3 first
* release 3.2.0 second
* Release branching and merging:
* branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant)
* After renaming `src/oas.md` to `versions/X.Y.Z.md` and [other adjustments](#specification-versions), merge `vX.Y.Z-rel` to `main`
* Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main`
* Post-release steps:
* If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `vX.Y-dev`
_Release lines are grouped by color, although the colors of `dev` and `main` are not significant as these diagrams are limited to only 8 colors._
```mermaid
---
config:
themeVariables:
git0: "#5588bb"
git1: "#cc8899"
git2: "#eedd88"
git3: "#ccbb66"
git4: "#aa9944"
git5: "#44ff77"
git6: "#22cc22"
git7: "#11aa11"
gitBranchLabel1: "#000000"
gitBranchLabel2: "#000000"
gitBranchLabel3: "#000000"
gitBranchLabel4: "#000000"
gitBranchLabel5: "#000000"
gitBranchLabel6: "#000000"
gitBranchLabel7: "#000000"
---
gitGraph TB:
commit id:"merge 3.1.1.md to main" tag:"3.1.1"
branch dev order:1
commit id:"rename 3.1.1.md to src/oas.md"
branch v3.1-dev order:2
commit id:"update version in src/oas.md to 3.1.2"
checkout dev
branch v3.2-dev order:6
commit id:"update version in src/oas.md to 3.2.0"
commit id:"some 3.2.0 work"
checkout v3.1-dev
commit id:"a 3.1.2 fix"
checkout v3.1-dev
branch v3.1.2-rel order:3
commit id:"rename src/oas.md to versions/3.1.2.md"
checkout main
merge v3.1.2-rel tag:"3.1.2"
checkout dev
merge main id:"auto-sync from main"
checkout v3.1-dev
merge dev id:"auto-sync from dev"
checkout v3.2-dev
merge dev id:"auto-sync from dev "
commit id:"more 3.2.0 work"
checkout v3.1-dev
commit id:"update version in src/oas.md to 3.1.3"
commit id:"a 3.1.3 fix"
checkout v3.2-dev
commit id:"still more 3.2.0 work"
checkout v3.1-dev
branch v3.1.3-rel order:4
commit id:"rename src/oas.md to versions/3.1.3.md"
checkout v3.2-dev
branch v3.2.0-rel order:7
commit id:"rename src/oas.md to versions/3.2.0.md"
checkout main
merge v3.1.3-rel tag:"3.1.3"
checkout dev
merge main id:" auto-sync from main"
checkout v3.1-dev
merge dev id:" auto-sync from dev"
checkout v3.2-dev
merge dev id:" auto-sync from dev "
checkout main
merge v3.2.0-rel tag:"3.2.0"
checkout dev
merge main id:" auto-sync from main"
checkout v3.1-dev
merge dev id:" auto-sync from dev"
checkout v3.2-dev
merge dev id:" auto-sync from dev "
checkout v3.2-dev
branch v3.3-dev order:9
checkout v3.2-dev
commit id:"update version in src/oas.md to 3.2.1"
checkout v3.3-dev
commit id:"update version in src/oas.md to 3.3.0"
checkout v3.2-dev
commit id:"a 3.2.1 fix"
checkout v3.2-dev
branch v3.2.1-rel order:8
commit id:"rename src/oas.md to versions/3.2.1.md"
checkout dev
merge main id:" auto-sync from main"
checkout v3.1-dev
merge dev id:" auto-sync from dev"
checkout v3.2-dev
merge dev id:" auto-sync from dev "
checkout v3.3-dev
merge dev id:" auto-sync from dev "
checkout main
merge v3.2.1-rel tag:"3.2.1"
checkout dev
merge main id:" auto-sync from main"
checkout v3.1-dev
merge dev id:" auto-sync from dev"
checkout v3.2-dev
merge dev id:" auto-sync from dev "
checkout v3.3-dev
merge dev id:" auto-sync from dev "
checkout v3.2-dev
commit id:"update version in src/oas.md to 3.2.2"
checkout v3.3-dev
commit id:"3.3 work"
```
### Branch sync automation
To keep changes in sync, we have some GitHub actions that open pull requests to take changes from `main` onto the `dev` branch, and from `dev` to each active version branch.
- `sync-main-to-dev` opens a pull request with all the changes from the `main` branch that aren't yet included on `dev`. This pull request needs a single approval from either maintainers or TSC and can be merged.
- `sync-dev-to-vX.Y-dev` opens pull requests with all the changes from `dev` that aren't yet included on the corresponding `vX.Y-dev` branch. These pull requests are automatically merged if all required status checks pass.
The aim is to bring build script and repository documentation changes to the other branches.
Published versions of the specifications will also move across branches with this approach.
## Appendix: Issue Automation
### Automated closure of issues Process
In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive.
This process makes use of the following labels:
* `Needs author feedback`: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow.
* `No recent activity`: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow.
* `Needs attention`: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow.
### Automated TDC agenda issues Process
An issue is opened every week, 7 days in advance, for the Technical Developer Community (TDC), it provides the information to connect the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping".
Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically.
================================================
FILE: EDITORS.md
================================================
# OpenAPI Specification Editors
## Active
* Henry Andrews [@handrews](https://github.com/handrews)
* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
* Karen Etheridge [@karenetheridge](https://github.com/karenetheridge)
* Lorna Mitchell [@lornajane](https://github.com/lornajane)
* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
* Miguel Quintero [@miqui](https://github.com/miqui)
* Mike Kistler [@mikekistler](https://github.com/mikekistler)
* Ralf Handl [@ralfhandl](https://github.com/ralfhandl)
* Vincent Biret [@baywet](https://github.com/baywet)
## Emeritus
* Ron Ratovsky [@webron](https://github.com/webron)
* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
* Uri Sarid [@usarid](https://github.com/usarid)
* Jason Harmon [@jharmn](https://github.com/jharmn)
* Tony Tam [@fehguy](https://github.com/fehguy)
================================================
FILE: GOVERNANCE.md
================================================
# Governance
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/participatehow-to-contribute/governance).
## Processes and procedures of the Technical Steering Committee (TSC)
The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines.
### 1. The establishment of roles and the responsibilities for each role
Roles:
* [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.
* [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.
* [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.
* [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members.
### 2. Adding members to the TSC
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.
A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting.
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.
Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 6 months.
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.
At most there are four voting periods per year (no more than one every three months), with a minimum of one per year.
### 3. Removal of membership from the TSC
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.
### 4. Criteria for decisions
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).
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.
================================================
FILE: IMPLEMENTATIONS.md
================================================
# Implementations
The list of implementations formerly in this file is no-longer maintained here.
You may find a more comprehensive list at <https://tools.openapis.org>
Instructions on listing your projects are contained in <https://github.com/OAI/Tooling#how-can-you-help>
These tools are not endorsed by the OAI.
================================================
FILE: LICENSE
================================================
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "{}"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright The Linux Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
================================================
FILE: MAINTAINERS.md
================================================
# OpenAPI Initiative Technical Steering Committee Members
## Active
* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
* Lorna Mitchell [@lornajane](https://github.com/lornajane)
* Mike Kistler [@mikekistler](https://github.com/mikekistler)
* Miguel Quintero [@miqui](https://github.com/miqui)
* Ralf Handl [@ralfhandl](https://github.com/ralfhandl)
## Emeritus
* Ron Ratovsky [@webron](https://github.com/webron)
* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
* Uri Sarid [@usarid](https://github.com/usarid)
* Jason Harmon [@jharmn](https://github.com/jharmn)
* Tony Tam [@fehguy](https://github.com/fehguy)
================================================
FILE: README.md
================================================
# The OpenAPI Specification
 [](https://www.codetriage.com/oai/openapi-specification)
The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
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.
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.
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.
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.
## Versions
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](https://github.com/OAI/OpenAPI-Specification/releases).
## See It in Action
If you just want to see it work, check out the [list of current examples](https://learn.openapis.org/examples/).
## Tools and Libraries
Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing
[list of implementations](IMPLEMENTATIONS.md).
## Participation
The current process for developing the OpenAPI Specification is described in
the [Contributing Guidelines](CONTRIBUTING.md).
Developing the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](MAINTAINERS.md). 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`.
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.
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:
* Review the specification [markdown sources](versions) and [authoritative _source-of-truth_ HTML renderings](https://spec.openapis.org/), including full credits and citations.
* Review the [contributing](CONTRIBUTING.md) process so you understand how the spec is evolving.
* 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.
* Subscribe to an open issue a day (or a week) in your inbox via [CodeTriage.com](https://www.codetriage.com/oai/openapi-specification).
* Create a discussion to describe a new concern, ideally with clear explanations of related use cases.
Not all feedback can be accommodated, and there may be solid arguments for or against a change being appropriate for the specification.
## Licensing
See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE)
================================================
FILE: SECURITY_CONSIDERATIONS.md
================================================
# Security Considerations
## OpenAPI Document Formats
OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations:
- [JSON](https://www.iana.org/assignments/media-types/application/json)
- [YAML](https://www.iana.org/assignments/media-types/application/yaml)
- [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13)
- [JSON Schema Validation](https://json-schema.org/draft/2020-12/json-schema-validation#name-security-considerations)
## Tooling and Usage Scenarios
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.
## Security Schemes
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.
## Handling External Resources
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.
## Markdown and HTML Sanitization
Certain properties allow the use of Markdown which can contain HTML including script. It is the responsibility of tooling to appropriately sanitize the Markdown.
================================================
FILE: SPECIAL_INTEREST_GROUPS.md
================================================
# OpenAPI Special Interest Groups (SIGs)
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.
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.
================================================
FILE: TOB.md
================================================
# Technical Oversight Board ("TOB")
## Description
> 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.
## TSC Elected - terms through May 2023
Isabelle Mauny @isamauny
Uri Sarid @usarid
Marsh Gardiner @earth2marsh
Ron Ratovsky @webron
## BGB Elected - terms through May 2022
Darrel Miller @darrelmiller
Jerome Louvel @jlouvel
Jeremy Whitlock @whitlockjc
================================================
FILE: _archive_/README.md
================================================
# Archive
This folder contains files that are no longer actively maintained.
================================================
FILE: _archive_/schemas/README.md
================================================
# Archive of outdated JSON Schema Files
> [!TIP]
> JSON Schema files for validating OpenAPI descriptions using current OpenAPI versions are available on https://spec.openapis.org/#openapi-specification-schemas.
>
> These schema files are maintained in the `src/schemas` folder of the corresponding `vX.Y-dev` branch in this repository.
> [!CAUTION]
> Schema files in this folder are not maintained any more and are not intended for productive use.
================================================
FILE: _archive_/schemas/v1.2/README.md
================================================
# Swagger Specification JSON Schemas
The work on the JSON Schema for the Swagger Specification was donated to the community by [Francis Galiegue](https://github.com/fge)!
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.
================================================
FILE: _archive_/schemas/v1.2/apiDeclaration.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/apiDeclaration.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [ "swaggerVersion", "basePath", "apis" ],
"properties": {
"swaggerVersion": { "enum": [ "1.2" ] },
"apiVersion": { "type": "string" },
"basePath": {
"type": "string",
"format": "uri",
"pattern": "^https?://"
},
"resourcePath": {
"type": "string",
"format": "uri",
"pattern": "^/"
},
"apis": {
"type": "array",
"items": { "$ref": "#/definitions/apiObject" }
},
"models": {
"type": "object",
"additionalProperties": {
"$ref": "modelsObject.json#"
}
},
"produces": { "$ref": "#/definitions/mimeTypeArray" },
"consumes": { "$ref": "#/definitions/mimeTypeArray" },
"authorizations": { "$ref": "authorizationObject.json#" }
},
"additionalProperties": false,
"definitions": {
"apiObject": {
"type": "object",
"required": [ "path", "operations" ],
"properties": {
"path": {
"type": "string",
"format": "uri-template",
"pattern": "^/"
},
"description": { "type": "string" },
"operations": {
"type": "array",
"items": { "$ref": "operationObject.json#" }
}
},
"additionalProperties": false
},
"mimeTypeArray": {
"type": "array",
"items": {
"type": "string",
"format": "mime-type"
},
"uniqueItems": true
}
}
}
================================================
FILE: _archive_/schemas/v1.2/authorizationObject.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/authorizationObject.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/definitions/basicAuth"
},
{
"$ref": "#/definitions/apiKey"
},
{
"$ref": "#/definitions/oauth2"
}
]
},
"definitions": {
"basicAuth": {
"required": [ "type" ],
"properties": {
"type": { "enum": [ "basicAuth" ] }
},
"additionalProperties": false
},
"apiKey": {
"required": [ "type", "passAs", "keyname" ],
"properties": {
"type": { "enum": [ "apiKey" ] },
"passAs": { "enum": [ "header", "query" ] },
"keyname": { "type": "string" }
},
"additionalProperties": false
},
"oauth2": {
"type": "object",
"required": [ "type", "grantTypes" ],
"properties": {
"type": { "enum": [ "oauth2" ] },
"scopes": {
"type": "array",
"items": { "$ref": "#/definitions/oauth2Scope" }
},
"grantTypes": { "$ref": "oauth2GrantType.json#" }
},
"additionalProperties": false
},
"oauth2Scope": {
"type": "object",
"required": [ "scope" ],
"properties": {
"scope": { "type": "string" },
"description": { "type": "string" }
},
"additionalProperties": false
}
}
}
================================================
FILE: _archive_/schemas/v1.2/dataType.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataType.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Data type as described by the specification (version 1.2)",
"type": "object",
"oneOf": [
{ "$ref": "#/definitions/refType" },
{ "$ref": "#/definitions/voidType" },
{ "$ref": "#/definitions/primitiveType" },
{ "$ref": "#/definitions/modelType" },
{ "$ref": "#/definitions/arrayType" }
],
"definitions": {
"refType": {
"required": [ "$ref" ],
"properties": {
"$ref": { "type": "string" }
},
"additionalProperties": false
},
"voidType": {
"enum": [ { "type": "void" } ]
},
"modelType": {
"required": [ "type" ],
"properties": {
"type": {
"type": "string",
"not": {
"enum": [ "boolean", "integer", "number", "string", "array" ]
}
}
},
"additionalProperties": false
},
"primitiveType": {
"required": [ "type" ],
"properties": {
"type": {
"enum": [ "boolean", "integer", "number", "string" ]
},
"format": { "type": "string" },
"defaultValue": {
"not": { "type": [ "array", "object", "null" ] }
},
"enum": {
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"uniqueItems": true
},
"minimum": { "type": "string" },
"maximum": { "type": "string" }
},
"additionalProperties": false,
"dependencies": {
"format": {
"oneOf": [
{
"properties": {
"type": { "enum": [ "integer" ] },
"format": { "enum": [ "int32", "int64" ] }
}
},
{
"properties": {
"type": { "enum": [ "number" ] },
"format": { "enum": [ "float", "double" ] }
}
},
{
"properties": {
"type": { "enum": [ "string" ] },
"format": {
"enum": [ "byte", "date", "date-time" ]
}
}
}
]
},
"enum": {
"properties": {
"type": { "enum": [ "string" ] }
}
},
"minimum": {
"properties": {
"type": { "enum": [ "integer", "number" ] }
}
},
"maximum": {
"properties": {
"type": { "enum": [ "integer", "number" ] }
}
}
}
},
"arrayType": {
"required": [ "type", "items" ],
"properties": {
"type": { "enum": [ "array" ] },
"items": {
"type": "array",
"items": { "$ref": "#/definitions/itemsObject" }
},
"uniqueItems": { "type": "boolean" }
},
"additionalProperties": false
},
"itemsObject": {
"oneOf": [
{
"$ref": "#/definitions/refType"
},
{
"allOf": [
{
"$ref": "#/definitions/primitiveType"
},
{
"properties": {
"type": {},
"format": {}
},
"additionalProperties": false
}
]
}
]
}
}
}
================================================
FILE: _archive_/schemas/v1.2/dataTypeBase.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataTypeBase.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Data type fields (section 4.3.3)",
"type": "object",
"oneOf": [
{ "required": [ "type" ] },
{ "required": [ "$ref" ] }
],
"properties": {
"type": { "type": "string" },
"$ref": { "type": "string" },
"format": { "type": "string" },
"defaultValue": {
"not": { "type": [ "array", "object", "null" ] }
},
"enum": {
"type": "array",
"items": { "type": "string" },
"uniqueItems": true,
"minItems": 1
},
"minimum": { "type": "string" },
"maximum": { "type": "string" },
"items": { "$ref": "#/definitions/itemsObject" },
"uniqueItems": { "type": "boolean" }
},
"dependencies": {
"format": {
"oneOf": [
{
"properties": {
"type": { "enum": [ "integer" ] },
"format": { "enum": [ "int32", "int64" ] }
}
},
{
"properties": {
"type": { "enum": [ "number" ] },
"format": { "enum": [ "float", "double" ] }
}
},
{
"properties": {
"type": { "enum": [ "string" ] },
"format": {
"enum": [ "byte", "date", "date-time" ]
}
}
}
]
}
},
"definitions": {
"itemsObject": {
"oneOf": [
{
"type": "object",
"required": [ "$ref" ],
"properties": {
"$ref": { "type": "string" }
},
"additionalProperties": false
},
{
"allOf": [
{ "$ref": "#" },
{
"required": [ "type" ],
"properties": {
"type": {},
"format": {}
},
"additionalProperties": false
}
]
}
]
}
}
}
================================================
FILE: _archive_/schemas/v1.2/infoObject.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/infoObject.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "info object (section 5.1.3)",
"type": "object",
"required": [ "title", "description" ],
"properties": {
"title": { "type": "string" },
"description": { "type": "string" },
"termsOfServiceUrl": { "type": "string", "format": "uri" },
"contact": { "type": "string", "format": "email" },
"license": { "type": "string" },
"licenseUrl": { "type": "string", "format": "uri" }
},
"additionalProperties": false
}
================================================
FILE: _archive_/schemas/v1.2/modelsObject.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/modelsObject.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [ "id", "properties" ],
"properties": {
"id": { "type": "string" },
"description": { "type": "string" },
"properties": {
"type": "object",
"additionalProperties": { "$ref": "#/definitions/propertyObject" }
},
"subTypes": {
"type": "array",
"items": { "type": "string" },
"uniqueItems": true
},
"discriminator": { "type": "string" }
},
"dependencies": {
"subTypes": [ "discriminator" ]
},
"definitions": {
"propertyObject": {
"allOf": [
{
"not": { "$ref": "#" }
},
{
"$ref": "dataTypeBase.json#"
}
]
}
}
}
================================================
FILE: _archive_/schemas/v1.2/oauth2GrantType.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/oauth2GrantType.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"minProperties": 1,
"properties": {
"implicit": { "$ref": "#/definitions/implicit" },
"authorization_code": { "$ref": "#/definitions/authorizationCode" }
},
"definitions": {
"implicit": {
"type": "object",
"required": [ "loginEndpoint" ],
"properties": {
"loginEndpoint": { "$ref": "#/definitions/loginEndpoint" },
"tokenName": { "type": "string" }
},
"additionalProperties": false
},
"authorizationCode": {
"type": "object",
"required": [ "tokenEndpoint", "tokenRequestEndpoint" ],
"properties": {
"tokenEndpoint": { "$ref": "#/definitions/tokenEndpoint" },
"tokenRequestEndpoint": { "$ref": "#/definitions/tokenRequestEndpoint" }
},
"additionalProperties": false
},
"loginEndpoint": {
"type": "object",
"required": [ "url" ],
"properties": {
"url": { "type": "string", "format": "uri" }
},
"additionalProperties": false
},
"tokenEndpoint": {
"type": "object",
"required": [ "url" ],
"properties": {
"url": { "type": "string", "format": "uri" },
"tokenName": { "type": "string" }
},
"additionalProperties": false
},
"tokenRequestEndpoint": {
"type": "object",
"required": [ "url" ],
"properties": {
"url": { "type": "string", "format": "uri" },
"clientIdName": { "type": "string" },
"clientSecretName": { "type": "string" }
},
"additionalProperties": false
}
}
}
================================================
FILE: _archive_/schemas/v1.2/operationObject.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/operationObject.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"allOf": [
{ "$ref": "dataTypeBase.json#" },
{
"required": [ "method", "nickname", "parameters" ],
"properties": {
"method": { "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" ] },
"summary": { "type": "string" },
"notes": { "type": "string" },
"nickname": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$"
},
"authorizations": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "authorizationObject.json#/definitions/oauth2Scope"
}
}
},
"parameters": {
"type": "array",
"items": { "$ref": "parameterObject.json#" }
},
"responseMessages": {
"type": "array",
"items": { "$ref": "#/definitions/responseMessageObject"}
},
"produces": { "$ref": "#/definitions/mimeTypeArray" },
"consumes": { "$ref": "#/definitions/mimeTypeArray" },
"deprecated": { "enum": [ "true", "false" ] }
}
}
],
"definitions": {
"responseMessageObject": {
"type": "object",
"required": [ "code", "message" ],
"properties": {
"code": { "$ref": "#/definitions/rfc2616section10" },
"message": { "type": "string" },
"responseModel": { "type": "string" }
}
},
"rfc2616section10": {
"type": "integer",
"minimum": 100,
"maximum": 600,
"exclusiveMaximum": true
},
"mimeTypeArray": {
"type": "array",
"items": {
"type": "string",
"format": "mime-type"
},
"uniqueItems": true
}
}
}
================================================
FILE: _archive_/schemas/v1.2/parameterObject.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/parameterObject.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"allOf": [
{ "$ref": "dataTypeBase.json#" },
{
"required": [ "paramType", "name" ],
"properties": {
"paramType": {
"enum": [ "path", "query", "body", "header", "form" ]
},
"name": { "type": "string" },
"description": { "type": "string" },
"required": { "type": "boolean" },
"allowMultiple": { "type": "boolean" }
}
},
{
"description": "type File requires special paramType and consumes",
"oneOf": [
{
"properties": {
"type": { "not": { "enum": [ "File" ] } }
}
},
{
"properties": {
"type": { "enum": [ "File" ] },
"paramType": { "enum": [ "form" ] },
"consumes": { "enum": [ "multipart/form-data" ] }
}
}
]
}
]
}
================================================
FILE: _archive_/schemas/v1.2/resourceListing.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceListing.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [ "swaggerVersion", "apis" ],
"properties": {
"swaggerVersion": { "enum": [ "1.2" ] },
"apis": {
"type": "array",
"items": { "$ref": "resourceObject.json#" }
},
"apiVersion": { "type": "string" },
"info": { "$ref": "infoObject.json#" },
"authorizations": { "$ref": "authorizationObject.json#" }
}
}
================================================
FILE: _archive_/schemas/v1.2/resourceObject.json
================================================
{
"id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceObject.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [ "path" ],
"properties": {
"path": { "type": "string", "format": "uri" },
"description": { "type": "string" }
},
"additionalProperties": false
}
================================================
FILE: _archive_/schemas/v2.0/README.md
================================================
# OpenAPI Specification v2.0 JSON Schema
This is the JSON Schema file for the OpenAPI Specification version 2.0. Download and install it via NPM.
## Install via NPM
```shell
npm install --save swagger-schema-official
```
## License
Apache-2.0
================================================
FILE: _archive_/schemas/v2.0/schema.json
================================================
{
"title": "A JSON Schema for Swagger 2.0 API.",
"id": "http://swagger.io/v2/schema.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [
"swagger",
"info",
"paths"
],
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"swagger": {
"type": "string",
"enum": [
"2.0"
],
"description": "The Swagger version of this document."
},
"info": {
"$ref": "#/definitions/info"
},
"host": {
"type": "string",
"pattern": "^[^{}/ :\\\\]+(?::\\d+)?$",
"description": "The host (name or ip) of the API. Example: 'swagger.io'"
},
"basePath": {
"type": "string",
"pattern": "^/",
"description": "The base path to the API. Example: '/api'."
},
"schemes": {
"$ref": "#/definitions/schemesList"
},
"consumes": {
"description": "A list of MIME types accepted by the API.",
"allOf": [
{
"$ref": "#/definitions/mediaTypeList"
}
]
},
"produces": {
"description": "A list of MIME types the API can produce.",
"allOf": [
{
"$ref": "#/definitions/mediaTypeList"
}
]
},
"paths": {
"$ref": "#/definitions/paths"
},
"definitions": {
"$ref": "#/definitions/definitions"
},
"parameters": {
"$ref": "#/definitions/parameterDefinitions"
},
"responses": {
"$ref": "#/definitions/responseDefinitions"
},
"security": {
"$ref": "#/definitions/security"
},
"securityDefinitions": {
"$ref": "#/definitions/securityDefinitions"
},
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/tag"
},
"uniqueItems": true
},
"externalDocs": {
"$ref": "#/definitions/externalDocs"
}
},
"definitions": {
"info": {
"type": "object",
"description": "General information about the API.",
"required": [
"version",
"title"
],
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"title": {
"type": "string",
"description": "A unique and precise title of the API."
},
"version": {
"type": "string",
"description": "A semantic version number of the API."
},
"description": {
"type": "string",
"description": "A longer description of the API. Should be different from the title. GitHub Flavored Markdown is allowed."
},
"termsOfService": {
"type": "string",
"description": "The terms of service for the API."
},
"contact": {
"$ref": "#/definitions/contact"
},
"license": {
"$ref": "#/definitions/license"
}
}
},
"contact": {
"type": "object",
"description": "Contact information for the owners of the API.",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The identifying name of the contact person/organization."
},
"url": {
"type": "string",
"description": "The URL pointing to the contact information.",
"format": "uri"
},
"email": {
"type": "string",
"description": "The email address of the contact person/organization.",
"format": "email"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"license": {
"type": "object",
"required": [
"name"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The name of the license type. It's encouraged to use an OSI compatible license."
},
"url": {
"type": "string",
"description": "The URL pointing to the license.",
"format": "uri"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"paths": {
"type": "object",
"description": "Relative paths to the individual endpoints. They must be relative to the 'basePath'.",
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
},
"^/": {
"$ref": "#/definitions/pathItem"
}
},
"additionalProperties": false
},
"definitions": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/schema"
},
"description": "One or more JSON objects describing the schemas being consumed and produced by the API."
},
"parameterDefinitions": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/parameter"
},
"description": "One or more JSON representations for parameters"
},
"responseDefinitions": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/response"
},
"description": "One or more JSON representations for responses"
},
"externalDocs": {
"type": "object",
"additionalProperties": false,
"description": "information about external documentation",
"required": [
"url"
],
"properties": {
"description": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"examples": {
"type": "object",
"additionalProperties": true
},
"mimeType": {
"type": "string",
"description": "The MIME type of the HTTP message."
},
"operation": {
"type": "object",
"required": [
"responses"
],
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"summary": {
"type": "string",
"description": "A brief summary of the operation."
},
"description": {
"type": "string",
"description": "A longer description of the operation, GitHub Flavored Markdown is allowed."
},
"externalDocs": {
"$ref": "#/definitions/externalDocs"
},
"operationId": {
"type": "string",
"description": "A unique identifier of the operation."
},
"produces": {
"description": "A list of MIME types the API can produce.",
"allOf": [
{
"$ref": "#/definitions/mediaTypeList"
}
]
},
"consumes": {
"description": "A list of MIME types the API can consume.",
"allOf": [
{
"$ref": "#/definitions/mediaTypeList"
}
]
},
"parameters": {
"$ref": "#/definitions/parametersList"
},
"responses": {
"$ref": "#/definitions/responses"
},
"schemes": {
"$ref": "#/definitions/schemesList"
},
"deprecated": {
"type": "boolean",
"default": false
},
"security": {
"$ref": "#/definitions/security"
}
}
},
"pathItem": {
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"$ref": {
"type": "string"
},
"get": {
"$ref": "#/definitions/operation"
},
"put": {
"$ref": "#/definitions/operation"
},
"post": {
"$ref": "#/definitions/operation"
},
"delete": {
"$ref": "#/definitions/operation"
},
"options": {
"$ref": "#/definitions/operation"
},
"head": {
"$ref": "#/definitions/operation"
},
"patch": {
"$ref": "#/definitions/operation"
},
"parameters": {
"$ref": "#/definitions/parametersList"
}
}
},
"responses": {
"type": "object",
"description": "Response objects names can either be any valid HTTP status code or 'default'.",
"minProperties": 1,
"additionalProperties": false,
"patternProperties": {
"^([0-9]{3})$|^(default)$": {
"$ref": "#/definitions/responseValue"
},
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"not": {
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
}
},
"responseValue": {
"oneOf": [
{
"$ref": "#/definitions/response"
},
{
"$ref": "#/definitions/jsonReference"
}
]
},
"response": {
"type": "object",
"required": [
"description"
],
"properties": {
"description": {
"type": "string"
},
"schema": {
"oneOf": [
{
"$ref": "#/definitions/schema"
},
{
"$ref": "#/definitions/fileSchema"
}
]
},
"headers": {
"$ref": "#/definitions/headers"
},
"examples": {
"$ref": "#/definitions/examples"
}
},
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"headers": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/header"
}
},
"header": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"string",
"number",
"integer",
"boolean",
"array"
]
},
"format": {
"type": "string"
},
"items": {
"$ref": "#/definitions/primitivesItems"
},
"collectionFormat": {
"$ref": "#/definitions/collectionFormat"
},
"default": {
"$ref": "#/definitions/default"
},
"maximum": {
"$ref": "#/definitions/maximum"
},
"exclusiveMaximum": {
"$ref": "#/definitions/exclusiveMaximum"
},
"minimum": {
"$ref": "#/definitions/minimum"
},
"exclusiveMinimum": {
"$ref": "#/definitions/exclusiveMinimum"
},
"maxLength": {
"$ref": "#/definitions/maxLength"
},
"minLength": {
"$ref": "#/definitions/minLength"
},
"pattern": {
"$ref": "#/definitions/pattern"
},
"maxItems": {
"$ref": "#/definitions/maxItems"
},
"minItems": {
"$ref": "#/definitions/minItems"
},
"uniqueItems": {
"$ref": "#/definitions/uniqueItems"
},
"enum": {
"$ref": "#/definitions/enum"
},
"multipleOf": {
"$ref": "#/definitions/multipleOf"
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"vendorExtension": {
"description": "Any property starting with x- is valid.",
"additionalProperties": true,
"additionalItems": true
},
"bodyParameter": {
"type": "object",
"required": [
"name",
"in",
"schema"
],
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"description": {
"type": "string",
"description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed."
},
"name": {
"type": "string",
"description": "The name of the parameter."
},
"in": {
"type": "string",
"description": "Determines the location of the parameter.",
"enum": [
"body"
]
},
"required": {
"type": "boolean",
"description": "Determines whether or not this parameter is required or optional.",
"default": false
},
"schema": {
"$ref": "#/definitions/schema"
}
},
"additionalProperties": false
},
"headerParameterSubSchema": {
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"required": {
"type": "boolean",
"description": "Determines whether or not this parameter is required or optional.",
"default": false
},
"in": {
"type": "string",
"description": "Determines the location of the parameter.",
"enum": [
"header"
]
},
"description": {
"type": "string",
"description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed."
},
"name": {
"type": "string",
"description": "The name of the parameter."
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"boolean",
"integer",
"array"
]
},
"format": {
"type": "string"
},
"items": {
"$ref": "#/definitions/primitivesItems"
},
"collectionFormat": {
"$ref": "#/definitions/collectionFormat"
},
"default": {
"$ref": "#/definitions/default"
},
"maximum": {
"$ref": "#/definitions/maximum"
},
"exclusiveMaximum": {
"$ref": "#/definitions/exclusiveMaximum"
},
"minimum": {
"$ref": "#/definitions/minimum"
},
"exclusiveMinimum": {
"$ref": "#/definitions/exclusiveMinimum"
},
"maxLength": {
"$ref": "#/definitions/maxLength"
},
"minLength": {
"$ref": "#/definitions/minLength"
},
"pattern": {
"$ref": "#/definitions/pattern"
},
"maxItems": {
"$ref": "#/definitions/maxItems"
},
"minItems": {
"$ref": "#/definitions/minItems"
},
"uniqueItems": {
"$ref": "#/definitions/uniqueItems"
},
"enum": {
"$ref": "#/definitions/enum"
},
"multipleOf": {
"$ref": "#/definitions/multipleOf"
}
}
},
"queryParameterSubSchema": {
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"required": {
"type": "boolean",
"description": "Determines whether or not this parameter is required or optional.",
"default": false
},
"in": {
"type": "string",
"description": "Determines the location of the parameter.",
"enum": [
"query"
]
},
"description": {
"type": "string",
"description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed."
},
"name": {
"type": "string",
"description": "The name of the parameter."
},
"allowEmptyValue": {
"type": "boolean",
"default": false,
"description": "allows sending a parameter by name only or with an empty value."
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"boolean",
"integer",
"array"
]
},
"format": {
"type": "string"
},
"items": {
"$ref": "#/definitions/primitivesItems"
},
"collectionFormat": {
"$ref": "#/definitions/collectionFormatWithMulti"
},
"default": {
"$ref": "#/definitions/default"
},
"maximum": {
"$ref": "#/definitions/maximum"
},
"exclusiveMaximum": {
"$ref": "#/definitions/exclusiveMaximum"
},
"minimum": {
"$ref": "#/definitions/minimum"
},
"exclusiveMinimum": {
"$ref": "#/definitions/exclusiveMinimum"
},
"maxLength": {
"$ref": "#/definitions/maxLength"
},
"minLength": {
"$ref": "#/definitions/minLength"
},
"pattern": {
"$ref": "#/definitions/pattern"
},
"maxItems": {
"$ref": "#/definitions/maxItems"
},
"minItems": {
"$ref": "#/definitions/minItems"
},
"uniqueItems": {
"$ref": "#/definitions/uniqueItems"
},
"enum": {
"$ref": "#/definitions/enum"
},
"multipleOf": {
"$ref": "#/definitions/multipleOf"
}
}
},
"formDataParameterSubSchema": {
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"required": {
"type": "boolean",
"description": "Determines whether or not this parameter is required or optional.",
"default": false
},
"in": {
"type": "string",
"description": "Determines the location of the parameter.",
"enum": [
"formData"
]
},
"description": {
"type": "string",
"description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed."
},
"name": {
"type": "string",
"description": "The name of the parameter."
},
"allowEmptyValue": {
"type": "boolean",
"default": false,
"description": "allows sending a parameter by name only or with an empty value."
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"boolean",
"integer",
"array",
"file"
]
},
"format": {
"type": "string"
},
"items": {
"$ref": "#/definitions/primitivesItems"
},
"collectionFormat": {
"$ref": "#/definitions/collectionFormatWithMulti"
},
"default": {
"$ref": "#/definitions/default"
},
"maximum": {
"$ref": "#/definitions/maximum"
},
"exclusiveMaximum": {
"$ref": "#/definitions/exclusiveMaximum"
},
"minimum": {
"$ref": "#/definitions/minimum"
},
"exclusiveMinimum": {
"$ref": "#/definitions/exclusiveMinimum"
},
"maxLength": {
"$ref": "#/definitions/maxLength"
},
"minLength": {
"$ref": "#/definitions/minLength"
},
"pattern": {
"$ref": "#/definitions/pattern"
},
"maxItems": {
"$ref": "#/definitions/maxItems"
},
"minItems": {
"$ref": "#/definitions/minItems"
},
"uniqueItems": {
"$ref": "#/definitions/uniqueItems"
},
"enum": {
"$ref": "#/definitions/enum"
},
"multipleOf": {
"$ref": "#/definitions/multipleOf"
}
}
},
"pathParameterSubSchema": {
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"required": [
"required"
],
"properties": {
"required": {
"type": "boolean",
"enum": [
true
],
"description": "Determines whether or not this parameter is required or optional."
},
"in": {
"type": "string",
"description": "Determines the location of the parameter.",
"enum": [
"path"
]
},
"description": {
"type": "string",
"description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed."
},
"name": {
"type": "string",
"description": "The name of the parameter."
},
"type": {
"type": "string",
"enum": [
"string",
"number",
"boolean",
"integer",
"array"
]
},
"format": {
"type": "string"
},
"items": {
"$ref": "#/definitions/primitivesItems"
},
"collectionFormat": {
"$ref": "#/definitions/collectionFormat"
},
"default": {
"$ref": "#/definitions/default"
},
"maximum": {
"$ref": "#/definitions/maximum"
},
"exclusiveMaximum": {
"$ref": "#/definitions/exclusiveMaximum"
},
"minimum": {
"$ref": "#/definitions/minimum"
},
"exclusiveMinimum": {
"$ref": "#/definitions/exclusiveMinimum"
},
"maxLength": {
"$ref": "#/definitions/maxLength"
},
"minLength": {
"$ref": "#/definitions/minLength"
},
"pattern": {
"$ref": "#/definitions/pattern"
},
"maxItems": {
"$ref": "#/definitions/maxItems"
},
"minItems": {
"$ref": "#/definitions/minItems"
},
"uniqueItems": {
"$ref": "#/definitions/uniqueItems"
},
"enum": {
"$ref": "#/definitions/enum"
},
"multipleOf": {
"$ref": "#/definitions/multipleOf"
}
}
},
"nonBodyParameter": {
"type": "object",
"required": [
"name",
"in",
"type"
],
"oneOf": [
{
"$ref": "#/definitions/headerParameterSubSchema"
},
{
"$ref": "#/definitions/formDataParameterSubSchema"
},
{
"$ref": "#/definitions/queryParameterSubSchema"
},
{
"$ref": "#/definitions/pathParameterSubSchema"
}
]
},
"parameter": {
"oneOf": [
{
"$ref": "#/definitions/bodyParameter"
},
{
"$ref": "#/definitions/nonBodyParameter"
}
]
},
"schema": {
"type": "object",
"description": "A deterministic version of a JSON Schema object.",
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"properties": {
"$ref": {
"type": "string"
},
"format": {
"type": "string"
},
"title": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/title"
},
"description": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/description"
},
"default": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/default"
},
"multipleOf": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf"
},
"maximum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/maximum"
},
"exclusiveMaximum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum"
},
"minimum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/minimum"
},
"exclusiveMinimum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum"
},
"maxLength": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger"
},
"minLength": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0"
},
"pattern": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/pattern"
},
"maxItems": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger"
},
"minItems": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0"
},
"uniqueItems": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems"
},
"maxProperties": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger"
},
"minProperties": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0"
},
"required": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/stringArray"
},
"enum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/enum"
},
"additionalProperties": {
"anyOf": [
{
"$ref": "#/definitions/schema"
},
{
"type": "boolean"
}
],
"default": {}
},
"type": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/type"
},
"items": {
"anyOf": [
{
"$ref": "#/definitions/schema"
},
{
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/definitions/schema"
}
}
],
"default": {}
},
"allOf": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/definitions/schema"
}
},
"properties": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/schema"
},
"default": {}
},
"discriminator": {
"type": "string"
},
"readOnly": {
"type": "boolean",
"default": false
},
"xml": {
"$ref": "#/definitions/xml"
},
"externalDocs": {
"$ref": "#/definitions/externalDocs"
},
"example": {}
},
"additionalProperties": false
},
"fileSchema": {
"type": "object",
"description": "A deterministic version of a JSON Schema object.",
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"required": [
"type"
],
"properties": {
"format": {
"type": "string"
},
"title": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/title"
},
"description": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/description"
},
"default": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/default"
},
"required": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/stringArray"
},
"type": {
"type": "string",
"enum": [
"file"
]
},
"readOnly": {
"type": "boolean",
"default": false
},
"externalDocs": {
"$ref": "#/definitions/externalDocs"
},
"example": {}
},
"additionalProperties": false
},
"primitivesItems": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"string",
"number",
"integer",
"boolean",
"array"
]
},
"format": {
"type": "string"
},
"items": {
"$ref": "#/definitions/primitivesItems"
},
"collectionFormat": {
"$ref": "#/definitions/collectionFormat"
},
"default": {
"$ref": "#/definitions/default"
},
"maximum": {
"$ref": "#/definitions/maximum"
},
"exclusiveMaximum": {
"$ref": "#/definitions/exclusiveMaximum"
},
"minimum": {
"$ref": "#/definitions/minimum"
},
"exclusiveMinimum": {
"$ref": "#/definitions/exclusiveMinimum"
},
"maxLength": {
"$ref": "#/definitions/maxLength"
},
"minLength": {
"$ref": "#/definitions/minLength"
},
"pattern": {
"$ref": "#/definitions/pattern"
},
"maxItems": {
"$ref": "#/definitions/maxItems"
},
"minItems": {
"$ref": "#/definitions/minItems"
},
"uniqueItems": {
"$ref": "#/definitions/uniqueItems"
},
"enum": {
"$ref": "#/definitions/enum"
},
"multipleOf": {
"$ref": "#/definitions/multipleOf"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"security": {
"type": "array",
"items": {
"$ref": "#/definitions/securityRequirement"
},
"uniqueItems": true
},
"securityRequirement": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
}
},
"xml": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"namespace": {
"type": "string"
},
"prefix": {
"type": "string"
},
"attribute": {
"type": "boolean",
"default": false
},
"wrapped": {
"type": "boolean",
"default": false
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"tag": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"externalDocs": {
"$ref": "#/definitions/externalDocs"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"securityDefinitions": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/definitions/basicAuthenticationSecurity"
},
{
"$ref": "#/definitions/apiKeySecurity"
},
{
"$ref": "#/definitions/oauth2ImplicitSecurity"
},
{
"$ref": "#/definitions/oauth2PasswordSecurity"
},
{
"$ref": "#/definitions/oauth2ApplicationSecurity"
},
{
"$ref": "#/definitions/oauth2AccessCodeSecurity"
}
]
}
},
"basicAuthenticationSecurity": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"basic"
]
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"apiKeySecurity": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"name",
"in"
],
"properties": {
"type": {
"type": "string",
"enum": [
"apiKey"
]
},
"name": {
"type": "string"
},
"in": {
"type": "string",
"enum": [
"header",
"query"
]
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"oauth2ImplicitSecurity": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"flow",
"authorizationUrl"
],
"properties": {
"type": {
"type": "string",
"enum": [
"oauth2"
]
},
"flow": {
"type": "string",
"enum": [
"implicit"
]
},
"scopes": {
"$ref": "#/definitions/oauth2Scopes"
},
"authorizationUrl": {
"type": "string",
"format": "uri"
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"oauth2PasswordSecurity": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"flow",
"tokenUrl"
],
"properties": {
"type": {
"type": "string",
"enum": [
"oauth2"
]
},
"flow": {
"type": "string",
"enum": [
"password"
]
},
"scopes": {
"$ref": "#/definitions/oauth2Scopes"
},
"tokenUrl": {
"type": "string",
"format": "uri"
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"oauth2ApplicationSecurity": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"flow",
"tokenUrl"
],
"properties": {
"type": {
"type": "string",
"enum": [
"oauth2"
]
},
"flow": {
"type": "string",
"enum": [
"application"
]
},
"scopes": {
"$ref": "#/definitions/oauth2Scopes"
},
"tokenUrl": {
"type": "string",
"format": "uri"
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"oauth2AccessCodeSecurity": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"flow",
"authorizationUrl",
"tokenUrl"
],
"properties": {
"type": {
"type": "string",
"enum": [
"oauth2"
]
},
"flow": {
"type": "string",
"enum": [
"accessCode"
]
},
"scopes": {
"$ref": "#/definitions/oauth2Scopes"
},
"authorizationUrl": {
"type": "string",
"format": "uri"
},
"tokenUrl": {
"type": "string",
"format": "uri"
},
"description": {
"type": "string"
}
},
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
}
},
"oauth2Scopes": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"mediaTypeList": {
"type": "array",
"items": {
"$ref": "#/definitions/mimeType"
},
"uniqueItems": true
},
"parametersList": {
"type": "array",
"description": "The parameters needed to send a valid API call.",
"additionalItems": false,
"items": {
"oneOf": [
{
"$ref": "#/definitions/parameter"
},
{
"$ref": "#/definitions/jsonReference"
}
]
},
"uniqueItems": true
},
"schemesList": {
"type": "array",
"description": "The transfer protocol of the API.",
"items": {
"type": "string",
"enum": [
"http",
"https",
"ws",
"wss"
]
},
"uniqueItems": true
},
"collectionFormat": {
"type": "string",
"enum": [
"csv",
"ssv",
"tsv",
"pipes"
],
"default": "csv"
},
"collectionFormatWithMulti": {
"type": "string",
"enum": [
"csv",
"ssv",
"tsv",
"pipes",
"multi"
],
"default": "csv"
},
"title": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/title"
},
"description": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/description"
},
"default": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/default"
},
"multipleOf": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf"
},
"maximum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/maximum"
},
"exclusiveMaximum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum"
},
"minimum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/minimum"
},
"exclusiveMinimum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum"
},
"maxLength": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger"
},
"minLength": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0"
},
"pattern": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/pattern"
},
"maxItems": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger"
},
"minItems": {
"$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0"
},
"uniqueItems": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems"
},
"enum": {
"$ref": "http://json-schema.org/draft-04/schema#/properties/enum"
},
"jsonReference": {
"type": "object",
"required": [
"$ref"
],
"additionalProperties": false,
"properties": {
"$ref": {
"type": "string"
}
}
}
}
}
================================================
FILE: _archive_/schemas/v3.0/README.md
================================================
# OpenAPI 3.0.X JSON Schema
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).
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`.
The source in this directory, which has `WORK-IN-PROGRESS` in its `id`, is _not intended for direct use_.
## Schema `id` dates
The published schemas on the spec site have an _iteration date_ in their `id`s.
This allows the schemas for a release line (in this case 3.0) to be updated independent of the spec patch release cycle.
The iteration version of the JSON Schema can be found in the `id` field.
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.
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.
## Improving the schema
As a reminder, the JSON Schema is not the source of truth for the Specification.
In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins.
Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance.
The schema only validates the mandatory aspects of the OAS.
Validating requirements that are optional, or field usage that has undefined or ignored behavior are not within the scope of this schema.
Schemas to perform additional optional validation are [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4141).
Improvements can be submitted by opening a PR against the `main` branch.
Modify the `schema.yaml` file and add test cases for your changes.
The TSC will then:
- Run tests on the updated schema
- Update the iteration version
- Publish the new version
The [test suite](../../tests/v3.0) is part of this package.
```bash
npm install
npm test
```
================================================
FILE: _archive_/schemas/v3.0/pass/api-with-examples.yaml
================================================
openapi: "3.0.0"
info:
title: Simple API overview
version: 2.0.0
paths:
/:
get:
operationId: listVersionsv2
summary: List API versions
responses:
'200':
description: |-
200 response
content:
application/json:
examples:
foo:
value:
{
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
},
{
"status": "EXPERIMENTAL",
"updated": "2013-07-23T11:33:21Z",
"id": "v3.0",
"links": [
{
"href": "http://127.0.0.1:8774/v3/",
"rel": "self"
}
]
}
]
}
'300':
description: |-
300 response
content:
application/json:
examples:
foo:
value: |
{
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
},
{
"status": "EXPERIMENTAL",
"updated": "2013-07-23T11:33:21Z",
"id": "v3.0",
"links": [
{
"href": "http://127.0.0.1:8774/v3/",
"rel": "self"
}
]
}
]
}
/v2:
get:
operationId: getVersionDetailsv2
summary: Show API version details
responses:
'200':
description: |-
200 response
content:
application/json:
examples:
foo:
value:
{
"version": {
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.compute+xml;version=2"
},
{
"base": "application/json",
"type": "application/vnd.openstack.compute+json;version=2"
}
],
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
},
{
"href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
"type": "application/pdf",
"rel": "describedby"
},
{
"href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
"type": "application/vnd.sun.wadl+xml",
"rel": "describedby"
},
{
"href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
"type": "application/vnd.sun.wadl+xml",
"rel": "describedby"
}
]
}
}
'203':
description: |-
203 response
content:
application/json:
examples:
foo:
value:
{
"version": {
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.compute+xml;version=2"
},
{
"base": "application/json",
"type": "application/vnd.openstack.compute+json;version=2"
}
],
"id": "v2.0",
"links": [
{
"href": "http://23.253.228.211:8774/v2/",
"rel": "self"
},
{
"href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
"type": "application/pdf",
"rel": "describedby"
},
{
"href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
"type": "application/vnd.sun.wadl+xml",
"rel": "describedby"
}
]
}
}
================================================
FILE: _archive_/schemas/v3.0/pass/callback-example.yaml
================================================
openapi: 3.0.0
info:
title: Callback Example
version: 1.0.0
paths:
/streams:
post:
description: subscribes a client to receive out-of-band data
parameters:
- name: callbackUrl
in: query
required: true
description: |
the location where data will be sent. Must be network accessible
by the source server
schema:
type: string
format: uri
example: https://tonys-server.com
responses:
'201':
description: subscription successfully created
content:
application/json:
schema:
description: subscription information
required:
- subscriptionId
properties:
subscriptionId:
description: this unique identifier allows management of the subscription
type: string
example: 2531329f-fb09-4ef7-887e-84e648214436
callbacks:
# the name `onData` is a convenience locator
onData:
# when data is sent, it will be sent to the `callbackUrl` provided
# when making the subscription PLUS the suffix `/data`
'{$request.query.callbackUrl}/data':
post:
requestBody:
description: subscription payload
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
format: date-time
userData:
type: string
responses:
'202':
description: |
Your server implementation should return this HTTP status code
if the data was received successfully
'204':
description: |
Your server should return this HTTP status code if no longer interested
in further updates
================================================
FILE: _archive_/schemas/v3.0/pass/link-example.yaml
================================================
openapi: 3.0.0
info:
title: Link Example
version: 1.0.0
paths:
/2.0/users/{username}:
get:
operationId: getUserByName
parameters:
- name: username
in: path
required: true
schema:
type: string
responses:
'200':
description: The User
content:
application/json:
schema:
$ref: '#/components/schemas/user'
links:
userRepositories:
$ref: '#/components/links/UserRepositories'
/2.0/repositories/{username}:
get:
operationId: getRepositoriesByOwner
parameters:
- name: username
in: path
required: true
schema:
type: string
responses:
'200':
description: repositories owned by the supplied user
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/repository'
links:
userRepository:
$ref: '#/components/links/UserRepository'
/2.0/repositories/{username}/{slug}:
get:
operationId: getRepository
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: slug
in: path
required: true
schema:
type: string
responses:
'200':
description: The repository
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
links:
repositoryPullRequests:
$ref: '#/components/links/RepositoryPullRequests'
/2.0/repositories/{username}/{slug}/pullrequests:
get:
operationId: getPullRequestsByRepository
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: slug
in: path
required: true
schema:
type: string
- name: state
in: query
schema:
type: string
enum:
- open
- merged
- declined
responses:
'200':
description: an array of pull request objects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pullrequest'
/2.0/repositories/{username}/{slug}/pullrequests/{pid}:
get:
operationId: getPullRequestsById
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: slug
in: path
required: true
schema:
type: string
- name: pid
in: path
required: true
schema:
type: string
responses:
'200':
description: a pull request object
content:
application/json:
schema:
$ref: '#/components/schemas/pullrequest'
links:
pullRequestMerge:
$ref: '#/components/links/PullRequestMerge'
/2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge:
post:
operationId: mergePullRequest
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: slug
in: path
required: true
schema:
type: string
- name: pid
in: path
required: true
schema:
type: string
responses:
'204':
description: the PR was successfully merged
components:
links:
UserRepositories:
# returns array of '#/components/schemas/repository'
operationId: getRepositoriesByOwner
parameters:
username: $response.body#/username
UserRepository:
# returns '#/components/schemas/repository'
operationId: getRepository
parameters:
username: $response.body#/owner/username
slug: $response.body#/slug
RepositoryPullRequests:
# returns '#/components/schemas/pullrequest'
operationId: getPullRequestsByRepository
parameters:
username: $response.body#/owner/username
slug: $response.body#/slug
PullRequestMerge:
# executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
operationId: mergePullRequest
parameters:
username: $response.body#/author/username
slug: $response.body#/repository/slug
pid: $response.body#/id
schemas:
user:
type: object
properties:
username:
type: string
uuid:
type: string
repository:
type: object
properties:
slug:
type: string
owner:
$ref: '#/components/schemas/user'
pullrequest:
type: object
properties:
id:
type: integer
title:
type: string
repository:
$ref: '#/components/schemas/repository'
author:
$ref: '#/components/schemas/user'
================================================
FILE: _archive_/schemas/v3.0/pass/petstore-expanded.yaml
================================================
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
termsOfService: http://swagger.io/terms/
contact:
name: Swagger API Team
email: apiteam@swagger.io
url: http://swagger.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://petstore.swagger.io/v2
paths:
/pets:
get:
description: |
Returns all pets from the system that the user has access to
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.
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.
operationId: findPets
parameters:
- name: tags
in: query
description: tags to filter by
required: false
style: form
schema:
type: array
items:
type: string
- name: limit
in: query
description: maximum number of results to return
required: false
schema:
type: integer
format: int32
responses:
'200':
description: pet response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
description: Creates a new pet in the store. Duplicates are allowed
operationId: addPet
requestBody:
description: Pet to add to the store
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewPet'
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/pets/{id}:
get:
description: Returns a user based on a single ID, if the user does not have access to the pet
operationId: find pet by id
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
schema:
type: integer
format: int64
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
description: deletes a single pet based on the ID supplied
operationId: deletePet
parameters:
- name: id
in: path
description: ID of pet to delete
required: true
schema:
type: integer
format: int64
responses:
'204':
description: pet deleted
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Pet:
allOf:
- $ref: '#/components/schemas/NewPet'
- type: object
required:
- id
properties:
id:
type: integer
format: int64
NewPet:
type: object
required:
- name
properties:
name:
type: string
tag:
type: string
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
================================================
FILE: _archive_/schemas/v3.0/pass/petstore.yaml
================================================
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
maximum: 100
format: int32
responses:
'200':
description: A paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
tags:
- pets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'201':
description: Null response
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
maxItems: 100
items:
$ref: "#/components/schemas/Pet"
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
================================================
FILE: _archive_/schemas/v3.0/pass/uspto.yaml
================================================
openapi: 3.0.1
servers:
- url: '{scheme}://developer.uspto.gov/ds-api'
variables:
scheme:
description: 'The Data Set API is accessible via https and http'
enum:
- 'https'
- 'http'
default: 'https'
info:
description: >-
The Data Set API (DSAPI) allows the public users to discover and search
USPTO exported data sets. This is a generic API that allows USPTO users to
make any CSV based data files searchable through API. With the help of GET
call, it returns the list of data fields that are searchable. With the help
of POST call, data can be fetched based on the filters on the field names.
Please note that POST call is used to search the actual data. The reason for
the POST call is that it allows users to specify any complex search criteria
without worry about the GET size limitations as well as encoding of the
input parameters.
version: 1.0.0
title: USPTO Data Set API
contact:
name: Open Data Portal
url: 'https://developer.uspto.gov'
email: developer@uspto.gov
tags:
- name: metadata
description: Find out about the data sets
- name: search
description: Search a data set
paths:
/:
get:
tags:
- metadata
operationId: list-data-sets
summary: List available data sets
responses:
'200':
description: Returns a list of data sets
content:
application/json:
schema:
$ref: '#/components/schemas/dataSetList'
example:
{
"total": 2,
"apis": [
{
"apiKey": "oa_citations",
"apiVersionNumber": "v1",
"apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields",
"apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json"
},
{
"apiKey": "cancer_moonshot",
"apiVersionNumber": "v1",
"apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields",
"apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json"
}
]
}
/{dataset}/{version}/fields:
get:
tags:
- metadata
summary: >-
Provides the general information about the API and the list of fields
that can be used to query the dataset.
description: >-
This GET API returns the list of all the searchable field names that are
in the oa_citations. Please see the 'fields' attribute which returns an
array of field names. Each field or a combination of fields can be
searched using the syntax options shown below.
operationId: list-searchable-fields
parameters:
- name: dataset
in: path
description: 'Name of the dataset.'
required: true
example: "oa_citations"
schema:
type: string
- name: version
in: path
description: Version of the dataset.
required: true
example: "v1"
schema:
type: string
responses:
'200':
description: >-
The dataset API for the given version is found and it is accessible
to consume.
content:
application/json:
schema:
type: string
'404':
description: >-
The combination of dataset name and version is not found in the
system or it is not published yet to be consumed by public.
content:
application/json:
schema:
type: string
/{dataset}/{version}/records:
post:
tags:
- search
summary: >-
Provides search capability for the data set with the given search
criteria.
description: >-
This API is based on Solr/Lucene Search. The data is indexed using
SOLR. This GET API returns the list of all the searchable field names
that are in the Solr Index. Please see the 'fields' attribute which
returns an array of field names. Each field or a combination of fields
can be searched using the Solr/Lucene Syntax. Please refer
https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for
the query syntax. List of field names that are searchable can be
determined using above GET api.
operationId: perform-search
parameters:
- name: version
in: path
description: Version of the dataset.
required: true
schema:
type: string
default: v1
- name: dataset
in: path
description: 'Name of the dataset. In this case, the default value is oa_citations'
required: true
schema:
type: string
default: oa_citations
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties:
type: object
'404':
description: No matching record found for the given criteria.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
criteria:
description: >-
Uses Lucene Query Syntax in the format of
propertyName:value, propertyName:[num1 TO num2] and date
range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the
response please see the 'docs' element which has the list of
record objects. Each record structure would consist of all
the fields and their corresponding values.
type: string
default: '*:*'
start:
description: Starting record number. Default value is 0.
type: integer
default: 0
rows:
description: >-
Specify number of rows to be returned. If you run the search
with default values, in the response you will see 'numFound'
attribute which will tell the number of records available in
the dataset.
type: integer
default: 100
required:
- criteria
components:
schemas:
dataSetList:
type: object
properties:
total:
type: integer
apis:
type: array
items:
type: object
properties:
apiKey:
type: string
description: To be used as a dataset parameter value
apiVersionNumber:
type: string
description: To be used as a version parameter value
apiUrl:
type: string
format: uriref
description: "The URL describing the dataset's fields"
apiDocumentationUrl:
type: string
format: uriref
description: A URL to the API console for each API
================================================
FILE: _archive_/schemas/v3.0/schema.test.mjs
================================================
import { readdirSync, readFileSync } from "node:fs";
import YAML from "yaml";
import { validate, setMetaSchemaOutputFormat } from "@hyperjump/json-schema/openapi-3-0";
import { BASIC } from "@hyperjump/json-schema/experimental";
import { describe, test, expect } from "vitest";
import contentTypeParser from "content-type";
import { addMediaTypePlugin } from "@hyperjump/browser";
import { buildSchemaDocument } from "@hyperjump/json-schema/experimental";
addMediaTypePlugin("application/schema+yaml", {
parse: async (response) => {
const contentType = contentTypeParser.parse(response.headers.get("content-type") ?? "");
const contextDialectId = contentType.parameters.schema ?? contentType.parameters.profile;
const foo = YAML.parse(await response.text());
return buildSchemaDocument(foo, response.url, contextDialectId);
},
fileMatcher: (path) => path.endsWith(".yaml")
});
const parseYamlFromFile = (filePath) => {
const schemaYaml = readFileSync(filePath, "utf8");
return YAML.parse(schemaYaml, { prettyErrors: true });
};
setMetaSchemaOutputFormat(BASIC);
const validateOpenApi = await validate("./_archive_/schemas/v3.0/schema.yaml");
const folder = './_archive_/schemas/v3.0/pass/';
describe("pass", async () => {
readdirSync(folder, { withFileTypes: true })
.filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name))
.forEach((entry) => {
test(entry.name, () => {
const instance = parseYamlFromFile(folder + entry.name);
const output = validateOpenApi(instance, BASIC);
expect(output.valid).to.equal(true);
});
});
});
================================================
FILE: _archive_/schemas/v3.0/schema.yaml
================================================
id: https://spec.openapis.org/oas/3.0/schema/WORK-IN-PROGRESS
$schema: http://json-schema.org/draft-04/schema#
description: The description of OpenAPI v3.0.x Documents
type: object
required:
- openapi
- info
- paths
properties:
openapi:
type: string
pattern: ^3\.0\.\d(-.+)?$
info:
$ref: '#/definitions/Info'
externalDocs:
$ref: '#/definitions/ExternalDocumentation'
servers:
type: array
items:
$ref: '#/definitions/Server'
security:
type: array
items:
$ref: '#/definitions/SecurityRequirement'
tags:
type: array
items:
$ref: '#/definitions/Tag'
uniqueItems: true
paths:
$ref: '#/definitions/Paths'
components:
$ref: '#/definitions/Components'
patternProperties:
'^x-': {}
additionalProperties: false
definitions:
Reference:
type: object
required:
- $ref
patternProperties:
'^\$ref$':
type: string
format: uri-reference
Info:
type: object
required:
- title
- version
properties:
title:
type: string
description:
type: string
termsOfService:
type: string
format: uri-reference
contact:
$ref: '#/definitions/Contact'
license:
$ref: '#/definitions/License'
version:
type: string
patternProperties:
'^x-': {}
additionalProperties: false
Contact:
type: object
properties:
name:
type: string
url:
type: string
format: uri-reference
email:
type: string
format: email
patternProperties:
'^x-': {}
additionalProperties: false
License:
type: object
required:
- name
properties:
name:
type: string
url:
type: string
format: uri-reference
patternProperties:
'^x-': {}
additionalProperties: false
Server:
type: object
required:
- url
properties:
url:
type: string
description:
type: string
variables:
type: object
additionalProperties:
$ref: '#/definitions/ServerVariable'
patternProperties:
'^x-': {}
additionalProperties: false
ServerVariable:
type: object
required:
- default
properties:
enum:
type: array
items:
type: string
default:
type: string
description:
type: string
patternProperties:
'^x-': {}
additionalProperties: false
Components:
type: object
properties:
schemas:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
responses:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/Response'
parameters:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/Parameter'
examples:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/Example'
requestBodies:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/RequestBody'
headers:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/Header'
securitySchemes:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/SecurityScheme'
links:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/Link'
callbacks:
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
oneOf:
- $ref: '#/definitions/Reference'
- $ref: '#/definitions/Callback'
patternProperties:
'^x-': {}
additionalProperties: false
Schema:
type: object
properties:
title:
type: string
multipleOf:
type: number
minimum: 0
exclusiveMinimum: true
maximum:
type: number
exclusiveMaximum:
type: boolean
default: false
minimum:
type: number
exclusiveMinimum:
type: boolean
default: false
maxLength:
type: integer
minimum: 0
minLength:
type: integer
minimum: 0
default: 0
pattern:
type: string
format: regex
maxItems:
type: integer
minimum: 0
minItems:
type: integer
minimum: 0
default: 0
uniqueItems:
type: boolean
default: false
maxProperties:
type: integer
minimum: 0
minProperties:
type: integer
minimum: 0
default: 0
required:
type: array
items:
type: string
minItems: 1
uniqueItems: true
enum:
type: array
items: {}
minItems: 1
uniqueItems: false
type:
type: string
enum:
- array
- boolean
- integer
- number
- object
- string
not:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
allOf:
type: array
items:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
oneOf:
type: array
items:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
anyOf:
type: array
items:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
items:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
properties:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
additionalProperties:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
- type: boolean
default: true
description:
type: string
format:
type: string
default: {}
nullable:
type: boolean
default: false
discriminator:
$ref: '#/definitions/Discriminator'
readOnly:
type: boolean
default: false
writeOnly:
type: boolean
default: false
example: {}
externalDocs:
$ref: '#/definitions/ExternalDocumentation'
deprecated:
type: boolean
default: false
xml:
$ref: '#/definitions/XML'
patternProperties:
'^x-': {}
additionalProperties: false
Discriminator:
type: object
required:
- propertyName
properties:
propertyName:
type: string
mapping:
type: object
additionalProperties:
type: string
XML:
type: object
properties:
name:
type: string
namespace:
type: string
format: uri
prefix:
type: string
attribute:
type: boolean
default: false
wrapped:
type: boolean
default: false
patternProperties:
'^x-': {}
additionalProperties: false
Response:
type: object
required:
- description
properties:
description:
type: string
headers:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Header'
- $ref: '#/definitions/Reference'
content:
type: object
additionalProperties:
$ref: '#/definitions/MediaType'
links:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Link'
- $ref: '#/definitions/Reference'
patternProperties:
'^x-': {}
additionalProperties: false
MediaType:
type: object
properties:
schema:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
example: {}
examples:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Example'
- $ref: '#/definitions/Reference'
encoding:
type: object
additionalProperties:
$ref: '#/definitions/Encoding'
patternProperties:
'^x-': {}
additionalProperties: false
allOf:
- $ref: '#/definitions/ExampleXORExamples'
Example:
type: object
properties:
summary:
type: string
description:
type: string
value: {}
externalValue:
type: string
format: uri-reference
patternProperties:
'^x-': {}
additionalProperties: false
Header:
type: object
properties:
description:
type: string
required:
type: boolean
default: false
deprecated:
type: boolean
default: false
allowEmptyValue:
type: boolean
default: false
style:
type: string
enum:
- simple
default: simple
explode:
type: boolean
allowReserved:
type: boolean
default: false
schema:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
content:
type: object
additionalProperties:
$ref: '#/definitions/MediaType'
minProperties: 1
maxProperties: 1
example: {}
examples:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Example'
- $ref: '#/definitions/Reference'
patternProperties:
'^x-': {}
additionalProperties: false
allOf:
- $ref: '#/definitions/ExampleXORExamples'
- $ref: '#/definitions/SchemaXORContent'
Paths:
type: object
patternProperties:
'^\/':
$ref: '#/definitions/PathItem'
'^x-': {}
additionalProperties: false
PathItem:
type: object
properties:
$ref:
type: string
summary:
type: string
description:
type: string
get:
$ref: '#/definitions/Operation'
put:
$ref: '#/definitions/Operation'
post:
$ref: '#/definitions/Operation'
delete:
$ref: '#/definitions/Operation'
options:
$ref: '#/definitions/Operation'
head:
$ref: '#/definitions/Operation'
patch:
$ref: '#/definitions/Operation'
trace:
$ref: '#/definitions/Operation'
servers:
type: array
items:
$ref: '#/definitions/Server'
parameters:
type: array
items:
oneOf:
- $ref: '#/definitions/Parameter'
- $ref: '#/definitions/Reference'
uniqueItems: true
patternProperties:
'^x-': {}
additionalProperties: false
Operation:
type: object
required:
- responses
properties:
tags:
type: array
items:
type: string
summary:
type: string
description:
type: string
externalDocs:
$ref: '#/definitions/ExternalDocumentation'
operationId:
type: string
parameters:
type: array
items:
oneOf:
- $ref: '#/definitions/Parameter'
- $ref: '#/definitions/Reference'
uniqueItems: true
requestBody:
oneOf:
- $ref: '#/definitions/RequestBody'
- $ref: '#/definitions/Reference'
responses:
$ref: '#/definitions/Responses'
callbacks:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Callback'
- $ref: '#/definitions/Reference'
deprecated:
type: boolean
default: false
security:
type: array
items:
$ref: '#/definitions/SecurityRequirement'
servers:
type: array
items:
$ref: '#/definitions/Server'
patternProperties:
'^x-': {}
additionalProperties: false
Responses:
type: object
properties:
default:
oneOf:
- $ref: '#/definitions/Response'
- $ref: '#/definitions/Reference'
patternProperties:
'^[1-5](?:\d{2}|XX)$':
oneOf:
- $ref: '#/definitions/Response'
- $ref: '#/definitions/Reference'
'^x-': {}
minProperties: 1
additionalProperties: false
SecurityRequirement:
type: object
additionalProperties:
type: array
items:
type: string
Tag:
type: object
required:
- name
properties:
name:
type: string
description:
type: string
externalDocs:
$ref: '#/definitions/ExternalDocumentation'
patternProperties:
'^x-': {}
additionalProperties: false
ExternalDocumentation:
type: object
required:
- url
properties:
description:
type: string
url:
type: string
format: uri-reference
patternProperties:
'^x-': {}
additionalProperties: false
ExampleXORExamples:
description: Example and examples are mutually exclusive
not:
required: [example, examples]
SchemaXORContent:
description: Schema and content are mutually exclusive, at least one is required
not:
required: [schema, content]
oneOf:
- required: [schema]
- required: [content]
description: Some properties are not allowed if content is present
allOf:
- not:
required: [style]
- not:
required: [explode]
- not:
required: [allowReserved]
- not:
required: [example]
- not:
required: [examples]
Parameter:
type: object
properties:
name:
type: string
in:
type: string
description:
type: string
required:
type: boolean
default: false
deprecated:
type: boolean
default: false
allowEmptyValue:
type: boolean
default: false
style:
type: string
explode:
type: boolean
allowReserved:
type: boolean
default: false
schema:
oneOf:
- $ref: '#/definitions/Schema'
- $ref: '#/definitions/Reference'
content:
type: object
additionalProperties:
$ref: '#/definitions/MediaType'
minProperties: 1
maxProperties: 1
example: {}
examples:
type: object
additionalProperties:
oneOf:
- $ref: '#/definitions/Example'
- $ref: '#/definitions/Reference'
patternProperties:
'^x-': {}
additionalProperties: false
required:
- name
- in
allOf:
- $ref: '#/definitions/ExampleXORExamples'
- $ref: '#/definitions/SchemaXORContent'
oneOf:
- $ref: '#/definitions/PathParameter'
- $ref: '#/definitions/QueryParameter'
- $ref: '#/definitions/HeaderParameter'
- $ref: '#/definitions/CookieParameter'
PathParameter:
description: Parameter in path
required:
- required
properties:
in:
enum: [path]
style:
enum: [matrix, label, simple]
default: simple
required:
enum: [true]
QueryParameter:
description: Parameter in query
properties:
in:
enum: [query]
style:
enum: [form, spaceDelimited, pipeDelimited, deepObject]
default: form
HeaderParameter:
description: Parameter in header
properties:
in:
enum: [header]
style:
enum: [simple]
default: simple
CookieParameter:
description: Parameter in cookie
properties:
in:
enum: [cookie]
style:
enum: [form]
default: form
RequestBody:
type: object
required:
- content
properties:
description:
type: string
content:
type: object
additionalProperties:
$ref: '#/definitions/MediaType'
required:
type: boolean
default: false
patternProperties:
'^x-': {}
additionalProperties: false
SecurityScheme:
oneOf:
- $ref: '#/definitions/APIKeySecurityScheme'
- $ref: '#/definitions/HTTPSecurityScheme'
- $ref: '#/definitions/OAuth2SecurityScheme'
- $ref: '#/definitions/OpenIdConnectSecurityScheme'
APIKeySecurityScheme:
type: object
required:
- type
- name
- in
properties:
type:
type: string
enum:
- apiKey
name:
type: string
in:
type: string
enum:
- header
- query
- cookie
description:
type: string
patternProperties:
'^x-': {}
additionalProperties: false
HTTPSecurityScheme:
type: object
required:
- scheme
- type
properties:
scheme:
type: string
bearerFormat:
type: string
description:
type: string
type:
type: string
enum:
- http
patternProperties:
'^x-': {}
additionalProperties: false
oneOf:
- description: Bearer
properties:
scheme:
type: string
pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$
- description: Non Bearer
not:
required: [bearerFormat]
properties:
scheme:
not:
type: string
pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$
OAuth2SecurityScheme:
type: object
required:
- type
- flows
properties:
type:
type: string
enum:
- oauth2
flows:
$ref: '#/definitions/OAuthFlows'
description:
type: string
patternProperties:
'^x-': {}
additionalProperties: false
OpenIdConnectSecurityScheme:
type: object
required:
- type
- openIdConnectUrl
properties:
type:
type: string
enum:
- openIdConnect
openIdConnectUrl:
type: string
format: uri-reference
description:
type: string
patternProperties:
'^x-': {}
additionalProperties: false
OAuthFlows:
type: object
properties:
implicit:
$ref: '#/definitions/ImplicitOAuthFlow'
password:
$ref: '#/definitions/PasswordOAuthFlow'
clientCredentials:
$ref: '#/definitions/ClientCredentialsFlow'
authorizationCode:
$ref: '#/definitions/AuthorizationCodeOAuthFlow'
patternProperties:
'^x-': {}
additionalProperties: false
ImplicitOAuthFlow:
type: object
required:
- authorizationUrl
- scopes
properties:
authorizationUrl:
type: string
format: uri-
gitextract_xldvqxs9/ ├── .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 ├── .linkspector.yml ├── .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.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 │ ├── start-release.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 │ └── schema/ │ └── oas-schema.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 │ ├── 3.1.2-editors.md │ ├── 3.1.2.md │ ├── 3.2.0-editors.md │ └── 3.2.0.md └── vitest.config.mjs
SYMBOL INDEX (4 symbols across 2 files)
FILE: scripts/md2html/md2html.js
function preface (line 172) | function preface(title,options) {
function doMaintainers (line 257) | function doMaintainers() {
function getPublishDate (line 274) | function getPublishDate(m) {
FILE: tests/md2html/md2html.test.mjs
function md2html (line 31) | function md2html(args, cwd) {
Condensed preview — 124 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (2,138K chars).
[
{
"path": ".gitattributes",
"chars": 25,
"preview": "*.md linguist-detectable\n"
},
{
"path": ".github/CODEOWNERS",
"chars": 222,
"preview": "# Global Repo Owners\n* @oai/openapi-maintainers @oai/tsc\n\n# Specification Versions\n/versions/ @oai/tsc\n\n# Protect specif"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"chars": 860,
"preview": "blank_issues_enabled: false\n\ncontact_links:\n - name: Have a question about using OpenAPI?\n url: https://communityinv"
},
{
"path": ".github/ISSUE_TEMPLATE/registry_feature_request.md",
"chars": 1051,
"preview": "---\nname: Contribute to the registries at spec.openapis.org/registry\nabout: Add a new registry entry, or edit an existin"
},
{
"path": ".github/ISSUE_TEMPLATE/spec_bug_report.md",
"chars": 524,
"preview": "---\nname: Report an error in the specification\nabout: Create a report to help us improve the specification\ntitle: 'vX.Y:"
},
{
"path": ".github/dependabot.yml",
"chars": 328,
"preview": "version: 2\nupdates:\n - package-ecosystem: github-actions\n directory: \"/\"\n schedule:\n interval: daily\n ope"
},
{
"path": ".github/pull_request_template.md",
"chars": 755,
"preview": "<!--\nThank you for contributing to the OpenAPI Specification!\n\nPlease make certain you are submitting your PR on the cor"
},
{
"path": ".github/templates/agenda.md",
"chars": 2531,
"preview": "## Weekly meetings happen on Thursdays at 9am - 10am Pacific\n\nThis agenda gives visibility into discussion topics for th"
},
{
"path": ".github/workflows/agenda.yaml",
"chars": 2327,
"preview": "name: agenda\n\n# author: @MikeRalphson\n# issue: various\n\n#\n# This workflow creates the agenda issue each week. It runs on"
},
{
"path": ".github/workflows/check-restricted-files.yaml",
"chars": 1998,
"preview": "name: check-restricted-files\n\n# Author: @ralfhandl\n# Issue: https://github.com/OAI/OpenAPI-Specification/issues/3432\n\n# "
},
{
"path": ".github/workflows/inactive-issues.yml",
"chars": 1150,
"preview": "on:\n issues:\n types: labeled\n workflow_dispatch:\n schedule:\n - cron: '*/5 * * * *'\n\npermissions:\n issues: writ"
},
{
"path": ".github/workflows/respec.yaml",
"chars": 2121,
"preview": "name: respec\n\n# author: @MikeRalphson, @ralfhandl\n# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564\n\n#\n#"
},
{
"path": ".github/workflows/schema-publish.yaml",
"chars": 2233,
"preview": "name: schema-publish\n\n# author: @ralfhandl\n# issue: https://github.com/OAI/OpenAPI-Specification/issues/3715\n\n#\n# This w"
},
{
"path": ".github/workflows/schema-tests.yaml",
"chars": 758,
"preview": "name: schema-test\n\n# Author: @MikeRalphson / runs @jdesrosiers tests\n# Issue: https://github.com/OAI/OpenAPI-Specificati"
},
{
"path": ".github/workflows/sync-dev-to-vX.Y-dev.yaml",
"chars": 2404,
"preview": "name: sync-dev-to-vX.Y-dev\n\n# author: @ralfhandl\n\n#\n# This workflow creates PRs to update the vX.Y-dev branch with the l"
},
{
"path": ".github/workflows/sync-main-to-dev.yaml",
"chars": 1955,
"preview": "name: sync-main-to-dev\n\n# author: @ralfhandl\n\n#\n# This workflow creates PRs to update the dev branch with the latest cha"
},
{
"path": ".github/workflows/validate-markdown.yaml",
"chars": 984,
"preview": "name: validate-markdown\n\n# Author: @MikeRalphson\n# Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130\n\n# Th"
},
{
"path": ".gitignore",
"chars": 124,
"preview": ".idea\n*.iml\n*.ipr\n*.iws\ntarget\natlassian-ide-plugin.xml\nnode_modules/\ndeploy/\ndeploy-preview/\ncoverage/\n_site/\nGemfile.l"
},
{
"path": ".gitmodules",
"chars": 0,
"preview": ""
},
{
"path": ".linkspector.yml",
"chars": 298,
"preview": "files:\n - src/oas.md\n - CONTRIBUTING.md\n - EDITORS.md\n - GOVERNANCE.md\n - IMPLEMENTATIONS.md\n - MAINTAINERS.md\n -"
},
{
"path": ".markdownlint.yaml",
"chars": 525,
"preview": "# First heading is a top-level heading\nMD002: true\n\n# Heading style (ATX is leading # symbols)\nMD003:\n style: atx\n\n# Un"
},
{
"path": "CONTRIBUTING.md",
"chars": 29366,
"preview": "# Contribute to the OpenAPI Specification\n\n## Key information\n\nThis project is covered by our [Code of Conduct](https://"
},
{
"path": "EDITORS.md",
"chars": 928,
"preview": "# OpenAPI Specification Editors\n\n## Active\n\n* Henry Andrews [@handrews](https://github.com/handrews)\n* Jeremy Whitlock ["
},
{
"path": "GOVERNANCE.md",
"chars": 3590,
"preview": "# Governance\n\nThe OpenAPI Specification is a project of the OpenAPI Initiative (OAI), under the auspices of the Linux Fo"
},
{
"path": "IMPLEMENTATIONS.md",
"chars": 319,
"preview": "# Implementations\n\nThe list of implementations formerly in this file is no-longer maintained here.\n\nYou may find a more "
},
{
"path": "LICENSE",
"chars": 11345,
"preview": " Apache License\n Version 2.0, January 2004\n "
},
{
"path": "MAINTAINERS.md",
"chars": 773,
"preview": "# OpenAPI Initiative Technical Steering Committee Members\n\n## Active\n\n* Jeremy Whitlock [@whitlockjc](https://github.com"
},
{
"path": "README.md",
"chars": 5464,
"preview": "# The OpenAPI Specification\n\n![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/ba"
},
{
"path": "SECURITY_CONSIDERATIONS.md",
"chars": 2034,
"preview": "# Security Considerations\n\n## OpenAPI Document Formats\n\nOpenAPI documents use JSON, YAML, and JSON Schema, and therefore"
},
{
"path": "SPECIAL_INTEREST_GROUPS.md",
"chars": 600,
"preview": "# OpenAPI Special Interest Groups (SIGs)\n\nOpenAPI Special Interest Groups, or \"SIGs\", are the OpenAPI Initiative's way o"
},
{
"path": "TOB.md",
"chars": 529,
"preview": "# Technical Oversight Board (\"TOB\")\n\n## Description\n\n> The TOB is responsible for managing conflicts, violations of proc"
},
{
"path": "_archive_/README.md",
"chars": 78,
"preview": "# Archive\n\nThis folder contains files that are no longer actively maintained.\n"
},
{
"path": "_archive_/schemas/README.md",
"chars": 450,
"preview": "# Archive of outdated JSON Schema Files\n\n> [!TIP]\n> JSON Schema files for validating OpenAPI descriptions using current "
},
{
"path": "_archive_/schemas/v1.2/README.md",
"chars": 325,
"preview": "# Swagger Specification JSON Schemas\n\nThe work on the JSON Schema for the Swagger Specification was donated to the commu"
},
{
"path": "_archive_/schemas/v1.2/apiDeclaration.json",
"chars": 1934,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/apiDeclaration.json#\",\n "
},
{
"path": "_archive_/schemas/v1.2/authorizationObject.json",
"chars": 1817,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/authorizationObject.json#\","
},
{
"path": "_archive_/schemas/v1.2/dataType.json",
"chars": 4552,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataType.json#\",\n \"$sche"
},
{
"path": "_archive_/schemas/v1.2/dataTypeBase.json",
"chars": 2586,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataTypeBase.json#\",\n \"$"
},
{
"path": "_archive_/schemas/v1.2/infoObject.json",
"chars": 661,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/infoObject.json#\",\n \"$sc"
},
{
"path": "_archive_/schemas/v1.2/modelsObject.json",
"chars": 1008,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/modelsObject.json#\",\n \"$"
},
{
"path": "_archive_/schemas/v1.2/oauth2GrantType.json",
"chars": 2036,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/oauth2GrantType.json#\",\n "
},
{
"path": "_archive_/schemas/v1.2/operationObject.json",
"chars": 2341,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/operationObject.json#\",\n "
},
{
"path": "_archive_/schemas/v1.2/parameterObject.json",
"chars": 1286,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/parameterObject.json#\",\n "
},
{
"path": "_archive_/schemas/v1.2/resourceListing.json",
"chars": 592,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceListing.json#\",\n "
},
{
"path": "_archive_/schemas/v1.2/resourceObject.json",
"chars": 385,
"preview": "{\n \"id\": \"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceObject.json#\",\n "
},
{
"path": "_archive_/schemas/v2.0/README.md",
"chars": 248,
"preview": "# OpenAPI Specification v2.0 JSON Schema\n\nThis is the JSON Schema file for the OpenAPI Specification version 2.0. Downlo"
},
{
"path": "_archive_/schemas/v2.0/schema.json",
"chars": 40247,
"preview": "{\n \"title\": \"A JSON Schema for Swagger 2.0 API.\",\n \"id\": \"http://swagger.io/v2/schema.json#\",\n \"$schema\": \"http://jso"
},
{
"path": "_archive_/schemas/v3.0/README.md",
"chars": 2164,
"preview": "# OpenAPI 3.0.X JSON Schema\n\nThis directory contains the YAML source for generating the JSON Schema for validating OpenA"
},
{
"path": "_archive_/schemas/v3.0/pass/api-with-examples.yaml",
"chars": 6444,
"preview": "openapi: \"3.0.0\"\ninfo:\n title: Simple API overview\n version: 2.0.0\npaths:\n /:\n get:\n operationId: listVersion"
},
{
"path": "_archive_/schemas/v3.0/pass/callback-example.yaml",
"chars": 2158,
"preview": "openapi: 3.0.0\ninfo:\n title: Callback Example\n version: 1.0.0\npaths:\n /streams:\n post:\n description: subscrib"
},
{
"path": "_archive_/schemas/v3.0/pass/link-example.yaml",
"chars": 5280,
"preview": "openapi: 3.0.0\ninfo: \n title: Link Example\n version: 1.0.0\npaths: \n /2.0/users/{username}: \n get: \n operation"
},
{
"path": "_archive_/schemas/v3.0/pass/petstore-expanded.yaml",
"chars": 5479,
"preview": "openapi: \"3.0.0\"\ninfo:\n version: 1.0.0\n title: Swagger Petstore\n description: A sample API that uses a petstore as an"
},
{
"path": "_archive_/schemas/v3.0/pass/petstore.yaml",
"chars": 2772,
"preview": "openapi: \"3.0.0\"\ninfo:\n version: 1.0.0\n title: Swagger Petstore\n license:\n name: MIT\nservers:\n - url: http://pets"
},
{
"path": "_archive_/schemas/v3.0/pass/uspto.yaml",
"chars": 7743,
"preview": "openapi: 3.0.1\nservers:\n - url: '{scheme}://developer.uspto.gov/ds-api'\n variables:\n scheme:\n descriptio"
},
{
"path": "_archive_/schemas/v3.0/schema.test.mjs",
"chars": 1689,
"preview": "import { readdirSync, readFileSync } from \"node:fs\";\nimport YAML from \"yaml\";\nimport { validate, setMetaSchemaOutputForm"
},
{
"path": "_archive_/schemas/v3.0/schema.yaml",
"chars": 22645,
"preview": "id: https://spec.openapis.org/oas/3.0/schema/WORK-IN-PROGRESS\n$schema: http://json-schema.org/draft-04/schema#\ndescripti"
},
{
"path": "package.json",
"chars": 1397,
"preview": "{\n \"name\": \"oas-infra\",\n \"version\": \"0.0.0\",\n \"description\": \"OpenAPI Specification Automation & Infrastructure\",\n \""
},
{
"path": "proposals/2019-01-01-Proposal-Template.md",
"chars": 2299,
"preview": "# Feature name\n\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[YYYY-MM-DD-Short-Name](https://github"
},
{
"path": "proposals/2019-03-15-Alternative-Schema.md",
"chars": 4032,
"preview": "# Alternative Schema\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[Alternative Schema](https://gith"
},
{
"path": "proposals/2019-07-17-Webhooks.md",
"chars": 10834,
"preview": "# Webhooks\n\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[2019-07-17-Webhooks](https://github.com/O"
},
{
"path": "proposals/2019-10-31-Clarify-Nullable.md",
"chars": 16797,
"preview": "# Clarify Semantics of `nullable` in OpenAPI 3.0\n\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[201"
},
{
"path": "proposals/2019-12-24-Overlays.md",
"chars": 10075,
"preview": "# Overlays\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[2019-12-24-Overlays](https://github.com/OA"
},
{
"path": "proposals/2020-10-28-Experimental.md",
"chars": 6672,
"preview": "# Experimental marker\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[Experimental](https://github.co"
},
{
"path": "proposals/2024-08-01-Self-Identification.md",
"chars": 9113,
"preview": "# Self-Identification\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[2024-08-01 Self-Identification]"
},
{
"path": "proposals/2024-09-01-Tags-Improvement.md",
"chars": 8830,
"preview": "# Tags Improvement\n\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[2024-09-01-Tags-Improvement](http"
},
{
"path": "proposals/2025-03-20-URIs-for-Tags.md",
"chars": 9345,
"preview": "# URIs for Tags\n\n\n## Metadata\n\n|Tag |Value |\n|---- | ---------------- |\n|Proposal |[2025-03-20-URIs-for-Tags](https://gi"
},
{
"path": "proposals/Alternative-Schema/CONTRIBUTORS.md",
"chars": 120,
"preview": "* Chuck Heazel [@cmheazel](https://github.com/cmheazel)\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)"
},
{
"path": "proposals/Alternative-Schema/alternative_schema_object.md",
"chars": 915,
"preview": "## Change: Add the Alternative Schema Object\n\nThe following text is to be inserted after the XML Object section\n\n### Alt"
},
{
"path": "proposals/Alternative-Schema/examples.md",
"chars": 1387,
"preview": "## Change: Add Alternative Schema Examples\n\nThe following text is to be inserted after the Alternative Schema Object sec"
},
{
"path": "proposals/Alternative-Schema/implementations.md",
"chars": 1556,
"preview": "# Implementations\n\n## Overview\n\nBelow is a list of tooling that claims to implement the Alternative Schema proposal. Whi"
},
{
"path": "proposals/Alternative-Schema/schema_object.md",
"chars": 2727,
"preview": "## Change: Extend the Schema Object to support Alternative Schemas\n\nThe following content shall be used to replace the F"
},
{
"path": "proposals/Overlays/Changes.yml",
"chars": 1767,
"preview": "# Create update methods (add,replace,merge,delete)? Is merge necessary?\n# Multiple additions or updates to the same targ"
},
{
"path": "proposals/Overlays/MergePatch.yml",
"chars": 169,
"preview": "overlay: 1.0.0\ninfo:\n title: An example of an overlay that performs a Merge Patch\n version: 1.0.0\nupdates:\n- target: \""
},
{
"path": "scripts/adjust-release-branch.sh",
"chars": 981,
"preview": "#!/usr/bin/env bash\n\n# Author: @ralfhandl\n\n# Run this script from the root of the repo. It is designed to be run manuall"
},
{
"path": "scripts/close-no-recent.ps1",
"chars": 1537,
"preview": "$inactivityDelay = [timespan]::FromDays([int]::Parse($Env:NO_RECENT_ACTIVITY_DURATION_CLOSE_IN_DAYS))\n$oldIssues = gh is"
},
{
"path": "scripts/fwdabort.sh",
"chars": 135,
"preview": "#!/bin/sh\n\n# Aborts a fwdport.sh run cleanly\n\n# Author: @MikeRalphson\n\ngit am -i --abort\nrm -f *.mbox *.patch *.rej\ngit "
},
{
"path": "scripts/fwdport.sh",
"chars": 2872,
"preview": "#!/bin/sh\n\n# Forward ports changes from the spec file of a source branch to the spec file of a target branch\n# For examp"
},
{
"path": "scripts/label-no-recent.ps1",
"chars": 1683,
"preview": "$inactivityDelay = [timespan]::FromDays([int]::Parse($Env:NO_RECENT_ACTIVITY_DURATION_IN_DAYS))\n$oldIssues = gh issue li"
},
{
"path": "scripts/md2html/.gitignore",
"chars": 15,
"preview": "*.err\ninput.bs\n"
},
{
"path": "scripts/md2html/analytics/google.html",
"chars": 307,
"preview": "<!-- Global site tag (gtag.js) - Google Analytics -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=UA-"
},
{
"path": "scripts/md2html/build.sh",
"chars": 2623,
"preview": "#!/bin/bash\n\n# Author: @MikeRalphson\n\n# run this script from the root of the repo\n# It is designed to be run by a GitHub"
},
{
"path": "scripts/md2html/gist.css",
"chars": 955,
"preview": "/**\n * GitHub Gist Theme\n * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro\n */\n\n.hljs {\n display: b"
},
{
"path": "scripts/md2html/main.css",
"chars": 5085,
"preview": "#respec-ui {\n visibility: hidden;\n}\n\n#title {\n color: #578000;\n}\n\n#subtitle {\n color: #578000;\n}\n\n.dt-published"
},
{
"path": "scripts/md2html/md2html.js",
"chars": 20051,
"preview": "/* ReSpec supports markdown formatting, but this shows up on the page before being rendered\nHence we render the markdown"
},
{
"path": "scripts/md2html/style-finish.html",
"chars": 9,
"preview": "</style>\n"
},
{
"path": "scripts/md2html/style-start.html",
"chars": 355,
"preview": "<style>\n/*.highlight:not(.idl) { background: hsl(24, 20%, 95%); }\ncode.highlight { padding: .1em; border-radius: .3em; }"
},
{
"path": "scripts/md2html/syntax-github.css",
"chars": 1148,
"preview": "/*\n\ngithub.com style (c) Vasily Polovnyov <vast@whiteants.net>\n\n*/\n\n.hljs {\n display: block;\n overflow-x: auto;\n padd"
},
{
"path": "scripts/schema-publish.sh",
"chars": 2940,
"preview": "#!/usr/bin/env bash\n\n# Author: @ralfhandl\n\n# Run this script from the root of the repo. It is designed to be run by a Gi"
},
{
"path": "scripts/start-release.sh",
"chars": 3804,
"preview": "#!/usr/bin/env bash\n\n# Author: @ralfhandl\n\n# Run this script from the root of the repo. It is designed to be run manuall"
},
{
"path": "scripts/validate.mjs",
"chars": 2041,
"preview": "#!/usr/bin/env node\n\nimport { readFile } from \"node:fs/promises\";\nimport YAML from \"yaml\";\nimport { setMetaSchemaOutputF"
},
{
"path": "spec.markdownlint.yaml",
"chars": 432,
"preview": "# Heading style (ATX is leading # symbols)\nMD003:\n style: atx\n\n# Unordered list symbol must be *\nMD004:\n style: asteri"
},
{
"path": "style-guide.md",
"chars": 3337,
"preview": "# Style Guide\n\nContributions to this repository should follow the style guide as described in this section.\n\n## Markdown"
},
{
"path": "tests/md2html/README.md",
"chars": 208,
"preview": "To view the HTML files in folder `fixtures` with respec formatting, you can\n~~~sh\nmkdir js\ncp ../../node_modules/respec/"
},
{
"path": "tests/md2html/fixtures/.gitattributes",
"chars": 18,
"preview": "*.html text eol=lf"
},
{
"path": "tests/md2html/fixtures/basic-new.html",
"chars": 17031,
"preview": "<!DOCTYPE html><html lang=\"en\"><head>\n<!-- Global site tag (gtag.js) - Google Analytics -->\n<script async src=\"https://w"
},
{
"path": "tests/md2html/fixtures/basic-new.maintainers",
"chars": 240,
"preview": "# Editors\n\n## Active\n* John Doe [@johndoe](https://github.com/johndoe)\n* Jane Doe [@janedow](https://github.com/janedoe)"
},
{
"path": "tests/md2html/fixtures/basic-new.md",
"chars": 2097,
"preview": "# Heading 1\n\nText for first chapter\n\n## Version 30.0.1\n\nThis is the conformance section\n\n## Heading 2\n\nText for <a name="
},
{
"path": "tests/md2html/fixtures/basic-old.html",
"chars": 9543,
"preview": "<!DOCTYPE html><html lang=\"en\"><head>\n<!-- Global site tag (gtag.js) - Google Analytics -->\n<script async src=\"https://w"
},
{
"path": "tests/md2html/fixtures/basic-old.maintainers",
"chars": 57,
"preview": "## Active\n* Foo Bar [@foobar](https://github.com/foobar)\n"
},
{
"path": "tests/md2html/fixtures/basic-old.md",
"chars": 319,
"preview": "# Heading 1\n\nText for first chapter\n\n#### Version 30.0.1\n\nThis is the conformance section\n\n## Table of Contents\n\nWill be"
},
{
"path": "tests/md2html/md2html.test.mjs",
"chars": 1275,
"preview": "import { readdirSync, readFileSync } from \"node:fs\";\nimport { execFile } from \"node:child_process\";\nimport { resolve } f"
},
{
"path": "tests/schema/oas-schema.mjs",
"chars": 1067,
"preview": "import { registerSchema } from \"@hyperjump/json-schema/draft-2020-12\";\nimport { defineVocabulary } from \"@hyperjump/json"
},
{
"path": "versions/1.2.md",
"chars": 49578,
"preview": "# Swagger RESTful API Documentation Specification\n\n#### Version 1.2\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHAL"
},
{
"path": "versions/2.0-editors.md",
"chars": 237,
"preview": "## Active\n* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)\n* Marsh Gardiner [@earth2marsh](https://github."
},
{
"path": "versions/2.0.md",
"chars": 80697,
"preview": "# OpenAPI Specification\n## (fka Swagger RESTful API Documentation Specification)\n\n#### Version 2.0\n\nThe key words \"MUST\""
},
{
"path": "versions/3.0.0-editors.md",
"chars": 302,
"preview": "## Active\n* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)\n* Marsh Gardiner [@earth2marsh](https://github."
},
{
"path": "versions/3.0.0.md",
"chars": 123368,
"preview": "# OpenAPI Specification\n\n#### Version 3.0.0\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD"
},
{
"path": "versions/3.0.1-editors.md",
"chars": 367,
"preview": "## Active\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)\n* Jeremy Whitlock [@whitlockjc](https://githu"
},
{
"path": "versions/3.0.1.md",
"chars": 121673,
"preview": "# OpenAPI Specification\n\n#### Version 3.0.1\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD"
},
{
"path": "versions/3.0.2-editors.md",
"chars": 481,
"preview": "## Active\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)\n* Jeremy Whitlock [@whitlockjc](https://githu"
},
{
"path": "versions/3.0.2.md",
"chars": 122440,
"preview": "# OpenAPI Specification\n\n#### Version 3.0.2\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD"
},
{
"path": "versions/3.0.3-editors.md",
"chars": 481,
"preview": "## Active\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)\n* Jeremy Whitlock [@whitlockjc](https://githu"
},
{
"path": "versions/3.0.3.md",
"chars": 125198,
"preview": "# OpenAPI Specification\n\n#### Version 3.0.3\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD"
},
{
"path": "versions/3.0.4-editors.md",
"chars": 802,
"preview": "# OpenAPI Specification Editors\n\n## Active\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)\n* Henry Andr"
},
{
"path": "versions/3.0.4.md",
"chars": 194942,
"preview": "# OpenAPI Specification\n\n## Version 3.0.4\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\","
},
{
"path": "versions/3.1.0-editors.md",
"chars": 481,
"preview": "## Active\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)\n* Jeremy Whitlock [@whitlockjc](https://githu"
},
{
"path": "versions/3.1.0.md",
"chars": 130284,
"preview": "# OpenAPI Specification\n\n#### Version 3.1.0\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD"
},
{
"path": "versions/3.1.1-editors.md",
"chars": 802,
"preview": "# OpenAPI Specification Editors\n\n## Active\n* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)\n* Henry Andr"
},
{
"path": "versions/3.1.1.md",
"chars": 212529,
"preview": "# OpenAPI Specification\n\n## Version 3.1.1\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\","
},
{
"path": "versions/3.1.2-editors.md",
"chars": 928,
"preview": "# OpenAPI Specification Editors\n\n## Active\n\n* Henry Andrews [@handrews](https://github.com/handrews)\n* Jeremy Whitlock ["
},
{
"path": "versions/3.1.2.md",
"chars": 221878,
"preview": "# OpenAPI Specification\n\n## Version 3.1.2\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\","
},
{
"path": "versions/3.2.0-editors.md",
"chars": 928,
"preview": "# OpenAPI Specification Editors\n\n## Active\n\n* Henry Andrews [@handrews](https://github.com/handrews)\n* Jeremy Whitlock ["
},
{
"path": "versions/3.2.0.md",
"chars": 296246,
"preview": "# OpenAPI Specification\n\n## Version 3.2.0\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\","
},
{
"path": "vitest.config.mjs",
"chars": 766,
"preview": "import { defineConfig } from 'vitest/config'\nimport { jsonSchemaCoveragePlugin } from \"@hyperjump/json-schema-coverage/v"
}
]
About this extraction
This page contains the full source code of the OAI/OpenAPI-Specification GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 124 files (2.0 MB), approximately 490.6k tokens, and a symbol index with 4 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.