Add OpenAPI 3.2 format detection and ruleset support

[mkistler]

Fixes #2910.

Checklist

• Tests added / updated
• Docs added / updated

Does this PR introduce a breaking change?

• Yes
• No

Screenshots

If applicable, add screenshots or gifs to help demonstrate the changes. If not applicable, remove this screenshots section before creating the PR.

Additional context

This PR was developed with the help of AI, specifically the Copilot CLI.

[YOU54F]

Hi @mkistler,

Thanks for the contribution, we really appreciate this, as will all Spectral users, and coming from an OpenAPI TSC member ❤️

does this bring full support for OpenAPI 3.2 rules, or are there any gaps to be aware of?

Just trying to ascertain before I dive in for a review and run though locally.

Thanks again,

Yousaf

[mkistler]

@YOU54F It's been a while since I created this, and I did it with the help of AI (now noted in the PR description), so I asked AI to check coverage of the new features as described in the changeling for OpenAPI 3.2. Here's what it reported:

OpenAPI 3.2 feature checklist

Source: OpenAPI 3.2.0 changelog

How this checklist was evaluated

• [x] means this repo has concrete support for the feature today, usually via oas3_2 format detection, bundled OpenAPI 3.2 schemas, or an explicit rule.
• [ ] means the feature is not covered end-to-end here, is only partially covered, or is a changelog item that is editorial/spec-text rather than something Spectral implements directly.

Baseline repo support for OpenAPI 3.2

• Detect OpenAPI 3.2 documents via the oas3_2 format. (packages/formats/src/openapi.ts:26-28, packages/formats/src/__tests__/openapi.test.ts:56-63)
• Apply the built-in OAS ruleset to oas3_2 documents. (packages/rulesets/src/oas/index.ts:33-35)
• Route OpenAPI 3.2 documents to the bundled OpenAPI 3.2 validator. (packages/rulesets/src/oas/functions/oasDocumentSchema.ts:19-28, packages/rulesets/scripts/compile-schemas.ts:15-26, packages/rulesets/scripts/compile-schemas.ts:59-64)

Headline features

• Multipurpose tags: support summary, parent, and kind on Tag Objects. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:1140-1157)

• Validate tag kind values against the OpenAPI tag-kind registry.

  • The bundled schema only treats kind as a free-form string. No repo logic was found that consults the registry.

• Support the new query HTTP method on Path Items. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:330-356)

• Support additionalOperations for non-standard HTTP methods. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:317-329)

• Apply generic operation-based OAS rules to query operations.

  • #OperationObject still only targets get,put,post,delete,options,head,patch,trace. (packages/rulesets/src/oas/index.ts:37-39)

• Apply generic operation-based OAS rules to additionalOperations.

  • No alias or rule target was found that traverses additionalOperations. (packages/rulesets/src/oas/index.ts:37-39)

• Accept top-level $self in OpenAPI 3.2 documents. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:7-16)

• Use $self to influence $ref resolution in repo code.

  • No non-schema usage of $self was found in packages/**/*.ts or packages/**/*.js.

Data modeling and representation

• Support in: querystring for parameters. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:477-550)
• Allow allowReserved across the parameter locations supported by the 3.2 schema. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:601-680)

- [ ] Allow allowReserved on Header Objects. REMOVED This was an error in the changelog

• Support style: cookie for cookie parameters. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:651-684)

• Support itemSchema for sequential media types. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:744-789)

• Support prefixEncoding and itemEncoding for multipart and sequential media types. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:763-789, packages/rulesets/src/oas/schemas/oas/v3.2/index.json:832-875)

• Implement media-type registry behavior or SSE/sequential-media semantics beyond schema acceptance.

  • The repo bundles the fields in the 3.2 schema, but no extra rule or runtime logic was found for registry-driven or streaming-specific behavior.

• Support XML nodeType. (packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json:65-71)

• Allow the xml keyword in the OpenAPI 3.2 schema vocabulary. (packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json:11-23)

• Allow XML namespaces as IRIs. (packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json:75-78)

• Mark xml.attribute and xml.wrapped as deprecated in the bundled OpenAPI 3.2 meta-schema. (packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json:82-89)

• Forbid xml.attribute: true with an explicit OAS 3.2 rule. (packages/rulesets/src/oas/index.ts:771-787, docs/reference/openapi-rules.md:1020-1028)

• Forbid xml.wrapped: true with an explicit OAS 3.2 rule.

  • wrapped is marked deprecated in the meta-schema, but there is no dedicated lint rule like oas3_2-no-deprecated-xml-attribute.

• Support dataValue and serializedValue on Example Objects. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:966-1009)

Additional features

• Support deviceAuthorization OAuth flow and deviceAuthorizationUrl. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:1333-1457)

• Support oauth2MetadataUrl on security schemes. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:1288-1298)

• Support deprecated on security schemes. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:1187-1197)

• Treat URI-based security scheme references as valid in the built-in security-defined rule.

  • oasSecurityDefined only accepts scheme names found in components.securitySchemes. (packages/rulesets/src/oas/functions/oasSecurityDefined.ts:36-52)

• Support the new name field on Server Objects. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:155-177)

• Explicitly lint server URLs to reject query strings or fragments.

  • Existing server validation checks substitutions and URL validity, but not the 3.2 restriction on query/fragment usage. (packages/rulesets/src/shared/functions/serverVariables/index.ts:84-127, packages/rulesets/src/shared/functions/serverVariables/index.ts:182-215)

• Support defaultMapping on discriminators. (packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json:26-40)

• Allow discriminator propertyName to be omitted. (packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json:35-40)

• Support optional description and new summary on Response Objects. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:905-933)

• Support reusable components.mediaTypes. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json:201-280)

• Explicitly validate the new 3.2 ABNF forms for path templates, server variables, and Link runtime expressions.

  • There is existing server-variable validation, but no 3.2-specific ABNF validator was found.

Standards and editorial changes

• Bundle the OpenAPI 3.2 schema, dialect, and meta-schema updates that reflect the new JSON Schema alignment. (packages/rulesets/src/oas/schemas/oas/v3.2/index.json, packages/rulesets/src/oas/schemas/oas/v3.2/dialect.schema.json, packages/rulesets/src/oas/schemas/oas/v3.2/meta.schema.json)
• Surface the changelog's editorial additions, examples, and registries as dedicated Spectral features or docs.
  • The repo docs mention OpenAPI 3.2 support and the single 3.2-only XML rule, but they do not mirror the full 3.2 changelog feature set. (docs/getting-started/4-openapi.md:5, docs/reference/openapi-rules.md:1020-1028, docs/guides/4-custom-rulesets.md:40)

Summary

Most OpenAPI 3.2 additions are covered at the schema-validation level because Spectral ships the official OpenAPI 3.2 schema bundle and wires oas3_2 into format detection and document validation.

The biggest gaps are:

• operation-rule coverage for the new query method and additionalOperations
• $self being accepted by schema but not used for reference resolution
• URI-based security scheme references conflicting with oas3-operation-security-defined
• a lack of dedicated validation for some 3.2 clarifications and editorial/spec-text items