feat: add support for validating Arazzo 1.1.0#2877
Conversation
🦋 Changeset detectedLatest commit: 4eacfbf The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Performance Benchmark (Lower is Faster)
|
DmitryAnansky
force-pushed
the
feat/support-linting-for-arazzo-3.1.0-version
branch
2 times, most recently
from
25febda to
0126f35
Compare
DmitryAnansky
force-pushed
the
feat/support-linting-for-arazzo-3.1.0-version
branch
from
05e73a3 to
856bc43
Compare
DmitryAnansky
force-pushed
the
feat/support-linting-for-arazzo-3.1.0-version
branch
from
31e7814 to
c360758
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>
|
|
||
| | Arazzo | Compatibility | | ||
| | ------ | ------------- | | ||
| | 1.x | ✅ | |
There was a problem hiding this comment.
If you're adding a separate 1.1 section, let's update this as well:
| | 1.x | ✅ | | |
| | 1.0.x | ✅ | | |
| | 1.1.x | ✅ | |
| expect(replaceSourceWithRef(results)).toEqual([]); | ||
| }); | ||
|
|
||
| it('rejects asyncapi sourceDescription type in Arazzo 1.0', async () => { |
There was a problem hiding this comment.
This test doesn't make too much sense. We cannot evaluate all invalid fields for any spec, so why make an exception for asyncapi?
There was a problem hiding this comment.
To illustrate difference in 1.0.1 and 1.1.0 - there is new sourceDescription that does not exists in 1.0.1, called async.
If we are to chose the approach when we extent the version instead of separation - we could remove the test.
| enter(sourceDescriptions, { report, location, specVersion }: UserContext) { | ||
| if (!sourceDescriptions.length) return; | ||
| const allowedTypes = | ||
| specVersion === 'arazzo1_1' ? ['openapi', 'arazzo', 'asyncapi'] : ['openapi', 'arazzo']; |
There was a problem hiding this comment.
I see you compare the specVersion inside the rule. So does it make sense to introduce arazzo1_1Rules field (which is supposed to separate the rules)?
| ? MUTUALLY_EXCLUSIVE_FIELDS_1_1 | ||
| : MUTUALLY_EXCLUSIVE_FIELDS_1_0; | ||
| const usedFields = fields.filter((field) => | ||
| Object.prototype.hasOwnProperty.call(step, field) |
There was a problem hiding this comment.
Is there a better alternative? I believe we already have the getOwn utility function. Let's reuse it? Or just use Object.hasOwn() if our configuration supports it.
| ...Arazzo1Types.Root, | ||
| properties: { | ||
| ...Arazzo1Types.Root.properties, | ||
| $self: { |
There was a problem hiding this comment.
There's no big deal in supporting this field in 1.0.
| targetSelectorType: (value: any) => { | ||
| if (!value) { | ||
| return undefined; | ||
| } else if (typeof value === 'string') { |
There was a problem hiding this comment.
Looks like it's almost the same as https://github.com/Redocly/redocly-cli/pull/2877/changes#diff-fa54876f4ff5cdf21c70bb980ae670097b0f18257cb382579428f539bfab1587R167. Does it make sense to reuse it?
|
|
||
| export const ARAZZO_1_1_VERSION_PATTERN = /^1\.1\.\d+(-.+)?$/; | ||
|
|
||
| export const ARAZZO_VERSIONS_SUPPORTED_BY_RESPECT = ['1.0.1']; |
There was a problem hiding this comment.
We should be supporting 1.1.x too, at least partially.
There was a problem hiding this comment.
Currently, we don't support anything new from Arazzo 1.1.0 in Respect.
So execution will be successful only when no new features needed.
| import { ARAZZO_1_1_VERSION_PATTERN, VERSION_PATTERN } from './typings/arazzo.js'; | ||
| import { isPlainObject } from './utils/is-plain-object.js'; | ||
|
|
||
| export const specVersions = [ |
There was a problem hiding this comment.
This duplication has been removed here: https://github.com/Redocly/redocly-cli/pull/2876/changes#diff-25dc3950a139fe66d03b1d9d75cb6a53221211f183c812a98f5a91bbedc7cf3e. Please do not re-introduce it.
| spec_full_version, | ||
| respect_x_security_auth_types: | ||
| spec_version === 'arazzo1' && respect_x_security_auth_types?.length | ||
| (spec_version === 'arazzo1' || spec_version === 'arazzo1_1') && |
There was a problem hiding this comment.
Either use getMajorSpecVersion or don't introduce the 1.0/1.1 split.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 4eacfbf. Configure here.
| } else if (version === 'arazzo1') { | ||
| } else if (version === 'async3') { | ||
| return 'async3'; | ||
| } else if (version === 'arazzo1' || version === 'arazzo1_1') { |
There was a problem hiding this comment.
Plugin arazzo1_1 rules never load
Medium Severity
Lint loads plugin rule sets via getRulesForSpecVersion(getMajorSpecVersion(specVersion)), and getMajorSpecVersion maps arazzo1_1 to arazzo1. The new getRulesForSpecVersion branch for arazzo1_1 never runs, so plugin entries under rules.arazzo1_1 (now part of the plugin API) are not registered for 1.1 documents.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit 4eacfbf. Configure here.
4 participants
What/Why/How?
What's new in Arazzo 1.1.0 (verified against spec.openapis.org/arazzo/latest.html)
$self(URI-reference, base URI for the doc)typegainsasyncapi(wasopenapi/arazzo)channelPath(AsyncAPI channel pointer, joins mutual-exclusivity group with operationId/operationPath/workflowId),action(send/receive),correlationId,timeout(integer, ms),dependsOn(list of stepIds)ingainsquerystring(OpenAPI 3.2 alignment)typeis now the generalized Expression Type Object; jsonpath versions gainrfc9535, xpath versions gainxpath-31type:jsonpath/xpath/jsonpointer;versionREQUIRED: jsonpath→rfc9535,draft-goessner-dispatch-jsonpath-00; xpath→xpath-31,xpath-30,xpath-20,xpath-10; jsonpointer→rfc6901context(REQUIRED),selector(REQUIRED),type(REQUIRED, string enum or Expression Type Object). Usable in outputs, parameter values, requestBody payload, payload replacement valuestargetSelectorType(string enum or Expression Type Object);valuemay be a Selector Objectparameters(list of Parameter Object | Reusable Object) for passing inputs to the referenced workflow$message.header.*,$message.payload,$selfsources (no lint impact — expressions are opaque strings to lint)Reference
Closes: #2825
Testing
Screenshots (optional)
Check yourself
Security
Note
Medium Risk
Broad config and spec-detection changes affect all Arazzo lint paths; incorrect version routing could mis-validate documents, but behavior is heavily covered by new unit and e2e tests.
Overview
Adds Arazzo 1.1.0 validation to
lint:arazzo: 1.1.xis detected asarazzo1_1and checked with a newArazzo1_1Typesschema (1.0.x still usesarazzo1/ 1.0.1). Config gains parallelarazzo1_1Rules/ preprocessors / decorators slots across presets andredocly.yaml, while docs steer users toward the sharedrules:block instead ofarazzo1Rulesonly.1.1 struct support covers
$self, AsyncAPIsourceDescriptions, stepchannelPath/action/correlationId/timeout/dependsOn, expression and selector objects, and related typing/visitor updates.New
spec-step-mutually-exclusive-fieldsrule flags steps that set more than one ofx-operation,operationId,operationPath,workflowId, orchannelPath.sourceDescription-typenow allowsasyncapifor 1.1 only. CLI telemetry and Respect collectors treatarazzo1_1likearazzo1where relevant.Reviewed by Cursor Bugbot for commit 4eacfbf. Bugbot is set up for automated code reviews on this repo. Configure here.