Reorganize OpenAPI schema properties for consistency by deluan · Pull Request #207 · opensubsonic/open-subsonic-api

deluan · 2026-02-08T15:28:10Z

Summary

This PR reorganizes properties across multiple OpenAPI schema files to establish a consistent ordering convention. Properties are reordered to group related fields together and follow a logical hierarchy, improving schema readability and maintainability.

Refer to #206

Key Changes

Schema Property Reordering

AlbumID3.json: Reorganized properties to group core album info (year, coverArt, starred) before metadata (duration, playCount, genre), moved artistId and songCount to end
AlbumInfo.json: Moved lastFmUrl to end after image URLs
Artist.json: Reordered to place starred before artistImageUrl
ArtistID3.json: Moved artistImageUrl after albumCount
ArtistInfo.json & ArtistInfo2.json: Moved lastFmUrl to end after image URLs
Bookmark.json: Moved entry property to beginning before position
Child.json: Significant reorganization - moved starred and played earlier, grouped rating/review fields together, moved video-specific and transcoding properties to end
Directory.json: Moved child array before parent, moved playCount to end
Genre.json: Reordered to place counts before value
JukeboxStatus.json: Moved position before volume
Lyrics.json: Moved value to end after artist/title
Playlist.json: Reorganized to group dates (created/changed) together, moved readonly/validUntil before comment, moved allowedUsernames to end
Share.json: Moved expires/lastVisited to end after entries
User.json: Moved folder to beginning, moved maxBitRate before videoConversionRole

Formatting Improvements

Fixed JSON formatting in AlbumID3.json and Child.json (proper indentation for allOf references)
Added newline at end of files for consistency across all modified schemas
Fixed spacing in Child.json example array formatting

Implementation Details

No functional changes to API contracts - this is purely organizational
Properties maintain their original types, descriptions, and validation rules
Follows a pattern of grouping core/primary properties first, then metadata, then optional/extended properties
Improves schema documentation readability and developer experience

Reorder properties in 15 OpenAPI schema files to match the attribute order used in the markdown documentation JSON examples. This makes it easier to verify that both sources contain identical properties and improves consistency across the project. Affected schemas: AlbumID3, AlbumInfo, Artist, ArtistID3, ArtistInfo, ArtistInfo2, Bookmark, Child, Directory, Genre, JukeboxStatus, Lyrics, Playlist, Share, User https://claude.ai/code/session_015LLNEbErYFkRrZvQZ3NMoV

netlify · 2026-02-08T15:28:16Z

✅ Deploy Preview for opensubsonic ready!

Name	Link
🔨 Latest commit	`6933fa4`
🔍 Latest deploy log	https://app.netlify.com/projects/opensubsonic/deploys/698d220ba0015600083bd5e4
😎 Deploy Preview	https://deploy-preview-207--opensubsonic.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

This PR reorganizes property ordering across multiple OpenAPI schema JSON files to make field layout more consistent and readable (referencing #206), plus a few formatting-normalization tweaks (e.g., allOf indentation, EOF newlines).

Changes:

Reordered properties in many schemas to group related fields and apply a consistent hierarchy.
Normalized some JSON formatting (notably allOf formatting and spacing) and ensured trailing newlines.
Minor reorganizations within complex schemas (notably Child.json) to group rating/review/video/transcoding fields.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
openapi/schemas/AlbumID3.json	Reordered core album fields and reformatted `allOf` blocks.
openapi/schemas/AlbumInfo.json	Moved `lastFmUrl` after image URLs.
openapi/schemas/Artist.json	Reordered `starred` before `artistImageUrl`.
openapi/schemas/ArtistID3.json	Moved `artistImageUrl` after `albumCount`.
openapi/schemas/ArtistInfo.json	Moved `lastFmUrl` after image URLs.
openapi/schemas/ArtistInfo2.json	Moved `lastFmUrl` after image URLs.
openapi/schemas/Bookmark.json	Moved `entry` earlier; reformatted `allOf` usage.
openapi/schemas/Child.json	Significant property regrouping; formatting normalization; moved rating/video/transcoding-related fields later.
openapi/schemas/Directory.json	Moved `child` before `parent`, moved `playCount` later.
openapi/schemas/Genre.json	Moved `value` after count fields.
openapi/schemas/JukeboxStatus.json	Moved `position` before `volume`.
openapi/schemas/Lyrics.json	Moved `value` after `artist`/`title`.
openapi/schemas/Playlist.json	Grouped `created`/`changed`; repositioned readonly/cache/comment-related fields.
openapi/schemas/Share.json	Moved `expires`/`lastVisited` after `entry`.
openapi/schemas/User.json	Moved `folder` to the beginning and `maxBitRate` near other capability flags.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

openapi/schemas/Child.json

openapi/schemas/AlbumID3.json

openapi/schemas/JukeboxStatus.json

openapi/schemas/Share.json

lachlan-00 · 2026-02-11T23:11:28Z

The arrangement of child in the doc and table is out of order and date

I think child spec here is more correct so that's a todo to update the examples and doc tables on the responses path after this

- Child.json: "played" refers to media, not album - AlbumID3.json: "starred" means starred/favorited, not added - Share.json: fix grammar "A list of shares"

lachlan-00 · 2026-02-11T23:21:16Z

@deluan if you want i can generate a diff instead of going through all these comments one at a time. which is a bit much for this.

Few things i noticed though.

Spec, vs output example, vs element list. in that conflict who is the winner?

If we focus on the spec first and then update docs and examples should we make sure that required elements are first followed by optional?

Then with OS elements should we append them to the bottom of the response unless required?

deluan · 2026-02-11T23:24:37Z

I'm fixing the discrepancies now, byt comparing with the OG Subsonic docs in:

The original Subsonic XSD and OpenSubsonic docs both use "gain" (float), not "volume" (integer). Fix the field name and change type from integer to number to match the 0.0-1.0 float range.

deluan · 2026-02-11T23:27:10Z

There are some errors in the OpenAPI spec. Ex:

JukeboxStatus does not have volume, it should be gain.
The averageRating cannot be 0, the original docs says min=1.0

I'm fixing those based on the original XSD spec.

The original Subsonic XSD defines AverageRating as xs:double with minInclusive=1.0, and the description already says "[1.0-5.0]". Directory and Artist schemas already use minimum: 1; only Child had the incorrect minimum: 0.

deluan · 2026-02-11T23:30:09Z

The arrangement of child in the doc and table is out of order and date

I think child spec here is more correct so that's a todo to update the examples and doc tables on the responses path after this

I can ask Claude to fix this as well, as part of this. Let me know.

lachlan-00 · 2026-02-11T23:51:54Z

That would be a huge help. examples aren't a huge one but the element tables matching the spec means they're consistent.

I'll keep reviewing here then if claude can do that

Aligns the documentation table with the Child.json schema ordering. Also fixes "played" description from "album" to "media".

The email field is defined in the original Subsonic XSD and was already present in the doc examples, but was missing from both the OpenAPI schema and the doc table.

deluan marked this pull request as ready for review February 9, 2026 21:57

Copilot AI review requested due to automatic review settings February 9, 2026 21:57

Copilot started reviewing on behalf of deluan February 9, 2026 21:57 View session

Copilot AI reviewed Feb 9, 2026

View reviewed changes

Fix description inconsistencies from PR review feedback

965b07e

- Child.json: "played" refers to media, not album - AlbumID3.json: "starred" means starred/favorited, not added - Share.json: fix grammar "A list of shares"

Fix JukeboxStatus: rename volume to gain and fix type

a3ba94d

The original Subsonic XSD and OpenSubsonic docs both use "gain" (float), not "volume" (integer). Fix the field name and change type from integer to number to match the 0.0-1.0 float range.

Fix Child averageRating minimum: 0 -> 1 to match XSD

1aacec4

The original Subsonic XSD defines AverageRating as xs:double with minInclusive=1.0, and the description already says "[1.0-5.0]". Directory and Artist schemas already use minimum: 1; only Child had the incorrect minimum: 0.

deluan added 2 commits February 11, 2026 19:32

Reorder Child.md doc table to match schema property order

c79da7e

Aligns the documentation table with the Child.json schema ordering. Also fixes "played" description from "album" to "media".

Add missing email field to User schema and doc table

6933fa4

The email field is defined in the original Subsonic XSD and was already present in the doc examples, but was missing from both the OpenAPI schema and the doc table.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganize OpenAPI schema properties for consistency#207

Reorganize OpenAPI schema properties for consistency#207
deluan wants to merge 6 commits intomainfrom
claude/sync-openapi-examples-TZWw1

deluan commented Feb 8, 2026 •

edited

Loading

Uh oh!

netlify bot commented Feb 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lachlan-00 commented Feb 11, 2026

Uh oh!

lachlan-00 commented Feb 11, 2026

Uh oh!

deluan commented Feb 11, 2026

Uh oh!

deluan commented Feb 11, 2026 •

edited

Loading

Uh oh!

deluan commented Feb 11, 2026

Uh oh!

lachlan-00 commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

deluan commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Schema Property Reordering

Formatting Improvements

Implementation Details

Uh oh!

netlify bot commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for opensubsonic ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lachlan-00 commented Feb 11, 2026

Uh oh!

lachlan-00 commented Feb 11, 2026

Uh oh!

deluan commented Feb 11, 2026

Uh oh!

deluan commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

deluan commented Feb 11, 2026

Uh oh!

lachlan-00 commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

deluan commented Feb 8, 2026 •

edited

Loading

netlify bot commented Feb 8, 2026 •

edited

Loading

deluan commented Feb 11, 2026 •

edited

Loading