Showing preview only (327K chars total). Download the full file or copy to clipboard to get everything.
Repository: OAI/Arazzo-Specification
Branch: main
Commit: 1abe8cba3860
Files: 48
Total size: 310.6 KB
Directory structure:
gitextract_s0wd0_vf/
├── .github/
│ ├── CODEOWNERS
│ ├── ISSUE_TEMPLATE/
│ │ └── use-case-template.yml
│ ├── dependabot.yml
│ ├── templates/
│ │ └── agenda.md
│ └── workflows/
│ ├── auto-merge-dependabot.yml
│ ├── respec.yaml
│ ├── schema-publish.yaml
│ ├── schema-tests.yaml
│ └── validate-markdown.yaml
├── .gitignore
├── .markdownlint.yaml
├── CONTRIBUTING.md
├── LICENSE
├── MAINTAINERS.md
├── README.md
├── SPECIAL_INTEREST_GROUP.md
├── _archive_/
│ └── schemas/
│ └── v1.0/
│ ├── readme.md
│ ├── schema.json
│ └── schema.yaml
├── examples/
│ └── 1.0.0/
│ ├── ExtendedParametersExample.arazzo.yaml
│ ├── FAPI-PAR.arazzo.yaml
│ ├── FAPI-PAR.openapi.yaml
│ ├── LoginAndRetrievePets.arazzo.yaml
│ ├── README.md
│ ├── bnpl-arazzo.yaml
│ ├── bnpl-openapi.yaml
│ ├── oauth.arazzo.yaml
│ ├── oauth.openapi.yaml
│ ├── pet-coupons.arazzo.yaml
│ └── pet-coupons.openapi.yaml
├── package.json
├── scripts/
│ ├── md2html/
│ │ ├── .gitignore
│ │ ├── analytics/
│ │ │ └── google.html
│ │ ├── build.sh
│ │ ├── gist.css
│ │ ├── main.css
│ │ ├── md2html.js
│ │ ├── style-finish.html
│ │ ├── style-start.html
│ │ └── syntax-github.css
│ ├── schema-publish.sh
│ ├── schema-test-coverage.mjs
│ ├── schema-test-coverage.sh
│ ├── validate.mjs
│ └── yaml2json/
│ └── yaml2json.js
├── spec.markdownlint.yaml
└── versions/
├── 1.0.0.md
└── 1.0.1.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/CODEOWNERS
================================================
* @OAI/arazzo-maintainers
================================================
FILE: .github/ISSUE_TEMPLATE/use-case-template.yml
================================================
name: "Workflow-SIG Usecase Create Form"
description: "Request form to describe a Workflow-SIG use case. Inorder to create a comprehensive solution Please provide a brief title, description, and fill out the details below and we'll get back to you ASAP."
title: "[Workflow-SIG Usecases, draft version]: "
labels: use-case
assignees: @OAI/sig-workflows-admins
-
body:
- type: markdown
attributes:
value: Thank you for contributing to the OAI work-flow SIG, please use this issue form to describe use cases in your industry.
- type: input
id: contact
attributes:
label: Contact Details
description: Please share the name(s) / handle(s) so we can followup with any additional questions comments.
validations:
required: true
- type: textarea
id: Title
attributes:
label: Give your usecase a unique name so we may refer to it in discussions
description: Each usecase needs a unique name starting with "USECASE-"
validations:
required: true
- type: textarea
id: description
attributes:
label: Give an overview of your use case.
description: A brief description that outlines your usecase.
validations:
required: true
- type: textarea
id: Industry
attributes:
label: Industry
description: Let us know if this is an industry specific usecase and any specific circumstances such as regulations that restrict the use case.
validations:
required: true
- type: textarea
id: Documentation
attributes:
label: Documentation
description: Share any existing documention, examples, or any other materials that will help the SIG understand the requirements.
validations:
required: false
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/OAI/Arazzo-Specification?tab=coc-ov-file#code-of-conduct)
options:
- label: I agree to follow this project's Code of Conduct
required: true
================================================
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/templates/agenda.md
================================================
## Bi-Weekly meetings happen on Wednesdays at 5PM GMT
This agenda gives visibility into discussion topics for the bi-weekly Arazzo Specification 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.us/j/91426197903](https://zoom.us/j/91426197903?pwd=cjNGcjgzWmRqZ1YyRW9PM3FFNFVFUT09), dial-in passcode: 763054
### Accessibility & Etiquette
* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/Arazzo-Specification?tab=coc-ov-file#code-of-conduct).
* 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/OAI/OpenAPI-Specification/assets/7367/f991722f-4651-40aa-9bc4-7e9a2a165a6a"> |
### Agenda Structure
| Topic | Owner | Decision/NextStep |
|-|-|-|
Intros and governance meta-topics (5 mins) | TDC / Arazzo maintainers | |
Any other business (add comments below to suggest topics) | TDC / Arazzo maintainers | |
[Approved spec PRs](https://github.com/OAI/Arazzo-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | Arazzo maintainers| |
[Active Projects](https://github.com/OAI/Arazzo-Specification/projects?query=is%3Aopen) | Arazzo maintainers | |
[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Farazzo-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | Arazzo maintainers | |
/cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.
================================================
FILE: .github/workflows/auto-merge-dependabot.yml
================================================
name: Auto-merge dependabot updates
on:
pull_request:
branches: [ main ]
permissions:
pull-requests: write
contents: write
jobs:
dependabot-merge:
runs-on: ubuntu-latest
if: ${{ github.actor == 'dependabot[bot]' }}
steps:
- name: Dependabot metadata
id: metadata
uses: dependabot/fetch-metadata@v3.0.0
with:
github-token: "${{ secrets.GITHUB_TOKEN }}"
- name: Enable auto-merge for Dependabot PRs
# Only if version bump is not a major version change
if: ${{steps.metadata.outputs.update-type != 'version-update:semver-major'}}
run: gh pr merge --auto --merge "$PR_URL"
env:
PR_URL: ${{github.event.pull_request.html_url}}
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
================================================
FILE: .github/workflows/respec.yaml
================================================
name: respec
# author: @frankkilcommins (inspired by work from @MikeRalphson)
#
# This workflow creates a pull request for publishing HTML spec versions to the spec.openapis.org site.
#
# run this on push to main with changes to files in the versions folder
on:
push:
paths:
- "versions/**"
branches:
- main
workflow_dispatch: {}
jobs:
respec:
runs-on: ubuntu-22.04
steps:
- name: Generate access token
id: generate-token
uses: actions/create-github-app-token@v3
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: arazzo-spec-version
base: main
delete-branch: true
path: deploy
labels: Arazzo,Specification
reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,whitlockjc,handrews,karenetheridge,frankkilcommins
title: Arazzo - 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`.
The `versions/*.md` files of the Arazzo Specification have changed and the corresponding HTML files are regenerated.
================================================
FILE: .github/workflows/schema-publish.yaml
================================================
name: schema-publish
# author: @ralfhandl, @frankkilcommins
#
# 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"
- "scripts/schema-publish.sh"
- ".github/workflows/schema-publish.yaml"
workflow_dispatch: {}
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Generate access token
id: generate-token
uses: actions/create-github-app-token@v3
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: arazzo-${{ github.ref_name }}-schema-iterations
base: main
delete-branch: true
path: deploy
labels: Arazzo,Schema
reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,whitlockjc,handrews,karenetheridge,frankkilcommins
title: "Arazzo - publish ${{ github.ref_name }} schema iterations"
commit-message: "New Arazzo schema iterations published from ${{ github.ref_name }}"
signoff: true
body: |
This pull request is automatically generated by GitHub action `schema-publish` in the OAI/Arazzo-Specification repo.
The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated.
================================================
FILE: .github/workflows/schema-tests.yaml
================================================
name: schema-tests
# 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:
push: {}
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 from main
run: npm ci
- name: Run tests
run: npm run test
================================================
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/arazzo.md with slightly different rules.
#
# run this on push to any branch and creation of pull-requests
on: [push, pull_request]
jobs:
mdv:
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: Lint work-in-progress spec
run: npx --yes markdownlint-cli2 --config spec.markdownlint.yaml src/arazzo.md
- name: Lint other files
run: npx --yes markdownlint-cli2 *.md
================================================
FILE: .gitignore
================================================
.vscode/settings.json
.idea
*.iml
*.ipr
*.iws
target
atlassian-ide-plugin.xml
node_modules/
deploy/
deploy-preview/
history
Gemfile.lock
coverage/
================================================
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 Arazzo Specification
We welcome contributions and discussion.
Bug reports and feature requests are welcome, please add an issue explaining your use case.
Pull requests are also welcome, but it is recommended to create an issue first, to allow discussion.
Questions and comments are also welcome - use the GitHub Discussions feature.
You will also find notes from past meetings in the Discussion tab.
## 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 documents 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/arazzo.md` on the appropriately-versioned branch.
For example, work on the next release for 1.1 is on `v1.1-dev` in the file `src/arazzo.md`.
The [spec site](https://spec.openapis.org) is the source of truth for the Arazzo specification as it contains all the citations and author credits.
The OpenAPI project (which Arazzo sits under) 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 |
| ------- | ------ | ----- |
| 1.0.2 | `v1.0-dev` | active patch release line |
| 1.1.0 | `v1.1-dev` | minor release in development |
## Pull Requests
Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start.
Pull requests MUST come from a fork; create a fresh branch on your fork based on the target branch for your change.
### Branching Strategy
Overview of branches:
- `main` holds the published versions of the specification, utility scripts and supporting documentation.
- `dev` is for development infrastructure and other changes that apply to multiple versions of development.
- Branches named `vX.Y-dev` are the active development branches for future releases.
- Branches name `vX.Y.Z-rel` are release branches (including when Z == 0). They exist primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links.
> All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance.
## Release Process and Scope
### Minor Releases
Our roadmap for Arazzo releases is community-driven, meaning the specification is open for proposed additions by anyone.
Changes in minor releases (such as 1.1) 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 Arazzo is used by practitioners, so that Arazzo 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.
- 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 Arazzo.
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.
## 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) and join the `#arazzo` channel.
- Start a [GitHub Discussion](https://github.com/OAI/Arazzo-Specification/discussions/).
- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/Arazzo-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHouse-keeping).
## Appendix
### Build the HTML version to publish
We use ReSpec to render the markdown specification as HTML for publishing and easier reading.
These instructions explain how you can build the HTML locally.
You will need NodeJS 18 or later.
Install dependencies:
```sh
npm install
```
Produce stand-alone HTML files in the local `deploy/arazzo` folder:
```sh
npm run build
```
Note that Linux users may need to add `--no-sandbox` to run `npx respec` as found in the `scripts/md2html/build.sh` file.
================================================
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 [yyyy] [name of copyright owner]
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
================================================
# Arazzo Specification Maintainers
## Active
* Frank Kilcommins [@frankkilcommins](https://github.com/frankkilcommins)
* Nick Denny [@ndenny](https://github.com/ndenny)
* Kevin Duffey [@kevinduffey](https://github.com/kevinduffey)
================================================
FILE: README.md
================================================
# The Arazzo Specification
The Arazzo Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
The Arazzo Specification defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI descriptions).
The Arazzo Specification can articulate these workflows in a deterministic human-readable and machine-readable manner, thus improving provider and consumer experiences when working with APIs. Similar to what OpenAPI has done for describing HTTP interfaces, the Arazzo Specification enables the ability to articulate the functional use cases offered by an API (or group of APIs) thus removing the guesswork for both human and machine consumers.
Use cases for machine-readable API workflow definition documents include, but are not limited to:
- interactive _living_ workflow documentation
- automated documentation generation (e.g. Developer Portal documentation)
- code and SDK generation driven by functional use cases
- automation of test cases
- automated regulatory compliance checks
- deterministic API invocation by AI-based LLMs
The Arazzo Specification does not mandate a specific development process such as _design-first_ or _code-first_. It does facilitate either technique by establishing clear workflow interactions with HTTP APIs described using the OpenAPI Specification.
This GitHub project is the starting point for Arazzo. Here you will find the information you need about the Arazzo Specification, simple examples of what it looks like, and some general information regarding the project.
## Current Version - 1.0.1
The latest version of the Arazzo Specification can be viewed at [Arazzo Specification - latest](https://spec.openapis.org/arazzo/latest.html).
## See Arazzo in Action
If you just want to see it work, check out the [list of current examples](./examples/1.0.0/).
## Getting Involved
The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the Arazzo Specification, check out the channels below.
- [Bi-weekly Call](https://github.com/OAI/Arazzo-Specification/discussions/5) - Wednesdays at 09:00 AM PDT
- [Discussions](https://github.com/OAI/Arazzo-Specification/discussions) - Use the GitHub discussions to ask questions, provide opinions and engage with the group
- [Issues](https://github.com/OAI/Arazzo-Specification/issues) - Feel free to submit a Github issue with any question or comment about the working group
- Slack - if you have access to the OpenAPI slack workspace, then join the `arazzo` channel. If you do not have access, [you're welcome to join](https://communityinviter.com/apps/open-api/openapi)
## Licensing
See: License [Apache-2.0](https://github.com/OAI/Arazzo-Specification/blob/main/LICENSE)
================================================
FILE: SPECIAL_INTEREST_GROUP.md
================================================
# OpenAPI Initiative (OAI) Workflows Special Interest Group
Work on the Arazzo Specification started under the remit of the OAI Workflows Special Interest Group (SIG-Workflows). The Workflows SIG provides a single place to manage artifacts, discussions, projects, and other aspects relating to how workflows can be represented using, or in combination with, the OpenAPI specification.
## 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 determine 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.
For more information, see [OAI Special Interest Groups](https://github.com/OAI/OpenAPI-Specification/blob/main/SPECIAL_INTEREST_GROUPS.md).
## Workflows Special Interest Group - Charter / Motivation
Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of an API specification.
Our aim is to propose an enhancement to the current OpenAPI, or accompanying specification (or means), that can define sequences of calls and their dependencies to be expressed in the context of delivering a particular outcome or set of outcomes.
The creation of the SIG-Workflows group is inspired by the need to store sequences of calls in the context of specific tests, and in order to communicate the particulars of a complex set of security related calls such as when using OAuth2 and the Financial-grade API security profile of OpenID Connect.
However, such a definition will be useful for understanding how to implement any dependent sequence of functional calls for any user of an API such as authorization calls, redirects and web hooks in order to achieve a certain technical or functional outcome.
Optimally, it should be possible to articulate these workflows in a human and machine readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience and understanding of an API specified using OpenAPI (or other supported specifications).
### Key focus areas
- **Context** - How to define quickly and easily what goal and key functions of an API are, and how to represent that in a specification
- **Workflows** - Handling key and complex sequences which may involve the reuse of endpoints for multiple uses, like token calls in a FAPI compliant sequence, in both a human and machine readable way, supporting both understanding and automation
- **Tooling** - How to best integrate to tools and provide machine readable context for those tools so that the spec can integrate with the tools used by developers
## Special Interest Group (SIG)
The initial Workflows SIG was made up of the following individuals.
### Champions
- David O'Neill ([COO, APIContext](https://www.linkedin.com/in/davidon/))
- Kin Lane ([API Governance Lead, Bloomberg](https://www.linkedin.com/in/kinlane/))
- Frank Kilcommins ([API Evangelist, SmartBear](https://www.linkedin.com/in/frank-kilcommins))
### Contributors
- Nick Denny ([Chief Engineer, APIContext](https://www.linkedin.com/in/nickdenny/))
- Frank Kilcommins ([API Evangelist, SmartBear](https://www.linkedin.com/in/frank-kilcommins))
- Mike Ralphson ([OpenAPI Specification Lead, Postman](https://www.linkedin.com/in/mikeralphson/))
- Alessandro Duminuco ([Senior Technical Leader, Cisco](https://www.linkedin.com/in/alessandroduminuco/))
- Mark Haine ([Founder, Considrd Consulting](https://www.linkedin.com/in/mark-haine/))
- Phil Sturgeon ([API Consultant](https://www.linkedin.com/in/philipsturgeon/))
- Kevin Duffey ([Tech Lead](https://www.linkedin.com/in/kmd/))
- Shai Sachs ([Staff Engineer, Chewy](https://linkedin.com/in/shaisachs/))
================================================
FILE: _archive_/schemas/v1.0/readme.md
================================================
# Archive of outdated JSON Schema Files
> [!TIP]
> JSON Schema files for validating Arazzo descriptions using current Arazzo versions are available at [https://spec.openapis.org/#arazzo-schemas](https://spec.openapis.org/#arazzo-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.0/schema.json
================================================
{
"$id": "https://spec.openapis.org/arazzo/1.0/schema/2024-08-01",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The description of Arazzo v1.0.x documents",
"type": "object",
"properties": {
"arazzo": {
"description": "The version number of the Arazzo Specification",
"type": "string",
"pattern": "^1\\.0\\.\\d+(-.+)?$"
},
"info": {
"$ref": "#/$defs/info"
},
"sourceDescriptions": {
"description": "A list of source descriptions such as Arazzo or OpenAPI",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/source-description-object"
}
},
"workflows": {
"description": "A list of workflows",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/workflow-object"
}
},
"components": {
"$ref": "#/$defs/components-object"
}
},
"required": [
"arazzo",
"info",
"sourceDescriptions",
"workflows"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false,
"$defs": {
"info": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#info-object",
"description": "Provides metadata about the Arazzo description",
"type": "object",
"properties": {
"title": {
"description": "A human readable title of the Arazzo Description",
"type": "string"
},
"summary": {
"description": "A short summary of the Arazzo Description",
"type": "string"
},
"description": {
"description": "A description of the purpose of the workflows defined. CommonMark syntax MAY be used for rich text representation",
"type": "string"
},
"version": {
"description": "The version identifier of the Arazzo document (which is distinct from the Arazzo Specification version)",
"type": "string"
}
},
"required": [
"title",
"version"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"source-description-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#source-description-object",
"description": "Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo description",
"type": "object",
"properties": {
"name": {
"description": "A unique name for the source description",
"type": "string",
"pattern": "^[A-Za-z0-9_\\-]+$"
},
"url": {
"description": "A URL to a source description to be used by a workflow",
"type": "string",
"format": "uri-reference"
},
"type": {
"description": "The type of source description",
"enum": [
"arazzo",
"openapi"
]
}
},
"required": [
"name",
"url"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"workflow-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#workflow-object",
"description": "Describes the steps to be taken across one or more APIs to achieve an objective",
"type": "object",
"properties": {
"workflowId": {
"description": "Unique string to represent the workflow",
"$anchor": "workflowId",
"type": "string"
},
"summary": {
"description": "A summary of the purpose or objective of the workflow",
"type": "string"
},
"description": {
"description": "A description of the workflow. CommonMark syntax MAY be used for rich text representation",
"type": "string"
},
"inputs": {
"description": "A JSON Schema 2020-12 object representing the input parameters used by this workflow",
"$ref": "#/$defs/schema"
},
"dependsOn": {
"description": "A list of workflows that MUST be completed before this workflow can be processed",
"type": "array",
"uniqueItems": true,
"items": {
"type": "string"
}
},
"steps": {
"description": "An ordered list of steps where each step represents a call to an API operation or to another workflow",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/step-object"
}
},
"successActions": {
"description": "A list of success actions that are applicable for all steps described under this workflow",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/success-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"failureActions": {
"description": "A list of failure actions that are applicable for all steps described under this workflow",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/failure-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"outputs": {
"description": "A map between a friendly name and a dynamic output value",
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\.\\-_]+$": {
"type": "string"
}
}
},
"parameters": {
"description": "A list of parameters that are applicable for all steps described under this workflow",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/parameter-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
}
},
"required": [
"workflowId",
"steps"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"step-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#step-object'",
"description": "Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object)",
"type": "object",
"properties": {
"stepId": {
"description": "Unique string to represent the step",
"$anchor": "stepId",
"type": "string"
},
"description": {
"description": "A description of the step. CommonMark syntax MAY be used for rich text representation",
"type": "string"
},
"operationId": {
"description": "The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions",
"type": "string"
},
"operationPath": {
"description": "A reference to a Source combined with a JSON Pointer to reference an operation",
"type": "string"
},
"workflowId": {
"description": "The workflowId referencing an existing workflow within the Arazzo description",
"$ref": "#workflowId"
},
"parameters": {
"description": "A list of parameters that MUST be passed to an operation or workflow as referenced by operationId, operationPath, or workflowId",
"type": "array",
"uniqueItems": true,
"items": true
},
"requestBody": {
"$ref": "#/$defs/request-body-object"
},
"successCriteria": {
"description": "A list of assertions to determine the success of the step",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/criterion-object"
}
},
"onSuccess": {
"description": "An array of success action objects that specify what to do upon step success",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/success-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"onFailure": {
"description": "An array of failure action objects that specify what to do upon step failure",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/failure-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"outputs": {
"description": "A map between a friendly name and a dynamic output value defined using a runtime expression",
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\.\\-_]+$": {
"type": "string"
}
}
}
},
"required": [
"stepId"
],
"oneOf": [
{
"required": [
"operationId"
]
},
{
"required": [
"operationPath"
]
},
{
"required": [
"workflowId"
]
}
],
"allOf": [
{
"if": {
"oneOf": [
{
"required": [
"operationPath"
]
},
{
"required": [
"operationId"
]
}
]
},
"then": {
"properties": {
"parameters": {
"items": {
"oneOf": [
{
"$ref": "#/$defs/reusable-object"
},
{
"$ref": "#/$defs/parameter-object",
"required": [
"in"
]
}
]
}
}
}
}
},
{
"if": {
"required": [
"workflowId"
]
},
"then": {
"properties": {
"parameters": {
"items": {
"oneOf": [
{
"$ref": "#/$defs/parameter-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
}
}
}
}
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"request-body-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#request-body-object",
"description": "The request body to pass to an operation as referenced by operationId or operationPath",
"type": "object",
"properties": {
"contentType": {
"description": "The Content-Type for the request content",
"type": "string"
},
"payload": true,
"replacements": {
"description": "A list of locations and values to set within a payload",
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/$defs/payload-replacement-object"
}
}
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"criterion-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-object",
"description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria",
"type": "object",
"properties": {
"context": {
"description": "A runtime expression used to set the context for the condition to be applied on",
"type": "string"
},
"condition": {
"description": "The condition to apply",
"type": "string"
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"description": "The type of condition to be applied",
"enum": [
"simple",
"regex",
"jsonpath",
"xpath"
],
"default": "simple"
}
}
},
{
"$ref": "#/$defs/criterion-expression-type-object"
}
],
"required": [
"condition"
],
"dependentRequired": {
"type": [
"context"
]
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"criterion-expression-type-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object",
"description": "An object used to describe the type and version of an expression used within a Criterion Object",
"type": "object",
"properties": {
"type": {
"description": "The type of condition to be applied",
"enum": [
"jsonpath",
"xpath"
]
},
"version": {
"description": "A short hand string representing the version of the expression type",
"type": "string"
}
},
"required": [
"type",
"version"
],
"allOf": [
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "jsonpath"
}
}
},
"then": {
"properties": {
"version": {
"const": "draft-goessner-dispatch-jsonpath-00"
}
}
}
},
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "xpath"
}
}
},
"then": {
"properties": {
"version": {
"enum": [
"xpath-10",
"xpath-20",
"xpath-30"
]
}
}
}
}
],
"$ref": "#/$defs/specification-extensions"
},
"success-action-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#success-action-object",
"description": "A single success action which describes an action to take upon success of a workflow step",
"type": "object",
"properties": {
"name": {
"description": "The name of the success action",
"type": "string"
},
"type": {
"description": "The type of action to take",
"enum": [
"end",
"goto"
]
},
"workflowId": {
"description": "The workflowId referencing an existing workflow within the Arazzo description to transfer to upon success of the step",
"$ref": "#workflowId"
},
"stepId": {
"description": "The stepId to transfer to upon success of the step",
"$ref": "#stepId"
},
"criteria": {
"description": "A list of assertions to determine if this action SHALL be executed",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/criterion-object"
}
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "goto"
}
}
},
"then": {
"oneOf": [
{
"required": [
"workflowId"
]
},
{
"required": [
"stepId"
]
}
]
}
}
],
"required": [
"name",
"type"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"failure-action-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#failure-action-object",
"description": "A single failure action which describes an action to take upon failure of a workflow step",
"type": "object",
"properties": {
"name": {
"description": "The name of the failure action",
"type": "string"
},
"type": {
"description": "The type of action to take",
"enum": [
"end",
"goto",
"retry"
]
},
"workflowId": {
"description": "The workflowId referencing an existing workflow within the Arazzo description to transfer to upon failure of the step",
"$ref": "#workflowId"
},
"stepId": {
"description": "The stepId to transfer to upon failure of the step",
"$ref": "#stepId"
},
"retryAfter": {
"description": "A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made",
"type": "number",
"minimum": 0
},
"retryLimit": {
"description": "A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step",
"type": "integer",
"minimum": 0
},
"criteria": {
"description": "A list of assertions to determine if this action SHALL be executed",
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/$defs/criterion-object"
}
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"enum": [
"goto",
"retry"
]
}
}
},
"then": {
"oneOf": [
{
"required": [
"workflowId"
]
},
{
"required": [
"stepId"
]
}
]
}
},
{
"if": {
"properties": {
"type": {
"const": "retry"
}
}
},
"then": {
"required": [
"retryAfter"
]
}
}
],
"required": [
"name",
"type"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"reusable-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#reusable-object",
"description": "A simple object to allow referencing of objects contained within the Components Object",
"type": "object",
"properties": {
"reference": {
"description": "A runtime expression used to reference the desired object",
"type": "string"
},
"value": {
"description": "Sets a value of the referenced parameter",
"type": [
"string",
"boolean",
"object",
"array",
"number",
"null"
]
}
},
"required": [
"reference"
],
"unevaluatedProperties": false
},
"parameter-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#parameter-object",
"description": "Describes a single step parameter",
"type": "object",
"properties": {
"name": {
"description": "The name of the parameter",
"type": "string"
},
"in": {
"description": "The named location of the parameter",
"enum": [
"path",
"query",
"header",
"cookie"
]
},
"value": {
"description": "The value to pass in the parameter",
"type": [
"string",
"boolean",
"object",
"array",
"number",
"null"
]
}
},
"required": [
"name",
"value"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"payload-replacement-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#payload-replacement-object",
"description": "Describes a location within a payload (e.g., a request body) and a value to set within the location",
"type": "object",
"properties": {
"target": {
"description": "A JSON Pointer or XPath Expression which MUST be resolved against the request body",
"type": "string"
},
"value": {
"description": "The value set within the target location",
"type": "string"
}
},
"required": [
"target",
"value"
],
"unevaluatedProperties": false,
"$ref": "#/$defs/specification-extensions"
},
"components-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#components-object",
"description": "Holds a set of reusable objects for different aspects of the Arazzo Specification",
"type": "object",
"properties": {
"inputs": {
"description": "An object to hold reusable JSON Schema 2020-12 schemas to be referenced from workflow inputs",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/schema"
}
},
"parameters": {
"description": "An object to hold reusable Parameter Objects",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/parameter-object"
}
},
"successActions": {
"description": "An object to hold reusable Success Actions Objects",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/success-action-object"
}
},
"failureActions": {
"description": "An object to hold reusable Failure Actions Objects",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/failure-action-object"
}
}
},
"patternProperties": {
"^(inputs|parameters|successActions|failureActions)$": {
"$comment": "Enumerating all of the property names in the regex is necessary for unevaluatedProperties to work as expected",
"propertyNames": {
"pattern": "^[a-zA-Z0-9\\.\\-_]+$"
}
}
},
"unevaluatedProperties": false,
"$ref": "#/$defs/specification-extensions"
},
"specification-extensions": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#specification-extensions",
"description": "While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points",
"patternProperties": {
"^x-": true
}
},
"schema": {
"$comment": "https://spec.openapis.org/arazzo/v1.0#schema-object",
"$ref": "https://json-schema.org/draft/2020-12/schema"
}
}
}
================================================
FILE: _archive_/schemas/v1.0/schema.yaml
================================================
$id: 'https://spec.openapis.org/arazzo/1.0/schema/2024-08-01'
$schema: 'https://json-schema.org/draft/2020-12/schema'
description: |-
The description of Arazzo v1.0.x documents
type: object
properties:
arazzo:
description: The version number of the Arazzo Specification
type: string
pattern: '^1\.0\.\d+(-.+)?$'
info:
$ref: '#/$defs/info'
sourceDescriptions:
description: A list of source descriptions such as Arazzo or OpenAPI
type: array
uniqueItems: true
minItems: 1
items:
$ref: '#/$defs/source-description-object'
workflows:
description: A list of workflows
type: array
uniqueItems: true
minItems: 1
items:
$ref: '#/$defs/workflow-object'
components:
$ref: '#/$defs/components-object'
required:
- arazzo
- info
- sourceDescriptions
- workflows
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
$defs:
info:
$comment: https://spec.openapis.org/arazzo/v1.0#info-object
description: Provides metadata about the Arazzo description
type: object
properties:
title:
description: A human readable title of the Arazzo Description
type: string
summary:
description: A short summary of the Arazzo Description
type: string
description:
description: A description of the purpose of the workflows defined. CommonMark syntax MAY be used for rich text representation
type: string
version:
description: The version identifier of the Arazzo document (which is distinct from the Arazzo Specification version)
type: string
required:
- title
- version
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
source-description-object:
$comment: https://spec.openapis.org/arazzo/v1.0#source-description-object
description: |-
Describes a source description (such as an OpenAPI description)
that will be referenced by one or more workflows described within
an Arazzo description
type: object
properties:
name:
description: A unique name for the source description
type: string
pattern: '^[A-Za-z0-9_\-]+$'
url:
description: A URL to a source description to be used by a workflow
type: string
format: uri-reference
type:
description: The type of source description
enum:
- arazzo
- openapi
required:
- name
- url
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
workflow-object:
$comment: https://spec.openapis.org/arazzo/v1.0#workflow-object
description: Describes the steps to be taken across one or more APIs to achieve an objective
type: object
properties:
workflowId:
description: Unique string to represent the workflow
$anchor: workflowId
type: string
summary:
description: A summary of the purpose or objective of the workflow
type: string
description:
description: A description of the workflow. CommonMark syntax MAY be used for rich text representation
type: string
inputs:
description: A JSON Schema 2020-12 object representing the input parameters used by this workflow
$ref: '#/$defs/schema'
dependsOn:
description: A list of workflows that MUST be completed before this workflow can be processed
type: array
uniqueItems: true
items:
type: string
steps:
description: An ordered list of steps where each step represents a call to an API operation or to another workflow
type: array
uniqueItems: true
minItems: 1
items:
$ref: '#/$defs/step-object'
successActions:
description: A list of success actions that are applicable for all steps described under this workflow
type: array
uniqueItems: true
items:
oneOf:
- $ref: '#/$defs/success-action-object'
- $ref: '#/$defs/reusable-object'
failureActions:
description: A list of failure actions that are applicable for all steps described under this workflow
type: array
uniqueItems: true
items:
oneOf:
- $ref: '#/$defs/failure-action-object'
- $ref: '#/$defs/reusable-object'
outputs:
description: A map between a friendly name and a dynamic output value
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
type: string
parameters:
description: A list of parameters that are applicable for all steps described under this workflow
type: array
uniqueItems: true
items:
oneOf:
- $ref: '#/$defs/parameter-object'
- $ref: '#/$defs/reusable-object'
required:
- workflowId
- steps
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
step-object:
$comment: https://spec.openapis.org/arazzo/v1.0#step-object'
description: |-
Describes a single workflow step which MAY be a call to an
API operation (OpenAPI Operation Object or another Workflow Object)
type: object
properties:
stepId:
description: Unique string to represent the step
$anchor: stepId
type: string
description:
description: A description of the step. CommonMark syntax MAY be used for rich text representation
type: string
operationId:
description: The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions
type: string
operationPath:
description: A reference to a Source combined with a JSON Pointer to reference an operation
type: string
workflowId:
description: The workflowId referencing an existing workflow within the Arazzo description
$ref: '#workflowId'
parameters:
description: A list of parameters that MUST be passed to an operation or workflow as referenced by operationId, operationPath, or workflowId
type: array
uniqueItems: true
items: true
requestBody:
$ref: '#/$defs/request-body-object'
successCriteria:
description: A list of assertions to determine the success of the step
type: array
uniqueItems: true
minItems: 1
items:
$ref: '#/$defs/criterion-object'
onSuccess:
description: An array of success action objects that specify what to do upon step success
type: array
uniqueItems: true
items:
oneOf:
- $ref: '#/$defs/success-action-object'
- $ref: '#/$defs/reusable-object'
onFailure:
description: An array of failure action objects that specify what to do upon step failure
type: array
uniqueItems: true
items:
oneOf:
- $ref: '#/$defs/failure-action-object'
- $ref: '#/$defs/reusable-object'
outputs:
description: A map between a friendly name and a dynamic output value defined using a runtime expression
type: object
patternProperties:
'^[a-zA-Z0-9\.\-_]+$':
type: string
required:
- stepId
oneOf:
- required:
- operationId
- required:
- operationPath
- required:
- workflowId
allOf:
- if:
oneOf:
- required:
- operationPath
- required:
- operationId
then:
properties:
parameters:
items:
oneOf:
- $ref: '#/$defs/reusable-object'
- $ref: '#/$defs/parameter-object'
required:
- in
- if:
required:
- workflowId
then:
properties:
parameters:
items:
oneOf:
- $ref: '#/$defs/parameter-object'
- $ref: '#/$defs/reusable-object'
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
request-body-object:
$comment: https://spec.openapis.org/arazzo/v1.0#request-body-object
description: The request body to pass to an operation as referenced by operationId or operationPath
type: object
properties:
contentType:
description: The Content-Type for the request content
type: string
payload: true
replacements:
description: A list of locations and values to set within a payload
type: array
uniqueItems: true
items:
$ref: '#/$defs/payload-replacement-object'
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
criterion-object:
$comment: https://spec.openapis.org/arazzo/v1.0#criterion-object
description: |-
An object used to specify the context, conditions, and condition types
that can be used to prove or satisfy assertions specified in Step Object successCriteria,
Success Action Object criteria, and Failure Action Object criteria
type: object
properties:
context:
description: A runtime expression used to set the context for the condition to be applied on
type: string
condition:
description: The condition to apply
type: string
anyOf:
- type: object
properties:
type:
description: The type of condition to be applied
enum:
- simple
- regex
- jsonpath
- xpath
default: simple
- $ref: '#/$defs/criterion-expression-type-object'
required:
- condition
dependentRequired:
type:
- context
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
criterion-expression-type-object:
$comment: https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object
description: An object used to describe the type and version of an expression used within a Criterion Object
type: object
properties:
type:
description: The type of condition to be applied
enum:
- jsonpath
- xpath
version:
description: A short hand string representing the version of the expression type
type: string
required:
- type
- version
allOf:
- if:
required:
- type
properties:
type:
const: jsonpath
then:
properties:
version:
const: draft-goessner-dispatch-jsonpath-00
- if:
required:
- type
properties:
type:
const: xpath
then:
properties:
version:
enum:
- xpath-10
- xpath-20
- xpath-30
$ref: '#/$defs/specification-extensions'
success-action-object:
$comment: https://spec.openapis.org/arazzo/v1.0#success-action-object
description: A single success action which describes an action to take upon success of a workflow step
type: object
properties:
name:
description: The name of the success action
type: string
type:
description: The type of action to take
enum:
- end
- goto
workflowId:
description: The workflowId referencing an existing workflow within the Arazzo description to transfer to upon success of the step
$ref: '#workflowId'
stepId:
description: The stepId to transfer to upon success of the step
$ref: '#stepId'
criteria:
description: A list of assertions to determine if this action SHALL be executed
type: array
uniqueItems: true
minItems: 1
items:
$ref: '#/$defs/criterion-object'
allOf:
- if:
properties:
type:
const: goto
then:
oneOf:
- required:
- workflowId
- required:
- stepId
required:
- name
- type
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
failure-action-object:
$comment: https://spec.openapis.org/arazzo/v1.0#failure-action-object
description: A single failure action which describes an action to take upon failure of a workflow step
type: object
properties:
name:
description: The name of the failure action
type: string
type:
description: The type of action to take
enum:
- end
- goto
- retry
workflowId:
description: The workflowId referencing an existing workflow within the Arazzo description to transfer to upon failure of the step
$ref: '#workflowId'
stepId:
description: The stepId to transfer to upon failure of the step
$ref: '#stepId'
retryAfter:
description: A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made
type: number
minimum: 0
retryLimit:
description: A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step
type: integer
minimum: 0
criteria:
description: A list of assertions to determine if this action SHALL be executed
type: array
uniqueItems: true
items:
$ref: '#/$defs/criterion-object'
allOf:
- if:
properties:
type:
enum:
- goto
- retry
then:
oneOf:
- required:
- workflowId
- required:
- stepId
- if:
properties:
type:
const: retry
then:
required:
- retryAfter
required:
- name
- type
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
reusable-object:
$comment: https://spec.openapis.org/arazzo/v1.0#reusable-object
description: A simple object to allow referencing of objects contained within the Components Object
type: object
properties:
reference:
description: A runtime expression used to reference the desired object
type: string
value:
description: Sets a value of the referenced parameter
type:
- string
- boolean
- object
- array
- number
- 'null'
required:
- reference
unevaluatedProperties: false
parameter-object:
$comment: https://spec.openapis.org/arazzo/v1.0#parameter-object
description: Describes a single step parameter
type: object
properties:
name:
description: The name of the parameter
type: string
in:
description: The named location of the parameter
enum:
- path
- query
- header
- cookie
value:
description: The value to pass in the parameter
type:
- string
- boolean
- object
- array
- number
- 'null'
required:
- name
- value
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false
payload-replacement-object:
$comment: https://spec.openapis.org/arazzo/v1.0#payload-replacement-object
description: Describes a location within a payload (e.g., a request body) and a value to set within the location
type: object
properties:
target:
description: A JSON Pointer or XPath Expression which MUST be resolved against the request body
type: string
value:
description: The value set within the target location
type: string
required:
- target
- value
unevaluatedProperties: false
$ref: '#/$defs/specification-extensions'
components-object:
$comment: https://spec.openapis.org/arazzo/v1.0#components-object
description: Holds a set of reusable objects for different aspects of the Arazzo Specification
type: object
properties:
inputs:
description: An object to hold reusable JSON Schema 2020-12 schemas to be referenced from workflow inputs
type: object
additionalProperties:
$ref: '#/$defs/schema'
parameters:
description: An object to hold reusable Parameter Objects
type: object
additionalProperties:
$ref: '#/$defs/parameter-object'
successActions:
description: An object to hold reusable Success Actions Objects
type: object
additionalProperties:
$ref: '#/$defs/success-action-object'
failureActions:
description: An object to hold reusable Failure Actions Objects
type: object
additionalProperties:
$ref: '#/$defs/failure-action-object'
patternProperties:
'^(inputs|parameters|successActions|failureActions)$':
$comment: Enumerating all of the property names in the regex is necessary for unevaluatedProperties to work as expected
propertyNames:
pattern: '^[a-zA-Z0-9\.\-_]+$'
unevaluatedProperties: false
$ref: '#/$defs/specification-extensions'
specification-extensions:
$comment: https://spec.openapis.org/arazzo/v1.0#specification-extensions
description: While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points
patternProperties:
'^x-': true
schema:
$comment: https://spec.openapis.org/arazzo/v1.0#schema-object
$ref: 'https://json-schema.org/draft/2020-12/schema'
================================================
FILE: examples/1.0.0/ExtendedParametersExample.arazzo.yaml
================================================
arazzo: 1.0.0
info:
title: Public Zoo API
version: '1.0'
sourceDescriptions:
- name: animals
type: openapi
url: ./animals.yaml
workflows:
- workflowId: animal-workflow
parameters:
- in: cookie
name: workflowLevelParamOne
value: someValue
- in: header
name: workflowLevelParamTwo
value: someValue
steps:
- stepId: post-step
parameters:
- in: cookie
name: authentication
value: SUPER_SECRET
operationId: $sourceDescriptions.animals.postAnimal
- stepId: get-step
operationId: $sourceDescriptions.animals.getRandomAnimal
================================================
FILE: examples/1.0.0/FAPI-PAR.arazzo.yaml
================================================
arazzo: 1.0.0
info:
title: PAR, Authorization and Token workflow
version: 1.0.0
description: >-
A workflow describing how to obtain a token from an OAuth2 and OpenID Connect Financial Grade authorization server which can be common for PSD2 API journeys
sourceDescriptions:
- name: auth-api
url: ./FAPI-PAR.openapi.yaml
type: openapi
workflows:
- workflowId: OIDC-PAR-AuthzCode
summary: PAR, Authorization and Token workflow
description: >-
PAR - Pushed Authorization Request - API Call - https://www.rfc-editor.org/rfc/rfc9126.html
Authorize - A web interaction that needs to be passed to a user agent (such as a browser) https://openid.net/specs/openid-connect-core-1_0.html
Token - An API call requesting the tokens
inputs:
type: object
properties:
client_id:
type: string
description: The identifier of the third party provider OAuth client. ClientId is returned during the TPP registration.
client_assertion:
type: object
description: |
Used for PAR client authentication. The assertion contains a JWS, in this an object `base64(JWS)`
signed with JWT signing private key related to the TPP OAuth client. See the Model and the Assertion
object for a detailed description of the content.
properties:
iss:
type: string
sub:
type: string
aud:
type: string
exp:
type: string
iat:
type: string
jti:
type: string
redirect_uri:
type: string
description: The value of the redirect URI that was used in the previous `/as/authorize.oauth2` call.
code_verifier:
type: string
description: The code verifier Proof Key of Code Exchange (PKCE)
PARrequestBody:
type: object
description: |
Parameters that comprise an authorization request are sent directly to the
pushed authorization request endpoint in the request body
[PAR Request](https://tools.ietf.org/html/draft-ietf-oauth-par-07#section-2.1)
properties:
response_type:
type: string
client_id:
type: string
sub:
type: string
scope:
type: string
prompt:
type: string
code_challenge_method:
type: string
code_challenge:
type: string
state:
type: string
nonce:
type: string
redirect_uri:
type: string
consent_id:
type: string
TokenRequestBody:
type: object
description: Request Schema for the token endpoint in the context of an OAuth2 Authorization code flow (**Note** this is place holder object that will have values replaced dynamically)
properties:
grant_type:
type: string
code:
type: string
redirect_uri:
type: string
code_verifier:
type: string
required:
- grant_type
- code
- redirect_uri
- code_verifier
required:
- PARrequestBody
- TokenRequestBody
steps:
- stepId: PARStep
description: Pushed Authorization Request
operationId: $sourceDescriptions.auth-api.PAR
parameters:
- name: client_id
in: query
value: $inputs.client_id
- name: client_assertion_type
in: query
value: 'urn:ietf:params:oauth:grant-type:jwt-bearer'
- name: client_assertion
in: query
value: $inputs.client_assertion
requestBody:
payload: $inputs.PARrequestBody
successCriteria:
# assertions to determine step was successful
- condition: $statusCode == 200
outputs:
request_uri: $response.body#/request_uri
- stepId: AuthzCodeStep
description: OIDC Authorization code request
operationId: $sourceDescriptions.auth-api.Authorization
parameters:
- name: request_uri
in: query
value: $steps.PARStep.outputs.request_uri
- name: client_id
in: query
value: $inputs.client_id
successCriteria:
# assertions to determine step was successful
- condition: $statusCode == 302
outputs:
code: $response.body#/code # Not really, this is a query parameter (need a way to represent out-of-band props)
- stepId: TokenStep
description: Get token from the OIDC Token endpoint
operationId: $sourceDescriptions.auth-api.Token
parameters:
- name: client_id
in: query
value: $inputs.client_id
- name: client_assertion_type
in: query
value: 'urn:ietf:params:oauth:grant-type:jwt-bearer'
- name: client_assertion
in: query
value: $inputs.client_assertion
requestBody:
payload: |
{
"grant_type": "authorization_code",
"code": "{$steps.AuthzCodeStep.outputs.code}",
"redirect_uri": "{$inputs.redirect_uri}",
"code_verifier": "{$inputs.code_verifier}"
}
successCriteria:
# assertions to determine step was successful
- condition: $statusCode == 200
outputs:
tokenResponse: $response.body
outputs:
access_token: $steps.TokenStep.outputs.tokenResponse
================================================
FILE: examples/1.0.0/FAPI-PAR.openapi.yaml
================================================
openapi: '3.0.0'
info:
version: '1.0.0'
title: 'Authentication API'
description: |
## OAuth2 and OpenID Connect are used to handle the security flows relating to API access.
These interfaces are used as part of the PSD2 API journeys there is a
[Getting Started Guide](https://developer.example.com)
and use case focussed developer documentation is available for the following cases:
1. [Delegated SCA](https://developer.example.com)
2. [Redirect based Account Access](https://developer.example.com)
3. [Redirect based Payments](https://developer.example.com)
The OAuth2 and OpenID interfaces are used in three sequences depending on the particular
requirements of the use cases.
When the third party app needs to get access without end-user involvement the Token
endpoint is used to get an access token. This is called the "Client Credentials Grant" of
OAuth2. The result of this is an access token than can be used to call some functional APIs.
When user interaction is required the "Authorization Code" grant is used. In this
implementation it consists of a sequence of calls.
*how far do we take this? include Create Consent and Init Payment at the start? include account and payment APIs at the end?*
1. PAR - Pushed Authorization Request - API Call
2. Authorize - A web interaction that needs to be passed to a user agent (such as a browser)
3. Token - An API call requesting the tokens
This sequence of calls returns an Access token, ID_Token and potentially a refresh token.
The access token provided as a result of the authorization code grant can access other APIs.
The refresh token can be used to request replacement access tokens with the same level of access.
This request is
### References
* [RFC6749 OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
* [RFC6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)
* [OpenID Connect Core 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-core-1_0.html)
* [Financial-grade API Security Profile 1.0 - Part 1: Baseline](https://openid.net/specs/openid-financial-api-part-1-1_0.html)
* [Financial-grade API Security Profile 1.0 - Part 2: Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html)
* [OAuth 2.0 Pushed Authorization Requests draft-ietf-oauth-par-07](https://tools.ietf.org/html/draft-ietf-oauth-par-07)
* [JOSE Related specs (including JWT, JWT, JWE)](https://datatracker.ietf.org/wg/jose/documents/)
servers:
- url: https://api.uat.example.com/
description: Sandbox - Test Server for registered external parties to use for testing and development
- url: https://api.example.com
description: Production - Live Server providing APIs to registered third parties
paths:
/.well-known/openid-configuration:
get:
summary: RFC 8414 Well known OAuth 2.0 configuration endpoint
description: |
The standard "OAuth 2.0 Authorization Server Metadata" describing
the configuration including endpoint addresses. The content of this
file is used by clients to confirm details of the configuration of
the OpenID Provider.
Generally speaking the OpenID configuration is not directly required for delivery of use cases.
externalDocs:
url: https://tools.ietf.org/html/rfc8414
security: []
operationId: WellKnown
tags:
- OAuth2
responses:
200:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/WellKnown"
/public/jwks:
get:
summary: JSON Web Key set
description: |
Retrieve the public server JSON Web Key (JWK) to verify the signature of an issued
token or to encrypt request objects to it.
externalDocs:
url: https://datatracker.ietf.org/doc/rfc7517/
operationId: JWKS
tags:
- OAuth2
responses:
200:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JWKResponse'
404:
description: Not Found
500:
description: Internal Server Error
/as/par.oauth2:
post:
summary: Submits the OAuth 2.0 authorisation request parameters to obtain a request_uri handle for use at the authorisation endpoint.
description: |
A Pushed Authorization request is used to set the parameters for the subsequent Authorization call
The OAuth2 client sends the signed request object in the POST to the PAR interface to avoid leakage of request parmeters.
This implementation requires PAR to be used.
**Mutual TLS client authentication is required to access this endpoint**
As stated in the draft spec : "The pushed authorization request can be composed of any of the parameters
applicable for use at authorization endpoint including those defined
in [RFC6749] as well as all applicable extensions."
For the purposes of the implementation there are a set of
parameters that will be required for a successful authorization request and
these are listed below in the request object parameter.
The `consent_id` key in the request body is found in response to the "Init Payment"
or "Create Consent" APIs
externalDocs:
url: https://tools.ietf.org/html/draft-ietf-oauth-par-07
operationId: Par
tags:
- OAuth2
parameters:
- name: Content-Type
in: header
schema:
type: string
default: application/x-www-form-urlencoded
enum:
- application/x-www-form-urlencoded
required: true
- name: client_id
in: query
required: true
description: The identifier of the third party provider OAuth client. ClientId is returned during the TPP registration.
schema:
type: string
- name: client_assertion_type
in: query
required: true
description: Type of assertion be used. In this case it must be "urn:ietf:params:oauth:grant-type:jwt-bearer"
schema:
type: string
default: urn:ietf:params:oauth:grant-type:jwt-bearer
enum:
- urn:ietf:params:oauth:grant-type:jwt-bearer
allowEmptyValue: false
- name: client_assertion
in: query
description: |
Used for PAR client authentication. The assertion contains a JWS, in this an object (base64(JWS))
signed with JWT signing private key related to the TPP OAuth client. See the Model and the Assertion
object for a detailed description of the content.
required: true
content:
application/json:
schema:
type: object
properties:
iss:
type: string
sub:
type: string
aud:
type: string
exp:
type: string
iat:
type: string
jti:
type: string
requestBody:
description: |
parameters that comprise an authorization request are sent directly to the
pushed authorization request endpoint in the request body
[PAR Request](https://tools.ietf.org/html/draft-ietf-oauth-par-07#section-2.1)
required: true
content:
application/json:
schema:
type: object
properties:
response_type:
type: string
client_id:
type: string
sub:
type: string
scope:
type: string
prompt:
type: string
code_challenge_method:
type: string
code_challenge:
type: string
state:
type: string
nonce:
type: string
redirect_uri:
type: string
consent_id:
type: string
responses:
200:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ParResponse'
links:
PAR_returned_request_uri:
operationId: Authorization
parameters:
request_uri: '$response.body#/request_uri'
description: >
The `request_uri` value returned in the response MUST be used as
the `request_uri` input parameter in `GET /as/authorize.oauth2` when
using the authorization code flow, before it expires.
400:
description: Bad Request
401:
description: Unauthorized
500:
description: Internal Server Error
/as/authorize.oauth2:
get:
summary: OAuth 2.0 Authorization endpoint
description: |
The OAuth 2.0 authorisation endpoint is where the end-user is redirected to Perform SCA using their browser.
**This is a Web interface not a REST API**
This is the standard RFC 6749 authorization endpoint. In this case the request parameters
are pushed in via the PAR endpoint prior to the authorize call and only the request_uri
returned from the PAR request and the client_id is given as input parameters to this call.
The call is normally triggered from the backend via browser based redirect to the
authorization server authorize endpoint.
### External Documentation:
[OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)
[OAuth2](https://tools.ietf.org/html/rfc6749)
security: []
operationId: Authorization
tags:
- OAuth2
parameters:
- name: request_uri
in: query
required: true
description: This parameter is returned by the preceeding /as/par.oauth2 call
schema:
type: string
- name: client_id
in: query
required: true
description: The Client ID issued when the app was registered in the developer portal
schema:
type: string
responses:
302:
description: |
Redirect to defined redirect uri with the authorization code as a standard OIDC response.
>**https://**_{your app redirect_uri}_
>**?code=**_{Arbirary String}_
>**&state=**_{state value from authorization request}_
>**&iss=**_https://api.example.com_
links:
Authorization_Response:
description: >
The `code` value returned in the response MUST be used as
the `request_uri` input parameter in `GET /as/authorize.oauth2` when
using the authorization code flow, before it expires.
operationId: Token
parameters:
code: '$response.path#/code'
500:
description: Internal Server Error
/as/token.oauth2:
post:
summary: Token endpoint with client authentication
description: |
There are three different cases where the token endpoint is used
1. Client Credentials Grant
2. Authorisation Code Grant
3. Refresh Grant
As a result there are different types of token endpoint request and response
There are three request types and two response types. All of these types use the same
interaction but with different request and responses
**Mutual TLS client authentication is required to access this endpoint**
When the **client credentials grant** is being used the Token request has no other calls as pre-requisities.
When the authorization code grant or refresh grant are being exercised there are dependancies on previous calls.
In the implementation the **Authorization code flow** depends upon previous calls to:
- /as/par.oauth2
- /as/authorize.oauth2
**The Refresh grant** depends on there being a previous authorization code flow that returned a refresh token.
operationId: Token
tags:
- OAuth2
parameters:
- name: Content-Type
in: header
schema:
type: string
default: application/x-www-form-urlencoded
enum:
- application/x-www-form-urlencoded
required: true
- name: client_id
in: query
required: true
description: The identifier of the third party provider OAuth client. ClientId is returned during the TPP registration.
schema:
type: string
- name: client_assertion_type
in: query
required: true
description: Type of assertion be used. In this case it must be "urn:ietf:params:oauth:grant-type:jwt-bearer"
schema:
type: string
default: urn:ietf:params:oauth:grant-type:jwt-bearer
enum:
- urn:ietf:params:oauth:grant-type:jwt-bearer
allowEmptyValue: false
- name: client_assertion
in: query
description: |
Used for PAR client authentication. The assertion contains a JWS, in this an object (base64(JWS))
signed with JWT signing private key related to the TPP OAuth client. See the Model and the Assertion
object for a detailed description of the content.
required: true
content:
application/json:
schema:
type: object
properties:
iss:
type: string
sub:
type: string
aud:
type: string
exp:
type: string
iat:
type: string
jti:
type: string
requestBody:
description: |
Body of the request made to the Token endpoint - 3 schemas available for different flows
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TokenClientCredsRequest'
- $ref: '#/components/schemas/TokenAuthzCodeRequest'
- $ref: '#/components/schemas/TokenRefreshRequest'
responses:
200:
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TokenClientCredsResponse'
- $ref: '#/components/schemas/TokenAuthzResponse'
400:
description: Bad Request with a token error code
401:
description: Unauthorized with a token error code
500:
description: Internal Server Error
components:
schemas:
WellKnown:
required:
- issuer
- authorization_endpoint
- token_endpoint
- response_types_supported
properties:
issuer:
type: string
authorization_endpoint:
type: string
token_endpoint:
type: string
revocation_endpoint:
type: string
userinfo_endpoint:
type: string
introspection_endpoint:
type: string
jwks_uri:
type: string
registration_endpoint:
type: string
ping_revoked_sris_endpoint:
type: string
ping_end_session_endpoint:
type: string
device_authorization_endpoint:
type: string
scopes_supported:
type: string
claims_supported:
type: string
response_types_supported:
type: string
response_modes_supported:
type: string
grant_types_supported:
type: string
subject_types_supported:
type: string
id_token_signing_alg_values_supported:
type: string
token_endpoint_auth_methods_supported:
type: string
token_endpoint_auth_signing_alg_values_supported:
type: string
claim_types_supported:
type: string
claims_parameter_supported:
type: string
request_parameter_supported:
type: string
request_uri_parameter_supported:
type: string
request_object_signing_alg_values_supported:
type: string
id_token_encryption_alg_values_supported:
type: string
id_token_encryption_enc_values_supported:
type: string
backchannel_authentication_endpoint:
type: string
backchannel_token_delivery_modes_supported:
type: string
backchannel_authentication_request_signing_alg_values_supported:
type: string
backchannel_user_code_parameter_supported:
type: string
tls_client_certificate_bound_access_tokens:
type: string
mtls_endpoint_aliases:
type: string
JWKResponse:
description: |
A JSON object containing the server public JWK set in the form of an array of
properties:
keys:
type: array
items:
type: object
properties:
kty:
type: string
use:
type: string
key_ops:
type: string
alg:
type: string
kid:
type: string
x5c:
type: string
x5u:
type: string
x5t:
type: string
x5t#s256:
type: string
ParResponse:
properties:
expires_in:
type: string
description: The expires in parameter defines the number of seconds when the reference uri expires.
request_uri:
type: string
description: The request uri to the request object in the request to the par endpoint.
AuthCodeRequest:
required:
- test
properties:
expires_in:
type: string
description: The expires in paremeter defines the number of seconds when the reference uri expires.
request_uri:
type: string
description: The request uri to the request object in the request to the par endpoint.
AuthCodeResponse1:
properties:
code:
type: string
description: The authorization code that will be used when making the subsequent request to the /as/token.oauth endpoint
state:
type: string
description: The request uri to the request object in the request to the par endpoint.
iss:
type: string
description: The request uri to the request object in the request to the par endpoint.
TokenClientCredsRequest:
description: Request Schema for the token endpoint in the context of a Client Credentials OAuth2 flow
required:
- grant_type
- scope
properties:
grant_type:
type: string
description: String that defines which OAuth2 grant this request is part of
enum:
- client_credentials
default: client_credentials
scope:
type: string
description: Space delimited list of OAuth2 scopes
TokenAuthzCodeRequest:
description: Request Schema for the token endpoint in the context of an OAuth2 Authorization code flow
required:
- grant_type
- code
- redirect_uri
- code_verifier
properties:
grant_type:
description: String that defines which OAuth2 grant this request is part of
type: string
default: authorization_code
code:
type: string
description: The authorization code provided as a parameter in the redirect back from the preceeding /as/authorize.oauth2 call
redirect_uri:
type: string
description: The value of the redirect URI that was used in the preceeding /as/authorize.oauth2 call
code_verifier:
type: string
description: The code verifier Proof Key of Code Exchange (PKCE).
TokenRefreshRequest:
description: Request Schema for the token endpoint in the context of an OAuth2 Refresh flow
required:
- grant_type
- refresh_token
properties:
grant_type:
description: String that defines which OAuth2 grant this request is part of
type: string
enum:
- refresh_token
default: refresh_token
refresh_token:
type: string
description: The refresh_token provided as a parameter in the response from a preceeding /as/token.oauth2 call
scope:
type: string
description: OPTIONAL - space delimited list of scopes that is equal to or a subset of the scopes requested by the preceeding authorization code flow
TokenClientCredsResponse:
required:
- access_token
- token_type
properties:
access_token:
type: string
description: The access token issued by the server.
token_type:
type: string
description: "bearer"
expires_in:
type: integer
description: The expires in paremeter defines the number of seconds when the access token expires.
scope:
type: string
description: space delimited list of scopes
TokenAuthzResponse:
required:
- access_token
- token_type
properties:
access_token:
type: string
description: The access token issued by the server.
refresh_token:
type: string
description: The refresh token issued by the server.
token_type:
type: string
description: "bearer"
expires_in:
type: integer
description: The expires in paremeter defines the number of seconds when the access token expires.
scope:
type: string
description: space delimited list of scopes
id_token:
type: string
description: The id token issued by the server.
================================================
FILE: examples/1.0.0/LoginAndRetrievePets.arazzo.yaml
================================================
arazzo: 1.0.0
info:
title: A pet purchasing workflow
summary: This workflow showcases how to purchase a pet through a sequence of API calls
description: |
This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet.
version: 1.0.1
sourceDescriptions:
- name: petStoreDescription
url: https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml
type: openapi
workflows:
- workflowId: loginUserRetrievePet
summary: Login User and then retrieve pets
description: This procedure lays out the steps to login a user and then retrieve pets
inputs:
type: object
properties:
username:
type: string
password:
type: string
steps:
- stepId: loginStep
description: This step demonstrates the user login step
operationId: $sourceDescriptions.petStoreDescription.loginUser
parameters:
# parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
- name: username
in: query
value: $inputs.username
- name: password
in: query
value: $inputs.password
successCriteria:
# assertions to determine step was successful
- condition: $statusCode == 200
outputs:
# outputs from this step
tokenExpires: $response.header.X-Expires-After
rateLimit: $response.header.X-Rate-Limit
sessionToken: $response.body
- stepId: getPetStep
description: retrieve a pet by status from the GET pets endpoint
operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus'
parameters:
- name: status
in: query
value: 'available'
- name: Authorization
in: header
value: $steps.loginStep.outputs.sessionToken
successCriteria:
- condition: $statusCode == 200
outputs:
# outputs from this step
availablePets: $response.body
outputs:
available: $steps.getPetStep.outputs.availablePets
================================================
FILE: examples/1.0.0/README.md
================================================
# Workflows Specification Examples
## Purpose
This README will provide details on the examples found in this directory as well as examples to be added to cover a
variety of use case scenarios.
## Examples
### FAPI
*needs description*
### OAuth
*needs description*
### Pet Coupons
*needs description*
## Examples to be added
* An example where a workflow imports another workflow both of which have components defined to show that the entry/root
workflow can not reference components defined in the imported workflow. Components are scoped to the workflow they
are defined in.
================================================
FILE: examples/1.0.0/bnpl-arazzo.yaml
================================================
arazzo: 1.0.0
info:
title: BNPL Workflow description
description: >-
Describes the steps to secure a loan at checkout from a BNPL platform. It is a multi-step process that requires multiple API calls across several API providers to be completed successfully.
version: 1.0.0
sourceDescriptions:
- name: BnplApi
url: https://raw.githubusercontent.com/OAI/Arazzo-Specification/main/examples/1.0.0/bnpl-openapi.yaml
type: openapi
workflows:
- workflowId: ApplyForLoanAtCheckout
summary: Apply for a loan at checkout using a BNPL platform
description: Describes the steps to secure a loan at checkout from a BNPL platform. It is a multistep process that requires multiple API calls across several API providers to be completed successfully.
inputs:
type: object
required:
- customer
- products
properties:
customer:
description: |
Customer can either be the customer details, which will be used for enrollment, or a link to an existing customer resource as the customer already uses the BNPL platform
oneOf:
- type: object
required:
- firstName
- lastName
- dateOfBirth
- postalCode
properties:
firstName:
description: First name of customer
type: string
minLength: 1
maxLength: 70
lastName:
description: Last name of customer
type: string
minLength: 1
maxLength: 70
dateOfBirth:
description: Customer date of birth
type: string
format: date-time
postalCode:
description: Zip code or postal code of customer
type: string
minLength: 1
maxLength: 70
additionalProperties: false
- type: object
required:
- uri
properties:
uri:
description: URI that points to an existing customer resource, as customer already enrolled on platform
type: string
format: uri
additionalProperties: false
products:
type: array
minItems: 1
items:
type: object
required:
- productCode
- purchaseAmount
properties:
merchantCategoryCode:
description: Merchant category code of merchant. Only required for marketplace ecommerce platforms
type: string
pattern: '^[0-9]{4}$'
productCode:
description: Product code for loan application. Required for eligibility check
type: string
purchaseAmount:
description: Product purchase amount and currency code
type: object
required:
- currency
- amount
properties:
currency:
description: Currency code
type: string
pattern: "^[A-Z]{3}$"
amount:
description: Amount
type: number
steps:
- stepId: checkLoanCanBeProvided
description: |
Call the BNPL API to filter the basket for products qualifying for checkout loans. Pass in the array of products from the workflow input as the payload for the API call.
Act on the response payload:
- If a list of qualifying products is returned then submit customer choices.
- If the list of qualifying products is empty then end the workflow
operationId: findEligibleProducts
requestBody:
contentType: application/json
payload: |
{
"customer": "{$inputs.customer}",
"products": "{$inputs.products}"
}
successCriteria:
- condition: $statusCode == 200
onSuccess:
- name: existingCustomerNotEligible
type: end
criteria:
- condition: $statusCode == 200
- condition: $response.body#/existingCustomerNotEligible == false
- name: qualifyingProductsFound
type: goto
stepId: getCustomerTermsAndConditions
criteria:
- condition: $statusCode == 200
- context: $response.body
type: jsonpath
condition: $[?count(@.products) > 0]
- name: qualifyingProductsNotFound
type: end
criteria:
- condition: $statusCode == 200
- context: $response.body
type: jsonpath
condition: $[?count(@.products) == 0]
outputs:
eligibilityCheckRequired: $response.body#/eligibilityCheckRequired
eligibleProducts: $response.body#/products
totalLoanAmount: $response.body#/totalAmount
- stepId: getCustomerTermsAndConditions
description: |
Get the terms and conditions for the BNPL loans. This is static data and therefore has no arguments.
The data will be displayed to the customer and they'll accept the terms out-of-band.
After this step the flow will need to do a customer eligibility check if required.
operationId: getTermsAndConditions
successCriteria:
- condition: $statusCode == 200
onSuccess:
- name: eligibilityCheckRequired
type: goto
stepId: createCustomer
criteria:
- condition: $steps.checkLoanCanBeProvided.outputs.eligibilityCheckRequired == true
- name: eligibilityCheckNotRequired
type: goto
stepId: initiateBnplTransaction
criteria:
- condition: $steps.checkLoanCanBeProvided.outputs.eligibilityCheckRequired == false
outputs:
termsAndConditions: $response.body
- stepId: createCustomer
description: |
Call the BNPL platform and verify the customer is eligible for the loan, which creates a customer resource. This step is skipped if the customer is already enrolled in the BNPL platform.
Accepting the terms and conditions is set to true as the assumption is they have been accepted when this step is invoked.
If the customer is eligible for the BNPL loan then a customer resource is created
operationId: createCustomer
requestBody:
contentType: application/json
payload: |
{
"firstName": "{$inputs.customer.firstName}",
"lastName": "{$inputs.customer.lastName}",
"dateOfBirth": "{$inputs.customer.dateOfBirth}",
"postalCode": "{$inputs.customer.postalCode}"
"termsAndConditionsAccepted": true
}
successCriteria:
- condition: $statusCode == 200 || $statusCode == 201
onSuccess:
- name: customerIsEligible
type: goto
stepId: initiateBnplTransaction
criteria:
- condition: $statusCode == 201
- name: customerIsNotEligible
type: end
criteria:
- condition: $statusCode == 200
outputs:
customer: $response.body#/links/self
- stepId: initiateBnplTransaction
description: Initiate the BNPL transaction by sending the customer identifier, eligible products, and indicative loan amount to initiate the loan process
operationId: createBnplTransaction
requestBody:
contentType: application/json
payload: |
{
"enrolledCustomer": "{$inputs.customer.uri}",
"newCustomer": "{$steps.createCustomer.outputs.customer}",
"products": "{$steps.checkLoanCanBeProvided.outputs.eligibleProducts}"
}
successCriteria:
- condition: $statusCode == 202
onSuccess:
- name: CustomerAuthorizationRequired
type: goto
stepId: authenticateCustomerAndAuthorizeLoan
criteria:
- condition: $response.body#/redirectAuthToken != null
- name: CustomerAuthorizationNotRequired
type: goto
stepId: retrieveFinalizedPaymentPlan
criteria:
- condition: $response.body#/redirectAuthToken == null
outputs:
redirectAuthToken: $response.body#/redirectAuthToken
loanTransactionResourceUrl: $response.body#/links/self
- stepId: authenticateCustomerAndAuthorizeLoan
description: |
Authenticate the customer and seek authorization for the loan.
Notes:
- Authenticate in this case does not necessarily mean with a valid set of credentials. It could be to prove the identity of the end user, possibly doing an UMA style interaction (which is too complex to tie into this example).
- A redirect is returned for to be sent to the customer. The customer should follow this, but the success of the authorisation is out-of-band.
- This flow mimics OAuth style authorization but is not an exact match as it does not rely on an authorisation code/access token exchange (as this seems somewhat artificial in this context).
operationId: getAuthorization
parameters:
- name: redirectAuthToken
in: query
value: $steps.authenticateCustomerAndAuthorizeLoan.outputs.redirectAuthToken
successCriteria:
- condition: $statusCode == 302
outputs:
redirectUrl: $response.header.Location
- stepId: retrieveFinalizedPaymentPlan
description: Retrieve finalized payment plan to show to customer once authorization is complete
operationId: retrieveBnplLoanTransaction
parameters:
- name: loanTransactionId
in: path
value: $steps.initiateBnplTransaction.outputs.loanTransactionId
successCriteria:
- condition: $statusCode == 200
outputs:
finalizedPaymentPlan: $response.body
- stepId: updateOrderStatus
description: Send update from eCommerce platform to indicate order fulfilled and loan is therefore active
operationId: updateBnplLoanTransactionStatus
parameters:
- name: loanTransactionId
in: path
value: $steps.initiateBnplTransaction.outputs.loanTransactionId
requestBody:
contentType: application/json
payload: { "loanStatus": "Completed" }
successCriteria:
- condition: $statusCode == 204
outputs:
finalizedPaymentPlan: $steps.retrieveFinalizedPaymentPlan.finalizedPaymentPlan
================================================
FILE: examples/1.0.0/bnpl-openapi.yaml
================================================
openapi: 3.0.0
info:
title: Arazzo Buy-now, Pay-later Loan API
description: |
This OpenAPI description provides an example of a buy-now, pay-later (BNPL) API that contains multiple operations that allow eCommerce platforms to facilitate loans on behalf of customers
version: 1.0.0
servers:
- url: /bnpl/v1
description: Default BNPL instance
tags:
- name: Loan Initiation
description: Allows a loan to initiated and finalized
paths:
/auth:
get:
summary: Get customer authorisation
description: |
Used to initiate authentication of the End User and authorisation by the customer.
Mimics an OAuth 2.0 style redirect, but cutdown for the purpose of an example.
operationId: getAuthorization
parameters:
- name: AuthorizationToken
in: query
description: Authorization token value elicited from loan initiation endpoint
required: true
schema:
$ref: '#/components/schemas/AuthorizationToken'
responses:
"302":
description: Instruction to redirect End User, based on validation of the authorisation token
headers:
Location:
description: URL to which the customer is redirected
schema:
type: string
default:
$ref: '#/components/responses/ErrorResponse'
/customers:
post:
summary: Create a customer
description: |
Create a customer for a BNPL loan if they are eligible for the loan in question.
If a customer is eligible a customer resource is created, a 201 returned, and the a link to the customer resource returned.
If the customer is not eligible a 200 is returned and a reason code indicating why the customer was rejected.
operationId: createCustomer
requestBody:
description: The customer properties
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CustomerProperties'
- description: Terms and conditions have been reviewed and accepted
type: object
required:
- termsAndConditionsAccepted
properties:
termsAndConditionsAccepted:
type: boolean
responses:
"200":
description: Customer is not eligible for BNPL loan
content:
application/json:
schema:
type: object
required:
- reasonCode
properties:
reasonCode:
type: string
additionalProperties: false
"201":
description: Customer resource has been created and can be linked to loan transaction
content:
application/json:
schema:
type: object
required:
- customerId
- links
properties:
customerId:
description: Unique identifier for the newly created customer resource
type: string
links:
type: object
required:
- self
properties:
self:
description: URL identifying this resource
allOf:
- $ref: '#/components/schemas/CustomerUri'
additionalProperties: false
additionalProperties: false
default:
$ref: '#/components/responses/ErrorResponse'
/loan-transactions:
post:
summary: Initiate a new loan transaction
description: |
Initiate a new loan based on customer details and in-scope products.
For the sake of this example:
* There is one error response, defined using the `default` keyword.
operationId: createBnplTransaction
requestBody:
content:
application/json:
schema:
description: Properties for the loan. the `enrolledCustomer` and `newCustomer` properties are required to support the two different sources in the calling Arazzo description
type: object
required:
- products
- totalAmount
properties:
enrolledCustomer:
description: The customer resource URI for a previously enrolled customer
allOf:
- $ref: '#/components/schemas/CustomerUri'
newCustomer:
description: A newly-created customer resource URI for this loan
allOf:
- $ref: '#/components/schemas/CustomerUri'
products:
description: Product codes for products included in loan. Supplied to ensure any special terms are included in loan agreement
type: array
minItems: 1
items:
$ref: '#/components/schemas/ProductCode'
totalAmount:
description: Loan amount being requested
allOf:
- $ref: '#/components/schemas/CurrencyAndAmount'
responses:
"202":
description: New loan initiated. This may require authorization before it is finalized
content:
application/json:
schema:
type: object
required:
- loanTransactionId
- links
properties:
redirectAuthToken:
description: A token that allows the loan to be completed without further authorisation. Is omitted if authentication and authorisation by the End User is required
loanTransactionId:
$ref: '#/components/schemas/LoanTransactionId'
links:
type: object
required:
- self
properties:
self:
description: Link to this resource
type: string
additionalProperties: false
additionalProperties: false
default:
$ref: '#/components/responses/ErrorResponse'
/loan-transactions/{loanTransactionId}:
parameters:
- $ref: '#/components/parameters/loanTransactionId'
get:
summary: Retrieve loan
description: Retrieve the finalised BNPL loan transaction with all installments
operationId: retrieveBnplLoanTransaction
responses:
"200":
description: Details of the loan transaction
content:
application/json:
schema:
$ref: '#/components/schemas/LoanTransaction'
default:
$ref: '#/components/responses/ErrorResponse'
/loan-transactions/{loanTransactionId}/status:
parameters:
- $ref: '#/components/parameters/loanTransactionId'
patch:
summary: Update loan status
description: Update the loan status to indicate order fulfilled and loan is active
operationId: updateBnplLoanTransactionStatus
requestBody:
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
$ref: '#/components/schemas/LoanTransactionStatuses'
additionalProperties: false
responses:
"204":
description: Update to status acknowledged and applied to loan transaction
default:
$ref: '#/components/responses/ErrorResponse'
/products:
post:
summary: Retrieve eligible products
description: |
Retrieve the list of products that are eligible for a buy-now, pay-later loan.
Implemented as a not particularly RESTful, RPC-style post operation for simplicity
operationId: findEligibleProducts
requestBody:
content:
application/json:
schema:
type: object
required:
- products
properties:
customer:
description: If the customer is already enrolled on the BNPL platform the customer URI can be supplied, which can be used to perform an upfront eligibility check
allOf:
- $ref: '#/components/schemas/CustomerUri'
products:
$ref: '#/components/schemas/Products'
additionalProperties: false
responses:
"200":
description: |
List of eligible products with information for subsequent steps
content:
application/json:
schema:
type: object
required:
- productCodes
properties:
existingCustomerNotEligible:
description: Flag to indicate existing customer found and is eligible. Associated workflows will stop if this flag is returned
type: boolean
productCodes:
description: This list of product codes that are eligible for a BNPL loan. Allows merchant to render screen showing matching products. Array will be empty if customer not eligible
type: array
items:
$ref: '#/components/schemas/ProductCode'
eligibilityCheckRequired:
description: Indicates whether the customer needs to be checked for eligibility. Required for new customers
type: boolean
default: false
totalAmount:
description: The total loan value for the products that are eligible
allOf:
- $ref: '#/components/schemas/CurrencyAndAmount'
additionalProperties: false
default:
$ref: '#/components/responses/ErrorResponse'
/terms-and-conditions:
get:
summary: Retrieve the terms and conditions for BNPL products
description: >
Retrieve the terms and conditions for BNPL products.
For the sake of this example:
* There is one set of customer T&Cs.
* There is one error response, defined using the `default` keyword.
operationId: getTermsAndConditions
responses:
"200":
description: The terms and conditions document as an array of `string` values
content:
application/json:
schema:
type: array
items:
type: string
minItems: 1
default:
$ref: '#/components/responses/ErrorResponse'
components:
parameters:
loanTransactionId:
name: loanTransactionId
description: Unique identifier for a given loan agreement
in: path
required: true
schema:
$ref: '#/components/schemas/LoanTransactionId'
responses:
ErrorResponse:
description: The error response details, encoded in the ProblemDetails format (RFC9457)
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
schemas:
AuthorizationToken:
description: An authorisation token used to tee up a customer for authentication and authorisation of the loan as required
type: string
format: uuid
CustomerProperties:
type: object
required:
- firstName
- lastName
- dateOfBirth
- postalCode
properties:
firstName:
description: First name of customer
type: string
minLength: 1
maxLength: 70
lastName:
description: Last name of customer
type: string
minLength: 1
maxLength: 70
dateOfBirth:
description: Customer date of birth
type: string
format: date-time
postalCode:
description: Zip code or postal code of customer
type: string
minLength: 1
maxLength: 70
additionalProperties: false
CustomerUri:
description: The URI that identifies the customer resource for the loan transaction
type: string
format: uri
LoanTransaction:
description: Details of the loan transaction including product codes, total amount and repayment schedule
type: object
required:
- customer
- products
- totalAmount
- paymentSchedule
properties:
customer:
description: Link to customer resource
type: string
format: uri
products:
description: List of products and purchase amounts included in BNPL loan transaction
allOf:
- $ref: '#/components/schemas/Products'
status:
$ref: '#/components/schemas/LoanTransactionStatuses'
totalAmount:
description: The total loan amount including interest
allOf:
- $ref: '#/components/schemas/CurrencyAndAmount'
paymentSchedule:
description: Schedule of payments for loan repayment
type: array
minItems: 1
items:
type: object
required:
- paymentDate
- amount
- lastPayment
properties:
paymentDate:
description: The date on which the payment is due
type: string
format: date
amount:
description: The currency and amount due
allOf:
- $ref: '#/components/schemas/CurrencyAndAmount'
lastPayment:
description: Indicator of whether this is the last payment that completes the loan repayment
type: boolean
default: false
additionalProperties: false
additionalProperties: false
LoanTransactionStatuses:
description: |
Loan transaction status values. Explanation
* Pending: Loan transaction is pending authorisation by the End User
* Finalised: Loan transaction has been finalised and is awaiting completion
* Completed: Loan transaction has been issued following completion of order and payments will be collected
type: string
enum:
- Pending
- Finalised
- Completed
LoanTransactionId:
description: Type for unique loan identifier
type: string
ProductCode:
description: Product code for loan application. Required for eligibility check
type: string
ProblemDetails:
type: object
required:
- type
properties:
type:
description: The problem type, expressed as a URI
type: string
status:
description: The HTTP return code generated by the server
type: string
pattern: "^[1-5][0-9]{2}$"
title:
description: The title of the problem, designed to be consumed by humans
type: string
detail:
description: A verbose error message, designed to be consumed by humans
type: string
instance:
description: A URI that identifies a specific occurrence of the problem
type: string
additionalProperties: true
CurrencyAndAmount:
description: Amount and currency code
type: object
required:
- currency
- amount
properties:
currency:
description: Currency code
type: string
pattern: "^[A-Z]{3}$"
amount:
description: Amount
type: number
Products:
type: array
minItems: 1
items:
type: object
required:
- productCode
- netAmount
properties:
merchantCategoryCode:
description: Merchant category code of merchant. Only required for marketplace eCommerce platforms
type: string
pattern: '^[0-9]{4}$'
productCode:
$ref: '#/components/schemas/ProductCode'
purchaseAmount:
description: Product purchase amount and currency code
allOf:
- $ref: '#/components/schemas/CurrencyAndAmount'
================================================
FILE: examples/1.0.0/oauth.arazzo.yaml
================================================
arazzo: 1.0.0
info:
title: Example OAuth service
version: 1.0.0
description: >-
Example OAuth service
sourceDescriptions:
- name: apim-auth
url: ./oauth.openapi.yaml
type: openapi
# This is how you can reference another workflow file
# - name: sample
# url: ./sample.arazzo.yml
# type: arazzo
workflows:
- workflowId: refresh-token-flow
summary: Refresh an access token
description: >-
This is how you can refresh an access token.
inputs:
type: object
properties:
my_client_id:
type: string
description: The client id
my_client_secret:
type: string
description: The client secret
my_redirect_uri:
type: string
description: The redirect uri
# refresh_token:
# type: string
# description: The refresh token
# # From authorization-code-flow.outputs.refresh_token
# # Or a previous refresh-token-flow.outputs.refresh_token
steps:
- stepId: do-the-auth-flow
description: >-
This is where you do the authorization code flow
workflowId: authorization-code-flow
parameters:
- name: client_id
value: $inputs.my_client_id
- name: redirect_uri
value: $inputs.my_redirect_uri
- name: client_secret
value: $inputs.my_client_secret
outputs:
my_refresh_token: $outputs.refresh_token
- stepId: do-the-refresh
description: >-
This is where you do the refresh
operationId: get-token
requestBody:
contentType: application/x-www-form-urlencoded
payload:
grant_type: refresh_token
refresh_token: $steps.do-the-auth-flow.outputs.my_refresh_token
successCriteria:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: jsonpath
outputs:
access_token: $response.body#/access_token
refresh_token: $response.body#/refresh_token
expires_in: $response.body#/expires_in
outputs:
access_token: $steps.do-the-refresh.outputs.access_token
refresh_token: $steps.do-the-refresh.outputs.refresh_token
expires_in: $steps.do-the-refresh.outputs.expires_in
- workflowId: client-credentials-flow
summary: Get an access token using client credentials
description: >-
This is how you can get an access token using client credentials.
inputs:
type: object
properties:
client_id:
type: string
description: The client id
client_secret:
type: string
description: The client secret
steps:
- stepId: get-client-creds-token
description: >-
This is where you get the token
operationId: get-token
requestBody:
contentType: application/x-www-form-urlencoded
payload:
client_id: $inputs.client_id
client_secret: $inputs.client_secret
grant_type: client_credentials
successCriteria:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: jsonpath
outputs:
access_token: $response.body#/access_token
outputs:
access_token: $steps.get-client-creds-token.outputs.access_token
- workflowId: authorization-code-flow
summary: Get an access token using an authorization code
description: >-
This is how you can get an access token using an authorization code.
inputs:
type: object
properties:
client_id:
type: string
description: The client id
client_secret:
type: string
description: The client secret
redirect_uri:
type: string
description: The redirect uri
steps:
- stepId: browser-authorize
description: >-
This URL is opened in the browser and redirects you back to
the registered redirect URI with an authorization code.
operationId: authorize
parameters:
- name: client_id
in: query
value: $inputs.client_id
- name: redirect_uri
in: query
value: $inputs.redirect_uri
- name: response_type
in: query
value: 'code'
- name: scope
in: query
value: 'read'
- name: state
in: query
value: '12345'
successCriteria:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: jsonpath
outputs:
code: $response.body#/code # Not really, this is a query parameter
- stepId: get-access-token
description: >-
This is where you get the token
operationId: get-token
requestBody:
contentType: application/x-www-form-urlencoded
payload:
grant_type: authorization_code
code: $steps.browser-authorize.outputs.code
redirect_uri: $inputs.redirect_uri
client_id: $inputs.client_id
client_secret: $inputs.client_secret
successCriteria:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: jsonpath
outputs:
access_token: $response.body#/access_token
refresh_token: $response.body#/refresh_token
expires_in: $response.body#/expires_in
outputs:
access_token: $steps.get-access-token.outputs.access_token
refresh_token: $steps.get-access-token.outputs.refresh_token
expires_in: $steps.get-access-token.outputs.expires_in
================================================
FILE: examples/1.0.0/oauth.openapi.yaml
================================================
openapi: 3.1.0
info:
title: Example OAuth service
version: 1.0.0
contact:
email: info@example.com
description: >-
OAuth service
x-optic-path-ignore:
- "**/*.+(ico|png|jpeg|jpg|gif)"
servers:
- url: https://auth.example.com
description: Example OAuth Production
paths:
/authorize:
get:
operationId: authorize
description: >-
This endpoint is used to authorize a user to access the Example API.
The user will be redirected to the login page if they are not already
logged in. If they are logged in, they will be asked to authorize the
application to access their account. If they accept, they will be
redirected back to the application with an authorization code.
parameters:
- name: client_id
in: query
required: true
schema:
type: string
- name: redirect_uri
in: query
required: true
schema:
type: string
- name: response_type
in: query
required: true
schema:
type: string
- name: scope
in: query
required: true
schema:
type: string
- name: state
in: query
required: true
schema:
type: string
responses:
"200":
description: 200 response
/oauth/token:
post:
operationId: get-token
description: >-
This endpoint is used to get an access token from an authorization code.
The authorization code is obtained from the authorize endpoint.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
grant_type:
type: string
code:
type: string
redirect_uri:
type: string
client_id:
type: string
client_secret:
type: string
required:
- grant_type
- client_id
responses:
"200":
description: 200 response
# callback:
# myCallback:
# '{$request.query.queryUrl}':
# post:
# requestBody:
# description: Callback payload
# content:
# 'application/json':
# schema:
# $ref: '#/components/schemas/SomePayload'
# responses:
# '200':
# description: callback successfully processed
================================================
FILE: examples/1.0.0/pet-coupons.arazzo.yaml
================================================
arazzo: 1.0.0
info:
title: Petstore - Apply Coupons
version: 1.0.0
description: >-
Illustrates a workflow whereby a client a) finds a pet in the petstore,
b) finds coupons for that pet, and finally
c) orders the pet while applying the coupons from step b.
sourceDescriptions:
- name: pet-coupons
url: ./pet-coupons.openapi.yaml
type: openapi
workflows:
- workflowId: apply-coupon
summary: Apply a coupon to a pet order.
description: >-
This is how you can find a pet, find an applicable coupon, and apply that coupon in your order.
The workflow concludes by outputting the ID of the placed order.
inputs:
$ref: "#/components/inputs/apply_coupon_input"
steps:
- stepId: find-pet
description: Find a pet based on the provided tags.
operationId: findPetsByTags
parameters:
- name: pet_tags
in: query
value: $inputs.my_pet_tags
successCriteria:
- condition: $statusCode == 200
outputs:
my_pet_id: $response.body#/0/id
# there is some implied selection here - findPetsByTags responds with a list of pets,
# but the client only wants to choose one, and that's what will be provided to the next step.
# not totally sure how to indicate that.
- stepId: find-coupons
description: Find a coupon available for the selected pet.
operationId: getPetCoupons
parameters:
- name: pet_id
in: path
value: $steps.find-pet.outputs.my_pet_id
successCriteria:
- condition: $statusCode == 200
outputs:
my_coupon_code: $response.body#/couponCode
- stepId: place-order
description: Place an order for the pet, applying the coupon.
workflowId: place-order
parameters:
- name: pet_id
value: $steps.find-pet.outputs.my_pet_id
- name: coupon_code
value: $steps.find-coupons.outputs.my_coupon_code
successCriteria:
- condition: $statusCode == 200
outputs:
my_order_id: $outputs.workflow_order_id
outputs:
apply_coupon_pet_order_id: $steps.place-order.outputs.my_order_id
- workflowId: buy-available-pet
summary: Buy an available pet if one is available.
description:
This workflow demonstrates a workflow very similar to `apply-coupon`, by intention.
It's meant to indicate how to reuse a step (`place-order`) as well as a parameter (`page`, `pageSize`).
inputs:
$ref: "#/components/inputs/buy_available_pet_input"
steps:
- stepId: find-pet
description: Find a pet that is available for purchase.
operationId: findPetsByStatus
parameters:
- name: status
in: query
value: "available"
- reference: $components.parameters.page
value: 1
- reference: $components.parameters.pageSize
value: 10
successCriteria:
- condition: $statusCode == 200
outputs:
my_pet_id: $response.body#/0/id
- stepId: place-order
description: Place an order for the pet.
workflowId: place-order
parameters:
- name: pet_id
value: $steps.find-pet.outputs.my_pet_id
successCriteria:
- condition: $statusCode == 200
outputs:
my_order_id: $outputs.workflow_order_id
outputs:
buy_pet_order_id: $steps.place-order.outputs.my_order_id
- workflowId: place-order
summary: Place an order for a pet.
description:
This workflow places an order for a pet. It may be reused by other workflows as the "final step" in a purchase.
inputs:
type: object
properties:
pet_id:
type: integer
format: int64
description: The ID of the pet to place in the order.
quantity:
type: integer
format: int32
description: The number of pets to place in the order.
coupon_code:
type: string
description: The coupon code to apply to the order.
steps:
- stepId: place-order
description: Place an order for the pet.
operationId: placeOrder
requestBody:
contentType: application/json
payload:
petId: $inputs.pet_id
quantity: $inputs.quantity
couponCode: $inputs.coupon_code
status: placed
complete: false
successCriteria:
- condition: $statusCode == 200
outputs:
step_order_id: $response.body#/id
outputs:
workflow_order_id: $steps.place-order.outputs.step_order_id
components:
inputs:
apply_coupon_input:
type: object
properties:
my_pet_tags:
type: array
items:
type: string
description: Desired tags to use when searching for a pet, in CSV format (e.g. "puppy, dalmatian")
store_id:
$ref: "#/components/inputs/store_id"
buy_available_pet_input:
type: object
properties:
store_id:
$ref: "#/components/inputs/store_id"
store_id:
type: string
description: Indicates the domain name of the store where the customer is browsing or buying pets, e.g. "pets.example.com" or "pets.example.co.uk".
parameters:
page:
name: page
in: query
value: 1
pageSize:
name: pageSize
in: query
value: 100
================================================
FILE: examples/1.0.0/pet-coupons.openapi.yaml
================================================
openapi: 3.0.3
info:
title: Swagger Petstore - OpenAPI 3.0
description: Modifies the standard Petstore example to illustrate a workflow in which coupons are discovered and then used in an order.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
tags:
- name: pet
description: Everything about your Pets
externalDocs:
description: Find out more
url: http://swagger.io
- name: store
description: Access to Petstore orders
externalDocs:
description: Find out more about our store
url: http://swagger.io
paths:
/pet:
put:
tags:
- pet
summary: Update an existing pet
description: Update an existing pet by Id
operationId: updatePet
requestBody:
description: Update an existent pet in the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
security:
- petstore_auth:
- write:pets
- read:pets
post:
tags:
- pet
summary: Add a new pet to the store
description: Add a new pet to the store
operationId: addPet
requestBody:
description: Create a new pet in the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
'405':
description: Invalid input
security:
- petstore_auth:
- write:pets
- read:pets
/pet/findByStatus:
get:
tags:
- pet
summary: Finds Pets by status
description: Multiple status values can be provided with comma separated strings
operationId: findPetsByStatus
parameters:
- name: status
in: query
description: Status values that need to be considered for filter
required: false
explode: true
schema:
type: string
default: available
enum:
- available
- pending
- sold
- name: page
in: query
description: Which page of results to display. First page is 1.
required: true
schema:
type: integer
format: int32
- name: pageSize
in: query
description: Number of results to display per page.
required: false
schema:
type: integer
format: int32
default: 10
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
'400':
description: Invalid status value
security:
- petstore_auth:
- write:pets
- read:pets
/pet/findByTags:
get:
tags:
- pet
summary: Finds Pets by tags
description: Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
operationId: findPetsByTags
parameters:
- name: tags
in: query
description: Tags to filter by
required: false
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
'400':
description: Invalid tag value
security:
- petstore_auth:
- write:pets
- read:pets
/pet/{petId}:
get:
tags:
- pet
summary: Find pet by ID
description: Returns a single pet
operationId: getPetById
parameters:
- name: petId
in: path
description: ID of pet to return
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
'400':
description: Invalid ID supplied
'404':
description: Pet not found
security:
- api_key: []
- petstore_auth:
- write:pets
- read:pets
post:
tags:
- pet
summary: Updates a pet in the store with form data
description: ''
operationId: updatePetWithForm
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
schema:
type: integer
format: int64
- name: name
in: query
description: Name of pet that needs to be updated
schema:
type: string
- name: status
in: query
description: Status of pet that needs to be updated
schema:
type: string
responses:
'405':
description: Invalid input
security:
- petstore_auth:
- write:pets
- read:pets
delete:
tags:
- pet
summary: Deletes a pet
description: delete a pet
operationId: deletePet
parameters:
- name: api_key
in: header
description: ''
required: false
schema:
type: string
- name: petId
in: path
description: Pet id to delete
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid pet value
security:
- petstore_auth:
- write:pets
- read:pets
/pet/{petId}/coupons:
get:
tags:
- pet
summary: Find a coupon available for a pet
description: Returns a coupon available for the pet, if applicable
operationId: getPetCoupons
parameters:
- name: petId
in: path
description: ID of pet with available coupons
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Coupon'
application/xml:
schema:
$ref: '#/components/schemas/Coupon'
'400':
description: Invalid ID supplied
'404':
description: Pet not found or coupon not available
security:
- api_key: []
- petstore_auth:
- read:pets
/store/order:
post:
tags:
- store
summary: Place an order for a pet
description: Place a new order in the store
operationId: placeOrder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Order'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
description: Invalid input
/store/order/{orderId}:
get:
tags:
- store
summary: Find purchase order by ID
description: For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
operationId: getOrderById
parameters:
- name: orderId
in: path
description: ID of order that needs to be fetched
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
'400':
description: Invalid ID supplied
'404':
description: Order not found
delete:
tags:
- store
summary: Delete purchase order by ID
description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
operationId: deleteOrder
parameters:
- name: orderId
in: path
description: ID of the order that needs to be deleted
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: integer
format: int64
example: 10
petId:
type: integer
format: int64
example: 198772
quantity:
type: integer
format: int32
example: 7
status:
type: string
description: Order Status
example: approved
enum:
- placed
- approved
- delivered
complete:
type: boolean
couponCode:
type: string
example: "SUMMERSALE"
xml:
name: order
Category:
type: object
properties:
id:
type: integer
format: int64
example: 1
name:
type: string
example: Dogs
xml:
name: category
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: tag
Pet:
required:
- name
- price
- photoUrls
type: object
properties:
id:
type: integer
format: int64
example: 10
name:
type: string
example: doggie
category:
$ref: '#/components/schemas/Category'
photoUrls:
type: array
xml:
wrapped: true
items:
type: string
xml:
name: photoUrl
price:
type: number
tags:
type: array
xml:
wrapped: true
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: pet status in the store
enum:
- available
- pending
- sold
xml:
name: pet
ApiResponse:
type: object
properties:
code:
type: integer
format: int32
type:
type: string
message:
type: string
xml:
name: '##default'
Coupon:
type: object
properties:
id:
type: integer
format: int64
example: 10
description:
type: string
example: "Summer Sale - 10% off!"
couponCode:
type: string
example: "SUMMERSALE"
xml:
name: coupon
requestBodies:
Pet:
description: Pet object that needs to be added to the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
securitySchemes:
petstore_auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://petstore3.swagger.io/oauth/authorize
scopes:
write:pets: modify pets in your account
read:pets: read your pets
api_key:
type: apiKey
name: api_key
in: header
================================================
FILE: package.json
================================================
{
"name": "arazzo",
"version": "1.0.0",
"description": "Arazzo Specification",
"scripts": {
"build": "bash ./scripts/md2html/build.sh",
"build-src": "npm run validate-markdown && bash ./scripts/md2html/build.sh src && bash ./scripts/schema-publish.sh src",
"test": "(c8 --100 vitest --watch=false || echo 'No vitest tests found — skipping...') && bash scripts/schema-test-coverage.sh",
"format-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml --fix src/arazzo.md && npx markdownlint-cli2 --fix *.md",
"validate-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml src/arazzo.md && npx markdownlint-cli2 *.md"
},
"repository": {
"type": "git",
"url": "https://github.com/OAI/Arazzo-Specification.git"
},
"keywords": [
"Arazzo",
"Workflows",
"Specification",
"API",
"Swagger",
"OpenAPI",
"OAS",
"OAI"
],
"author": {
"name": "OpenAPI Initiative - Arazzo Working Group",
"email": "tsc@openapis.org",
"url": "https://openapis.org/"
},
"readmeFilename": "README.md",
"license": "Apache-2.0",
"bugs": {
"url": "https://github.com/OAI/Arazzo-Specification/issues"
},
"homepage": "https://github.com/yourusername/your-project-name#readme",
"dependencies": {
"cheerio": "^1.2.0",
"highlight.js": "^11.11.1",
"markdown-it": "^14.1.1",
"respec": "35.9.0",
"yargs": "^18.0.0"
},
"devDependencies": {
"markdownlint-cli2": "^0.22.0",
"yaml": "2.8.3",
"@hyperjump/json-schema": "^1.17.5",
"c8": "^11.0.0",
"vitest": "^4.1.4"
}
}
================================================
FILE: scripts/md2html/.gitignore
================================================
*.err
input.bs
================================================
FILE: scripts/md2html/analytics/google.html
================================================
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-831873-42');
</script>
================================================
FILE: scripts/md2html/build.sh
================================================
#!/bin/bash
# Author: @frankkilcommins (inspired by the work of @MikeRalphson)
# Author: @MikeRalphson
# run this script from the root of the repo. It is designed to be run by a GitHub workflow.
#
# When run with no arguments, it builds artifacts for all published specification versions.
# It may also be run with a specific version argument, such as "1.0.1" or "latest"
# Finally, it may be run with "src" to build "src/arazzo.md"
#
# It contains bashisms
if [ "$1" = "src" ]; then
deploydir="deploy-preview"
else
deploydir="deploy/arazzo"
fi
mkdir -p $deploydir
mkdir -p $deploydir/js
mkdir -p $deploydir/temp
cp -p node_modules/respec/builds/respec-w3c.* $deploydir/js/
latest=$(git describe --abbrev=0 --tags)
allVersions=$(ls -1 versions/[123456789].*.md | sort -r)
if [ -z "$1" ]; then
specifications=$allVersions
elif [ "$1" = "latest" ]; then
specifications=$(ls -1 versions/$latest.md)
elif [ "$1" = "src" ]; then
specifications="src/arazzo.md"
else
specifications=$(ls -1 versions/$1.md)
fi
latestCopied="none"
lastMinor="-"
for specification in $specifications; do
version=$(basename $specification .md)
if [ "$1" = "src" ]; then
destination="$deploydir/$version.html"
else
destination="$deploydir/v$version.html"
fi
minorVersion=${version:0:3}
tempfile="$deploydir/temp/$version.html"
tempfile2="$deploydir/temp/$version-2.html"
echo === Building $version to $destination
node scripts/md2html/md2html.js --maintainers MAINTAINERS.md $specification "$allVersions" > $tempfile
npx respec --no-sandbox --use-local --src $tempfile --out $tempfile2
# remove unwanted Google Tag Manager and Google Analytics scripts
sed -e 's/<script type="text\/javascript" async="" src="https:\/\/www.google-analytics.com\/analytics.js"><\/script>//' \
-e 's/<script type="text\/javascript" async="" src="https:\/\/www.googletagmanager.com\/gtag\/js?id=G-[^"]*"><\/script>//' \
$tempfile2 > $destination
echo === Built $destination
if [ $version = $latest ]; then
if [[ ${version} != *"rc"* ]]; then
# version is not a Release Candidate
ln -sf $(basename $destination) $deploydir/latest.html
latestCopied="v$version"
fi
fi
if [ ${minorVersion} != ${lastMinor} ] && [[ ${minorVersion} =~ ^[3-9] ]]; then
ln -sf $(basename $destination) $deploydir/v$minorVersion.html
lastMinor=$minorVersion
fi
done
if [ "$latestCopied" != "none" ]; then
echo Latest tag is $latest, copied $latestCopied to latest.html
fi
rm -r $deploydir/js
rm -r $deploydir/temp
================================================
FILE: scripts/md2html/gist.css
================================================
/**
* GitHub Gist Theme
* Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro
*/
.hljs {
display: block;
background: white;
padding: 0.5em;
color: #333333;
overflow-x: auto;
}
.hljs-comment,
.hljs-meta {
color: #727070;
}
.hljs-string,
.hljs-variable,
.hljs-template-variable,
.hljs-strong,
.hljs-emphasis,
.hljs-quote {
color: #c74700;
}
.hljs-number {
color: #005e5e;
}
.hljs-keyword,
.hljs-selector-tag,
.hljs-type {
color: #a71d5d;
}
.hljs-literal,
.hljs-symbol,
.hljs-bullet,
.hljs-attribute {
color: #007aa2;
}
.hljs-section,
.hljs-name {
color: #4b7c46;
}
.hljs-tag {
color: #333333;
}
.hljs-title,
.hljs-attr,
.hljs-selector-id,
.hljs-selector-class,
.hljs-selector-attr,
.hljs-selector-pseudo {
color: #795da3;
}
.hljs-addition {
color: #55a532;
background-color: #eaffea;
}
.hljs-deletion {
color: #bd2c00;
background-color: #ffecec;
}
.hljs-link {
text-decoration: underline;
}
================================================
FILE: scripts/md2html/main.css
================================================
#respec-ui {
visibility: hidden;
}
#title {
color: #578000;
}
#subtitle {
color: #578000;
}
.dt-published {
color: #578000;
}
.dt-published::before {
content: "Published ";
}
h1, h2, h3, h4, h5, h6 {
color: #578000;
font-weight: normal;
font-style: normal;
}
a[href] {
color: #45512c;
}
body:not(.toc-inline) #toc h2 {
color: #45512c;
}
table {
display: block;
width: 100%;
overflow: auto;
}
table th {
font-weight: 600;
}
table th, table td {
padding: 6px 13px;
border: 1px solid #dfe2e5;
}
table tr {
background-color: #fff;
border-top: 1px solid #c6cbd1;
}
table tr:nth-child(2n) {
background-color: #f6f8fa;
}
pre {
background-color: #f6f8fa !important;
}
code {
color: #c83500
}
th code {
color: inherit
}
a.bibref {
text-decoration: underline;
}
body.darkmode {
--toclink-underline: #6a9000;
--toclink-visited-underline: #fff;
}
body.darkmode a,
body.darkmode .tocxref,
body.darkmode .u-url {
color: #6a9000;
}
body.darkmode code {
color: #e66c33;
}
body.darkmode:not(.toc-inline) #toc h2,
body.darkmode h1,
body.darkmode h2,
body.darkmode h3,
body.darkmode h4,
body.darkmode h5,
body.darkmode h6,
body.darkmode #title,
body.darkmode #subtitle,
body.darkmode .toc-inline,
body.darkmode .dt-published {
color: #7bb01c;
}
body.darkmode pre,
body.darkmode table tr:nth-child(2n),
body.darkmode table tr {
background-color: #1e1e1e !important;
color: #dcdcdc;
}
body.darkmode img {
background: transparent;
}
body.darkmode .logo img {
display: none;
}
body.darkmode .logo::before {
content: "";
display: inline-block;
height: 48px;
width: 175px;
background: url("https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/refs/heads/main/graphics/bitmap/OpenAPI_Logo_Pantone.png") no-repeat center / contain;
vertical-align: middle;
}
/** This contains the content of the https://www.w3.org/StyleSheets/TR/2021/dark.css file */
body.darkmode {
--text: #ddd;
--bg: black;
/* Absolute URLs due to https://bugs.webkit.org/show_bug.cgi?id=230243 */
--unofficial-watermark: url(https://www.w3.org/StyleSheets/TR/2021/logos/UD-watermark-dark-unofficial);
--draft-watermark: url(https://www.w3.org/StyleSheets/TR/2021/logos/UD-watermark-dark-draft);
--logo-bg: #1a5e9a;
--logo-active-bg: #c00;
--logo-text: white;
--tocnav-normal-text: #999;
--tocnav-normal-bg: var(--bg);
--tocnav-hover-text: var(--tocnav-normal-text);
--tocnav-hover-bg: #080808;
--tocnav-active-text: #f44;
--tocnav-active-bg: var(--tocnav-normal-bg);
--tocsidebar-text: var(--text);
--tocsidebar-bg: #080808;
--tocsidebar-shadow: rgba(255,255,255,.1);
--tocsidebar-heading-text: hsla(203,20%,40%,.7);
--toclink-text: var(--text);
--toclink-underline: #6af;
--toclink-visited-text: var(--toclink-text);
--toclink-visited-underline: #054572;
--heading-text: #8af;
--hr-text: var(--text);
--algo-border: #456;
--del-text: #f44;
--del-bg: transparent;
--ins-text: #4a4;
--ins-bg: transparent;
--a-normal-text: #6af;
--a-normal-underline: #555;
--a-visited-text: var(--a-normal-text);
--a-visited-underline: var(--a-normal-underline);
--a-hover-bg: rgba(25%, 25%, 25%, .2);
--a-active-text: #f44;
--a-active-underline: var(--a-active-text);
--borderedblock-bg: rgba(255, 255, 255, .05);
--blockquote-border: silver;
--blockquote-bg: var(--borderedblock-bg);
--blockquote-text: currentcolor;
--issue-border: #e05252;
--issue-bg: var(--borderedblock-bg);
--issue-text: var(--text);
--issueheading-text: hsl(0deg, 70%, 70%);
--example-border: hsl(50deg, 90%, 60%);
--example-bg: var(--borderedblock-bg);
--example-text: var(--text);
--exampleheading-text: hsl(50deg, 70%, 70%);
--note-border: hsl(120deg, 100%, 35%);
--note-bg: var(--borderedblock-bg);
--note-text: var(--text);
--noteheading-text: hsl(120, 70%, 70%);
--notesummary-underline: silver;
--advisement-border: orange;
--advisement-bg: #222218;
--advisement-text: var(--text);
--advisementheading-text: #f84;
--amendment-border: #330099;
--amendment-bg: var(--borderedblock-bg);
--amendment-text: var(--text);
--amendmentheading-text: #a086ff;
--amendment-border: #330099;
--amendment-bg: #080010;
--amendment-text: var(--text);
--amendmentheading-text: #cc00ff;
--warning-border: red;
--warning-bg: hsla(40,100%,20%,0.95);
--warning-text: var(--text);
--def-border: #8ccbf2;
--def-bg: #080818;
--def-text: var(--text);
--defrow-border: #136;
--datacell-border: silver;
--indexinfo-text: #aaa;
--indextable-hover-text: var(--text);
--indextable-hover-bg: #181818;
--outdatedspec-bg: rgba(255, 255, 255, .5);
--outdatedspec-text: black;
--outdated-bg: maroon;
--outdated-text: white;
--outdated-shadow: red;
--editedrec-bg: darkorange;
}
================================================
FILE: scripts/md2html/md2html.js
================================================
/* ReSpec supports markdown formatting, but this shows up on the page before being rendered
Hence we render the markdown to HTML ourselves, this gives us
complete control over formatting and syntax highlighting */
'use strict';
/**
@author Frank Kilcommins <frank.kilcommins@gmail.com> //heavily inspired by work by Mike Ralphson on the OpenAPI-Specifications repo
@author Mike Ralphson <mike.ralphson@gmail.com>
**/
const fs = require('fs');
const path = require('path');
const url = require('url');
const hljs = require('highlight.js');
const cheerio = require('cheerio');
let argv = require('yargs')
.boolean('respec')
.alias('r','respec')
.describe('respec','Output in respec format')
.default('respec',true)
.string('maintainers')
.alias('m','maintainers')
.describe('maintainers','path to MAINTAINERS.md')
.demandCommand(1)
.argv;
const abstract = 'What is the Arazzo Specification?';
let maintainers = [];
let emeritus = [];
const md = require('markdown-it')({
html: true,
linkify: true,
typographer: true,
highlight: function (str, lang) {
if (lang && hljs.getLanguage(lang)) { // && !argv.respec) {
try {
return '<pre class="nohighlight"><code>' +
hljs.highlight(str, { language: lang }).value +
'</code></pre>';
} catch (__) { }
}
return '<pre class="highlight '+lang+'"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
}
});
function preface(title,options) {
const respec = {
specStatus: "base",
latestVersion: "https://spec.openapis.org/arazzo/latest.html",
editors: maintainers,
formerEditors: emeritus,
publishDate: options.publishDate,
subtitle: 'Version '+options.subtitle,
edDraftURI: "https://github.com/OAI/Arazzo-Specification/",
shortName: "Arazzo",
historyURI: null, // prevent ReSpec from fetching a W3C history based on the shortName
lint: false,
logos:[{
src: "https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png",
alt: "OpenAPI Initiative",
height: 48,
url: "https://openapis.org/"}],
otherLinks: [
{
key: "Participate",
data: [
{
value: "GitHub OAI/Arazzo-Specification",
href: "https://github.com/OAI/Arazzo-Specification/",
},
{
value: "File a bug",
href: "https://github.com/OAI/Arazzo-Specification/issues",
},
{
value: "Commit history",
href: `https://github.com/OAI/Arazzo-Specification/commits/main/versions/${options.subtitle}.md`,
},
{
value: "Pull requests",
href: "https://github.com/OAI/Arazzo-Specification/pulls",
},
],
},
],
};
let preface = `<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>${md.utils.escapeHtml(title)}</title>`;
// SEO
preface += '<meta name="description" content="The Arazzo Specification provides a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions)">';
preface += '<link rel="canonical" href="https://spec.openapis.org/arazzo/latest.html" />';
if (options.respec) {
preface += '<meta name="color-scheme" content="light dark">';
preface += '<script src="../js/respec-w3c.js" class="remove"></script>';
preface += `<script class="remove">var respecConfig = ${JSON.stringify(respec)};</script>`;
try {
preface += fs.readFileSync('./analytics/google.html','utf8');
}
catch (ex) {}
preface += '</head><body>';
preface += '<style>';
preface += fs.readFileSync(path.resolve(__dirname,'main.css'),'utf8').split(/\r?\n/).join(' ');
preface += fs.readFileSync(path.resolve(__dirname,'gist.css'),'utf8').split(/\r?\n/).join(' ');
preface += '</style>';
preface += `<h1 id="title">${title.split('|')[0]}</h1>`;
preface += `<p class="copyright">Copyright © ${options.publishDate.getFullYear()} the Linux Foundation</p>`;
preface += `<section class="notoc" id="abstract"><h2>${abstract}</h2>`;
preface += 'The Arazzo Specification provides a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions).';
preface += '</section>';
preface += '<section class="override" id="sotd" data-max-toc="0">';
preface += '<h2>Status of This Document</h2>';
preface += 'The source-of-truth for the specification is the GitHub markdown file referenced above.';
preface += '</section>';
}
else {
preface += '</head><body>';
}
return preface;
}
function doMaintainers() {
let m = fs.readFileSync(argv.maintainers,'utf8');
let h = md.render(m);
let $ = cheerio.load(h);
let u = $('ul').first();
$(u).children('li').each(function(e){
let t = $(this).text().split('@')[0];
maintainers.push({name:t});
});
if ($("ul").length < 2) return;
u = $("ul").last();
$(u).children('li').each(function(e){
let t = $(this).text().split('@')[0];
emeritus.push({name:t});
});
}
function getPublishDate(m) {
let result = new Date();
let h = md.render(m);
let $ = cheerio.load(h);
$('table').each(function(i,table){
const h = $(table).find('th');
const headers = [];
$(h).each(function(i,header){
headers.push($(header).text());
});
if (headers.length >= 2 && headers[0] === 'Version' && headers[1] === 'Date') {
let c = $(table).find('tr').find('td');
let v = $(c[0]).text();
let d = $(c[1]).text();
argv.subtitle = v;
if (d !== 'TBA') result = new Date(d);
}
});
return result;
}
if (argv.maintainers) {
doMaintainers();
}
let s = fs.readFileSync(argv._[0],'utf8');
if (argv.respec) {
argv.publishDate = getPublishDate(s);
}
let lines = s.split(/\r?\n/);
let prevHeading = 0;
let lastIndent = 0;
let inTOC = false;
let inDefs = false;
let inCodeBlock = false;
let bsFix = true;
let indents = [0];
// process the markdown
for (let l in lines) {
let line = lines[l];
let linkTarget;
if (line.startsWith('## Table of Contents')) inTOC = true;
if (line.startsWith('<!-- /TOC')) inTOC = false;
if (inTOC) line = '';
if (line.startsWith('## Definitions')) {
inDefs = true;
bsFix = false;
}
else if (line.startsWith('## ')) inDefs = false;
if (line.startsWith('```')) {
inCodeBlock = !inCodeBlock;
line += '\n'; // fixes formatting of first line of syntax-highlighted blocks
}
if (!inCodeBlock && line.startsWith('#')) {
let indent = 0;
while (line[indent] === '#') indent++;
let originalIndent = indent;
let prevIndent = indents[indents.length-1]; // peek
let delta = indent-prevIndent;
if (!argv.respec) {
if (delta===0) indent = lastIndent
else if (delta<0) indent = lastIndent-1
else if (delta>0) indent = lastIndent+1;
}
if (indent < 0) {
indent = 1;
}
if (argv.respec && (indent > 1)) {
indent--;
}
let newIndent = indent;
if (!argv.respec && (indent <= 2) && bsFix) {
newIndent++;
gitextract_s0wd0_vf/
├── .github/
│ ├── CODEOWNERS
│ ├── ISSUE_TEMPLATE/
│ │ └── use-case-template.yml
│ ├── dependabot.yml
│ ├── templates/
│ │ └── agenda.md
│ └── workflows/
│ ├── auto-merge-dependabot.yml
│ ├── respec.yaml
│ ├── schema-publish.yaml
│ ├── schema-tests.yaml
│ └── validate-markdown.yaml
├── .gitignore
├── .markdownlint.yaml
├── CONTRIBUTING.md
├── LICENSE
├── MAINTAINERS.md
├── README.md
├── SPECIAL_INTEREST_GROUP.md
├── _archive_/
│ └── schemas/
│ └── v1.0/
│ ├── readme.md
│ ├── schema.json
│ └── schema.yaml
├── examples/
│ └── 1.0.0/
│ ├── ExtendedParametersExample.arazzo.yaml
│ ├── FAPI-PAR.arazzo.yaml
│ ├── FAPI-PAR.openapi.yaml
│ ├── LoginAndRetrievePets.arazzo.yaml
│ ├── README.md
│ ├── bnpl-arazzo.yaml
│ ├── bnpl-openapi.yaml
│ ├── oauth.arazzo.yaml
│ ├── oauth.openapi.yaml
│ ├── pet-coupons.arazzo.yaml
│ └── pet-coupons.openapi.yaml
├── package.json
├── scripts/
│ ├── md2html/
│ │ ├── .gitignore
│ │ ├── analytics/
│ │ │ └── google.html
│ │ ├── build.sh
│ │ ├── gist.css
│ │ ├── main.css
│ │ ├── md2html.js
│ │ ├── style-finish.html
│ │ ├── style-start.html
│ │ └── syntax-github.css
│ ├── schema-publish.sh
│ ├── schema-test-coverage.mjs
│ ├── schema-test-coverage.sh
│ ├── validate.mjs
│ └── yaml2json/
│ └── yaml2json.js
├── spec.markdownlint.yaml
└── versions/
├── 1.0.0.md
└── 1.0.1.md
SYMBOL INDEX (4 symbols across 2 files)
FILE: scripts/md2html/md2html.js
function preface (line 50) | function preface(title,options) {
function doMaintainers (line 127) | function doMaintainers() {
function getPublishDate (line 144) | function getPublishDate(m) {
FILE: scripts/yaml2json/yaml2json.js
function convert (line 8) | function convert(filename) {
Condensed preview — 48 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (333K chars).
[
{
"path": ".github/CODEOWNERS",
"chars": 26,
"preview": "* @OAI/arazzo-maintainers\n"
},
{
"path": ".github/ISSUE_TEMPLATE/use-case-template.yml",
"chars": 2093,
"preview": "name: \"Workflow-SIG Usecase Create Form\"\ndescription: \"Request form to describe a Workflow-SIG use case. Inorder to crea"
},
{
"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/templates/agenda.md",
"chars": 2394,
"preview": "## Bi-Weekly meetings happen on Wednesdays at 5PM GMT\n\nThis agenda gives visibility into discussion topics for the bi-we"
},
{
"path": ".github/workflows/auto-merge-dependabot.yml",
"chars": 792,
"preview": "name: Auto-merge dependabot updates\n\non:\n pull_request:\n branches: [ main ]\n\npermissions:\n pull-requests: write\n c"
},
{
"path": ".github/workflows/respec.yaml",
"chars": 2125,
"preview": "name: respec\n\n# author: @frankkilcommins (inspired by work from @MikeRalphson)\n\n#\n# This workflow creates a pull request"
},
{
"path": ".github/workflows/schema-publish.yaml",
"chars": 2280,
"preview": "name: schema-publish\n\n# author: @ralfhandl, @frankkilcommins\n\n#\n# This workflow creates a pull request for publishing sc"
},
{
"path": ".github/workflows/schema-tests.yaml",
"chars": 719,
"preview": "name: schema-tests\n\n# Author: @MikeRalphson / runs @jdesrosiers tests\n# Issue: https://github.com/OAI/OpenAPI-Specificat"
},
{
"path": ".github/workflows/validate-markdown.yaml",
"chars": 812,
"preview": "name: validate-markdown\n\n# Author: @MikeRalphson\n# Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130\n\n#\n# "
},
{
"path": ".gitignore",
"chars": 160,
"preview": ".vscode/settings.json\r\n.idea\r\n*.iml\r\n*.ipr\r\n*.iws\r\ntarget\r\natlassian-ide-plugin.xml\r\nnode_modules/\r\ndeploy/\r\ndeploy-prev"
},
{
"path": ".markdownlint.yaml",
"chars": 524,
"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": 5317,
"preview": "# Contribute to the Arazzo Specification\n\nWe welcome contributions and discussion.\nBug reports and feature requests are "
},
{
"path": "LICENSE",
"chars": 11357,
"preview": " Apache License\n Version 2.0, January 2004\n "
},
{
"path": "MAINTAINERS.md",
"chars": 240,
"preview": "# Arazzo Specification Maintainers\r\n\r\n## Active\r\n\r\n* Frank Kilcommins [@frankkilcommins](https://github.com/frankkilcomm"
},
{
"path": "README.md",
"chars": 3377,
"preview": "# The Arazzo Specification\r\n\r\n\r\n\r\nThe Arazzo Specification is a community-dr"
},
{
"path": "SPECIAL_INTEREST_GROUP.md",
"chars": 4039,
"preview": "# OpenAPI Initiative (OAI) Workflows Special Interest Group\r\n\r\nWork on the Arazzo Specification started under the remit "
},
{
"path": "_archive_/schemas/v1.0/readme.md",
"chars": 478,
"preview": "# Archive of outdated JSON Schema Files\n\n> [!TIP]\n> JSON Schema files for validating Arazzo descriptions using current A"
},
{
"path": "_archive_/schemas/v1.0/schema.json",
"chars": 31953,
"preview": "{\n \"$id\": \"https://spec.openapis.org/arazzo/1.0/schema/2024-08-01\",\n \"$schema\": \"https://json-schema.org/draft/202"
},
{
"path": "_archive_/schemas/v1.0/schema.yaml",
"chars": 18074,
"preview": "$id: 'https://spec.openapis.org/arazzo/1.0/schema/2024-08-01'\n$schema: 'https://json-schema.org/draft/2020-12/schema'\nde"
},
{
"path": "examples/1.0.0/ExtendedParametersExample.arazzo.yaml",
"chars": 654,
"preview": "arazzo: 1.0.0\ninfo:\n title: Public Zoo API\n version: '1.0'\nsourceDescriptions:\n - name: animals\n type: openapi\n "
},
{
"path": "examples/1.0.0/FAPI-PAR.arazzo.yaml",
"chars": 6092,
"preview": "arazzo: 1.0.0\r\ninfo:\r\n title: PAR, Authorization and Token workflow\r\n version: 1.0.0\r\n description: >-\r\n A workflo"
},
{
"path": "examples/1.0.0/FAPI-PAR.openapi.yaml",
"chars": 24337,
"preview": "openapi: '3.0.0'\r\ninfo:\r\n version: '1.0.0'\r\n title: 'Authentication API'\r\n description: |\r\n ## OAuth2 and OpenID "
},
{
"path": "examples/1.0.0/LoginAndRetrievePets.arazzo.yaml",
"chars": 2222,
"preview": "arazzo: 1.0.0\r\ninfo:\r\n title: A pet purchasing workflow\r\n summary: This workflow showcases how to purchase a pet t"
},
{
"path": "examples/1.0.0/README.md",
"chars": 611,
"preview": "# Workflows Specification Examples\r\n\r\n## Purpose\r\n\r\nThis README will provide details on the examples found in this direc"
},
{
"path": "examples/1.0.0/bnpl-arazzo.yaml",
"chars": 10343,
"preview": "arazzo: 1.0.0\ninfo:\n title: BNPL Workflow description\n description: >-\n Describes the steps to secure a loan at che"
},
{
"path": "examples/1.0.0/bnpl-openapi.yaml",
"chars": 16726,
"preview": "openapi: 3.0.0\ninfo:\n title: Arazzo Buy-now, Pay-later Loan API\n description: |\n This OpenAPI description provides"
},
{
"path": "examples/1.0.0/oauth.arazzo.yaml",
"chars": 5923,
"preview": "arazzo: 1.0.0\ninfo:\n title: Example OAuth service\n version: 1.0.0\n description: >-\n Example OAuth service\nsourceDe"
},
{
"path": "examples/1.0.0/oauth.openapi.yaml",
"chars": 2629,
"preview": "openapi: 3.1.0\ninfo:\n title: Example OAuth service\n version: 1.0.0\n contact: \n email: info@example.com\n descripti"
},
{
"path": "examples/1.0.0/pet-coupons.arazzo.yaml",
"chars": 5555,
"preview": "arazzo: 1.0.0\ninfo:\n title: Petstore - Apply Coupons\n version: 1.0.0\n description: >-\n Illustrates a workflow wher"
},
{
"path": "examples/1.0.0/pet-coupons.openapi.yaml",
"chars": 13988,
"preview": "openapi: 3.0.3\ninfo:\n title: Swagger Petstore - OpenAPI 3.0\n description: Modifies the standard Petstore example to il"
},
{
"path": "package.json",
"chars": 1816,
"preview": "\r\n{\r\n \"name\": \"arazzo\",\r\n \"version\": \"1.0.0\",\r\n \"description\": \"Arazzo Specification\",\r\n \"scripts\": {\r\n "
},
{
"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": 2558,
"preview": "#!/bin/bash\n\n# Author: @frankkilcommins (inspired by the work of @MikeRalphson)\n# Author: @MikeRalphson\n\n# run this scri"
},
{
"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": 12296,
"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": 2156,
"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/schema-test-coverage.mjs",
"chars": 3767,
"preview": "import { readdir, readFile } from \"node:fs/promises\";\nimport YAML from \"yaml\";\nimport { join } from \"node:path\";\nimport "
},
{
"path": "scripts/schema-test-coverage.sh",
"chars": 477,
"preview": "#!/usr/bin/env bash\n\n# Author: @ralfhandl\n\n# Run this script from the root of the repo\n\nSCHEMA_FILE=\"src/schemas/validat"
},
{
"path": "scripts/validate.mjs",
"chars": 2038,
"preview": "#!/usr/bin/env node\n\nimport { readFile } from \"node:fs/promises\";\nimport YAML from \"yaml\";\nimport { setMetaSchemaOutputF"
},
{
"path": "scripts/yaml2json/yaml2json.js",
"chars": 645,
"preview": "#!/usr/bin/env node\n\n'use strict';\n\nconst fs = require('fs');\nconst yaml = require('yaml');\n\nfunction convert(filename) "
},
{
"path": "spec.markdownlint.yaml",
"chars": 431,
"preview": "# Heading style (ATX is leading # symbols)\nMD003:\n style: atx\n\n# Unordered list symbol must be *\nMD004:\n style: asteri"
},
{
"path": "versions/1.0.0.md",
"chars": 53726,
"preview": "# Arazzo Specification\n\n#### Version 1.0.0\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\""
},
{
"path": "versions/1.0.1.md",
"chars": 54061,
"preview": "# Arazzo Specification\n\n#### Version 1.0.1\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\""
}
]
About this extraction
This page contains the full source code of the OAI/Arazzo-Specification GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 48 files (310.6 KB), approximately 71.5k 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.