Migrate to v3.2

.github/workflows/ci.yaml

@@ -90,6 +90,9 @@ jobs:
 
       - run: bun --bun run bundle
 
+      - name: lint the downleveled bundles as the version they declare
+        run: bun --bun run test:versions
+
       - uses: actions/github-script@v9
         with:
           script: |

CLAUDE.md

@@ -176,10 +176,11 @@ Never add a YAML comment. A fact about the API belongs in a `description`.
   decorator changes `drift` only, and does not reach the schema check.
 - `respect` masks secrets in the capture and sends the real value. `********` in
   a HAR is evidence about nothing.
-- `dist/openapi-test.yaml` defines `jsonschema` and `internal`, so `x-if` takes
-  its `then` branch. The published bundles take `else`. Both must describe the
-  same traffic; check which one you are validating against before believing a
-  finding.
+- `openapi.json` and `openapi-internal.json` carry the source's OpenAPI version.
+  The `-3.x` bundles pass through `downlevel/openapi` from
+  `packages/redocly-plugin-downlevel`, which rewrites them as that version.
+  `dist/openapi-test.yaml` carries the source as written. Check which one you
+  are validating against before believing a finding.
 - `drift`'s `security-baseline` flags every unauthenticated workflow for the
   missing cookie it exists to assert. Every finding it produces is a 401 and
   none is actionable, so `test:drift` names the rules it wants instead of taking
@@ -226,6 +227,7 @@ Never add a YAML comment. A fact about the API belongs in a `description`.
 | `pnpm test:coverage` | what the traffic never reached |
 | `pnpm test:drift` | where traffic and description disagree |
 | `pnpm test:downlevel` | test and build `packages/redocly-plugin-downlevel` |
+| `pnpm test:versions` | lint the downleveled bundles as the version they declare |
 | `sh test/report.sh` | the last run's failures as Markdown |
 | `sh test/report.sh --format github` | the same, as CI annotations |
 

eslint.config.mjs

@@ -16,14 +16,6 @@ export default configure({
 	rules: {
 		"yaml/sort-keys": [
 			"error",
-			{
-				pathPattern: ".*x-if.*",
-				order: [
-					"when",
-					"then",
-					"else"
-				]
-			},
 			{
 				pathPattern: ".*",
 				hasProperties: [

openapi/components/paths/favorites.yaml

@@ -122,7 +122,6 @@ paths:
       tags:
         - favorites
       requestBody:
-        description: ""
         content:
           application/json:
             examples:

openapi/components/paths/miscellaneous.yaml

@@ -237,7 +237,6 @@ paths:
       tags:
         - miscellaneous
       requestBody:
-        description: ""
         content:
           application/json:
             schema:

openapi/components/paths/playermoderation.yaml

@@ -92,7 +92,6 @@ paths:
       tags:
         - playermoderation
       requestBody:
-        description: ""
         required: true
         content:
           application/json:

openapi/components/paths/worlds.yaml

@@ -52,7 +52,6 @@ paths:
       tags:
         - worlds
       requestBody:
-        description: ""
         content:
           application/json:
             schema:

openapi/components/requests/CreateAvatarRequest.yaml

@@ -28,7 +28,6 @@ properties:
     $ref: ../schemas/ReleaseStatus.yaml
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml
   thumbnailImageUrl:

openapi/components/requests/CreateFileRequest.yaml

@@ -11,7 +11,6 @@ properties:
     minLength: 0
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml
 required:

openapi/components/requests/CreateGroupGalleryRequest.yaml

@@ -17,27 +17,19 @@ properties:
     example: Example Gallery
     minLength: 1
   roleIdsToAutoApprove:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
   roleIdsToManage:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
   roleIdsToSubmit:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
   roleIdsToView:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
 required:

openapi/components/requests/CreateGroupRequest.yaml

@@ -2,16 +2,14 @@ title: CreateGroupRequest
 type: object
 properties:
   bannerId:
-    type: string
-    nullable: true
+    type: ["null", string]
     default: null
   description:
     type: string
     maxLength: 250
     minLength: 0
   iconId:
-    type: string
-    nullable: true
+    type: ["null", string]
     default: null
   joinState:
     $ref: ../schemas/GroupJoinState.yaml

openapi/components/requests/CreateInstanceRequest.yaml

@@ -29,16 +29,14 @@ properties:
     description: Currently unused, but will eventually be a flag to set if the closing of the instance should kick people.
     default: false
   instancePersistenceEnabled:
-    type: boolean
-    nullable: true
+    type: [boolean, "null"]
   inviteOnly:
     type: boolean
     default: false
   ownerId:
     $ref: ../schemas/InstanceOwnerId.yaml
   playerPersistenceEnabled:
-    type: boolean
-    nullable: true
+    type: [boolean, "null"]
   queueEnabled:
     type: boolean
     default: false

openapi/components/requests/CreateWorldRequest.yaml

@@ -33,7 +33,6 @@ properties:
     $ref: ../schemas/ReleaseStatus.yaml
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml
   unityPackageUrl:

openapi/components/requests/FinishFileDataUploadRequest.yaml

@@ -1,6 +1,5 @@
 title: FinishFileDataUploadRequest
 type: object
-description: ""
 properties:
   etags:
     type: array

openapi/components/requests/UpdateAvatarRequest.yaml

@@ -22,7 +22,6 @@ properties:
     $ref: ../schemas/ReleaseStatus.yaml
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml
   unityPackageUrl:

openapi/components/requests/UpdateGroupGalleryRequest.yaml

@@ -17,26 +17,18 @@ properties:
     example: Example Gallery
     minLength: 1
   roleIdsToAutoApprove:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
   roleIdsToManage:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
   roleIdsToSubmit:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml
   roleIdsToView:
-    type: array
-    description: " "
-    nullable: true
+    type: [array, "null"]
     items:
       $ref: ../schemas/GroupRoleID.yaml

openapi/components/requests/UpdateGroupRequest.yaml

@@ -2,16 +2,14 @@ title: UpdateGroupRequest
 type: object
 properties:
   bannerId:
-    type: string
-    nullable: true
+    type: ["null", string]
     default: null
   description:
     type: string
     maxLength: 250
     minLength: 0
   iconId:
-    type: string
-    nullable: true
+    type: ["null", string]
     default: null
   joinState:
     $ref: ../schemas/GroupJoinState.yaml
@@ -32,8 +30,7 @@ properties:
     maxLength: 64
     minLength: 3
   nameplateId:
-    type: string
-    nullable: true
+    type: ["null", string]
     default: null
   rules:
     type: string
@@ -43,6 +40,5 @@ properties:
     minLength: 3
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml

openapi/components/requests/UpdateUserRequest.yaml

@@ -42,7 +42,6 @@ properties:
     type: string
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml
   unsubscribe:

openapi/components/requests/UpdateWorldRequest.yaml

@@ -32,16 +32,14 @@ properties:
   platform:
     $ref: ../schemas/Platform.yaml
   previewYoutubeId:
-    type: string
-    nullable: true
+    type: ["null", string]
   recommendedCapacity:
     type: integer
     example: 4
   releaseStatus:
     $ref: ../schemas/ReleaseStatus.yaml
   tags:
     type: array
-    description: " "
     items:
       $ref: ../schemas/Tag.yaml
   unityPackageUrl:

openapi/components/responses/authentication/CurrentUserLoginResponse.yaml

@@ -2,14 +2,10 @@ description: OK
 content:
   application/json:
     schema:
-      x-if:
-        when: jsonschema
-        then:
-          oneOf:
-            - $ref: ../../schemas/CurrentUser.yaml
-            - $ref: ../../schemas/RequiresTwoFactorAuth.yaml
-        else:
-          $ref: ../../schemas/CurrentUser.yaml
+      title: CurrentUserLoginResponse
+      oneOf:
+        - $ref: ../../schemas/CurrentUser.yaml
+        - $ref: ../../schemas/RequiresTwoFactorAuth.yaml
 headers:
   Set-Cookie:
     description: Successful authentication returns an `auth` cookie.

openapi/components/responses/economy/UpdateTiliaTOSResponse.yaml

@@ -2,5 +2,4 @@ description: Returns a UserSubscription object.
 content:
   application/json:
     schema:
-      type: object
-      nullable: true
+      type: ["null", object]

openapi/components/responses/groups/GroupGalleryImageListResponse.yaml

@@ -2,6 +2,7 @@ description: Returns a list of GroupGalleryImage objects, wrapped in a paginated
 content:
   application/json:
     schema:
+      title: GroupGalleryImageListResponse
       oneOf:
         - type: array
           items:

openapi/components/responses/groups/GroupMemberSearchResponse.yaml

@@ -2,6 +2,7 @@ description: Returns a list of GroupMember objects from a search.
 content:
   application/json:
     schema:
+      title: GroupMemberSearchResponse
       type: object
       properties:
         results:

openapi/components/responses/groups/GroupPostsResponse.yaml

@@ -2,6 +2,7 @@ description: Returns a GroupPost Array.
 content:
   application/json:
     schema:
+      title: GroupPostsResponse
       type: object
       properties:
         posts:

openapi/components/responses/users/UserGroupInstanceListResponse.yaml

@@ -2,6 +2,7 @@ description: Returns a list of Instance objects with a fetched at time.
 content:
   application/json:
     schema:
+      title: UserGroupInstanceListResponse
       type: object
       properties:
         fetchedAt:

openapi/components/responses/users/UserResponse.yaml

@@ -7,11 +7,7 @@ description: |-
 content:
   application/json:
     schema:
-      x-if:
-        when: jsonschema
-        then:
-          oneOf:
-            - $ref: ../../schemas/User.yaml
-            - $ref: ../../schemas/CurrentUser.yaml
-        else:
-          $ref: ../../schemas/User.yaml
+      title: UserResponse
+      oneOf:
+        - $ref: ../../schemas/User.yaml
+        - $ref: ../../schemas/CurrentUser.yaml

openapi/components/schemas/AccountDeletionLog.yaml

@@ -6,9 +6,8 @@ properties:
     description: Date and time of the deletion request.
     format: date-time
   deletionScheduled:
-    type: string
+    type: ["null", string]
     description: When the deletion is scheduled to happen, standard is 14 days after the request.
-    nullable: true
     format: date-time
   message:
     type: string

openapi/components/schemas/AdminAssetBundle.yaml

@@ -1,6 +1,5 @@
 title: AdminAssetBundle
 type: object
-description: ""
 properties:
   _created_at:
     type: string
@@ -29,8 +28,7 @@ properties:
   thumbnailImageUrl:
     type: string
   unityPackageUrl:
-    type: string
-    nullable: true
+    type: ["null", string]
   unityPackages:
     type: array
     items:

openapi/components/schemas/AdminUnityPackage.yaml

@@ -1,6 +1,5 @@
 title: AdminUnityPackage
 type: object
-description: ""
 properties:
   assetUrl:
     type: string