feat(openapi): document error responses and undocumented schema fields - #591
Open
ariesclark wants to merge 4 commits into
Open
feat(openapi): document error responses and undocumented schema fields#591ariesclark wants to merge 4 commits into
ariesclark wants to merge 4 commits into
Conversation
ariesclark
requested review from
Foorack,
Miner28,
VinyarionHyarmendacil and
jellejurre
August 3, 2026 22:54
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands the OpenAPI specification by documenting additional observed response fields, introducing new schemas/responses for previously undocumented error bodies, and marking/organizing deprecated routes more explicitly.
Changes:
- Added/updated many component schemas to reflect newly observed response properties (profiles, groups, economy, notifications, inventory, infoPush, etc.).
- Added new schemas and response components for previously undocumented success/error shapes (e.g., RouteNotImplemented, BareError, SSO/OAuth redirect code).
- Updated multiple path definitions to include additional response codes, optional-auth security requirements for some endpoints, and improved deprecation tagging/wording.
Reviewed changes
Copilot reviewed 103 out of 103 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| openapi/components/tags.yaml | Adds a deprecated tag category for grouping deprecated operations. |
| openapi/components/schemas/World.yaml | Documents additional World fields and tightens instance tuple length constraints. |
| openapi/components/schemas/User.yaml | Adds missing User fields and references a dedicated FriendRequestStatus schema. |
| openapi/components/schemas/Transaction.yaml | Makes agreement schema conditional for jsonschema vs OpenAPI generation. |
| openapi/components/schemas/Subscription.yaml | Adds gifted-bundle related fields and a placeholder for periodAmount. |
| openapi/components/schemas/StoreShelf.yaml | Adds new shelf image FileID references. |
| openapi/components/schemas/SsoToken.yaml | New schema for third-party SSO token response body. |
| openapi/components/schemas/SsoProvider.yaml | New enum schema for supported SSO providers. |
| openapi/components/schemas/RouteNotImplemented.yaml | New schema for the non-standard “not implemented” 404 body shape. |
| openapi/components/schemas/RepresentedGroup.yaml | Adds undocumented represented-group fields. |
| openapi/components/schemas/ReportReason.yaml | Reformats and adds policy field; updates required fields. |
| openapi/components/schemas/ReportCategory.yaml | Reformats and adds undocumented category fields (ipsArticle, order). |
| openapi/components/schemas/PublicProfile.yaml | Simplifies representedGroup schema reference with nullable handling. |
| openapi/components/schemas/ProductListingAttributionCreator.yaml | New schema for attribution creator objects on listings. |
| openapi/components/schemas/ProductListingAttribution.yaml | New schema for listing attribution (creator/publisher). |
| openapi/components/schemas/ProductListing.yaml | Adds attribution/collab fields and clarifies hydration/id lists. |
| openapi/components/schemas/PrivateProfile.yaml | Adds friendRequestStatus and makes note nullable. |
| openapi/components/schemas/OAuthRedirectCode.yaml | New schema for OAuth redirect handoff code response. |
| openapi/components/schemas/NotificationV2DataEmpty.yaml | Constrains empty notification payload shape to preserve union discrimination. |
| openapi/components/schemas/NotificationV2.yaml | Adds fields and nullability updates for notification properties. |
| openapi/components/schemas/NotificationDetailEmpty.yaml | Constrains empty details branch to avoid matching populated branches. |
| openapi/components/schemas/MutualFriend.yaml | Adds additional profile/visual fields returned in mutual-friends results. |
| openapi/components/schemas/LocalizedString.yaml | New schema representing localization keys with fallback text. |
| openapi/components/schemas/LimitedWorld.yaml | Adds undocumented disabledPropAbilities field. |
| openapi/components/schemas/LimitedUserGroups.yaml | Adds undocumented nameplate fields. |
| openapi/components/schemas/LimitedUserFriend.yaml | Adds additional profile/visual fields returned in friends list results. |
| openapi/components/schemas/LimitedGroup.yaml | Adds undocumented nameplate fields. |
| openapi/components/schemas/JamSubmission.yaml | Adds an additional ratings score field for jam submissions. |
| openapi/components/schemas/Jam.yaml | Adds missing timestamps and type field. |
| openapi/components/schemas/InventoryTemplate.yaml | Adds new fields and updates required list. |
| openapi/components/schemas/InventoryMetadata.yaml | Adds a new propKind field. |
| openapi/components/schemas/InventoryItem.yaml | Adds acquisition/attribution and additional metadata fields. |
| openapi/components/schemas/InventoryDrop.yaml | Renames/remaps drop status fields and adjusts required fields. |
| openapi/components/schemas/Instance.yaml | Adds nullability and additional instance language/performance fields. |
| openapi/components/schemas/InfoPushIpsQuery.yaml | New schema for InfoPush IPS query parameters. |
| openapi/components/schemas/InfoPushExperiment.yaml | New schema for InfoPush experiment metadata. |
| openapi/components/schemas/InfoPushEmbeddedLink.yaml | New schema for embedded link data structures. |
| openapi/components/schemas/InfoPushDataSearch.yaml | New schema for search payload within InfoPush data. |
| openapi/components/schemas/InfoPushDataClickable.yaml | Extends enum of supported “onPressed” commands. |
| openapi/components/schemas/InfoPushDataCategory.yaml | New schema for category metadata including localized names. |
| openapi/components/schemas/InfoPushDataArticleContent.yaml | Adds missing fields (id/title/videoUrl) to article content blocks. |
| openapi/components/schemas/InfoPushDataArticle.yaml | Expands article schema to include lists/links rather than single content ref. |
| openapi/components/schemas/InfoPushData.yaml | Significantly expands InfoPush data fields and localized-string handling. |
| openapi/components/schemas/InfoPush.yaml | Adds new properties and nullability adjustments for InfoPush items. |
| openapi/components/schemas/GroupRoleTemplateValues.yaml | Changes roles to an array of role objects via new schema. |
| openapi/components/schemas/GroupRoleTemplateRole.yaml | New schema for role template role entries. |
| openapi/components/schemas/GroupRole.yaml | Adds role flags (defaultRole, isAddedOnJoin). |
| openapi/components/schemas/GroupPost.yaml | Renames role field to roleIds to match list type. |
| openapi/components/schemas/GroupPermission.yaml | Adds dependsOn relationship field. |
| openapi/components/schemas/GroupAnnouncement.yaml | Documents announcement-as-post behavior and adds missing fields. |
| openapi/components/schemas/Group.yaml | Adds undocumented nameplate fields and normalizes formatting. |
| openapi/components/schemas/FriendRequestStatus.yaml | New schema documenting friend-request status string behavior. |
| openapi/components/schemas/FileAnalysisAvatarStats.yaml | Adds missing raycastCount field. |
| openapi/components/schemas/FavoritedWorld.yaml | Adds undocumented disabledPropAbilities field. |
| openapi/components/schemas/EconomyBalances.yaml | Adjusts required fields to match observed responses. |
| openapi/components/schemas/DynamicContentRow.yaml | Expands dynamic content row fields and localizable naming behavior. |
| openapi/components/schemas/CurrentUserPresence.yaml | Adds additional presence/profile presentation fields. |
| openapi/components/schemas/CurrentUser.yaml | Expands CurrentUser with many observed fields and tweaks deprecation text wrapping. |
| openapi/components/schemas/CalendarEventDiscovery.yaml | Adjusts required fields to match observed pagination behavior. |
| openapi/components/schemas/CalendarEvent.yaml | Adds occurrenceModified field. |
| openapi/components/schemas/BareError.yaml | New schema for error bodies that only contain a message string. |
| openapi/components/schemas/Avatar.yaml | Wraps long descriptions and adds a placeholder attribution field. |
| openapi/components/schemas/APIConfigProfileDefaults.yaml | New schema for default profile theme colors. |
| openapi/components/schemas/APIConfigLoadingScreenWeights.yaml | New schema for loading screen category weighting. |
| openapi/components/schemas/APIConfigEventShelfCampaign.yaml | New schema for event shelf campaign configuration. |
| openapi/components/schemas/APIConfigEvents.yaml | Adds an additional events config boolean flag. |
| openapi/components/schemas/APIConfigAudioConfig.yaml | Adds additional audio config fields. |
| openapi/components/schemas/APIConfig.yaml | Adds note about decoy properties and permits additional properties; adds many observed config fields. |
| openapi/components/responses/users/UserResponse.yaml | Documents that self-lookup may return CurrentUser and conditionally models schema. |
| openapi/components/responses/users/UserNotFoundError.yaml | New reusable 404 error response for missing users. |
| openapi/components/responses/users/UpdateOtherUserForbiddenError.yaml | New reusable 403 error response for editing other users. |
| openapi/components/responses/users/PersistenceOwnershipError.yaml | New reusable 403 error response using BareError shape. |
| openapi/components/responses/system/InfoPushBadRequestError.yaml | New 400 error response for InfoPush list-parameter validation. |
| openapi/components/responses/RouteNotImplementedError.yaml | New response component referencing RouteNotImplemented schema. |
| openapi/components/responses/RequestValidationError.yaml | New response component for request-body validation failures. |
| openapi/components/responses/notifications/HideNotificationSuccess.yaml | New success response component for hide-notification operation. |
| openapi/components/responses/instances/InstanceBadRequestError.yaml | New 400 response component for instance creation failures. |
| openapi/components/responses/groups/GroupPostsResponse.yaml | Adds total field to group posts response schema. |
| openapi/components/responses/economy/StoresUnavailableError.yaml | New 403 error response for store visibility/availability. |
| openapi/components/responses/economy/ProductListingsForbiddenError.yaml | New 403 error response for accessing other users’ listings. |
| openapi/components/responses/economy/AccountStateError.yaml | New 400 error response for invalid account state in economy flows. |
| openapi/components/responses/authentication/SsoTokenResponse.yaml | New response component for SSO token endpoint. |
| openapi/components/responses/authentication/SsoProviderUnsupportedError.yaml | New 400 error response for unsupported SSO provider. |
| openapi/components/responses/authentication/OAuthRedirectCodeResponse.yaml | New response component for OAuth redirect code endpoint. |
| openapi/components/requests/UpdateWorldRequest.yaml | Adds missing request fields for world updates. |
| openapi/components/requests/CreateInstanceRequest.yaml | Removes nullable: true for displayName in create-instance request. |
| openapi/components/requests/CreateGroupAnnouncementRequest.yaml | Fixes required fields for announcement creation request. |
| openapi/components/paths/worlds.yaml | Adds validation/permission responses and corrects tag-deletion path naming. |
| openapi/components/paths/users.yaml | Adds missing 403/404 responses and tags deprecated operations. |
| openapi/components/paths/props.yaml | Adds 400 validation errors and marks removed routes as deprecated with RouteNotImplemented errors. |
| openapi/components/paths/notifications.yaml | Corrects hide-notification 200 response to a success envelope. |
| openapi/components/paths/miscellaneous.yaml | Adds missing 401/400 responses for health/infoPush endpoints. |
| openapi/components/paths/jams.yaml | Normalizes formatting and adds a 400 validation response to submission endpoint. |
| openapi/components/paths/invite.yaml | Adds 403 responses mirroring existing authorization errors. |
| openapi/components/paths/instances.yaml | Adds 400 response and makes some endpoints optionally authenticated. |
| openapi/components/paths/groups.yaml | Large normalization plus many missing 400/403 responses and optional deprecation tagging. |
| openapi/components/paths/favorites.yaml | Adds query parameter and 400 validation response. |
| openapi/components/paths/economy.yaml | Adds deprecation markers, new parameters, and missing error responses. |
| openapi/components/paths/calendar.yaml | Makes some endpoints optionally authenticated and documents rationale. |
| openapi/components/paths/avatars.yaml | Adds validation response and wraps long descriptions. |
| openapi/components/paths/authentication.yaml | Adds OAuth redirect code and SSO token endpoints and responses. |
| openapi/components/paths.yaml | Wires new/renamed paths into the root paths index. |
| openapi/components/parameters.yaml | Adds SSO provider path param and new query param variants (e.g., favoriteGroupTypeQuery). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
273
to
276
| /economy/stores: | ||
| parameters: | ||
| - $ref: ../parameters.yaml#/sellerIdQuery | ||
| - $ref: ../parameters.yaml#/sellerId | ||
| - $ref: ../parameters.yaml#/managementPov |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 103 out of 103 changed files in this pull request and generated no new comments.
Suppressed comments (3)
openapi/components/paths/economy.yaml:276
/economy/storesis described as "optionally filtered to a seller", but the parameters list now references#/sellerId, which is markedrequired: trueincomponents/parameters. This makes the filter mandatory and conflicts with the endpoint description / likely behavior. Use the optional#/sellerIdQueryparameter here (or makesellerIdoptional if you intend it to be required everywhere).
/economy/stores:
parameters:
- $ref: ../parameters.yaml#/sellerId
- $ref: ../parameters.yaml#/managementPov
openapi/components/responses/users/UserNotFoundError.yaml:9
- The example error message uses inconsistent casing (
"not Found") compared to other NotFound examples in this spec (typically"not found"). If this string isn't required to match the upstream API exactly, consider normalizing it for consistency/readability.
openapi/components/paths/users.yaml:166 /users/activedoesn't take a user id, but the added404response referencesUserNotFoundError, whose description is specifically about a missing user by id. Unless the upstream API is confirmed to return this exact 404/error body for this search endpoint, this response mapping is misleading and should be removed or replaced with an endpoint-appropriate error response.
"404":
$ref: ../responses/users/UserNotFoundError.yaml
jellejurre
reviewed
Aug 4, 2026
| tags: | ||
| - instances | ||
| security: | ||
| - {} |
Contributor
There was a problem hiding this comment.
Why is this empty object added here?
Member
Author
There was a problem hiding this comment.
If security has authCookie, it signifies that the endpoint requires authentication, if it also contains an empty security, it signifies authentication is optional.
| tags: | ||
| - instances | ||
| security: | ||
| - {} |
| "403": | ||
| $ref: ../responses/NoPermission.yaml | ||
| "404": | ||
| $ref: ../responses/props/NoSuchPropError.yaml |
| $ref: ../responses/economy/SellerEligibilityResponse.yaml | ||
| "401": | ||
| $ref: ../responses/MissingCredentialsError.yaml | ||
| "404": |
Contributor
There was a problem hiding this comment.
This entire error should not exist, right?
jellejurre
reviewed
Aug 4, 2026
| "401": | ||
| $ref: ../responses/MissingCredentialsError.yaml | ||
| "404": | ||
| $ref: ../responses/RouteNotImplementedError.yaml |
Contributor
There was a problem hiding this comment.
Same here and with all other instances of this error
Member
Author
There was a problem hiding this comment.
The new test suite checks that a response completely matches, and for removed endpoints
If we mark them as depricated (and keep them in the spec) we might as well assert that they stay removed and not reappear at some point.
| @@ -0,0 +1,11 @@ | |||
| description: Bad request error response when a list parameter is not an array. | |||
Contributor
There was a problem hiding this comment.
Why is this seperate from the generic RequestValidationError?
| @@ -0,0 +1,11 @@ | |||
| description: Bad request error response when creating an instance | |||
Contributor
There was a problem hiding this comment.
Why is this seperate from the generic RequestValidationError?
| @@ -0,0 +1,10 @@ | |||
| description: The route is not served by VRChat. A live route answers 200 or 401. | |||
Contributor
There was a problem hiding this comment.
Way more status codes are returned according to the spec
| @@ -1,2 +1,6 @@ | |||
| title: NotificationDetailEmpty | |||
Contributor
There was a problem hiding this comment.
Is there any reason not to merge all the empty schemas other than comments?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.