feat(openapi): document error responses and undocumented schema fields

[ariesclark]

No description provided.

[Copilot]

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.

[Copilot]

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/stores is described as "optionally filtered to a seller", but the parameters list now references #/sellerId, which is marked required: true in components/parameters. This makes the filter mandatory and conflicts with the endpoint description / likely behavior. Use the optional #/sellerIdQuery parameter here (or make sellerId optional 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/active doesn't take a user id, but the added 404 response references UserNotFoundError, 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

[lillithrosepup]

surface level diff nitpicks, no actual api checking

[Copilot]

Pull request overview

Copilot reviewed 118 out of 118 changed files in this pull request and generated no new comments.

Suppressed comments (2)

openapi/components/schemas/InfoPushEmbeddedLink.yaml:13

• The properties here are not in alphabetical order (parameters appears before command, id, and name), which deviates from the alphabetical property ordering consistently followed across the other schemas in this repository (e.g., InfoPushDataArticleContent.yaml, InfoPushData.yaml). Consider reordering for consistency. (Optional/nit.)
  openapi/components/schemas/InventoryMetadata.yaml:25
• There is a stray blank line between the propId and propKind properties, which is inconsistent with the rest of this mapping (and the other schema files). Consider removing it. (Optional/nit.)