diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml index 8c4716c..606fa20 100644 --- a/.github/workflows/validate-markdown.yaml +++ b/.github/workflows/validate-markdown.yaml @@ -1,10 +1,9 @@ name: validate-markdown -# Author: @MikeRalphson -# Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130 +# Author: @ralfhandl based on work of @MikeRalphson # -# This workflow validates files in the versions directory matching 1.*.md +# This workflow validates markdown files in the `versions` and `schemas` directories matching *.md # # run this on push to any branch and creation of pull-requests @@ -16,10 +15,16 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 # checkout repo content - - uses: actions/setup-node@v1 # setup Node.js + - uses: actions/checkout@v4 # checkout repo content with: - node-version: '18.x' + fetch-depth: 0 + # - name: use the javascript environment from main + # run: | + # git checkout remotes/origin/main -- package.json package-lock.json .markdownlint.yaml + - uses: actions/setup-node@v4 # setup Node.js + with: + node-version: '20.x' - name: Validate markdown - run: npx mdv versions/1.*.md - + run: npx --yes mdv versions/*.md + - name: Lint markdown + run: npx --yes markdownlint-cli --config .markdownlint.yaml ./{versions,schemas/**}/*.md diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..3f95ad4 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,12 @@ +# Unordered list indentation +MD007: + indent: 2 + +MD012: false # allow blank lines + +MD013: + line_length: 800 + tables: false + +MD024: false # duplicate headings +MD033: false # inline HTML diff --git a/package-lock.json b/package-lock.json index fdf4595..7f3e522 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,10 +12,11 @@ "cheerio": "^1.0.0-rc.5", "highlight.js": "^11.9.0", "markdown-it": "^14.1.0", - "respec": "^35.1.1", + "respec": "35.1.1", "yargs": "^17.7.2" }, "devDependencies": { + "markdownlint-cli": "^0.42.0", "mdv": "^1.3.4", "yaml": "2.4.2" } @@ -57,6 +58,109 @@ "node": ">=6.9.0" } }, + "node_modules/@isaacs/cliui": { + "version": "8.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/@isaacs/cliui/-/cliui-8.0.2.tgz", + "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", + "dev": true, + "license": "ISC", + "dependencies": { + "string-width": "^5.1.2", + "string-width-cjs": "npm:string-width@^4.2.0", + "strip-ansi": "^7.0.1", + "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", + "wrap-ansi": "^8.1.0", + "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@isaacs/cliui/node_modules/ansi-regex": { + "version": "6.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ansi-regex/-/ansi-regex-6.1.0.tgz", + "integrity": "sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/@isaacs/cliui/node_modules/ansi-styles": { + "version": "6.2.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ansi-styles/-/ansi-styles-6.2.1.tgz", + "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/@isaacs/cliui/node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@isaacs/cliui/node_modules/string-width": { + "version": "5.1.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@isaacs/cliui/node_modules/strip-ansi": { + "version": "7.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/strip-ansi/-/strip-ansi-7.1.0.tgz", + "integrity": "sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/@isaacs/cliui/node_modules/wrap-ansi": { + "version": "8.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/wrap-ansi/-/wrap-ansi-8.1.0.tgz", + "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.1.0", + "string-width": "^5.0.1", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, "node_modules/@puppeteer/browsers": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/@puppeteer/browsers/-/browsers-2.3.0.tgz", @@ -491,6 +595,16 @@ "node": ">=0.1.90" } }, + "node_modules/commander": { + "version": "12.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/commander/-/commander-12.1.0.tgz", + "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, "node_modules/concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", @@ -523,6 +637,21 @@ } } }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/css-select": { "version": "5.1.0", "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.1.0.tgz", @@ -567,6 +696,16 @@ "ms": "2.0.0" } }, + "node_modules/deep-extend": { + "version": "0.6.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/deep-extend/-/deep-extend-0.6.0.tgz", + "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4.0.0" + } + }, "node_modules/define-lazy-prop": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz", @@ -675,6 +814,13 @@ "url": "https://github.com/fb55/domutils?sponsor=1" } }, + "node_modules/eastasianwidth": { + "version": "0.2.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/eastasianwidth/-/eastasianwidth-0.2.0.tgz", + "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==", + "dev": true, + "license": "MIT" + }, "node_modules/ee-first": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", @@ -893,6 +1039,23 @@ "node": ">= 0.8" } }, + "node_modules/foreground-child": { + "version": "3.3.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/foreground-child/-/foreground-child-3.3.0.tgz", + "integrity": "sha512-Ld2g8rrAyMYFXBhEqMz8ZAHBi4J4uS1i/CxGMDnjyFWddMXLVcDp051DZfu+t7+ab7Wv6SMqpWmyFIj5UbfFvg==", + "dev": true, + "license": "ISC", + "dependencies": { + "cross-spawn": "^7.0.0", + "signal-exit": "^4.0.1" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/fresh": { "version": "0.5.2", "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", @@ -930,6 +1093,19 @@ "node": "6.* || 8.* || >= 10.*" } }, + "node_modules/get-stdin": { + "version": "9.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/get-stdin/-/get-stdin-9.0.0.tgz", + "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/get-stream": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz", @@ -1152,6 +1328,16 @@ ], "license": "BSD-3-Clause" }, + "node_modules/ignore": { + "version": "6.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ignore/-/ignore-6.0.2.tgz", + "integrity": "sha512-InwqeHHN2XpumIkMvpl/DCJVrAHgCsG5+cn1XlnLWGwtZBm8QJfSusItfrwx81CTp5agNZqpKU2J/ccC5nGT4A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, "node_modules/import-fresh": { "version": "3.3.0", "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", @@ -1184,6 +1370,16 @@ "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==" }, + "node_modules/ini": { + "version": "4.1.3", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ini/-/ini-4.1.3.tgz", + "integrity": "sha512-X7rqawQBvfdjS10YU1y1YVreA3SsLrW9dX2CewP2EbBJM4ypVNLDkO5y04gejPwKIY9lR+7r9gn3rFPt/kmWFg==", + "dev": true, + "license": "ISC", + "engines": { + "node": "^14.17.0 || ^16.13.0 || >=18.0.0" + } + }, "node_modules/ip-address": { "version": "9.0.5", "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-9.0.5.tgz", @@ -1238,6 +1434,29 @@ "node": ">=8" } }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, + "license": "ISC" + }, + "node_modules/jackspeak": { + "version": "4.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/jackspeak/-/jackspeak-4.0.2.tgz", + "integrity": "sha512-bZsjR/iRjl1Nk1UkjGpAzLNfQtzuijhn2g+pbZb98HQ1Gk8vM9hfbxeMBP+M2/UUdwj0RqGG3mlvk2MsAqwvEw==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/cliui": "^8.0.2" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/jgexml": { "version": "0.4.4", "resolved": "https://registry.npmjs.org/jgexml/-/jgexml-0.4.4.tgz", @@ -1279,6 +1498,13 @@ "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==", "license": "MIT" }, + "node_modules/jsonc-parser": { + "version": "3.3.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/jsonc-parser/-/jsonc-parser-3.3.1.tgz", + "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==", + "dev": true, + "license": "MIT" + }, "node_modules/jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -1291,6 +1517,16 @@ "graceful-fs": "^4.1.6" } }, + "node_modules/jsonpointer": { + "version": "5.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/jsonpointer/-/jsonpointer-5.0.1.tgz", + "integrity": "sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/lines-and-columns": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", @@ -1348,6 +1584,112 @@ "markdown-it": "bin/markdown-it.mjs" } }, + "node_modules/markdownlint": { + "version": "0.35.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/markdownlint/-/markdownlint-0.35.0.tgz", + "integrity": "sha512-wgp8yesWjFBL7bycA3hxwHRdsZGJhjhyP1dSxKVKrza0EPFYtn+mHtkVy6dvP1kGSjovyG5B8yNP6Frj0UFUJg==", + "dev": true, + "license": "MIT", + "dependencies": { + "markdown-it": "14.1.0", + "markdownlint-micromark": "0.1.10" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, + "node_modules/markdownlint-cli": { + "version": "0.42.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/markdownlint-cli/-/markdownlint-cli-0.42.0.tgz", + "integrity": "sha512-AjkzhhZa3TmEGi/CE2Wpmny69x1IrzqK2gPB0k8SmNMRgnSAJfyEO5FgZdWTHtJ6Nrdv5FWt5c4C5pkG6Dk30A==", + "dev": true, + "license": "MIT", + "dependencies": { + "commander": "~12.1.0", + "get-stdin": "~9.0.0", + "glob": "~11.0.0", + "ignore": "~6.0.2", + "js-yaml": "^4.1.0", + "jsonc-parser": "~3.3.1", + "jsonpointer": "5.0.1", + "markdownlint": "~0.35.0", + "minimatch": "~10.0.1", + "run-con": "~1.3.2", + "smol-toml": "~1.3.0" + }, + "bin": { + "markdownlint": "markdownlint.js" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/markdownlint-cli/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/markdownlint-cli/node_modules/glob": { + "version": "11.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/glob/-/glob-11.0.0.tgz", + "integrity": "sha512-9UiX/Bl6J2yaBbxKoEBRm4Cipxgok8kQYcOPEhScPwebu2I0HoQOuYdIO6S3hLuWoZgpDpwQZMzTFxgpkyT76g==", + "dev": true, + "license": "ISC", + "dependencies": { + "foreground-child": "^3.1.0", + "jackspeak": "^4.0.1", + "minimatch": "^10.0.0", + "minipass": "^7.1.2", + "package-json-from-dist": "^1.0.0", + "path-scurry": "^2.0.0" + }, + "bin": { + "glob": "dist/esm/bin.mjs" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/markdownlint-cli/node_modules/minimatch": { + "version": "10.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/minimatch/-/minimatch-10.0.1.tgz", + "integrity": "sha512-ethXTt3SGGR+95gudmqJ1eNhRO7eGEGIgYA9vnPatK4/etz2MEVDno5GMCibdMTuBMyElzIlgxMna3K94XDIDQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/markdownlint-micromark": { + "version": "0.1.10", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/markdownlint-micromark/-/markdownlint-micromark-0.1.10.tgz", + "integrity": "sha512-no5ZfdqAdWGxftCLlySHSgddEjyW4kui4z7amQcGsSKfYC5v/ou+8mIQVyg9KQMeEZLNtz9OPDTj7nnTnoR4FQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, "node_modules/marked": { "version": "12.0.2", "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz", @@ -1458,6 +1800,26 @@ "node": "*" } }, + "node_modules/minimist": { + "version": "1.2.8", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/minipass": { + "version": "7.1.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/minipass/-/minipass-7.1.2.tgz", + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, "node_modules/mitt": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz", @@ -1591,6 +1953,13 @@ "node": ">= 14" } }, + "node_modules/package-json-from-dist": { + "version": "1.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", + "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", + "dev": true, + "license": "BlueOak-1.0.0" + }, "node_modules/parent-module": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", @@ -1662,6 +2031,43 @@ "node": ">=0.10.0" } }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-scurry": { + "version": "2.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/path-scurry/-/path-scurry-2.0.0.tgz", + "integrity": "sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^11.0.0", + "minipass": "^7.1.2" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/path-scurry/node_modules/lru-cache": { + "version": "11.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/lru-cache/-/lru-cache-11.0.2.tgz", + "integrity": "sha512-123qHRfJBmo2jXDbo/a5YOQrJoHF/GNQTLzQ5+IdK5pWpceK17yRc6ozlWd25FxvGKQbIUs91fDFkXmDHTKcyA==", + "dev": true, + "license": "ISC", + "engines": { + "node": "20 || >=22" + } + }, "node_modules/pend": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz", @@ -1885,6 +2291,22 @@ "lodash.uniq": "^4.5.0" } }, + "node_modules/run-con": { + "version": "1.3.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/run-con/-/run-con-1.3.2.tgz", + "integrity": "sha512-CcfE+mYiTcKEzg0IqS08+efdnH0oJ3zV0wSUFBNrMHMuxCtXvBCLzCJHatwuXDcu/RlhjTziTo/a1ruQik6/Yg==", + "dev": true, + "license": "(BSD-2-Clause OR MIT OR Apache-2.0)", + "dependencies": { + "deep-extend": "^0.6.0", + "ini": "~4.1.0", + "minimist": "^1.2.8", + "strip-json-comments": "~3.1.1" + }, + "bin": { + "run-con": "cli.js" + } + }, "node_modules/sade": { "version": "1.8.1", "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz", @@ -1960,6 +2382,42 @@ "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", "license": "ISC" }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/smart-buffer": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz", @@ -1970,6 +2428,19 @@ "npm": ">= 3.0.0" } }, + "node_modules/smol-toml": { + "version": "1.3.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/smol-toml/-/smol-toml-1.3.1.tgz", + "integrity": "sha512-tEYNll18pPKHroYSmLLrksq233j021G0giwW7P3D24jC54pQ5W5BXMsQ/Mvw1OJCmEYDgY+lrzT+3nNUtoNfXQ==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">= 18" + }, + "funding": { + "url": "https://github.com/sponsors/cyyynthia" + } + }, "node_modules/socks": { "version": "2.8.3", "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.3.tgz", @@ -2073,6 +2544,22 @@ "node": ">=8" } }, + "node_modules/string-width-cjs": { + "name": "string-width", + "version": "4.2.3", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/strip-ansi": { "version": "6.0.1", "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", @@ -2084,6 +2571,33 @@ "node": ">=8" } }, + "node_modules/strip-ansi-cjs": { + "name": "strip-ansi", + "version": "6.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-json-comments": { + "version": "3.1.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/supports-color": { "version": "5.5.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", @@ -2197,6 +2711,22 @@ "integrity": "sha512-H/A06tKD7sS1O1X2SshBVeA5FLycRpjqiBeqGKmBwBDBy28EnRjORxTNe269KSSr5un5qyWi1iL61wLxpd+ZOg==", "license": "MIT" }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/wrap-ansi": { "version": "7.0.0", "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", @@ -2213,6 +2743,25 @@ "url": "https://github.com/chalk/wrap-ansi?sponsor=1" } }, + "node_modules/wrap-ansi-cjs": { + "name": "wrap-ansi", + "version": "7.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, "node_modules/wrappy": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", @@ -2330,6 +2879,71 @@ "picocolors": "^1.0.0" } }, + "@isaacs/cliui": { + "version": "8.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/@isaacs/cliui/-/cliui-8.0.2.tgz", + "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", + "dev": true, + "requires": { + "string-width": "^5.1.2", + "string-width-cjs": "npm:string-width@^4.2.0", + "strip-ansi": "^7.0.1", + "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", + "wrap-ansi": "^8.1.0", + "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" + }, + "dependencies": { + "ansi-regex": { + "version": "6.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ansi-regex/-/ansi-regex-6.1.0.tgz", + "integrity": "sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA==", + "dev": true + }, + "ansi-styles": { + "version": "6.2.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ansi-styles/-/ansi-styles-6.2.1.tgz", + "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==", + "dev": true + }, + "emoji-regex": { + "version": "9.2.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "dev": true + }, + "string-width": { + "version": "5.1.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "dev": true, + "requires": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + } + }, + "strip-ansi": { + "version": "7.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/strip-ansi/-/strip-ansi-7.1.0.tgz", + "integrity": "sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==", + "dev": true, + "requires": { + "ansi-regex": "^6.0.1" + } + }, + "wrap-ansi": { + "version": "8.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/wrap-ansi/-/wrap-ansi-8.1.0.tgz", + "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", + "dev": true, + "requires": { + "ansi-styles": "^6.1.0", + "string-width": "^5.0.1", + "strip-ansi": "^7.0.1" + } + } + } + }, "@puppeteer/browsers": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/@puppeteer/browsers/-/browsers-2.3.0.tgz", @@ -2635,6 +3249,12 @@ "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz", "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA==" }, + "commander": { + "version": "12.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/commander/-/commander-12.1.0.tgz", + "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==", + "dev": true + }, "concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", @@ -2652,6 +3272,17 @@ "parse-json": "^5.2.0" } }, + "cross-spawn": { + "version": "7.0.6", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, + "requires": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + } + }, "css-select": { "version": "5.1.0", "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.1.0.tgz", @@ -2682,6 +3313,12 @@ "ms": "2.0.0" } }, + "deep-extend": { + "version": "0.6.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/deep-extend/-/deep-extend-0.6.0.tgz", + "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==", + "dev": true + }, "define-lazy-prop": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz", @@ -2752,6 +3389,12 @@ "domhandler": "^5.0.3" } }, + "eastasianwidth": { + "version": "0.2.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/eastasianwidth/-/eastasianwidth-0.2.0.tgz", + "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==", + "dev": true + }, "ee-first": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", @@ -2892,6 +3535,16 @@ "unpipe": "~1.0.0" } }, + "foreground-child": { + "version": "3.3.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/foreground-child/-/foreground-child-3.3.0.tgz", + "integrity": "sha512-Ld2g8rrAyMYFXBhEqMz8ZAHBi4J4uS1i/CxGMDnjyFWddMXLVcDp051DZfu+t7+ab7Wv6SMqpWmyFIj5UbfFvg==", + "dev": true, + "requires": { + "cross-spawn": "^7.0.0", + "signal-exit": "^4.0.1" + } + }, "fresh": { "version": "0.5.2", "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", @@ -2918,6 +3571,12 @@ "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==" }, + "get-stdin": { + "version": "9.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/get-stdin/-/get-stdin-9.0.0.tgz", + "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==", + "dev": true + }, "get-stream": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz", @@ -3057,6 +3716,12 @@ "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==" }, + "ignore": { + "version": "6.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ignore/-/ignore-6.0.2.tgz", + "integrity": "sha512-InwqeHHN2XpumIkMvpl/DCJVrAHgCsG5+cn1XlnLWGwtZBm8QJfSusItfrwx81CTp5agNZqpKU2J/ccC5nGT4A==", + "dev": true + }, "import-fresh": { "version": "3.3.0", "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", @@ -3081,6 +3746,12 @@ "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==" }, + "ini": { + "version": "4.1.3", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/ini/-/ini-4.1.3.tgz", + "integrity": "sha512-X7rqawQBvfdjS10YU1y1YVreA3SsLrW9dX2CewP2EbBJM4ypVNLDkO5y04gejPwKIY9lR+7r9gn3rFPt/kmWFg==", + "dev": true + }, "ip-address": { "version": "9.0.5", "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-9.0.5.tgz", @@ -3115,6 +3786,21 @@ "is-docker": "^2.0.0" } }, + "isexe": { + "version": "2.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true + }, + "jackspeak": { + "version": "4.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/jackspeak/-/jackspeak-4.0.2.tgz", + "integrity": "sha512-bZsjR/iRjl1Nk1UkjGpAzLNfQtzuijhn2g+pbZb98HQ1Gk8vM9hfbxeMBP+M2/UUdwj0RqGG3mlvk2MsAqwvEw==", + "dev": true, + "requires": { + "@isaacs/cliui": "^8.0.2" + } + }, "jgexml": { "version": "0.4.4", "resolved": "https://registry.npmjs.org/jgexml/-/jgexml-0.4.4.tgz", @@ -3144,6 +3830,12 @@ "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz", "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==" }, + "jsonc-parser": { + "version": "3.3.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/jsonc-parser/-/jsonc-parser-3.3.1.tgz", + "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==", + "dev": true + }, "jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -3153,6 +3845,12 @@ "universalify": "^2.0.0" } }, + "jsonpointer": { + "version": "5.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/jsonpointer/-/jsonpointer-5.0.1.tgz", + "integrity": "sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==", + "dev": true + }, "lines-and-columns": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", @@ -3202,6 +3900,75 @@ "uc.micro": "^2.1.0" } }, + "markdownlint": { + "version": "0.35.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/markdownlint/-/markdownlint-0.35.0.tgz", + "integrity": "sha512-wgp8yesWjFBL7bycA3hxwHRdsZGJhjhyP1dSxKVKrza0EPFYtn+mHtkVy6dvP1kGSjovyG5B8yNP6Frj0UFUJg==", + "dev": true, + "requires": { + "markdown-it": "14.1.0", + "markdownlint-micromark": "0.1.10" + } + }, + "markdownlint-cli": { + "version": "0.42.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/markdownlint-cli/-/markdownlint-cli-0.42.0.tgz", + "integrity": "sha512-AjkzhhZa3TmEGi/CE2Wpmny69x1IrzqK2gPB0k8SmNMRgnSAJfyEO5FgZdWTHtJ6Nrdv5FWt5c4C5pkG6Dk30A==", + "dev": true, + "requires": { + "commander": "~12.1.0", + "get-stdin": "~9.0.0", + "glob": "~11.0.0", + "ignore": "~6.0.2", + "js-yaml": "^4.1.0", + "jsonc-parser": "~3.3.1", + "jsonpointer": "5.0.1", + "markdownlint": "~0.35.0", + "minimatch": "~10.0.1", + "run-con": "~1.3.2", + "smol-toml": "~1.3.0" + }, + "dependencies": { + "brace-expansion": { + "version": "2.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "requires": { + "balanced-match": "^1.0.0" + } + }, + "glob": { + "version": "11.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/glob/-/glob-11.0.0.tgz", + "integrity": "sha512-9UiX/Bl6J2yaBbxKoEBRm4Cipxgok8kQYcOPEhScPwebu2I0HoQOuYdIO6S3hLuWoZgpDpwQZMzTFxgpkyT76g==", + "dev": true, + "requires": { + "foreground-child": "^3.1.0", + "jackspeak": "^4.0.1", + "minimatch": "^10.0.0", + "minipass": "^7.1.2", + "package-json-from-dist": "^1.0.0", + "path-scurry": "^2.0.0" + } + }, + "minimatch": { + "version": "10.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/minimatch/-/minimatch-10.0.1.tgz", + "integrity": "sha512-ethXTt3SGGR+95gudmqJ1eNhRO7eGEGIgYA9vnPatK4/etz2MEVDno5GMCibdMTuBMyElzIlgxMna3K94XDIDQ==", + "dev": true, + "requires": { + "brace-expansion": "^2.0.1" + } + } + } + }, + "markdownlint-micromark": { + "version": "0.1.10", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/markdownlint-micromark/-/markdownlint-micromark-0.1.10.tgz", + "integrity": "sha512-no5ZfdqAdWGxftCLlySHSgddEjyW4kui4z7amQcGsSKfYC5v/ou+8mIQVyg9KQMeEZLNtz9OPDTj7nnTnoR4FQ==", + "dev": true + }, "marked": { "version": "12.0.2", "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz", @@ -3285,6 +4052,18 @@ "brace-expansion": "^1.1.7" } }, + "minimist": { + "version": "1.2.8", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==", + "dev": true + }, + "minipass": { + "version": "7.1.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/minipass/-/minipass-7.1.2.tgz", + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "dev": true + }, "mitt": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz", @@ -3379,6 +4158,12 @@ "netmask": "^2.0.2" } }, + "package-json-from-dist": { + "version": "1.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", + "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", + "dev": true + }, "parent-module": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", @@ -3426,6 +4211,30 @@ "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", "dev": true }, + "path-key": { + "version": "3.1.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true + }, + "path-scurry": { + "version": "2.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/path-scurry/-/path-scurry-2.0.0.tgz", + "integrity": "sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==", + "dev": true, + "requires": { + "lru-cache": "^11.0.0", + "minipass": "^7.1.2" + }, + "dependencies": { + "lru-cache": { + "version": "11.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/lru-cache/-/lru-cache-11.0.2.tgz", + "integrity": "sha512-123qHRfJBmo2jXDbo/a5YOQrJoHF/GNQTLzQ5+IdK5pWpceK17yRc6ozlWd25FxvGKQbIUs91fDFkXmDHTKcyA==", + "dev": true + } + } + }, "pend": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz", @@ -3579,6 +4388,18 @@ "lodash.uniq": "^4.5.0" } }, + "run-con": { + "version": "1.3.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/run-con/-/run-con-1.3.2.tgz", + "integrity": "sha512-CcfE+mYiTcKEzg0IqS08+efdnH0oJ3zV0wSUFBNrMHMuxCtXvBCLzCJHatwuXDcu/RlhjTziTo/a1ruQik6/Yg==", + "dev": true, + "requires": { + "deep-extend": "^0.6.0", + "ini": "~4.1.0", + "minimist": "^1.2.8", + "strip-json-comments": "~3.1.1" + } + }, "sade": { "version": "1.8.1", "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz", @@ -3635,11 +4456,38 @@ "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==" }, + "shebang-command": { + "version": "2.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "requires": { + "shebang-regex": "^3.0.0" + } + }, + "shebang-regex": { + "version": "3.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true + }, + "signal-exit": { + "version": "4.1.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true + }, "smart-buffer": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz", "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==" }, + "smol-toml": { + "version": "1.3.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/smol-toml/-/smol-toml-1.3.1.tgz", + "integrity": "sha512-tEYNll18pPKHroYSmLLrksq233j021G0giwW7P3D24jC54pQ5W5BXMsQ/Mvw1OJCmEYDgY+lrzT+3nNUtoNfXQ==", + "dev": true + }, "socks": { "version": "2.8.3", "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.3.tgz", @@ -3711,6 +4559,17 @@ "strip-ansi": "^6.0.1" } }, + "string-width-cjs": { + "version": "npm:string-width@4.2.3", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, "strip-ansi": { "version": "6.0.1", "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", @@ -3719,6 +4578,21 @@ "ansi-regex": "^5.0.1" } }, + "strip-ansi-cjs": { + "version": "npm:strip-ansi@6.0.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "strip-json-comments": { + "version": "3.1.1", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "dev": true + }, "supports-color": { "version": "5.5.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", @@ -3806,6 +4680,15 @@ "resolved": "https://registry.npmjs.org/urlpattern-polyfill/-/urlpattern-polyfill-10.0.0.tgz", "integrity": "sha512-H/A06tKD7sS1O1X2SshBVeA5FLycRpjqiBeqGKmBwBDBy28EnRjORxTNe269KSSr5un5qyWi1iL61wLxpd+ZOg==" }, + "which": { + "version": "2.0.2", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + }, "wrap-ansi": { "version": "7.0.0", "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", @@ -3816,6 +4699,17 @@ "strip-ansi": "^6.0.0" } }, + "wrap-ansi-cjs": { + "version": "npm:wrap-ansi@7.0.0", + "resolved": "https://artifactory.us.caas.oneadp.com/artifactory/api/npm/npm/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "requires": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + } + }, "wrappy": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", diff --git a/package.json b/package.json index ecdeb2d..d0fbf91 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,8 @@ "description": "Arazzo Specification", "scripts": { "build": "bash ./scripts/md2html/build.sh", - "test": "echo \"Error: no test specified\" && exit 1" + "test": "echo \"Error: no test specified\" && exit 1", + "format-markdown": "bash ./scripts/format-markdown.sh ./{versions,schemas/**}/*.md" }, "repository": { "type": "git", @@ -37,6 +38,7 @@ }, "devDependencies": { "mdv": "^1.3.4", - "yaml": "2.4.2" + "yaml": "2.4.2", + "markdownlint-cli": "^0.42.0" } } diff --git a/scripts/format-markdown.sh b/scripts/format-markdown.sh new file mode 100644 index 0000000..c04b971 --- /dev/null +++ b/scripts/format-markdown.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +SRCDIR="$(dirname "${BASH_SOURCE[0]}")" # check on Windows + +for filename in $*; do + # mostly to format code blocks with examples, unfortunately messes up bullet lists and tables + npx prettier --write --single-quote $filename + + # repair the tables: remove superfluos spaces and dashes that make diffing revisions harder + # and sed -i is not portable, so we need to use a temporary file + sed -E -e "s/ +\|/ |/g" -e "s/\| +/| /g" -e "s/-----+/----/g" $filename > $filename.tmp && mv $filename.tmp $filename + + # repair the bullet lists and various other markdown formatting issues + npx --yes markdownlint-cli --fix --config $SRCDIR/../.markdownlint.yaml $filename +done diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d629203..696ae15 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -1,6 +1,6 @@ # Arazzo Specification -#### Version 1.0.0 +## Version 1.0.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -13,10 +13,11 @@ Being able to express specific sequences of calls and articulate the dependencie The Arazzo Specification can articulate these workflows in a human-readable 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. + ## Table of Contents - [Definitions](#definitions) - - [Arazzo Description](#arazzo-description) + - [Arazzo Description](#arazzo-description) - [Specification](#specification) - [Versions](#versions) - [Format](#format) @@ -46,7 +47,8 @@ The Arazzo Specification can articulate these workflows in a human-readable and ## Definitions -##### Arazzo Description +### Arazzo Description + A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). An Arazzo Description uses and conforms to the Arazzo Specification, and `MUST` contain a valid Arazzo Specification version field (`arazzo`), an [info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source Description](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. ## Specification @@ -80,14 +82,14 @@ Data types in the Arazzo Specification are based on the types supported by the [ As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7), data types can have an optional modifier property: `format`. Arazzo additionally supports the formats (similar to the OpenAPI specification) to provide fine detail for primitive data types. The formats defined are: -[`type`](#data-types) | `format` | Comments ------- | -------- | -------- -`integer` | `int32` | signed 32 bits -`integer` | `int64` | signed 64 bits (a.k.a long) -`number` | `float` | | -`number` | `double` | | -`string` | `password` | A hint to UIs to obscure input. +| [`type`](#data-types) | `format` | Comments | +| ---- | ---- | ---- | +| `integer` | `int32` | signed 32 bits | +| `integer` | `int64` | signed 64 bits (a.k.a long) | +| `number` | `float` | | +| `number` | `double` | | +| `string` | `password` | A hint to UIs to obscure input. | ### Relative References in URLs @@ -104,13 +106,13 @@ This is the root object of the [Arazzo Description](#arazzo-description). ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -arazzo | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Arazzo Specification that the Arazzo Description uses. The `arazzo` field MUST be used by tooling to interpret the Arazzo Description. -info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required. -sourceDescriptions | [[Source Description Object](#source-description-object)] | **REQUIRED**. A list of source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. The list MUST have at least one entry. -workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. -components | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description. +| Field Name | Type | Description | +| ---- | :----: | ---- | +| arazzo | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Arazzo Specification that the Arazzo Description uses. The `arazzo` field MUST be used by tooling to interpret the Arazzo Description. | +| info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required. | +| sourceDescriptions | [[Source Description Object](#source-description-object)] | **REQUIRED**. A list of source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. The list MUST have at least one entry. | +| workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. | +| components | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -122,60 +124,60 @@ info: title: A pet purchasing workflow summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls description: | - This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet. + This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sourceDescriptions: -- name: petStoreDescription - url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml - type: openapi + - name: petStoreDescription + url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml + type: openapi workflows: -- workflowId: loginUserAndRetrievePet - summary: Login User and then retrieve pets - description: This workflow lays out the steps to login a user and then retrieve pets - inputs: + - workflowId: loginUserAndRetrievePet + summary: Login User and then retrieve pets + description: This workflow 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: 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/get' - parameters: - - name: status - in: query - value: 'available' - - name: Authorization - in: header - value: $steps.loginUser.outputs.sessionToken - successCriteria: - - condition: $statusCode == 200 + username: + type: string + password: + type: string + steps: + - stepId: loginStep + description: This step demonstrates the user login step + operationId: 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/get' + parameters: + - name: status + in: query + value: 'available' + - name: Authorization + in: header + value: $steps.loginUser.outputs.sessionToken + successCriteria: + - condition: $statusCode == 200 + outputs: + # outputs from this step + availablePets: $response.body outputs: - # outputs from this step - availablePets: $response.body - outputs: available: $steps.getPetStep.availablePets ``` @@ -186,13 +188,12 @@ The metadata MAY be used by the clients if needed. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -title | `string` | **REQUIRED**. A human readable title of the Arazzo Description. -summary | `string` | A short summary of the Arazzo Description. -description | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -version | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)). - +| Field Name | Type | Description | +| ---- | :----: | ---- | +| title | `string` | **REQUIRED**. A human readable title of the Arazzo Description. | +| summary | `string` | A short summary of the Arazzo Description. | +| description | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| version | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -202,7 +203,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten 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. + This workflow walks you through the steps of searching for, selecting, and purchasing an available pet. version: 1.0.1 ``` @@ -214,12 +215,11 @@ An object storing a map between named description keys and location URLs to the ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. -url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). -type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`. - +| Field Name | Type | Description | +| ---- | :----: | ---- | +| name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | +| url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). | +| type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -237,19 +237,18 @@ Describes the steps to be taken across one or more APIs to achieve an objective. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Arazzo Description. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. -summary | `string` | A summary of the purpose or objective of the workflow. -description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. -dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. Each value provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. -steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. -successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. -failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. -outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. -parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. - +| Field Name | Type | Description | +| ---- | :----: | ---- | +| workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Arazzo Description. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | +| summary | `string` | A summary of the purpose or objective of the workflow. | +| description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. | +| dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. Each value provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. | +| steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. | +| successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. | +| failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. | +| outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. | +| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -260,12 +259,12 @@ workflowId: loginUser summary: Login User description: This workflow lays out the steps to login a user inputs: - type: object - properties: - username: - type: string - password: - type: string + type: object + properties: + username: + type: string + password: + type: string steps: - stepId: loginStep description: This step demonstrates the user login step @@ -279,14 +278,14 @@ steps: in: query value: $inputs.password successCriteria: - # assertions to determine step was successful - - condition: $statusCode == 200 + # 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 + # outputs from this step + tokenExpires: $response.header.X-Expires-After + rateLimit: $response.header.X-Rate-Limit outputs: - tokenExpires: $steps.loginStep.outputs.tokenExpires + tokenExpires: $steps.loginStep.outputs.tokenExpires ``` #### Step Object @@ -295,48 +294,48 @@ Describes a single workflow step which MAY be a call to an API operation ([OpenA ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. -operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. -operationPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. -workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. -parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. -requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. -successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. -onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. -onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. -outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. +| Field Name | Type | Description | +| ---- | :----: | ---- | +| description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | +| operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. | +| operationPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. | +| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. | +| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. | +| requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. | +| successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. | +| onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. | +| onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. | +| outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Step Object Example -**Single step** +###### Single step ```yaml stepId: loginStep description: This step demonstrates the user login step operationId: 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 + # 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 + # 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 + # outputs from this step + tokenExpires: $response.header.X-Expires-After + rateLimit: $response.header.X-Rate-Limit ``` -**Multiple steps** +###### Multiple steps ```yaml steps: @@ -344,7 +343,7 @@ steps: description: This step demonstrates the user login step operationId: 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) + # 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 @@ -352,13 +351,13 @@ steps: in: query value: $inputs.password successCriteria: - # assertions to determine step was successful + # 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 + # 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/get' @@ -372,29 +371,32 @@ steps: successCriteria: - condition: $statusCode == 200 outputs: - # outputs from this step - availablePets: $response.body + # outputs from this step + availablePets: $response.body ``` #### Parameter Object Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are four possible locations specified by the `in` field: - - path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. - - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. - - header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. - - cookie - Used to pass a specific cookie value to the source API. + +- path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. +- query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. +- header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. +- cookie - Used to pass a specific cookie value to the source API. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- - name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. - in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, or `"cookie"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. - value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. | +| in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, or `"cookie"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. | +| value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Parameter Object Example -**Query Example** + +###### Query Example ```yaml - name: username @@ -402,7 +404,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten value: $inputs.username ``` -**Header Example** +###### Header Example ```yaml - name: X-Api-Key @@ -413,19 +415,19 @@ This object MAY be extended with [Specification Extensions](#specification-exten #### Success Action Object A single success action which describes an action to take upon success of a workflow step. There are two possible values for the `type` field. - - end - The workflow ends, and context returns to the caller with applicable outputs - - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- - name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. - type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. - workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. - stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. - criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. +- end - The workflow ends, and context returns to the caller with applicable outputs +- goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) +##### Fixed Fields +| Field Name | Type | Description | +| ---- | :----: | ---- | +| name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. | +| type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. | +| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. | +| stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. | +| criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -436,30 +438,31 @@ name: JoinWaitingList type: goto stepId: joinWaitingListStep criteria: - # assertions to determine if this success action should be executed - - context: $response.body - condition: $[?count(@.pets) > 0] - type: jsonpath + # assertions to determine if this success action should be executed + - context: $response.body + condition: $[?count(@.pets) > 0] + type: jsonpath ``` #### Failure Action Object A single failure action which describes an action to take upon failure of a workflow step. There are three possible values for the `type` field. - - end - The workflow ends, and context returns to the caller with applicable outputs - - retry - The current step will be retried. The retry will be constrained by the `retryAfter` and `retryLimit` fields. If a `stepId` or `workflowId` are specified, then the reference is executed and the context is returned, after which the current step is retried. - - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) + +- end - The workflow ends, and context returns to the caller with applicable outputs +- retry - The current step will be retried. The retry will be constrained by the `retryAfter` and `retryLimit` fields. If a `stepId` or `workflowId` are specified, then the reference is executed and the context is returned, after which the current step is retried. +- goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- - name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. - type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. - workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. - stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. - retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. - retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. - criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). +| Field Name | Type | Description | +| ---- | :----: | ---- | +| name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. | +| type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. | +| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. | +| stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. | +| retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. | +| retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. | +| criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -471,8 +474,8 @@ type: retry retryAfter: 1 retryLimit: 5 criteria: - # assertions to determine if this action should be executed - - condition: $statusCode == 503 + # assertions to determine if this action should be executed + - condition: $statusCode == 503 ``` #### Components Object @@ -483,21 +486,20 @@ Components are scoped to the Arazzo document they are defined in. For example, i ##### Fixed Fields -Field Name | Type | Description ----|:---|--- - inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. -parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects -successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects. -failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects. +| Field Name | Type | Description | +| ---- | :---- | ---- | +| inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. | +| parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects | +| successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects. | +| failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects. | This object MAY be extended with [Specification Extensions](#specification-extensions). - All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow Description. Field Name Examples: -``` +```text User User_1 User_Name @@ -532,8 +534,8 @@ components: retryLimit: 5 workflowId: refreshTokenWorkflowId criteria: - # assertions to determine if this action should be executed - - condition: $statusCode == 401 + # assertions to determine if this action should be executed + - condition: $statusCode == 401 ``` ```json @@ -581,37 +583,37 @@ components: A simple object to allow referencing of objects contained within the [Components Object](#components-object). It can be used from locations within steps or workflows in the Arazzo Description. **Note** - Input Objects MUST use standard JSON Schema referencing via the `$ref` keyword while all non JSON Schema objects use this object and its expression based referencing mechanism. - ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -reference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object. -value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| reference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object. | +| value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. | This object cannot be extended with additional properties and any properties added MUST be ignored. ##### Reusable Object Example ```yaml - reference: $components.successActions.notify +reference: $components.successActions.notify ``` ```json - { - "reference": "$components.successActions.notify" - } +{ + "reference": "$components.successActions.notify" +} ``` ```yaml - reference: $components.parameters.page - value: 1 +reference: $components.parameters.page +value: 1 ``` ```json - { - "reference": "$components.parameters.page", - "value": 1 - } +{ + "reference": "$components.parameters.page", + "value": 1 +} ``` #### Criterion Object @@ -619,65 +621,70 @@ This object cannot be extended with additional properties and any properties add An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in [Step Object](#step-object) `successCriteria`, [Success Action Object](#success-action-object) `criteria`, and [Failure Action Object](#failure-action-object) `criteria`. There are four flavors of conditions supported: + - simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions). - regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions). - jsonpath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). - xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). ##### Literals + As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. -Type | Literal value ----|--- -`boolean` | `true` or `false` -`null` | `null` -`number` | Any number format supported in [Data Types](#data-types) -`string` | Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). +| Type | Literal value | +| ---- | ---- | +| `boolean` | `true` or `false` | +| `null` | `null` | +| `number` | Any number format supported in [Data Types](#data-types) | +| `string` | Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). | ##### Operators -Operator | Description ----|--- -`<`| Less than -`<=`| Less than or equal -`>`| Greater than -`>=`| Greater than or equal -`==`| Equal -`!=`| Not equal -`!`| Not -`&&`| And -\|\|| Or -`()`| Logical Grouping -`[]`| Index (0-based) -`.`| Property de-reference + +| Operator | Description | +| ---- | ---- | +| `<` | Less than | +| `<=` | Less than or equal | +| `>` | Greater than | +| `>=` | Greater than or equal | +| `==` | Equal | +| `!=` | Not equal | +| `!` | Not | +| `&&` | And | +| \|\| | Or | +| `()` | Logical Grouping | +| `[]` | Index (0-based) | +| `.` | Property de-reference | String comparisons `MUST` be case insensitive. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -context | `{expression}` | A [Runtime Expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). -condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. -type | `string` \| [Criterion Expression Type Object](#criterion-expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Criterion Expression Type Object](#criterion-expression-type-object) MUST be specified. +| Field Name | Type | Description | +| ---- | :----: | ---- | +| context | `{expression}` | A [Runtime Expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). | +| condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. | +| type | `string` \| [Criterion Expression Type Object](#criterion-expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Criterion Expression Type Object](#criterion-expression-type-object) MUST be specified. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Criterion Object Example -**Simple Condition Example** +###### Simple Condition Example ```yaml - condition: $statusCode == 200 ``` -**Regex Condition Example** +###### Regex Condition Example + ```yaml - context: $statusCode condition: '^200$' type: regex ``` -**JSONPath Condition Example** +###### JSONPath Condition Example + ```yaml - context: $response.body condition: $[?count(@.pets) > 0] @@ -687,31 +694,35 @@ This object MAY be extended with [Specification Extensions](#specification-exten #### Criterion Expression Type Object An object used to describe the type and version of an expression used within a [Criterion Object](#criterion-object). If this object is not defined, then the following defaults apply: - - JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535) - - XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31) + +- JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535) +- XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31) Defining this object gives the ability to utilize tooling compatible with older versions of either JSONPath or XPath. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -type | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`. -version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSONPath are `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`. + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| type | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`. | +| version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSONPath are `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Criterion Expression Type Example -**JSONPath Example** +###### JSONPath Example + ```yaml - type: jsonpath - version: draft-goessner-dispatch-jsonpath-00 +type: jsonpath +version: draft-goessner-dispatch-jsonpath-00 ``` -**XPath Example** +###### XPath Example + ```yaml - type: xpath - version: xpath-30 +type: xpath +version: xpath-30 ``` #### Request Body Object @@ -719,107 +730,118 @@ This object MAY be extended with [Specification Extensions](#specification-exten A single request body describing the `Content-Type` and request body content to be passed by a step to an operation. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements. -payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. -replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload. + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements. | +| payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. | +| replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### RequestBody Object Example -**JSON Templated Example** +###### JSON Templated Example + ```yaml - contentType: application/json - payload: | - { - "petOrder": { - "petId": "{$inputs.pet_id}", - "couponCode": "{$inputs.coupon_code}", - "quantity": "{$inputs.quantity}", - "status": "placed", - "complete": false - } +contentType: application/json +payload: | + { + "petOrder": { + "petId": "{$inputs.pet_id}", + "couponCode": "{$inputs.coupon_code}", + "quantity": "{$inputs.quantity}", + "status": "placed", + "complete": false } + } ``` -**JSON Object Example** +###### JSON Object Example + ```yaml - contentType: application/json - payload: - petOrder: - petId: $inputs.pet_id - couponCode: $inputs.coupon_code - quantity: $inputs.quantity - status: placed - complete: false +contentType: application/json +payload: + petOrder: + petId: $inputs.pet_id + couponCode: $inputs.coupon_code + quantity: $inputs.quantity + status: placed + complete: false ``` -**Complete Runtime Expression** +###### Complete Runtime Expression + ```yaml - contentType: application/json - payload: $inputs.petOrderRequest +contentType: application/json +payload: $inputs.petOrderRequest ``` -**XML Templated Example** +###### XML Templated Example + ```yaml - contentType: application/xml - payload: | - - {$inputs.pet_id} - {$inputs.coupon_code} - {$inputs.quantity} - placed - false - +contentType: application/xml +payload: | + + {$inputs.pet_id} + {$inputs.coupon_code} + {$inputs.quantity} + placed + false + ``` -**Form Data Example** +###### Form Data Example + ```yaml - contentType: application/x-www-form-urlencoded - payload: - client_id: $inputs.clientId - grant_type: $inputs.grantType - redirect_uri: $inputs.redirectUri - client_secret: $inputs.clientSecret - code: $steps.browser-authorize.outputs.code - scope: $inputs.scope -``` - -**Form Data String Example** +contentType: application/x-www-form-urlencoded +payload: + client_id: $inputs.clientId + grant_type: $inputs.grantType + redirect_uri: $inputs.redirectUri + client_secret: $inputs.clientSecret + code: $steps.browser-authorize.outputs.code + scope: $inputs.scope +``` + +###### Form Data String Example + ```yaml - contentType: application/x-www-form-urlencoded - payload: "client_id={$inputs.clientId}&grant_type={$inputs.grantType}&redirect_uri={$inputs.redirectUri}&client_secret={$inputs.clientSecret}&code{$steps.browser-authorize.outputs.code}&scope=$inputs.scope}" +contentType: application/x-www-form-urlencoded +payload: 'client_id={$inputs.clientId}&grant_type={$inputs.grantType}&redirect_uri={$inputs.redirectUri}&client_secret={$inputs.clientSecret}&code{$steps.browser-authorize.outputs.code}&scope=$inputs.scope}' ``` #### Payload Replacement Object -Describes a location within a payload (e.g., a request body) and a value to set within the location. + +Describes a location within a payload (e.g., a request body) and a value to set within the location. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901) or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions) which MUST be resolved against the request body. Used to identify the location to inject the `value`. - value | Any \| {expression} | **REQUIRED**. The value set within the target location. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901) or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions) which MUST be resolved against the request body. Used to identify the location to inject the `value`. | +| value | Any \| {expression} | **REQUIRED**. The value set within the target location. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Payload Replacement Object Example -**Runtime Expression Example** +###### Runtime Expression Example + ```yaml - target: /petId - value: $inputs.pet_id +target: /petId +value: $inputs.pet_id ``` -**Literal Example** +###### Literal Example + ```yaml - target: /quantity - value: 10 +target: /quantity +value: 10 ``` - ### Runtime Expressions + A runtime expression allows values to be defined based on information that will be available within the HTTP message in an actual API call, or within objects serialized from the Arazzo document such as [workflows](#workflow-object) or [steps](#step-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: @@ -846,33 +868,32 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org #### Examples -Source Location | example expression | notes ----|:---|:---| -HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. -Requested media type | `$request.header.accept` | -Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. -Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. -Request URL | `$url` | -Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. -Response header | `$response.header.Server` | Single header values only are available -workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available -Step output value | `$steps.someStep.pets` | In situations where the output named property return payloads, references may be made to portions of the response body or the entire body. -Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available -Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. +| Source Location | example expression | notes | +| ---- | :---- | :---- | +| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. | +| Requested media type | `$request.header.accept` | | +| Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. | +| Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. | +| Request URL | `$url` | | +| Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. | +| Response header | `$response.header.Server` | Single header values only are available | +| workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available | +| Step output value | `$steps.someStep.pets` | In situations where the output named property return payloads, references may be made to portions of the response body or the entire body. | +| Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available | +| Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. | Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. - ### Specification Extensions While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extension properties are implemented as patterned fields that are always prefixed by `"x-"`. -Field Pattern | Type | Description ----|:---:|--- -^x- | Any | Allows extensions to the Arazzo Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-`, `x-oas-`, and `x-arazzo` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. +| Field Pattern | Type | Description | +| ---- | :--: | ---- | +| ^x- | Any | Allows extensions to the Arazzo Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-`, `x-oas-`, and `x-arazzo` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. | The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). @@ -946,6 +967,6 @@ The proposed MIME media type for Arazzo documents (e.g. workflows) that require ## Appendix A: Revision History -Version | Date | Notes ---- | --- | --- -1.0.0 | 2024-05-29 | First release of the Arazzo Specification +| Version | Date | Notes | +| ---- | ---- | ---- | +| 1.0.0 | 2024-05-29 | First release of the Arazzo Specification |