Something + add comments to proto

proto/metadata/v1/metadata.proto

@@ -4,8 +4,12 @@ package metadata.v1;
 
 option go_package = "github.com/metadata-agregator/pkg/gen/metadata/v1;metadatav1";
 
+// Provider identifies the upstream metadata source a request is resolved
+// against. It also selects which ID namespace bare `id` fields refer to.
 enum Provider {
+  // Unset. Requests default to the server's configured default provider.
   PROVIDER_UNSPECIFIED = 0;
+  // MusicBrainz (https://musicbrainz.org). Native IDs are MBIDs (UUIDs).
   PROVIDER_MUSICBRAINZ = 1;
 }
 
@@ -22,179 +26,319 @@ service MetadataService {
 
 // Requests
 
+// GetArtistRequest looks up a single artist by one of its identifiers.
 message GetArtistRequest {
+  // How to locate the artist. Exactly one field must be set.
   oneof identifier {
+    // Provider-native identifier for the artist, in the ID namespace of
+    // `provider`. For PROVIDER_MUSICBRAINZ this is the artist MBID.
+    // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da" (Radiohead).
     string id = 1;
+    // Identifier from a specific external source, when the source differs
+    // from `provider` or must be named explicitly.
+    // Example: {source: "musicbrainz", source_id: "5b11f4ce-..."}.
     ExternalID external = 2;
   }
+  // Source to resolve against and the ID namespace of `id`.
+  // Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 3;
 }
 
+// SearchArtistsRequest performs a fuzzy, paginated artist search.
 message SearchArtistsRequest {
+  // Free-text search terms, typically the artist name. Example: "radiohead".
   string query = 1;
+  // Maximum number of results to return. Example: 25 (0 uses the default).
   int32 limit = 2;
+  // Number of leading results to skip, for pagination. Example: 25.
   int32 offset = 3;
+  // Source to search. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 4;
 }
 
+// GetAlbumRequest looks up a single album (release group) by identifier.
 message GetAlbumRequest {
+  // How to locate the album. Exactly one field must be set.
   oneof identifier {
+    // Provider-native album identifier, in the ID namespace of `provider`.
+    // For PROVIDER_MUSICBRAINZ this is the release-group MBID.
+    // Example: "b1392450-e666-3926-a536-22c65f834433" (OK Computer).
     string id = 1;
+    // Identifier from a specific external source.
+    // Example: {source: "musicbrainz", source_id: "b1392450-..."}.
     ExternalID external = 2;
   }
+  // Source to resolve against. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 3;
 }
 
+// GetArtistAlbumsRequest lists an artist's albums, paginated and optionally
+// filtered by release type.
 message GetArtistAlbumsRequest {
+  // Provider-native artist identifier (same namespace as GetArtistRequest.id).
+  // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da".
   string artist_id = 1;
+  // Maximum number of albums to return. Example: 50.
   int32 limit = 2;
+  // Number of leading albums to skip, for pagination. Example: 0.
   int32 offset = 3;
+  // Source to query. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 4;
+  // Optional release-type filter; empty means all types.
+  // Example: ["album", "ep"].
   repeated string album_types = 5;
 }
 
+// GetTrackRequest looks up a single track (recording) by identifier.
 message GetTrackRequest {
+  // How to locate the track. Exactly one field must be set.
   oneof identifier {
+    // Provider-native track identifier, in the ID namespace of `provider`.
+    // For PROVIDER_MUSICBRAINZ this is the recording MBID.
+    // Example: "b9d99e0e-1472-4a37-8b2a-2f6b0a1234ab".
     string id = 1;
+    // Identifier from a specific external source.
+    // Example: {source: "musicbrainz", source_id: "b9d99e0e-..."}.
     ExternalID external = 2;
+    // International Standard Recording Code. Example: "GBAYE9600477".
     string isrc = 3;
   }
+  // Source to resolve against. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 4;
 }
 
+// GetAlbumTracksRequest lists the tracks belonging to an album.
 message GetAlbumTracksRequest {
+  // Provider-native album identifier (same namespace as GetAlbumRequest.id).
+  // Example: "b1392450-e666-3926-a536-22c65f834433".
   string album_id = 1;
+  // Source to query. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 2;
 }
 
+// SearchAlbumsRequest performs a fuzzy, paginated album search.
 message SearchAlbumsRequest {
+  // Free-text search terms, typically the album title. Example: "ok computer".
   string query = 1;
+  // Optional artist name to narrow the search. Example: "radiohead".
   string artist = 2;
+  // Maximum number of results to return. Example: 25.
   int32 limit = 3;
+  // Number of leading results to skip, for pagination. Example: 0.
   int32 offset = 4;
+  // Source to search. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 5;
+  // Optional release-type filter; empty means all types.
+  // Example: ["album"].
   repeated string album_types = 6;
 }
 
+// SyncArtistRequest fetches an artist and their catalog from a provider and
+// persists it to the local store.
 message SyncArtistRequest {
+  // How to identify the artist to sync. Exactly one field must be set.
   oneof target {
+    // Artist name to resolve via search before syncing. Example: "Radiohead".
     string name = 1;
+    // Exact external identifier of the artist to sync.
+    // Example: {source: "musicbrainz", source_id: "5b11f4ce-..."}.
     ExternalID external = 2;
   }
+  // Source to sync from. Example: PROVIDER_MUSICBRAINZ.
   Provider provider = 3;
 }
 
 // Responses
 
 message GetArtistResponse {
+  // The resolved artist.
   Artist artist = 1;
 }
 
 message SearchArtistsResponse {
+  // Matching artists, ordered by relevance.
   repeated Artist artists = 1;
+  // Total number of matches available across all pages. Example: 137.
   int32 total = 2;
 }
 
 message GetAlbumResponse {
+  // The resolved album.
   Album album = 1;
 }
 
 message GetArtistAlbumsResponse {
+  // The artist's albums for the requested page.
   repeated Album albums = 1;
+  // Total number of albums available across all pages. Example: 42.
   int32 total = 2;
 }
 
 message GetTrackResponse {
+  // The resolved track.
   Track track = 1;
 }
 
 message GetAlbumTracksResponse {
+  // The album's tracks, ordered by disc then track number.
   repeated Track tracks = 1;
 }
 
 message SearchAlbumsResponse {
+  // Matching albums, ordered by relevance.
   repeated Album albums = 1;
+  // Total number of matches available across all pages. Example: 58.
   int32 total = 2;
 }
 
 message SyncArtistResponse {
+  // The synced artist as persisted locally.
   Artist artist = 1;
+  // Number of albums fetched and stored during the sync. Example: 12.
   int32 albums_synced = 2;
+  // Number of tracks fetched and stored during the sync. Example: 148.
   int32 tracks_synced = 3;
 }
 
 // Core Entities
 
+// Artist is a performer or group.
 message Artist {
+  // Provider-native identifier (MBID for MusicBrainz).
+  // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da".
   string id = 1;
+  // Display name. Example: "Radiohead".
   string name = 2;
+  // Name normalized for alphabetical sorting. Example: "Radiohead"; for a
+  // person, "Beatles, The" or "Hendrix, Jimi".
   string sort_name = 3;
+  // Kind of artist. Example: "Group", "Person".
   string artist_type = 4;
+  // ISO 3166-1 alpha-2 country code. Example: "GB".
   string country = 5;
+  // Date the artist formed or was born, ISO 8601. Partial dates allowed.
+  // Example: "1985" or "1985-05-01".
   string formed_date = 6;
+  // Date the artist disbanded or died, ISO 8601; empty if still active.
+  // Example: "2011-04-30".
   string disbanded_date = 7;
+  // Free-text biography or annotation.
   string description = 8;
+  // URL of a representative image. Example: "https://example.org/radiohead.jpg".
   string image_url = 9;
+  // Genres associated with the artist.
   repeated Genre genres = 10;
+  // Identifiers for this artist in external sources.
   repeated ExternalID external_ids = 11;
 }
 
+// Album is a release group / collection of tracks.
 message Album {
+  // Provider-native identifier (release-group MBID for MusicBrainz).
+  // Example: "b1392450-e666-3926-a536-22c65f834433".
   string id = 1;
+  // Album title. Example: "OK Computer".
   string title = 2;
+  // Release type. Example: "album", "ep", "single", "compilation".
   string album_type = 3;
+  // Release date, ISO 8601. Partial dates allowed. Example: "1997-05-21".
   string release_date = 4;
+  // Universal Product Code (barcode). Example: "724385522925".
   string upc = 5;
+  // Number of tracks across all discs. Example: 12.
   int32 total_tracks = 6;
+  // Number of discs in the release. Example: 1.
   int32 total_discs = 7;
+  // URL of the cover art. Example: "https://coverartarchive.org/release/.../front".
   string cover_url = 8;
+  // Credited artists, in credit order.
   repeated ArtistCredit artists = 9;
+  // Releasing label, if known.
   Label label = 10;
+  // Genres associated with the album.
   repeated Genre genres = 11;
+  // Identifiers for this album in external sources.
   repeated ExternalID external_ids = 12;
 }
 
+// Track is a recording as it appears on an album.
 message Track {
+  // Provider-native identifier (recording MBID for MusicBrainz).
+  // Example: "b9d99e0e-1472-4a37-8b2a-2f6b0a1234ab".
   string id = 1;
+  // Track title. Example: "Paranoid Android".
   string title = 2;
+  // Playing time in milliseconds. Example: 383000 (6:23).
   int32 duration_ms = 3;
+  // International Standard Recording Code. Example: "GBAYE9600477".
   string isrc = 4;
+  // Whether the track is flagged as explicit.
   bool explicit = 5;
+  // 1-based disc number the track appears on. Example: 1.
   int32 disc_number = 6;
+  // 1-based position of the track within its disc. Example: 2.
   int32 track_number = 7;
+  // Credited performers, in credit order.
   repeated ArtistCredit artists = 8;
+  // Underlying composition, if linked.
   Work work = 9;
+  // Identifiers for this track in external sources.
   repeated ExternalID external_ids = 10;
 }
 
+// Work is the underlying composition a track recording is based on.
 message Work {
+  // Provider-native identifier (work MBID for MusicBrainz).
   string id = 1;
+  // Work title. Example: "Paranoid Android".
   string title = 2;
+  // Kind of work. Example: "Song".
   string work_type = 3;
+  // ISO 639-3 language code of the lyrics. Example: "eng".
   string language = 4;
+  // Credited composers and lyricists.
   repeated ArtistCredit composers = 5;
 }
 
+// Label is a record label.
 message Label {
+  // Provider-native identifier (label MBID for MusicBrainz).
   string id = 1;
+  // Label name. Example: "Parlophone".
   string name = 2;
+  // ISO 3166-1 alpha-2 country code. Example: "GB".
   string country = 3;
 }
 
+// Genre is a musical genre tag.
 message Genre {
+  // Provider-native identifier (genre MBID for MusicBrainz).
   string id = 1;
+  // Genre name. Example: "alternative rock".
   string name = 2;
 }
 
+// ArtistCredit links an artist to a release or track, preserving how the
+// artist is credited (role, order, and connecting text).
 message ArtistCredit {
+  // The credited artist.
   Artist artist = 1;
+  // Role in this credit. Example: "main", "featured", "composer".
   string role = 2;
+  // 0-based position within the credit list. Example: 0.
   int32 position = 3;
+  // Text joining this credit to the next. Example: " feat. " or " & ".
   string join_phrase = 4;
 }
 
+// ExternalID identifies an entity within a third-party source.
 message ExternalID {
+  // Source name. Example: "musicbrainz", "spotify", "discogs".
   string source = 1;
+  // The entity's identifier within that source.
+  // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da".
   string source_id = 2;
+  // Canonical URL of the entity at the source, if available.
+  // Example: "https://musicbrainz.org/artist/5b11f4ce-...".
   string url = 3;
 }