[API Clarification] Clarify what the legacy "year" field means on albums now that we have originalReleaseDate

[dweymouth]

Type of change

API Clarification

Proposal description

Since "originalReleaseDate" is now a field on the OpenSubsonic AlbumID3, should we clarify that "Year" should always be the reissue year of the release, if available? Or should we add another "reissueDate" OpenSubsonic field so that the year can be the original release year?

Backward compatibility impact

Clarifying that "year" means reissue year might not be the behavior expected by legacy clients. Adding a new "reissueDate" field would have no backward compatibility impact

Backward compatibility

• No backward compatibility impact.

API details

Either specify that year is the reissue year if both original and reissue dates are known; or create a new reissueDate field alongside originalReleaseDate

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[Tolriq]

There's no concept of reissue Date in tags.

There's Original release date that is now exposed.

There's recording date and year (they are linked in the tags definitions)

And there's release date that can be different from the recording date, remaster, ...

So year is recording date and I don't think we should change it's definition if there's any doubts around it as whatever we enforce it can be breaking for some.

But we can expose recordingDate and releaseDate as new fields if wanted yes.

BTW you did not review you request (#65) ;)

[dweymouth]

Approved - thanks for the reminder :) Also you are right it looks like releaseDate is the standard naming of the tag. I can prepare a PR to add releaseDate later. I think it would be really useful for clients to be able to display the original year and reissue year of the release, if the release in the user's library is a remaster or special edition for example

[certuna]

I agree here - makes sense adding releaseDate

Problem that the recording year for an album often is not actually a single value - hundreds of thousands of albums have songs from different years on them, it's so common you can't even call it an edge case. This is why Navidrome displays for an album a year range (minYear-maxYear, "1995-2005") aggregated from the individual recording dates of the songs, while the releaseDate and originalReleaseDate of the album is, logically, a singular date ("2018-12-31")

[dweymouth]

Oh - another question is are servers allowed to put just a year in the releaseDate and originalReleaseDate fields, or fill in the month and day to 01/01 if the file tags only specify the year and not the full date?

[dweymouth]

It wouldn't be a random string if we define the format as such. You could tell which of the 3 sub-formats you have just by strlen, and then a simple regex or even just atoi on the known substring indices where the year, month, and day are found to parse it.

I don't care that strongly either way, it just seems like maybe a full xml node / json object just for a year-month-day is a bit overengineered

[Tolriq]

It's still a string to parse with 3 possible values and error handling.Versus a properly defined object.

Since we improve the API let's do it correctly. This is not over engineering, this is a strongly typed API results.

[dweymouth]

Has there been any offline discussion on this? I'm fine with going with the complex object for dates, just hoping @epoupon and @Tolriq can coordinate the breaking change so we don't have to support both originalReleaseDate and originalReleaseDate2

[Tolriq]

I have already marked the field to ignore invalid data and it's in prod, so we can migrate at any time, it won't break sync, just no data is not matching but that's a small issue.

[dweymouth]

Sounds good, I can prepare a PR to update the type of that field and tag you and epoupon as reviewers (and it'd need a 3rd signoff as well like every merge)

[certuna]

The dates definition has always been tricky in the tags:

• there's date, TDRC ("recording time") in id3v2.4, aka Year in iTunes/Apple Music. Strictly it should hold the recording date, but often (mis?)used to store the album (re)release date instead, for example by Picard, Beets, etc.
• there's originaldate, TDOR which according to id3v2.4 means the date when the original (in case of a cover, a classical composition, a live version, etc) was released, but over the years this field got re-purposed by many (incl. Picard) to mean "original album release date"
• there's releasedate, TDRL, which is pretty straightforward

Assuming that OpenSubsonic does not want to go into the minefield of trying to say who's using it wrong, probably best to just support originaldate/date/releasedate, and let servers/clients figure out what that actually means?

[Tolriq]

and let servers/clients figure out what that actually means?

This is exactly why OpenSubsonic was started, a public API used by multiple different server must behave the same between the servers. Else we're back to square one and every server implementing Subsonic in a different way.
The default behavior should be well define. If servers want to offer settings to override the default so that the user can adapt or to fit new needs this is fine. But clients and servers must have a common ground to ensure a standard behavior.

[certuna]

That's fine with me but then what should we follow then - does originalDate mean what id3v2.4 says (original date of the song/work, i.e. 1789 for some classical piece), or what Picard/etc use it for (original album date)?

[Tolriq]

That's the whole point of the discussion in #68 ;)

[certuna]

Ah sorry yes I'll continue there then :)