discogs-service/Sources/DiscogsService/openapi.yaml

## ===----------------------------------------------------------------------===
## 
## This source file is part of the Discogs Service open source project
## 
## Copyright (c) 2025 Röck+Cöde VoF. and the Discogs Service project authors
## Licensed under Apache license v2.0
## 
## See LICENSE for license information
## See CONTRIBUTORS for the list of Discogs Service project authors
##
## SPDX-License-Identifier: Apache-2.0
## 
## ===----------------------------------------------------------------------===

openapi: 3.1.1
info:
  title: Discogs API
  version: v2.0
  summary: The Discogs RESTFul API.
  description: |
    # Overview

    The Discogs API v2.0 is a RESTful interface to Discogs data. You can access JSON-formatted information about Database objects such as _Artists_, _Releases_, and _Labels_. Your application can also manage _User Collections_ and _Wantlists_, create _Marketplace_ listings, and more.
    
    Some Discogs data is made available under the [CC0 No Rights Reserved](https://creativecommons.org/public-domain/cc0/) license, and some is restricted data, as defined in our [API Terms of Use](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use).
    
    Our monthly data dumps are available under the the [CC0 No Rights Reserved](https://creativecommons.org/public-domain/cc0/) license.
    
    If you utilize the Discogs API, you are subject to the [API Terms of Use](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use). Please also ensure that any application you develop follows the Discogs [Application Name and Description Policy](https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use)

    # Quickstart 

    If you just want to see some results right now, issue this _curl_ command:

    ```bash
    curl https://api.discogs.com/releases/249504 --user-agent "FooBarApp/3.0"
    ```

    # General information

    General Information 

    **Your application must provide a User-Agent string that identifies itself** - preferably something that follows [RFC 1945](https://datatracker.ietf.org/doc/html/rfc1945#section-3.7). Some good examples include:
    
    ```
    AwesomeDiscogsBrowser/0.1 +http://adb.example.com
    LibraryMetadataEnhancer/0.3 +http://example.com/lime
    MyDiscogsClient/1.0 +http://mydiscogsclient.org
    ```
    
    Please don’t just copy one of those! Make it unique so we can let you know if your application starts to misbehave - the alternative is that we just silently block it, which will confuse and infuriate your users.
    
    Here are some bad examples that are unclear or obscure the nature of the application:
    
    ```
    curl/7.9.8 (i686-pc-linux-gnu) libcurl 7.9.8 (OpenSSL 0.9.6b)
    Mozilla/5.0 (X11; Linux i686; rv:6.0.2) Gecko/20100101 Firefox/6.0.2
    my app
    ```

    # Authentication

    Most endpoints require authentication. The API supports multiple methods:
    1.  **Discogs Auth (Key & Secret):** For read-only access to public data with a higher rate limit.
    2.  **Discogs Auth (Personal Access Token):** For full access to your own user account data.
    3.  **OAuth 1.0a:** For building third-party applications that act on behalf of other Discogs users.

    # Rate Limiting 

    **Requests are throttled by the server by source IP to 60 per minute for authenticated requests, and 25 per minute for unauthenticated requests, with some exceptions.**

    Your application should identify itself to our servers via a unique user agent string in order to achieve the maximum number of requests per minute.

    Our rate limiting tracks your requests using a moving average over a 60 second window. If no requests are made in 60 seconds, your window will reset.

    We attach the following headers to responses to help you track your rate limit use:

    * `X-Discogs-Ratelimit`: The total number of requests that can make in a one minute window.
    * `X-Discogs-Ratelimit-Used` : The number of requests made in an existing rate limit window.
    * `X-Discogs-Ratelimit-Remaining`: The number of remaining requests to make in an existing rate limit window.

    Your application should take our global limit into account and throttle its requests locally.

    In the future, we may update these rate limits at any time in order to provide service for all users.

    # Pagination 
    
    Some resources represent collections of objects and may be paginated. By default, 50 items per page are shown.
    
    To browse different pages, or change the number of items per page (up to 100), use the page and per_page query string parameters:

    ```
    GET https://api.discogs.com/artists/1/releases?page=2&per_page=75
    ```

    Responses include a `Link` header:

    ```
    Link: <https://api.discogs.com/artists/1/releases?page=3&per_page=75>; rel=next,
    <https://api.discogs.com/artists/1/releases?page=1&per_page=75>; rel=first,
    <https://api.discogs.com/artists/1/releases?page=30&per_page=75>; rel=last,
    <https://api.discogs.com/artists/1/releases?page=1&per_page=75>; rel=prev
    ```

    And a pagination object in the response body:

    ```json
    {
      "pagination": { 
        "page": 2, 
        "pages": 30, 
        "items": 2255, 
        "per_page": 75, 
        "urls":
          { 
            "first": "https://api.discogs.com/artists/1/releases?page=1&per_page=75",
            "prev": "https://api.discogs.com/artists/1/releases?page=1&per_page=75", 
            "next": "https://api.discogs.com/artists/1/releases?page=3&per_page=75", 
            last": "https://api.discogs.com/artists/1/releases?page=30&per_page=75"
          } 
      }, 
      "releases":
        [ ... ] 
      }
    }
    ```

    # Versioning and Media Types 

    Currently, the API only supports one version: `v2`. However, you can specify a version in your requests to future-proof your application. By adding an `Accept` header with the version and media type, you can guarantee your requests will receive data from the correct version you develop your app on.

    A standard `Accept` header may look like this:

    ```
    application/vnd.discogs.v2.html+json
    ```

    If case of requesting information from an endpoint that may have text formatting in it, it is possible to choose which kind of formatting to be returned by changing that section of the `Accept` header. We currently support 3 types:

    * `application/vnd.discogs.v2.html+json`
    * `application/vnd.discogs.v2.plaintext+json`
    * `application/vnd.discogs.v2.discogs+json`

    If no `Accept` header is supplied, or if the Accept header differs from one of the three previous options, we default to `application/vnd.discogs.v2.discogs+json`.

    # Videos 

    In case an application integrates **YouTube** videos, then third party cookies may be used. Please refer to the [YouTube and Google's cookie policy](https://policies.google.com/technologies/cookies).

    # FAQ 

    **1) Why am I getting an empty response from the server?**

    This generally happens when no `User-Agent` header is added to the requests.

    **2) How do I get updates about the API?**

    Subscribe to the [API Announcements forum thread](https://www.discogs.com/forum/thread/521520689469733cfcfd2089). For larger, breaking changes, an email notice to all developers with a registered Discogs application will be sent.

    **3) Where can I register a Discogs application?**

    A Discogs application can be registered on the [Developer Settings](https://www.discogs.com/settings/developers).

    **4) If I have a question/issue with the API, should I file a Support Request?**

    It's generally best to start out with a forum post on the [API topic](https://www.discogs.com/forum/topic/1082) since other developers may have had similar issues and they can point in the right direction. If the issue requires privacy, then a support request is the best way to go.

    **5) I'm getting a 404 response when trying to fetch images; what gives?**

    This may seem obvious, but make sure the URL has not been changed. The URLs returned are signed URLs, so trying to change one part of the URL (e.g., _Release ID_ number) will generally not work.

    **6) What are the authentication requirements for requesting images?**

    Please see the [Images documentation page](https://www.discogs.com/developers/#page:images).

    **7) Why am I getting a particular HTTP response?**

    **200 OK**

    The request was successful, and the requested data is provided in the response body.

    **201 Continue**

    POST request is sent to a list of resources to    create a new one. The ID of the newly-created resource will be provided in the body of the response.

    **204 No Content**

    The request was successful, and the server has no     additional information to convey, so the response body is empty.

    **401 Unauthorized**

    A resource that first requires [authentication](https://www.discogs.com/developers/#page:authentication) is being accessed. See Authenticating with OAuth.

    **403 Forbidden**

    The access to a resource is not allowed, even if authenticated. Trying to modify another user's profile, for example, will produce this error.

    **404 Not Found**

    The requested resource does not exist.

    **405 Method Not Allowed**

    A HTTP verb is not supported by the resource. Trying to `PUT` to `/artists/1`, for example, will fail because `Artists` are read-only.

    **422 Unprocessable Entity**

    Even though the request is well-formed, there is something semantically wrong with the body of the request. This can be due to malformed JSON, a missing parameter or the wrong type, or trying to perform an action that doesn not make any sense. Check the response body for specific information about what went wrong.

    **500 Internal Server Error**

    Something went wrong on the service while attempting to process the request. The message field of the response body will contain an error code that can be sent to Discogs Support (which will help on tracking down your specific issue).

  termsOfService: https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use
  contact:
    name: Discogs API Support
    url: https://www.discogs.com/forum/topic/1082
    email: api@discogs.com
  license:
    name: API Terms of Use
    url: https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use
externalDocs:
  description: Discogs Developers Portal
  url: https://www.discogs.com/developers
servers:
  - url: https://api.discogs.com/
    description: Live Server
tags:
  - name: Service
    description: Access data on the service.
  - name: Authentication
    description: Access data on authenticating to the service.
  - name: Database
    description: Access data on artists, labels, and releases.
  - name: User Identity
    description: Manage and retrieve user profile information, submissions, and contributions.
  - name: User Collection
    description: Manage a user's record collection.
  - name: User Wantlist
    description: Manage a user's wantlist.
  - name: User Lists
    description: Manage user-created lists.
  - name: Marketplace
    description: Interact with the marketplace, including listings, orders, and fees.
  - name: Inventory Management
    description: Bulk inventory management via CSV uploads and exports.
paths:
  /:
    get:
      summary: Get information about the service.
      description:  Retrieves any available information related to the service.
      operationId: getService
      tags:
        - Service
      responses: 
        '200':
          description: Service information returned successfully.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '500':
          $ref: '#/components/responses/Unavailable'
  /oauth/request_token:
    get:
      tags:
        - Authentication
      summary: Get details about a OAuth request token.
      description: |
        Retrieve a request token to initialize an *OAuth* authentication process.

        This endpoint represents the [2nd step of the OAuth flow process](https://www.discogs.com/developers#header-2.-send-a-get-request-to-the-discogs-request-token-url), thus it requires to configure an *Authorization* header to have a value like this:
        
        ```
        OAuth oauth_consumer_key="your_consumer_key", oauth_nonce="random_string_or_timestamp", oauth_signature="your_consumer_secret&", oauth_signature_method="PLAINTEXT", oauth_timestamp="current_timestamp", oauth_callback="your_callback"
        ```

        For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
      operationId: getRequestToken
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/UserAgent'
      responses:
        '200':
          description: |
            Successfully retrieved request token details.

            With this request token, then it is possible to continue with the [next step in the OAuth flow](https://www.discogs.com/developers#header-3.-redirect-your-user-to-the-discogs-authorize-page) process.
          headers:
            oauth_token:
              $ref: '#/components/headers/OAuthToken'
            oauth_token_secret: 
              $ref: '#/components/headers/OAuthSecret'
            oauth_callback-confirmed:
              $ref: '#/components/headers/OAuthCallback'
        '500':
          $ref: '#/components/responses/InternalError'
  /oauth/access_token:
    post:
      tags:
        - Authentication
      summary: Provide required credentials data to obtain an access token.
      description: |
        Provide to the service some required credentials details to obtain an access token at the end of the *OAuth* process.

        This endpoint represents the [4th step of the OAuth flow process](https://www.discogs.com/developers#header-4.-send-a-post-request-to-the-discogs-access-token-url), thus it requires to configure an *Authorization* header to have a value like this:
        
        ```
        OAuth oauth_consumer_key="your_consumer_key", oauth_nonce="random_string_or_timestamp", oauth_token="oauth_token_received_from_step_2" oauth_signature="your_consumer_secret&", oauth_signature_method="PLAINTEXT", oauth_timestamp="current_timestamp", oauth_verifier="users_verifier"
        ```

        For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
      operationId: postAccessToken
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/UserAgent'
      responses:
        '200':
          description: Successfully retrieved an access token at the end of the OAuth authentication process.
          headers:
            oauth_token:
              $ref: '#/components/headers/OAuthToken'
            oauth_token_secret: 
              $ref: '#/components/headers/OAuthSecret'
        '500':
          $ref: '#/components/responses/InternalError'
  /oauth/identity:
    get:
      tags:
        - Authentication
      summary: Get information about an authenticated user.
      description: |
        Retrieve basic information about the authenticated user.

        This endpoint represents the (optional) [5th step of the OAuth flow process](https://www.discogs.com/developers#header-5-send-authenticated-requests-to-discogs-endpoints), as it is advised to perform a sanity check to ensure the *OAuth* process finished successfully.

        For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation.
      operationId: getUserIdentity
      security:
        - UserToken: []
        - ConsumerKeySecret: []
        - OAuth: []
      responses:
        '200':
          description: Successfully retrieved information about an authenticated user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentity'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /database/search:
    get:
      tags:
        - Database
      summary: Search any information from the database.
      description: |
        Issue a search query to the Discogs database. 
        
        This endpoint supports pagination and also, it requires authentication.
      operationId: searchDatabase
      parameters:
        - name: query
          description: A query to search for.
          in: query
          schema:
            type: string
        - name: type
          description: A type of resource to search for.
          in: query
          schema:
            type: string
            enum: 
              - release
              - master
              - artist
              - label
        - name: title
          description: |
            A title to search for.

            This parameter can be combined with the `name` query parameter.
          in: query
          schema:
            type: string
        - name: release_title
          description: A release title to search for.
          in: query
          schema:
            type: string
        - name: credit
          in: query
          description: Some credits to search for.
          schema:
            type: string
        - name: artist
          description: An artist name to search for.
          in: query
          schema:
            type: string
        - name: anv
          description: A ANV (Artist Name Variation) to search for.
          in: query
          schema:
            type: string
        - name: label
          description: A label name to search for.
          in: query
          schema:
            type: string
        - name: genre
          description: A music genre to search for.
          in: query
          schema:
            type: string
        - name: style
          description: A musical style to search for.
          in: query
          schema:
            type: string
        - name: country
          description: A country to search for.
          in: query
          schema:
            type: string
        - name: year
          description: A release year to search for.
          in: query
          schema:
            type: string
        - name: format
          description: A release format to search for.
          in: query
          schema:
            type: string
        - name: catno
          description: A catalogg number to search for.
          in: query
          schema:
            type: string
        - name: barcode
          description: A barcode number to search for.
          in: query
          schema:
            type: string
        - name: track
          description: A track title to search for.
          in: query
          schema:
            type: string
        - name: submitter
          description: A username of a submitter to search for.
          in: query
          schema:
            type: string
        - name: contributor
          description: A username of a contributor to search for.
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      security:
        - UserToken: []
        - ConsumerKeySecret: []
        - OAuth: []
      responses:
        '200':
          description: Successfully retrieved search results.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  results:
                    description: A list of artist, label, master and/or release search results.
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/ReleaseResult'
                        - $ref: '#/components/schemas/MasterResult'
                        - $ref: '#/components/schemas/ArtistResult'
                        - $ref: '#/components/schemas/LabelResult'
                required:
                  - pagination
                  - results
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /artists/{artist_id}:
    get:
      tags:
        - Database
      summary: Get information about an artist.
      description: Retrieves any available information for a specific artist.
      operationId: getArtist
      parameters:
        - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: Successfully retrieved artist details.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artist'
        '404':
          $ref: '#/components/responses/NotFound'
  /artists/{artist_id}/releases:
    get:
      tags:
        - Database
      summary: Get information about releases of an artist.
      description: |
        Returns a list of releases and masters associated with an artist. 
        
        This endpoint supports pagination.
      operationId: getArtistReleases
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/ArtistReleasesSort'
        - $ref: '#/components/parameters/SortOrder'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of releases of an artist.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  releases:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtistRelease'
                required:
                  - pagination
                  - releases
        '404':
          $ref: '#/components/responses/NotFound'
  /labels/{label_id}:
    get:
      tags:
        - Database
      summary: Get information about a label
      description: Retrieves any available information for a specific label.
      operationId: getLabel
      parameters:
        - $ref: '#/components/parameters/LabelId'
      responses:
        '200':
          description: Successfully retrieved label details.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '404':
          $ref: '#/components/responses/NotFound'
  /labels/{label_id}/releases:  
    get:  
      tags:  
        - Database  
      summary: Get information about the releases of a label.  
      description: |
        Returns a list of releases associated with a label. 
        
        This endpoint Supports pagination.  
      operationId: getLabelReleases  
      parameters:  
        - $ref: '#/components/parameters/LabelId'  
        - $ref: '#/components/parameters/Page'  
        - $ref: '#/components/parameters/PerPage'  
      responses:  
        '200':  
          description: A paginated list of the label's releases.  
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:  
            application/json:  
              schema:  
                type: object  
                properties:  
                  pagination:  
                    $ref: '#/components/schemas/Pagination'  
                  releases:  
                    type: array  
                    items:  
                      $ref: '#/components/schemas/LabelRelease'
                required:
                  - pagination
                  - releases
        '404':  
          $ref: '#/components/responses/NotFound'  
  /masters/{master_id}:
    get:
      tags:
        - Database
      summary: Get information about a master release.
      description: |
        Retrieves any available information for a specific master release.

        A master release represents a set of similar releases.
      operationId: getMaster
      parameters:
        - $ref: '#/components/parameters/MasterId'
      responses:
        '200':
          description: Successfully retrieved master release details.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Master'
        '404':
          $ref: '#/components/responses/NotFound'
  /masters/{master_id}/versions:
    get:
      tags:
        - Database
      summary: Get information about the versions of a master release.
      description: |
        Retrieves a list of all releases that are versions of the specified master release. 
        
        This request supports pagination.
      operationId: getMasterVersions
      parameters:
        - $ref: '#/components/parameters/MasterId'
        - $ref: '#/components/parameters/Format'
        - $ref: '#/components/parameters/Label'
        - $ref: '#/components/parameters/Released'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/MasterVersionsSort'
        - $ref: '#/components/parameters/SortOrder'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of releases belonging to the master.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReleaseVersion'
                required:
                  - pagination
                  - versions
        '404':
          $ref: '#/components/responses/NotFound'
  /releases/{release_id}:
    get:
      tags:
        - Database
      summary: Get information about a release
      description: Retrieves details for a specific release.
      operationId: getRelease
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Currency'
      responses:
        '200':
          description: Successfully retrieved release details.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
        '404':
          $ref: '#/components/responses/NotFound'
  /releases/{release_id}/rating:
    get:
      tags:
        - Database
      summary: Get information about a rating of release.
      description: Retrieves the average rating and the total number of user ratings for a given release.
      operationId: getReleaseRating
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
      responses:
        '200':
          description: Successfully retrieved release rating details.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseRating'
        '404':
          $ref: '#/components/responses/NotFound'
  /releases/{release_id}/rating/{username}:
    get:
      tags:
        - Database
      summary: Get information about a rating of release by a user.
      description: Retrieves the rating for a given release by a specific user.
      operationId: getReleaseRatingByUser
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Successfully retrieved release rating details by a given user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseRatingByUser'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: 
        - Database
      summary: Update information about a rating of release by a user.
      description: |
        Updates a rating of a release for a given user. 
        
        This endpoint requires authentication.
      operationId: putReleaseRatingByUser
      parameters: 
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/Rating'
      security:
        - UserToken: []
        - ConsumerKeySecret: []
        - OAuth: []
      responses:
        '200':
          description: Successfully updated a rating for a specific release by a given user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseRatingByUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete: 
      tags:
        - Database
      summary: Delete information about a rating of release by a user.
      description: |
        Updates a rating of a release for a given user. 
        
        This endpoint requires authentication.
      operationId: deleteReleaseRatingByUser
      parameters: 
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Username'
      security:
        - UserToken: []
        - ConsumerKeySecret: []
        - OAuth: []
      responses:
        '200':
          description: Successfully deleted a rating for a specific release by a given user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /releases/{release_id}/stats:
    get:
      tags:
        - Database
      summary: Get information about statistics of release.
      description: Retrieves the total number of “haves” (in the community's collections) and “wants” (in the community's wantlists) for a given release.
      operationId: getReleaseStats
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
      responses:
        '200':
          description: |
            Successfully retrieved release rating details by a given user.

            > warning: There is a discrepancy about this response between was is documented and what the endpoints actually responds. In the [documentation](https://www.discogs.com/developers#page:database,header:database-release-stats), it is defined that a type containing a statistical data would be returned but the actual response returns an object that contains a boolean flag instead.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ReleaseStats'
                  - type: object
                    properties:
                      is_offensive:
                        type: boolean
                    required:
                      - is_offensive
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{username}:
    get:
      tags:
        - User Identity
      summary: Get information about a user.
      description: |
        Retrieves a user profile by username.

        In case of being authenticated as the requested user, the `email` property will be visible, and the `num_list` count will also include a user's private lists.
        
        In case of being authenticated as the requested user, or a user's collection or wantlist is public, the `num_collection` and the `num_wantlist` properties will also be visible.
      operationId: getUserProfile
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Successfully retrieved profile user information by a given username.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - User Identity
      summary: Update information about a user.
      description: |
        Edits some user profile information by username.

        This endpoint requires authentication.
      operationId: postUserProfile
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/Name'
        - $ref: '#/components/parameters/HomePage'
        - $ref: '#/components/parameters/Location'
        - $ref: '#/components/parameters/Profile'
        - $ref: '#/components/parameters/Currency'
      security:
        - UserToken: []
        - ConsumerKeySecret: []
        - OAuth: []
      responses:
        '200':
          description: Successfully retrieved an updated profile user information by a given username.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/contributions:
    get:
      tags:
        - User Identity
      summary: Get contributions of a user.
      description: |
        Retrieves all the contributions or additions to releases, labels, and artist done by username.

        This endpoints accepts pagination headers.
      operationId: getUserContributions
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/SortField'
        - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: Successfully retrieved items contributed by a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  submissions:
                    description: A type that represents all items submitted by a user.
                    $ref: '#/components/schemas/UserItems'
                required:
                  - pagination
                  - contributions
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/submissions:
    get:
      tags:
        - User Identity
      summary: Get submissions of a user.
      description: |
        Retrieves all the submissions or edits to releases, labels, and artist done by username.

        This endpoints accepts pagination headers.
      operationId: getUserSubmissions
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Successfully retrieved items submitted by a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  submissions:
                    description: A type that represents all items edited by a user.
                    $ref: '#/components/schemas/UserItems'
                required:
                  - pagination
                  - submissions
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/folders:
    get:
      tags:
        - User Collection
      summary: Get all the collection folders of a user.
      description: |
        Retrieves a list of folders in a collection of a user. 
        
        In case the collection has been made private by its owner, authentication as the collection owner is required. Otherwise, only folder `ID 0`` (the “All” folder) will be visible only if the requested collection of a user is public.
      operationId: getCollectionFolders
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Successfully retrieved all the collection folders by a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  folders:
                    description: A list of collection folders of a user.
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
                required:
                  - pagination
                  - folders
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - User Collection
      summary: Create a new collection folder for a user.
      description: |
        Creates a new folder in the collection of a user.

        This endpoint requires authentication for the owner.
      operationId: postCollectionFolders
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/Name'
          description: A name for a new folder.
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '201':
          description: Successfully create a new collection folder for a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/folders/{folder_id}:
    get:
      tags:
        - User Collection
      summary: Get information about a collection folder of a user.
      description: |
        Retrieves metadata about a collection folder of a user.

        In case the `folder_id` is not 0, then the endpoint requires authentication as the collection owner.
      operationId: getCollectionFolder
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
      responses:
        '200':
          description: Successfully retrieved a specific collection folder of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '403':
          $ref: '#/components/responses/NotAccessable'          
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - User Collection
      summary: Update information about a collection folder of a user.
      description: |
        Edits the metadata for a collection folder of a user. Please bear in mind that the folders with identifier `0` and `1` cannot be renamed.

        Authentication as the collection owner is required.
      operationId: postCollectionFolder
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/Name'
          description: A new name for a collection folder of a user.
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '200':
          description: Successfully retrieved an updated collection folder of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - User Collection
      summary: Delete a collection folder from a collection of a user.
      description: |
        Deletes a collection folder from a collection of a user. 
        
        > important: A folder must be empty before it can be deleted.

        This endpoints requires authentication as the collection owner.
      operationId: deleteCollectionFolder
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully delete a specific collection folder of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/releases/{release_id}:
    get:
      tags:
        - User Collection
      summary: Get collection items of a user that contains a given release.
      description: |
        Views those collection folder of a user which contain a specified release. This will also show information about each release instance.

        > important: A given `release_id` must not be `0`.

        This endpoint requires authentication as the collection owner only in case the collection is private.
      operationId: getCollectionItemsByRelease
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/ReleaseId'
      responses:
        '200':
          description: Successfully retrieved a list of collection items that contains a specified release. 
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  releases:
                    description: A list of collection folders of a user that contains a specified release.
                    type: array
                    items:
                      $ref: '#/components/schemas/ReleaseInFolder'
                required:
                  - pagination
                  - releases
        '403':
          $ref: '#/components/responses/NotAccessable'          
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/folders/{folder_id}/releases:
    get:
      tags:
        - User Collection
      summary: Get collection items of a user inside a specified folder.
      description: |
        Returns the list of item in a specified collection folder of a user.
        
        Basic information about each release is provided, suitable for display in a list. For detailed information, make another API call to fetch the corresponding release.
        
        This endpoint provides pagination parameters and also, requires authentication as an owner of a collection only in case the `folder_id` is not `0`, or the collection has been made private by its owner. Otherwise, only public notes fields will be visible.
      operationId: getCollectionItemsByFolder
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/SortField'
        - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: Successfully retrieved a specific collection folder of a 
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  releases:
                    description: A list of collection folders of a user that contains a 
                    type: array
                    items:
                      $ref: '#/components/schemas/ReleaseInFolder'
                required:
                  - pagination
                  - releases
        '403':
          $ref: '#/components/responses/NotAccessable'          
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/folders/{folder_id}/releases/{release_id}:
    post:
      tags:
        - User Collection
      summary: Add a release to a collection folder of a user.
      description: |
        Adds a release to a collection folder of a user.

        > important: A `folder_id` must not be `0`, so it is possible to use the identifier `1` for the *Uncategorized* folder.

        This endpoint requires authentication as the collection owner.
      operationId: postReleaseToCollectionFolder
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/ReleaseId'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '201':
          description: Successfully added a specific release into a collection folder of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseInstance'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}:
    post:
      tags:
        - User Collection
      summary: Update a rating for a specified release instance in a specified collection folder of a user.
      description: |
        Changes the rating on a release and/or move the instance to another folder.

        This endpoint potentially takes 2 `folder_id` parameters: 1) in the URL (which is the folder you are requesting, and is required), and 2) in the request body (representing the folder you want to move the instance to, which is optional)

        This endpoints requires authentication as the collection owner.
      operationId: postChangeRatingOfRelease
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/InstanceId'
        - $ref: '#/components/parameters/Rating'
      requestBody:
        $ref: '#/components/requestBodies/MoveInstance'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully updated a rating for a specific release instance inside a collection folder of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - User Collection
      summary: Delete a specified release instance in a specified collection folder of a user.
      description: |
        Removes an instance of a release from a collection folder of a user.
        
        > important: To move the release to the *Uncategorized* folder instead, use the `POST` method.
        
        This endpoint requires authentication as the collection owner.
      operationId: deleteInstanceFromCollectionFolder
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/InstanceId'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully deleted a specific release instance inside a collection folder of a user. 
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}/fields/{field_id}:
    post:
      tags: 
        - User Collection
      summary: Update a value of a custom field assigned to a release instance.
      description: Changes the value of a notes field on a particular instance.
      operationId: editFieldsInstance
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/InstanceId'
        - $ref: '#/components/parameters/FieldId'
        - $ref: '#/components/parameters/FieldValue'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully updated a value of a custom notes field for a release instance in a collection folder.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/fields:
    get:
      tags:
        - User Collection
      summary: Get a list of custom fields defined by a user.
      description: |
        Retrieves a list of collection notes fields defined by a user. 
        
        These fields are available on every release in a collection. In case a collection has been made private by its owner, then the endpoints requires authentication as the collection owner. Otherwise only public custom fields will be visible.
      operationId: getCustomFields
      parameters:
        - $ref: '#/components/parameters/Username'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '200':
          description: Successfully retrieved a list of custom fields defined by a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                description: A type that contains a list of retrieved custom fields of a user.
                type: object
                properties:
                  fields:
                    description: A list of custom fields.
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomField'
                required:
                  - fields
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/collection/value:
    get:
      tags:
        - User Collection
      summary: Get the estimated monetary value for a collection of a user.
      description: |
        Returns the estimated minimum, median, and maximum values for a collection of a user.

        This endpoint requires authentication as the collection owner.
      operationId: getCollectionValue
      parameters:
        - $ref: '#/components/parameters/Username'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '200':
          description: Successfully retrieved the estimated monetary value for a collection of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionValue'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/wants:
    get:
      tags: 
        - User Wantlist
      summary: Get a list of releases in a wantlist of a user.
      description: |
        Returnss the list of releases in a wantlist of a user. Accepts Pagination parameters.

        Basic information about each release is provided, suitable for display in a list. For detailed information, make another API call to fetch the corresponding release.

        If the wantlist has been made private by its owner, you must be authenticated as the owner to view it.

        The notes field will be visible if you are authenticated as the wantlist owner.
      operationId: getWantlist
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Successfully retrieved a list of releases in a wantlist of a user.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema: 
                description: A type that contains a list of lists of a user.
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  wants:
                    description: A list of lists of a user.
                    type: array
                    items:
                      $ref: '#/components/schemas/ReleaseInFolder'
                required:
                  - pagination
                  - wants
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/wants/{release_id}:
    put:
      tags:
        - User Wantlist
      summary: Add a release into a wantlist of a user.
      description: |
        Adds a release to a wantlist of a user.

        This endpoint requires authentication as the wantlist owner.
      operationId: addToWantlist
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Notes'
        - $ref: '#/components/parameters/Rating'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '201':
          description: Successfully added a release into a wantlist of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                description: A type that represents a newly added release in a wantlist of a user.
                $ref: '#/components/schemas/ReleaseInFolder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - User Wantlist
      summary: Update a release into a wantlist of a user.
      description: |
        Modifies some metadata associated with a release in a wantlist of a user.

        This endpoint requires authentication as the wantlist owner.
      operationId: updateInWantlist
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Notes'
        - $ref: '#/components/parameters/Rating'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '200':
          description: Successfully updated a release in a wantlist of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                description: A type that represents an updated release in a wantlist of a user.
                $ref: '#/components/schemas/ReleaseInFolder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - User Wantlist
      summary: Delete a release from a wantlist of a user.
      description: |
        Deletes a release from a wantlist of a user.

        This endpoint requires authentication as the wantlist owner.
      operationId: deleteFromWantlist
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/ReleaseId'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully deleted a release from a wantlist of a user.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/lists:
    get:
      tags:
        - User Lists
      summary: Get a list of lists of a user.
      description: |
        Returns a list of lists created by a users.
        
        This endpoints accepts pagination and, to show private lists it is required to be authenticated as a owner.
      operationId: getLists
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Successfully retrieved a list of lists of a user.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema: 
                description: A type that contains a list of lists of a user.
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  lists:
                    description: A list of lists of a user.
                    type: array
                    items:
                      $ref: '#/components/schemas/ListId'
                required:
                  - lists
                  - pagination
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /lists/{list_id}:
    get:
      tags:
        - User Lists
      summary: Get items from a specified list.
      description: |
        Returns items from a specified list.
        
        Private lists are not shown unless a user is authenticated as an owner.
      operationId: getList
      parameters:
        - $ref: '#/components/parameters/ListId'
      responses:
        '200':
          description: Successfully retrieved the items associated with a specified list.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/inventory:
    get:
      tags:
        - Marketplace
      summary: Get the listings in an inventory of a seller.
      description: |
        Returns the list of listings for an inventory of a user. 

        Basic information about each listing and the corresponding release is provided, suitable for display in a list. For detailed information about the release, make another API call to fetch the corresponding Release.

        This endpoints accepts pagination and also, in case of authenticated as an inventory owner, items that not only have the `For Sale` state will be shown as well as other  extra fields in those items such as `weight`, `format_quality`, `external_id`, `location`, and `quantity_keys`. Note that the `quantity` field is read-only for *NearMint* users, who will see *1* for all quantity values, regardless of their actual count. 
        
        In case the user is authorized, the listing will contain a `in_cart` boolean field indicating whether or not this listing is in their cart.
      operationId: getInventory
      parameters:
        - $ref: '#/components/parameters/Username'
        - $ref: '#/components/parameters/InventoryStatus'
        - $ref: '#/components/parameters/SortInventory'
        - $ref: '#/components/parameters/SortOrder'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Successfully retrieved the list of listings in an inventory of a seller.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                description: A type that contains a list of listing in an inventory of a user.
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  listings:
                    description: A list of listings in an inventory of a user.
                    type: array
                    items:
                      $ref: '#/components/schemas/Listing'
                required:
                  - listings
                  - pagination
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
  /marketplace/listings/{listing_id}:
    get:
      tags:
        - Marketplace
      summary: Get information about a listing in the marketplace.
      description: |  
        Views the data associated with a listing in the marketplace.

        In case of authenticated as an inventory owner, items that not only have the `For Sale` state will be shown as well as other  extra fields in those items such as `weight`, `format_quality`, `external_id`, `location`, and `quantity_keys`. Note that the `quantity` field is read-only for *NearMint* users, who will see *1* for all quantity values, regardless of their actual count. 
        
        In case the user is authorized, the listing will contain a `in_cart` boolean field indicating whether or not this listing is in their cart.
      operationId: getListing
      parameters:
        - $ref: '#/components/parameters/ListingId'
        - $ref: '#/components/parameters/Currency'
      responses:
        '200':
          description: Successfully retrieved a listing in a marketplace.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - Marketplace
      summary: Update a listing in a marketplace.
      description: |
        Edits the data associated with a listing in a marketplace.

        In case a status of a listingis not `For Sale`, `Draft`, or `Expired`, it cannot be modified - only deleted. To re-list a Sold listing, a new listing must be created.

        This endpoint requires authentication as a listing owner.
      operationId: editListing
      parameters:
        - $ref: '#/components/parameters/ListingId'
      requestBody:
        $ref: '#/components/requestBodies/Listing'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully edited a listing from a marketplace.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - Marketplace
      summary: Delete a listing from a marketplace.
      description: |
        Removes permanently a listing from a Marketplace.

        This endpoints requires authentication as a listing owner.
      operationId: deleteListing
      parameters:
        - $ref: '#/components/parameters/ListingId'
      security:
        - ConsumerKeySecret: []
        - UserToken: []
        - OAuth: []
      responses:
        '204':
          description: Successfully deleted a listing from a marketplace.
          headers:
            X-Discogs-RateLimit:
              $ref: '#/components/headers/RateLimit'
            X-Discogs-RateLimit-Used:
              $ref: '#/components/headers/RateLimitUsed'
            X-Discogs-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAccessable'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    Link:
      description: |
        Contains URLs for pagination, compliant with RFC 5988. 
        
        It provides `first`, `prev`, `next`, and `last` links where applicable.
      schema:
        type: string
        example: <https://api.discogs.com/artists/1/releases?page=2&per_page=75>; rel="next", <https://api.discogs.com/artists/1/releases?page=30&per_page=75>; rel="last"
    OAuthCallback:
      description: An OAuth callback confirmed.
      schema:
        type: boolean
        default: true
    OAuthSecret:
      description: An OAuth request token secret.
      schema:
        type: string
    OAuthToken:
      description: An OAuth request token.
      schema:
        type: string
    RateLimit:
      description: A total number of requests that can be made in a minute window.
      schema:
        type: integer
        minimum: 25
        maximum: 60
        example: 60
      required: true
    RateLimitRemaining:
      description: A number of remaining requests that can be made in an existing rate limit window.
      schema:
        type: integer
        minimum: 0
        maximum: 60
        example: 59
      required: true
    RateLimitUsed:
      description: A number of requests that have been made in an existing rate limit window.
      schema:
        type: integer
        minimum: 0
        maximum: 60
        example: 1
      required: true
  parameters:
    ArtistId:
      description: An identifier of an artist.
      name: artist_id
      in: path
      required: true
      schema:
        type: integer
      example: 108713
    ArtistReleasesSort:
      description: A value to sort the releases of an artist by.
      name: sort
      in: query
      required: false
      schema:
        type: string
        enum:
          - year
          - title
          - format
    Authorization:
      description: A string to authenticate a user with a service by carrying credentials.
      name: Authorization
      in: header
      required: true
      schema:
        type: string
    ContentType:
      description: A content type for a response.
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        enum:
          - application/json
          - application/x-www-form-urlencoded
    Country:
      description: A filter by country.
      name: country
      in: query
      schema:
        type: string    
    Currency:
      description: |
        A currency code in the marketplace. 

        Defaults to the authenticated users currency.
      name: curr_abbr
      in: query
      schema:
        $ref: '#/components/schemas/Currency'
    FieldId:
      description: An identifier of a custom field.
      name: field_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
      example: 8
    FieldValue:
      description: A value of a custom field.
      name: value
      in: query
      required: true
      schema:
        type: string
    FolderId:
      description: An identifier of a collection folder.
      name: folder_id
      in: path
      required: true
      schema:
        type: integer
      example: 0
    Format:
      description: A filter by format.
      name: format
      in: query
      schema:
        type: string
    HomePage:
      description: A URI to a website of a user.
      name: home_page
      in: query
      schema:
        type: string
        format: uri
      example: https://www.some-home.page
    InstanceId:
      description: An identifier of a release instance.
      name: instance_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
      example: 3
    InventoryStatus:
      description: A status of a inventory.
      name: status
      in: query
      schema:
        type: string
        enum:
          - All
          - For Sale
          - Draft
          - Expired
          - Sold
          - Violation
          - Suspended
          - Deleted
    Label:
      description: A filter by label.
      name: label
      in: query
      schema:
        type: string    
    LabelId:
      description: An identifier of a label.
      name: label_id
      in: path
      required: true
      schema:
        type: integer
      example: 1
    ListId:
      description: An identifier of a list.
      name: list_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
      example: 123
    ListingId:
      description: An identifier of a listing.
      name: listing_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
      example: 172723812
    Location:
      description: A geographical location of a user.
      name: location
      in: query
      schema:
        type: string
      example: Planet Earth
    MasterId:
      description: An identifier of a master.
      name: master_id
      in: path
      required: true
      schema:
        type: integer
      example: 1000    
    MasterVersionsSort:
      description: A value to sort the master versions by.
      name: sort
      in: query
      schema:
        type: string
        enum: 
          - released
          - title
          - format
          - label
          - catno
          - country
    Name: 
      description: A real name of a user.
      name: name
      in: query
      schema: 
        type: string
    Notes:
      description: A custom note about a release.
      name: notes
      in: query
      schema:
        type: string
    Page:
      description: A number of page of results to return.
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
    PerPage:
      description: A number of items to return per page.
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
    Profile:
      description: A biographical information about a user.
      name: profile
      in: query
      schema:
        type: string
      example: Some biographical information about a user goes here...
    Rating:
      description: A number for a rating of a release.
      name: rating
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 5
    ReleaseId:
      description: An identifier of a release.
      name: release_id
      in: path
      required: true
      schema:
        type: integer
      example: 249504
    Released:
      description: A filter by release year.
      name: released
      in: query
      schema:
        type: string    
    SortField:
      description: A filter by field.
      name: sort
      in: query
      schema:
        type: string
        enum:
          - label
          - artist
          - title
          - catno
          - format
          - rating
          - year
          - added
    SortInventory:
      description: A filter by an inventory field.
      name: sort
      in: query
      schema:
        type: string
        enum: 
          - listed
          - price
          - item
          - artist
          - label
          - catno
          - audio
          - status
          - location
    SortOrder:
      description: The order to sort the results. 
      name: sort_order
      in: query
      schema:
        type: string
        enum: 
          - asc
          - desc
    UserAgent:
      name: User-Agent
      description: A name of a software agent responsible for interacting with the service.
      in: header
      required: true
      schema:
        type: string
    Username:
      description: A username of a user.
      name: username
      in: path
      required: true
      schema:
        type: string
      example: memory
  requestBodies:
    Listing:
      description: A container to use in case of either creating a new release into a marketplace or midfying a release already existing in a marketplace.
      required: true
      content:
        application/json:
          schema:
            properties:
              listing_id:
                description: An identifier of a listing, if any.
                type: integer
                minimum: 0
              release_id:
                description: An identifier of a release.
                type: integer
                minimum: 0
              condition:
                description: A media condition of a listing.
                $ref: '#/components/schemas/ConditionMedia'
              sleeve_condition:
                description: A sleeve condition of a listing.
                $ref: '#/components/schemas/ConditionSleeve'
              price:
                description: A price of a listing in a seller's currency.
                type: number
                format: float
                minimum: 0
              comments:
                description: Any remark about a listing that would be shown to buyers.
                type: string
              allow_offers:
                description: A flag that indicates whether buyers are allowed to make offers for a listing or not.
                type: boolean
              status: 
                description: A status explanation of a listing.
                type: string
                enum:
                  - Draft
                  - For Sale
                default: Draft
              external_id:
                description: |
                  A freeform field that could be used by a seller to comment about a listing.

                  The information stored in this field is not shown to anobody except a seller who owns a listing.
                type: string
              location:
                description: |
                  A geographical location of a listing.

                  The information stored in this field is not shown to anobody except a seller who owns a listing.
                type: string
              weight:
                description: A weight of a listing in grams for the purpose of calculating shipping costs.
                anyOf:
                  - type: number
                    format: float
                  - type: string
                    enum: 
                      - auto
                    default: auto
              format_quantity: 
                description: A number of items of a listing, for the purpose of calculating shipping costs.
                anyOf:
                  - type: number
                    format: float
                  - type: string
                    enum: 
                      - auto
                    default: auto
            required:
              - condition
              - price
              - release_id
              - status
    MoveInstance:
      description: A container to use in case of moving a release instance from a collection folder into another.
      required: false
      content:
        application/json:
          schema:
            properties:
              folder_id:
                description: An identifier of a collection folder to move a release instance.
                type: integer
                minimum: 0
  responses:
    InternalError:
      description: An Internal Server error was encountered.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
          examples:
            Timeout:
              value:
                message: Query time exceeded. Please try a simpler query.
            Malformed:
              value:
                message: An internal server error occurred. (Malformed query?)
    NotAccessable:
      description: A requested resource cannot be accessed due to a lack of permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
          example:
            message: You must have permission to access this resource.
    NotFound:
      description: A requested resource cannot be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
          example:
            message: Resource not found.
    Unauthorized:
      description: A requested resource cannot be accessed due to a lack of authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
          example:
            message: You must authenticate to access this resource.
    Unavailable:
      description: The service is currently unavailable to handle requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
          example:
            message: Server is currently unavailable.
    Unprocessable:
      description: An invalid parameter has been sent
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
          example:
            message: Invalid parameter - expected one of accepted values.
  schemas:
    Artist:
      description: A type that represents an artist or a group.
      type: object
      properties:
        id:
          description: An identifier of an artist.
          type: integer
          readOnly: true
        name:
          description: A name of an artist.
          type: string
        realname:
          description: A real name of an artist, if any.
          type: string
        resource_url:
          description: A URI resource of an artist.
          type: string
          format: uri
          readOnly: true
        uri:
          description: A URI representation of an artist.
          type: string
          format: uri
          readOnly: true
        releases_url:
          description: A URL to the releases of an artist.
          type: string
          format: uri
        profile:
          description: A detailed profile of an artist, if any.
          type: string
        urls:
          description: A list of URLs related to an artist, if any.
          type: array
          items:
            type: string
            format: uri
        namevariations:
          description: A list of name variations related to an artist, if any.
          type: array
          items:
            type: string
        members:
          description: A list of artists related to an artist (in case of group), if any.
          type: array
          items:
            $ref: '#/components/schemas/ArtistId'
        images:
          description: A list of images related to an artist, if any.
          type: array
          items:
            $ref: '#/components/schemas/Image'
        data_quality:
          description: An explanation for the data quality related to an artist.
          type: string
      required: 
        - data_quality
        - id
        - name
        - releases_url
        - resource_url
        - uri
    ArtistId:
      description: A type that references an artist.
      type: object
      properties:
        id:
          description: An identifier of an artist.
          type: integer
          readOnly: true
        name:
          description: A name of an artist.
          type: string
        resource_url:
          description: A URI resource of an artist.
          type: string
          format: uri
          readOnly: true
        active:
          description: A flag that indicates whether the relation is currently active or not.
          type: boolean
        anv:
          description: TBD
          type: string
        join:
          description: TBD
          type: string
        role:
          description: A role of an artist.
          type: string
        tracks:
          description: TBD
          type: string
      required:
        - id
        - name
        - resource_url
    ArtistRelease:
      description: A type that represents a release of an artist.
      type: object
      properties:
        id:
          description: An identifier of a release.
          type: integer
          readOnly: true
        resource_url:
          description: A URI resource of a release.
          type: string
          format: uri
          readOnly: true
        type:
          description: A type of a release.
          type: string
          enum:
            - release
            - master
        title:
          description: A title of a release.
          type: string
        thumb:
          description: A URL link to a thumbnail of a release.
          type: string
          format: uri
        artist:
          description: A name for the artist of a release.
          type: string
        role:
          description: A role of a release.
          type: string
        year:
          description: A number of year of a release.
          type: integer
        format:
          description: A format of a release.
          type: string
        label:
          description: A label of a release.
          type: string
        status:
          description: A status of a release.
          type: string
      required:
        - artist
        - id
        - resource_url
        - role
        - title
        - thumb
        - type
    ArtistResult:
      description: A type that represents an artist search result.
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          properties:
            type:
              enum: [artist]
    CollectionValue:
      description: A type that represents the monetary value of a collection.
      type: object
      properties:
        maximum:
          description: An estimated maximum monetary value of a collection.
          type: string
        median:
          description: An estimated median monetary value of a collection.
          type: string
        minimum:
          description: An estimated minimumn monetary value of a collection.
          type: string
      required:
        - maximum
        - median
        - minimum
    Community:
      description: A type that represents a community of users, in relationship to a release.
      type: object
      properties:
        have:
          description: A number of users that have a release.
          type: integer
        want:
          description: A number of users that want a release.
          type: integer
        rating:
          $ref: '#/components/schemas/Rating'
        submitter:        
          description: A reference of a user that submitted the release into the database.
          $ref: '#/components/schemas/UserId'
        contributors:
          description: A list of references of users that contributed data of a release into the database.
          type: array
          items:
            $ref: '#/components/schemas/UserId'
        data_quality:
          description: An explanation for the data quality related to a community.
          type: string
        status:
          description: An explanation for the stat status of a community.
          type: string
    ConditionMedia:
      description: A type that represents a media condition.
      type: string
      enum:
        - Mint (M)
        - Near Mint (NM or M-)
        - Very Good Plus (VG+)
        - Very Good (VG)
        - Good Plus (G+)
        - Good (G)
        - Fair (F)
        - Poor (P)
    ConditionSleeve:
      description: A type that represents a sleeve condition.
      type: string
      enum:
        - Mint (M)
        - Near Mint (NM or M-)
        - Very Good Plus (VG+)
        - Very Good (VG)
        - Good Plus (G+)
        - Good (G)
        - Fair (F)
        - Poor (P)
        - Generic
        - Not Graded
        - No Cover
    Currency:
      description: A list of currency codes defined in the marketplace.
      type: string
      minLength: 3
      maxLength: 3
      enum: 
        - USD
        - GBP
        - EUR
        - CAD
        - AUD
        - JPY
        - CHF
        - MXN
        - BRL
        - NZD
        - SEK
        - ZAR
    CustomField:
      description: A type that represents a custom field.
      type: object
      properties:
        id:
          description: An identifier of a custom field.
          type: integer
          readOnly: true
        name:
          description: A name of a custom field.
          type: string
        position:
          description: A position of a custom field.
          type: integer
          minimum: 1
        public:
          description: A flag that indicates whether a custom field is public or not.
          type: boolean
        type:
          description: A type of a custom field.
          type: string
          enum:
            - dropdown
            - textarea
        lines:
          description: A number of lines of content to allow for a custom field of a textarea type.
          type: integer
          minimum: 1
        options:
          description: A list of options to display, in case the field is of dropdown type.
          type: array
          items:
            type: string
      required:
        - id
        - name
        - position
        - public
        - type
    Folder:
      description: A type that represents a collection folder of a user.
      type: object
      properties:
        id:
          description: An identifier of a collection folder.
          type: integer
          readOnly: true
        name:
          description: A name of a collection folder.
          type: string
        count:
          description: A number of items a collection folder contains.
          type: integer
        resource_url:
          description: A URI resource of a collection folder.
          type: string
          format: uri
          readOnly: true
      required:
        - count
        - id
        - name
        - resource_url
    Identifier:
      description: A type that represents an identifier.
      type: object
      properties:
        type:
          description: A type of an identifier.
          type: string
        value:
          description: A value of an identifier, if any.
          type: string
        description:
          description: A description of an identifier, if any.
          type: string
      required:
        - type  
    Image:
      description: A type that represents an image of a resource.
      type: object
      properties:
        type:
          description: A type of an image.
          type: string
          enum: 
            - primary
            - secondary
        uri:
          description: A URI representation of an image.
          type: string
          format: uri
          readOnly: true
        resource_url:
          description: A URI resource of an image.
          type: string
          format: uri
          readOnly: true
        uri150:
          description: TBD
          type: string
          format: uri
        width:
          description: A width of an image (in pixels).
          type: integer
        height:
          description: A height of an image (in pixels).
          type: integer
      required:
        - height
        - resource_url
        - type
        - uri
        - uri150
        - width
    Label:
      description: A type that represents a label, company, recording studio, etc.
      type: object
      properties:
        id:
          description: An identifier of a label.
          type: integer
          readOnly: true
        name:
          description: A name of a label.
          type: string
        resource_url:
          description: A URI resource of a label.
          type: string
          format: uri
          readOnly: true
        uri:
          description: A URI representation of a label.
          type: string
          format: uri
          readOnly: true
        releases_url:
          description: A URL to the releases of a label.
          type: string
          format: uri
          readOnly: true
        profile:
          description: A detailed profile of a label, if any.
          type: string
        contact_info:
          description: A contact information of a label, if any.
          type: string
        parent_label:
          description: A reference to a parent label of a label, if any.
          $ref: '#/components/schemas/LabelId'
        sublabels:
          description: A list of sub-labels references of a label.
          type: array
          items:
            $ref: '#/components/schemas/LabelId'
        urls:
          description: A list of URLs related to a label, if any.
          type: array
          items:
            type: string
            format: uri
        images:
          description: A list of images related to a label, if any.
          type: array
          items:
            $ref: '#/components/schemas/Image'
        data_quality:
          description: An explanation for the data quality related to a label.
          type: string
      required:
        - data_quality
        - id
        - name
        - releases_url
        - resource_url
        - uri
    LabelId:
      description: A type that references a label.
      type: object
      properties:
        id:
          description: An identifier of a label.
          type: integer
          readOnly: true
        name:
          description: A name of a label.
          type: string
        resource_url:
          description: A URI resource of a label.
          type: string
          format: uri
        catno:
          description: A category number of a label, if any.
          type: string
        entity_type:
          description: An entity name of a label, if any.
          type: string
      required:
        - id
        - name
        - resource_url
    LabelRelease:
      description: A type that represents a release of a label.
      type: object
      properties:
        id:
          description: An identifier of a release.
          type: integer
          readOnly: true
        resource_url:
          description: A URI resource of a release.
          type: string
          format: uri
        thumb:
          description: A URL link to a thumbnail of a release.
          type: string
          format: uri
        artist:
          description: A name for the artist of a release.
          type: string
        title:
          description: A title of a release.
          type: string
        format:
          description: A format of a release.
          type: string
        catno:
          description: A category number of a release.
          type: string
        status:
          description: A status of a release.
          type: string
        year:
          description: A number of year of a release.
          type: integer   
      required:
        - artist
        - catno
        - format
        - id
        - resource_url
        - status
        - title
        - thumb
        - year 
    LabelResult:
      description: A type that represents a label search result.
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          properties:
            type:
              enum: [label]
    ListId:
      description: A type that references a list.
      type: object
      properties:
        id: 
          description: An identifier of a list.
          type: integer
          minimum: 0
          readOnly: true
        uri:
          description:  A URI representation of a list.
          type: string
          format: uri
        resource_url:
          description: A URI resource of a list.
          type: string
          format: uri
          readOnly: true
        name:
          description: A name of a list.
          type: string
        description:
          description: A descriptive explanation of a list.
          type: string
        public:
          description: A flag that indicates whether a list is public or not.
          type: boolean
        date_added:
          description: A date and time in which a list was created.
          type: string
          format: date-time
        date_changed:
          description: A date and time in which a list was last changed.
          type: string
          format: date-time
      required:
        - date_added
        - date_changed
        - description
        - id
        - name
        - public
        - resource_url
        - uri
    List:
      description: A type that represents a list.
      type: object
      properties:
        list_id:
          description: An identifier of a list.
          type: integer
          minimum: 0
          readOnly: true
        resource_url:
          description: A URI resource of a list.
          type: string
          format: uri
          readOnly: true
        url:
          description: A URL representation of a list.
          type: string
          format: uri
        name: 
          description: A name of a list.
          type: string
        description: 
          description: A descriptive explanation of a list.
          type: string
        public:
          description: A flag that indicates whether a list is public or not.
          type: boolean
        created_ts:
          description: A date and time in which a list was created.
          type: string
          format: date-time
        modified_ts:
          description: A date and time in which a list was last modified.
          type: string
          format: date-time
        items:
          description: A list of items contained by a list
          type: array
          items:
            description: A type that represents a list item.
            type: object
            properties:
              id:
                description: An identifier of a list item.
                type: integer
                minimum: 0
                readOnly: true
              uri: 
                description: A URI representation of a list item.
                type: string
                format: uri
                readOnly: true
              resource_url: 
                description: A URI resource of a list item.
                type: string
                format: uri
                readOnly: true
              type:
                description: A type of a list item.
                type: string
                enum:
                  - artist
                  - label
                  - release
              display_title:
                description: A display title of a list item.
                type: string
              image_url:
                description: An image URL associated with a list item.
                type: string
                format: uri
              comment:
                description: A comment associated with a list item.
                type: string
            required:
              - display_title
              - id
              - image_url
              - resource_url
              - type
              - uri
      required: 
        - created_ts
        - description
        - list_id
        - modified_ts
        - name
        - public
        - resource_url
        - url
    Listing:
      description: A type that represents a listing.
      type: object
      properties:
        id:
          description: An identifier of a listing.
          type: integer
          minimum: 0
          readOnly: true
        uri:
          description: A URI representation of a listing.
          type: string
          format: uri
          readOnly: true
        resource_url:
          description: A URI resource of a listing.
          type: string
          format: uri
          readOnly: true
        status:
          description: A status of a listing.
          type: string
          enum:
            - Draft
            - Expired
            - For Sale
            - Sold
        price:
          description: A price assigned to a listing.
          $ref: '#/components/schemas/Price'
        original_price:
          description: An original price assigned to a listing.
          $ref: '#/components/schemas/PriceFormatted'
        shipping_price:
          description: A shipping price assigned to a listing.
          $ref: '#/components/schemas/Price'
        original_shipping_price:
          description: An original shipping price assigned to a listing.
          $ref: '#/components/schemas/PriceFormatted'
        allow_offers:
          description: A flag that indicates whether a listing allow to receive offers or not.
          type: boolean
        offer_submitted:
          description: A flag that indicates whether a user submitted an offer for a listing.
          type: boolean
        condition:
          description: A media condition of a listing.
          $ref: '#/components/schemas/ConditionMedia'
        sleeve_condition: 
          description: A sleeve condition of a listing.
          $ref: '#/components/schemas/ConditionSleeve'
        posted:
          description: A date and time a listing was posted in the marketplace.
          type: string
          format: date-time
        ships_from:
          description: A country from where a listing will be shipped.
          type: string
        comments:
          description: A comment related to a listing.
          type: string
        seller:
          description: A seller of a listing.
          $ref: '#/components/schemas/Seller'
        release:
          description: A release of a listing.
          $ref: '#/components/schemas/ReleaseInListing'
        audio:
          description: A flag that indicates whether is an audio listing or not.
          type: boolean
        external_id:
          description: Any private comment for the seller, if any.
          type: string
        format_quantity:
          description: A number of units this listing counts as for shipping, if any.
          type: integer
          minimum: 1
        location:
          description: A geographical location of a listing, if any.
          type: string
        weight:
          description: A weight in grams of a listing, if any.
          type: integer
          minimum: 0
        in_cart:
          description: A flag that indicates whether a listing is in the shopping cart of a user, if any.
          type: boolean
      required:
        - allow_offers
        - audio
        - comments
        - condition
        - id
        - offer_submitted
        - original_price
        - original_shipping_price
        - posted
        - price
        - release
        - resource_url
        - seller
        - shipping_price
        - ships_from
        - sleeve_condition
        - status
        - uri
    Master:
      description: A type that represents a set of similar releases.
      type: object
      allOf:
        - $ref: '#/components/schemas/Release'
        - type: object
          properties:
            main_release:
              description: An identifier of the main release for this master.
              type: integer
            main_release_url:
              description: A URL link of the main release for this master.
              type: string
              format: uri
            versions_url:
              description: A URL link to the versions of this master.
              type: string
              format: uri
    MasterResult:
      description: A type that represents a master search result.
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          properties:
            type:
              enum: [master]
            main_release:
              description: An identifier of a main release for a master.
              type: integer
    Pagination:
      description: A type that provides details about a paginated result.
      type: object
      properties:
        page:
          description: A number for the current page in a result.
          type: integer
        pages:
          description: A total number of pages in a result.
          type: integer
        per_page:
          description: A total number of items per page in a result.
          type: integer
        items:
          description: A total number of items in a result.
          type: integer
        urls:
          description: A collection of URLs to navigate through the pages in a result.
          type: object
          properties:
            first:
              description: A URL link to the first page in a result, if any.
              type: string
              format: uri
            prev:
              description: A URL link to a previous page in a result, if any.
              type: string
              format: uri
            next:
              description: A URL link to a next page in a result, if any.
              type: string
              format: uri
            last:
              description: A URL link to the last page in a result, if any.
              type: string
              format: uri
      required:
        - page
        - pages
        - per_page
        - items
        - urls
    Price:
      description: A type that represents a price.
      type: object
      properties:
        currency: 
          $ref: '#/components/schemas/Currency'
        value:
          description: A decimal number of a price.
          type: number
          format: float
          minimum: 0
      required:
        - currency
        - value
    PriceFormatted:
      description: A type that represents a formatted price.
      type: object
      properties:
        curr_abbr:
          description: An abbreviation of a currency in a marketplace.
          $ref: '#/components/schemas/Currency'
        curr_id:
          description: An identifier of a currency in a marketplace.
          type: integer
          minimum: 0
          readOnly: true
        formatted:
          description: A price in formatted form.
          type: string
        value:
          description: A decimal number of a price.
          type: number
          format: float
          minimum: 0
      required:
        - curr_abbr
        - curr_id
        - formatted
        - value
    Rating: 
      description: A type that represents a community rating of a release.
      type: object
      properties:
        count:
          description: A number of ratings given by users of a release.
          type: integer
        average:
          description: An average of the ratings given by users of a release.
          type: number
          format: float
      required:
        - average
        - count    
    Release:
      description: A type that eepresents a particular physical or digital object released by one or more artists.
      type: object
      properties:
        id:
          description: An identifier of a release.
          type: integer
          readOnly: true
        title:
          description: A title of a release.
          type: string
        resource_url:
          description: A URI resource of a release.
          type: string
          format: uri
          readOnly: true
        uri:
          description: A URI representation of a release.
          type: string
          format: uri
          readOnly: true
        status:
          description: A status of a release.
          type: string
        data_quality:
          description: An explanation for the data quality related to a release.
          type: string
        thumb:
          description: A URL link to a thumbnail of a release.
          type: string
          format: uri
        country:
          description: A country of a release, if any.
          type: string
        year:
          description: A number of year of a release, if any.
          type: integer
        notes:
          description: Notes of a release, if any.
          type: string
        released:
          description: A release date of a release in a free-text format.
          type: string
        released_formatted:
          description: A released date of a release in formatted text.
          type: string
        date_added:
          description: A date and time of a release being added to the database.
          type: string
          format: date-time
        date_changed:
          description: A date and time of a release being updated in the database.
          type: string
          format: date-time
        lowest_price:
          description: A decimal number for the lowest price of a release in the marketplace, if any.
          type: number
          format: float
        num_for_sale:
          description: A number of items of a release for sale in the marketplace, if any.
          type: integer
        estimated_weight: 
          description: An estimated weight of a release, if any.
          type: integer
        format_quantity:
          description: A total number of formats of a release.
          type: integer
        blocked_from_sale:
          description: A flag that indicates whether the a released is blocked for sale in a marketplace.
          type: boolean
        is_offensive:
          description: A flag that indicates whether a release have explicit language/content or not.
          type: boolean
        master_id:
          description: An identifier of a master associated with a release, if any.
          type: integer
        master_url: 
          description: A URL link to a master associated with a release, if any.
          type: string
          format: uri
        artists:
          description: A list of artists associated with a release.
          type: array
          items:
            $ref: '#/components/schemas/ArtistId'
        labels:
          description: A list of labels associated with a release.
          type: array
          items:
            $ref: '#/components/schemas/LabelId'
        extraartists:
          description: A list of extra artists associated with a release.
          type: array
          items:
            $ref: '#/components/schemas/ArtistId'
        formats:
          description: A list of formats of a release.
          type: array
          items:
            $ref: '#/components/schemas/ReleaseFormat'
        genres:
          description: A list of music genres of a release.
          type: array
          items:
            type: string
        styles:
          description: A list of musical styles of a release.
          type: array
          items:
            type: string
        community:
          description: Some community information of a release.
          $ref: '#/components/schemas/Community'
        companies:
          description: A list of companies related to a release, if any.
          type: array
          items:
            $ref: '#/components/schemas/LabelId'
        tracklist:
          description: A list of tracks of a release, if any.
          type: array
          items:
            $ref: '#/components/schemas/Track'
        images:
          description: A list of images of a release, if any.
          type: array
          items:
            $ref: '#/components/schemas/Image'
        videos:
          description: A list of videos associated with a release, if any.
          type: array
          items:
            $ref: '#/components/schemas/Video'
        identifiers:
          description: A list of identifiers associated with a release.
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
      required:
        - artists
        - data_quality
        - genres        
        - id
        - resource_url
        - status
        - styles
        - title
        - uri
    ReleaseId:
      description: A type that referenced a release.
      type: object
      properties:
        id:
          description: An identifier of a release.
          type: integer
          minimum: 0
          readOnly: true
        resource_url:
          description: A URI resource of a release.
          type: string
          format: uri
          readOnly: true
      required:
        - id
        - resource_url
    ReleaseInFolder:
      description: A type that represents an appearance of a release in a collection folder of a user.
      type: object
      properties:
        id:
          description: An identifier of an appearance of a release in a collection folder.
          type: integer
          readOnly: true
        folder_id:
          description: An identifier of a collection folder that contains a specified release, if any.
          type: integer
          readOnly: true
        instance_id: 
          description: An identifier of a release instance, if any.
          type: integer
          readOnly: true
        resource_url:
          description: A URI resource to a release, if any.
          type: string
          format: uri
          readOnly: true
        date_added:
          description: A date and time in which a release was added into the collection folder of a user.
          type: string
          format: date-time
        rating:
          description: A rating given to a release by a user that added it into a collection folder.
          type: integer
          minimum: 0
          maximum: 5
        basic_information:
          description: The available information about a release that was added into a collection folder of a user.
          $ref: '#/components/schemas/Release'
        notes: 
          description: A list of additional notes related to a release in a collection folder of a user.
          type: array
          items:
            description: A type that represents a note about a release in a collection folder of a user.
            type: object
            properties:
              field_id:
                description: An identifier of a custom field.
                type: integer
                readOnly: true
              value:
                description: A value assigned to a custom field.
                type: string
            required:
              - field_id
              - value
      required:
        - basic_information
        - id
        - date_added
    ReleaseInListing:
      description: A type that represents a release in a listing.
      allOf:
        - $ref: '#/components/schemas/ReleaseId'
        - type: object
          properties:
            catalog_number:
              description: A catalog number of a release.
              type: string
            title: 
              description: A title of a release.
              type: string
            artist:
              description: An artist of a release.
              type: string
            label:
              description: A label of a release.
              type: string
            description:
              description: A descriptive explanation of a release.
              type: string
            year:
              description: A number of year of a release.
              type: integer
              minimum: 1800
            thumbnail:
              description: A thumbnail image of a release.
              type: string
              format: uri
            images: 
              description: A list of images associated with a release.
              type: array
              items:
                $ref: '#/components/schemas/Image'
            stats:
              description: A type that represents statistical information about a release.
              type: object
              properties:
                community:
                  description: A type that represents statistical information about a release provided by a community.
                  type: object
                  properties:
                    in_collection:
                      description: A total number of users in a community that have a release in their collection.
                      type: integer
                      minimum: 0
                    in_wantlist:
                      description: A total number of users in a community that have a release in their wantlist.
                      type: integer
                      minimum: 0
                  required:
                    - in_collection
                    - in_wantlist
              required:
                - community
          required:
            - artist
            - catalog_number
            - description
            - images
            - label
            - thumbnail
            - stats
            - title
            - year
    ReleaseInstance:
      description: A type that represents an instace of a release.
      type: object
      properties:
        instance_id:
          description: An identifier of a release instance.
          type: integer
          readOnly: true
        resource_url:
          description: A URI resource of a release instance.
          type: string
          format: uri
      required:
        - instance_id
        - resource_url
    ReleaseFormat:
      description: A type that represents a format of a release.
      type: object
      properties:
        name:
          description: A name of a format.
          type: string
        qty:
          description: A quantity of a format.
          type: string # Note: API returns this as a string
        text:
          description: An explanation of a format, if any.
          type: string
        descriptions:
          description: A list of descriptions of a format.
          type: array
          items:
            type: string
      required:
        - name
        - qty
        - descriptions
    ReleaseRating:
      description: A type that represents a community rating of a release.
      type: object
      properties:
        rating:
          $ref: '#/components/schemas/Rating'
        release_id:
          description: An identifier of a release.
          type: integer
          readOnly: true
      required:
        - rating
        - release_id
    ReleaseRatingByUser:
      description: A type that represents a rating of a release by a user.
      type: object
      properties:
        username:
          description: A username of a user.
          type: string
          readOnly: true
        release_id:
          description: An identifier of a release.
          type: integer
          readOnly: true
        rating:
          description: A number that defines a rating value of a release.
          type: integer
          minimum: 0
          maximum: 5
      required:
        - rating
        - release_id
        - username
    ReleaseResult:
      description: A type that represents a release search result.
      allOf:
        - $ref: '#/components/schemas/SearchResult'
        - type: object
          properties:
            type:
              enum: [release]
    ReleaseStats:
      description: A type that represents the statistics of a release.
      type: object
      properties:
        num_have:
          description: A total number of users that have a release in their collection.
          type: integer
          minimum: 0
        num_want:
          description: A total number of users that have a release in their wantlist.
          type: integer
          minimum: 0
      required:
        - num_have
        - num_want
    ReleaseVersion:
      description: A type that represents a version of a release.
      type: object
      properties:
        id:
          description: An identifier of a release version.
          type: integer
          readOnly: true
        resource_url:
          description: A URI resource of a release version.
          type: string
          format: uri
          readOnly: true
        status:
          description:  A status of a release version.
          type: string
        thumb:
          description: A URL link to a thumbnail of a release version.
          type: string
          format: uri
        format:
          description: A format of a release version.
          type: string
        country:
          description: A country of a release version, if any.
          type: string
        title:
          description: A title of a release version.
          type: string
        label:
          description: A label of a release version.
          type: string
        released:
          description: A release year of a release version.
          type: string
        major_formats:
          description: A list of formats of a release version.
          type: array
          items:
            type: string
        catno:
          description: A category number of a release version, if any.
          type: string
        stats:
          description: A type contains statictics about a release version.
          type: object
          properties:
            community:
              description: A type that represents the relationship between users and a release version.
              type: object
              properties:
                in_collection:
                  description: A total number of users that have a release version in their collections.
                  type: integer
                in_wantlist:
                  description: A total number of users that have a release version in their wantlist.
                  type: integer
              required:
                - in_collection
                - in_wantlist
      required:
        - format
        - id
        - label
        - major_formats
        - released
        - resource_url
        - stats
        - status
        - thumb
        - title
    SearchResult:
      description: A type that represents a search result.
      type: object
      properties:
        id:
          description: An identifier of a result.
          type: integer
          readOnly: true
        type:
          description: A type of a result.
          type: string
          enum: ['']
        title:
          description: A title of a result
          type: string
        thumb:
          description: A URL link to a thumbnail of a result.
          type: string
          format: uri
        cover_image:
          description: A URL link to a cover image of a result.
          type: string
          format: uri
        resource_url:
          description: A URI resource of a result.
          type: string
          format: uri
          readOnly: true
        uri:
          description: A URI representation of a release.
          type: string
          readOnly: true
        country:
          description: A country of a result.
          type: string
        year:
          description: A number of year of a result.
          type: string
        community:
          $ref: '#/components/schemas/Community'
        format:
          description: A list of formats associated with a result.
          type: array
          items:
            type: string
        label:
          description: A list of labels associated with a result.
          type: array
          items:
            type: string
        catno:
          description: A category number of a result.
          type: string
        genre:
          description: A list of music genres associated with a result.
          type: array
          items:
            type: string
        style:
          description: A list of music styles associated with a result.
          type: array
          items:
            type: string
        barcode:
          description: A list of barcode numbers associated with a result.
          type: array
          items:
            type: string
      required:
        - barcode
        - catno
        - community
        - country
        - cover_image
        - format
        - genre
        - id
        - label
        - resource_url
        - style
        - thumb
        - title
        - type
        - uri
        - year
    Seller:
      description: A type that represents a user that sells inventory in a marketplace.
      allOf:
        - $ref: '#/components/schemas/UserId'
        - type: object
          properties:
            uid: 
              description: An identifier of a user associated with a seller.
              type: integer
              minimum: 0
              readOnly: true
            url:
              description: A URI related to a user.
              type: string
              format: uri
            avatar_url:
              description: An avatar URL of a user.
              type: string
              format: uri
            html_url:
              description: A URL to the website of a seller.
              type: string
              format: uri
            min_order_total:
              description: A number of 
              type: integer
              minimum: 0
            payment:
              description: A payment type preferred by a seller.
              type: string
            shipping:
              description: An explanation of the shipping conditions of a seller.
              type: string
            stats:
              description: A type that represents the statistics associated with a seller.
              type: object
              properties:
                rating:
                  description: A total percentage number of the ratings given to a seller.
                  type: string
                  maxLength: 5
                  pattern: '^\d{1,3}\.\d{1}$'
                stars:
                  description: An average number of stars given to a seller.
                  type: number
                  format: float
                  minimum: 0
                  maximum: 5
                total:
                  description: A total number of rating reviews given to a seller.
                  type: integer
                  minimum: 0
              required:
                - rating
                - stars
                - total
          required:
            - avatar_url
            - html_url
            - min_order_total
            - payment
            - shipping
            - uid
            - url
    Service:
      description: A type that encapsulates any available information about the service.
      type: object
      properties:
        api_version:
          description: A current API version of the service.
          type: string
        documentation_url:
          description: A URI link to the Developers' documentation available online.
          type: string
          format: uri
        hello:
          description: A welcome message send by the service.
          type: string
        statistics:
          description: A type that encapsulates statistical data about the service.
          type: object
          properties:
            artists:
              description: A total number of artists registered in the service.
              type: integer
            labels:
              description: A total number of labels registered in the service.
              type: integer
            releases:
              description: A total number of releases registered in the service.
              type: integer
          required:
            - artists
            - labels
            - releases
      required:
        - api_version
        - documentation_url
        - hello
        - statistics
    ServiceError:
      description: A type that contains any error data.
      type: object
      properties:
        message:
          description: A message of a service error.
          type: string
      required: 
        - message
    Track:
      description: A type that represents a track.
      type: object
      properties:
        position:
          description: A position number of a track.
          type: string
        type_:
          description: A type of a track.
          type: string
        title:
          description: A title of a track.
          type: string
        duration:
          description: A duration of a track in number of seconds.
          type: string
        extraartists:
          description: A list of extra artists related to a track.
          type: array
          items:
            $ref: '#/components/schemas/ArtistId'
    UserId:
      description: A type that references a user.
      type: object
      properties:
        id:
          description: An identifier of a user, if any.
          type: integer
        username:
          description: A username of a user.
          type: string
        resource_url:
          description: A URI resource of a user.
          type: string
          format: uri
      required:
        - resource_url
        - username
    UserIdentity:
      description: A type that represents a user identity.
      allOf:
        - $ref: '#/components/schemas/UserId'
        - type: object
          properties:
            consumer_name:
              description: A name of an application a user utilizes to interacts with the service.
              type: string
    UserItems:
      description: A type that represents all items added and/or edited by a user.
      type: object
      properties:
        artists:
          description: A list of artists added and/or edited by a user.
          type: array
          items:
            $ref: '#/components/schemas/Artist'
        labels:
          description: A list of labels added and/or edited by a user.
          type: array
          items:
            $ref: '#/components/schemas/Label'
        releases:
          description: A list of releases added and/or edited by a user.
          type: array
          items:
            $ref: '#/components/schemas/Release'
    UserProfile:
      description: A type that represents a user profile.
      allOf:
        - $ref: '#/components/schemas/UserId'
        - type: object
          properties:
            name:
              description: A real name of a user.
              type: string
            email:
              description: An e-mail address of a user, if any.
              type: string
              format: email
            profile:
              description: A biographical information of a user.
              type: string
            location:
              description: A geographical location of a user.
              type: string
            uri:
              description: A URL to the resource of a user.
              type: string
              format: uri
            home_page:
              description: A URI to a website of a user.
              type: string
              format: uri
            registered:
              description: A date and time a user registered to the service.
              type: string
              format: date-time
            rank:
              description: A number of rank of a user.
              type: integer
            curr_abbr:
              description: A code of a currency used by a user in the marketplace.
              type: string
              minLength: 3
              maxLength: 3
            activated:
              description: A flag that indicates whether a user is active or not.
              type: boolean
            marketplace_suspended:
              description: A flag that indicates whether a user is suspended at the marketplace or not.
              type: boolean
            is_staff:
              description: A flag that indicates whether a user is member of the staff at the service or not.
              type: boolean
            num_collection:
              description: A number of items a user have in its collection.
              type: integer
            num_lists:
              description: A number of list a user created.
              type: integer
            num_pending:
              description: A number of items a user have in its pending list.
              type: integer
            num_for_sale:
              description: A number of item a user have for sale in the marketplace.
              type: integer
            num_wantlist:
              description: A number of items a user have in its want list, if any.
              type: integer
            rating_avg:
              description: An average rating to the total of releases a user rated.
              type: number
              format: float
              minimum: 0
              maximum: 5
            releases_contributed:
              description: A number of releases that a user contributed information.
              type: integer
            releases_rated:
              description: A number of release that a user rated.
              type: integer
            buyer_rating:
              description: An average rating a user have in the marketplace as a buyer.
              type: number
              format: float
              minimum: 0
              maximum: 100
            buyer_rating_stars:
              description: A number of star rating a user have in the marketplace as a buyer.
              type: integer
              minimum: 0
              maximum: 5
            buyer_num_ratings:
              description: A total number of ratings a user have in the marketplace as a buyer.
              type: integer
            seller_rating:
              description: An average rating a user have in the marketplace as a seller.
              type: number
              format: float
              minimum: 0
              maximum: 100
            seller_rating_stars:
              description: A number of star rating a user have in the marketplace as a seller.
              type: integer
              minimum: 0
              maximum: 5
            seller_num_ratings:
              description: A total number of ratings a user have in the marketplace as a seller.
              type: integer
            avatar_url:
              description: A URL to the avatar of a user.
              type: string
              format: uri
            banner_url:
              description: A URL to th banner of a user.
              type: string
              format: uri
            collection_fields_url:
              description: A URL to the collection fields of a user.
              type: string
              format: uri
            collection_folders_url:
              description: A URL to the collection forlder of a user.
              type: string
              format: uri
            inventory_url:
              description: A URL to the inventory of a user.
              type: string
              format: uri
            wantlist_url:
              description: A URI to the want list of a user.
              type: string
              format: uri
          required:
            - activated
            - avatar_url
            - banner_url
            - buyer_num_ratings
            - buyer_rating
            - buyer_rating_stars
            - collection_fields_url
            - collection_folders_url
            - curr_abbr
            - home_page
            - inventory_url
            - is_staff
            - location
            - marketplace_suspended
            - name
            - num_collection
            - num_lists
            - num_for_sale
            - num_pending
            - profile
            - rating_avg
            - rank
            - registered
            - releases_contributed
            - releases_rated
            - seller_num_ratings
            - seller_rating
            - seller_rating_stars
            - uri
            - wantlist_url
    Video:
      description: A type that represents a video.
      type: object
      properties:
        uri:
          description: A URI representation of a video.
          type: string
          format: uri
          readOnly: true
        duration:
          description: A duration of a video in number of seconds.
          type: integer
        title:
          description: A title of a video.
          type: string
        description:
          description: A description of a video.
          type: string
        embed:
          description: A flag that indicates whether a video is embedded or not.
          type: boolean
      required: 
        - description
        - duration
        - embed
        - title
        - uri
  securitySchemes:
    ConsumerKeySecret:
      description: |
        Discogs authentication using a key/secret pair. 
        
        The `Authorization` header should be in format:
        ```
        Discogs key={A_CONSUMER_KEY}, secret={A_CONSUMER_SECRET}
        ```
      type: apiKey
      name: Authorization
      in: header
    OAuth:
      description: |
        OAuth 1.0a flow for third-party applications. 
        
        This is a placeholder as OpenAPI 3.1 does not directly support OAuth 1.0a. 
        
        The `Authorization` header should be constructed according to OAuth 1.0a specs, for example: `OAuth oauth_consumer_key="...", oauth_nonce="...", ...`
      type: http
      scheme: oauth
    UserToken:
      description: |
        Discogs authentication using a personal access token. 
        
        The `Authorization` header should be in format:
        ```
        Discogs token={YOUR_PERSONAL_ACCESS_TOKEN}
        ```
      type: apiKey
      name: Authorization
      in: header