java.lang.NullPointerException at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:852)

[garydgregory]

java.lang.NullPointerException
    at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:852)
    at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:830)
    at io.swagger.v3.parser.converter.SwaggerConverter.lambda$convert$11(SwaggerConverter.java:1083)
    at java.util.LinkedHashMap.forEach(LinkedHashMap.java:684)
    at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:1082)
    at java.util.stream.ReferencePipeline$3$1.accept(ReferencePipeline.java:193)
    at java.util.ArrayList$ArrayListSpliterator.forEachRemaining(ArrayList.java:1382)
    at java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:481)
    at java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:471)
    at java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:708)
    at java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
    at java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:499)
    at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:1064)
    at io.swagger.v3.parser.converter.SwaggerConverter.convert(SwaggerConverter.java:215)
    at io.swagger.v3.parser.converter.SwaggerConverter.readLocation(SwaggerConverter.java:93)
    at io.swagger.v3.parser.OpenAPIV3Parser.read(OpenAPIV3Parser.java:90)
    at io.swagger.v3.parser.OpenAPIV3Parser.read(OpenAPIV3Parser.java:78)

while parsing:

swagger: '2.0'
schemes:
  - https
host: api.npr.org
info:
  contact:
    email: NPROneEnterprise@npr.org
    name: NPR One Enterprise Team
    url: 'http://dev.npr.org'
  description: |-
    NPR One is a smart application that brings the best of NPR and Member Station programming, newscasts,
    podcasts, and stories together to create a new experience for listening. It provides an editor-curated and
    localized mobile listening experience based on the content the listener chooses, likes, shares, and enjoys.
    The API provides all of the content and customization in a simple, structured way that is easy for application
    developers to implement.
  termsOfService: 'http://dev.npr.org/develop/terms-of-use'
  title: NPR One API Reference
  version: Calcium
  x-apisguru-categories:
    - media
  x-logo:
    url: 'https://pbs.twimg.com/profile_images/722199003845304320/s2zwEoao_400x400.jpg'
  x-origin:
    - format: swagger
      url: 'https://api.npr.org/documentation/calcium/swagger.json'
      version: '2.0'
  x-providerName: npr.org
externalDocs:
  description: Learn more at the NPR One Developer Center
  url: 'http://dev.npr.org'
consumes:
  - application/json
  - application/vnd.collection.doc+json
produces:
  - application/json
  - application/vnd.collection.doc+json
  - 'application/hal+json '
securityDefinitions:
  oauth2:
    authorizationUrl: 'https://api.npr.org/authorization/v2/authorize'
    flow: accessCode
    scopes:
      identity.readonly: 'See your personal information, such as your first name, last name, and favorite station.'
      identity.write: 'Update your personal information, such as your favorite station(s) or program(s) you follow, on your behalf.'
      listening.readonly: See your NPR One listening history and get audio recommendations.
      listening.write: 'Record that you have heard, marked as interesting, and/or skipped NPR One stories in order to personalize future audio recommendations.'
      localactivation: Connect you with your local NPR member station for communication purposes.
    tokenUrl: 'https://api.npr.org/authorization/v2/token'
    type: oauth2
parameters:
  Authorization:
    description: 'Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token.'
    in: header
    name: Authorization
    required: true
    type: string
  X-Advertising-ID:
    description: 'A device-specific advertising identifier, if possible. Apple''s IDFA is an example.'
    in: header
    name: X-Advertising-ID
    required: false
    type: string
  channel:
    default: npr
    description: Determines the focus of the recommendations returned. Channel `npr` is recommended for most use cases.
    enum:
      - npr
      - followed
      - recommended
      - emailstories
      - emailprograms
      - lapsedusersemail
      - ongoing email
      - newscasts
      - shows
    in: query
    name: channel
    required: false
    type: string
responses:
  400WithDocument:
    description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
    headers:
      X-RateLimit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-RateLimit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-RateLimit-Reset:
        description: The number of seconds left in the current period
        type: integer
    schema:
      $ref: '#/definitions/ErrorDocument'
  401WithDocument:
    description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
    schema:
      $ref: '#/definitions/ErrorDocument'
  404WithDocument:
    description: 'The resource with the requested ID could not be found, and the server was unable to complete the request.'
    headers:
      X-RateLimit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-RateLimit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-RateLimit-Reset:
        description: The number of seconds left in the current period
        type: integer
    schema:
      $ref: '#/definitions/ErrorDocument'
  429WithDocument:
    description: 'The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps.'
    headers:
      X-RateLimit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-RateLimit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-RateLimit-Reset:
        description: The number of seconds left in the current period
        type: integer
    schema:
      $ref: '#/definitions/ErrorDocument'
  500WithDocument:
    description: A server error
    headers:
      X-RateLimit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-RateLimit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-RateLimit-Reset:
        description: The number of seconds left in the current period
        type: integer
    schema:
      $ref: '#/definitions/ErrorDocument'
  503WithDocument:
    description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
    headers:
      Retry-After:
        description: The predicted time the system will be back up
        format: date-time
        type: string
    schema:
      $ref: '#/definitions/ErrorDocument'
  IdentitySuccess:
    description: The request was successful
    headers:
      X-RateLimit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-RateLimit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-RateLimit-Reset:
        description: The number of seconds left in the current period
        type: integer
    schema:
      $ref: '#/definitions/UserDocument'
  ListeningSuccess:
    description: A list of audio items (recommendations)
    headers:
      X-RateLimit-Limit:
        description: The number of allowed requests in the current period
        type: integer
      X-RateLimit-Remaining:
        description: The number of remaining requests in the current period
        type: integer
      X-RateLimit-Reset:
        description: The number of seconds left in the current period
        type: integer
    schema:
      $ref: '#/definitions/AudioItemListDocument'
  Simple400:
    description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
    schema:
      $ref: '#/definitions/SimpleError'
  Simple401:
    description: The client credentials were invalid or the authorization server denied the request.
    schema:
      $ref: '#/definitions/SimpleError'
  Simple500:
    description: A server error
    schema:
      $ref: '#/definitions/SimpleError'
  Simple503:
    description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
    headers:
      Retry-After:
        description: The predicted time the system will be back up
        format: date-time
        type: string
    schema:
      $ref: '#/definitions/SimpleError'
tags:
  - description: The interface to our OAuth2 server
    name: authorization
  - description: The entry point to user-specific information
    name: identity
  - description: Audio recommendations tailored to a user's preferences
    name: listening
  - description: Connects users to their local stations
    name: localactivation
  - description: Sponsorship for non-NPR One client applications
    name: sponsorship
  - description: 'Allows clients to look up information for organizations that partner with NPR, including stations and third-party content providers.'
    name: organizationDataService
  - description: Allows clients to look up NPR member station information
    name: stationfinder
paths:
  /authorization/v2/authorize:
    get:
      description: |-
        If the parameters passed to this endpoint are correct, it will redirect to `npr.org/oauth2/login` for the user to complete the sign-in.

        Currently acceptable values for `scope` are any combination of the following:
        - `identity.readonly` - for read-only access to the Identity Service
        - `identity.write` - for write access to the Identity Service
        - `listening.readonly` - for read-only access to the Listening Service
        - `listening.write` - for write access to the Listening Service
        - `localactivation` - for all access to the Local Activation Service

        It is generally suggested that you assume that you will need all of the current scopes in order to successfully implement an NPR One application.

        If the parameters passed in are NOT correct and the client passed in a valid `redirect_uri` parameter, the request will be redirected to `{{YOUR_REDIRECT_URI}}?error={{ERROR_TYPE}}&message={{ERROR_DESCRIPTION}}`.
        If the parameters passed are NOT correct and the client did not pass in a valid `redirect_uri` parameter, this endpoint will return the errors encoded as JSON objects (along with the corresponding HTTP status code -- usually 400).
        The latter is intended for development and debugging purposes -- in a real-world situation, errors returned as JSON objects are irretrievable by the client application, and thus passing in a valid `redirect_uri` is critical even for the purpose of capturing errors.

        If the user successfully logs in and authorizes the application, the request will be redirected to `{{YOUR_REDIRECT_URI}}?code={{AUTHORIZATION_CODE}}&state={{CSRF_TOKEN}}`

        If the user DENIES the application, they will be redirected to `{{YOUR_REDIRECT_URI}}?error=denied&message=The%20user%20has%20denied%20the%20login%20and%20access%20request&state={{CSRF_TOKEN}}`.
        This means that if your application flow requires a user to log in in order to proceed, it is up to you to give them the proper messaging explaining that the sign-in must be authorized in order to continue.

        Finally, please do not confuse an authorization code with an access token. Once your app has completed this flow, you will still need to call `POST /authorization/v2/token` in order to swap the code for a valid access token.
      operationId: getAuthorizationPage
      parameters:
        - description: The client's ID
          in: query
          name: client_id
          required: true
          type: string
        - description: The client's URL to redirect to if the authentication is approved
          in: query
          name: redirect_uri
          required: true
          type: string
        - description: 'The type of response; currently, only `code` is supported'
          enum:
            - code
          in: query
          name: response_type
          required: true
          type: string
        - description: A space-separated list of scope(s) requested by the application
          in: query
          name: scope
          required: true
          type: string
        - description: 'A CSRF token generated by the client, to be roundtripped through the request for added security'
          in: query
          name: state
          required: true
          type: string
      produces:
        - text/html
      responses:
        '302':
          description: 'The correct parameters were passed in and we are redirecting to the authentication page; OR, a valid `redirect_uri` was supplied but there was another error, and the error type and message are embedded in the querystring.'
          headers:
            Location:
              description: The sign-in page to redirect to; most clients will process this redirect automatically.
              format: url
              type: string
        '400':
          description: 'A bad request; generally, one or more parameters passed in were incorrect or missing. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
          schema:
            $ref: '#/definitions/SimpleError'
        '401':
          description: 'The client credentials were invalid (i.e., the `redirect_uri` does not match what we have stored for this client) or the authorization server denied the request. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
          schema:
            $ref: '#/definitions/SimpleError'
        '500':
          description: 'There was an unspecified server error. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
          schema:
            $ref: '#/definitions/SimpleError'
        '503':
          description: 'The system is undergoing maintenance and we are unable to fulfill this request. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring.'
          schema:
            $ref: '#/definitions/SimpleError'
      summary: Show a web-based login/signup form to a user
      tags:
        - authorization
  /authorization/v2/device:
    post:
      consumes:
        - application/x-www-form-urlencoded
      description: |-
        This flow should only be used by clients who cannot show a native webview or do not have advanced input controls. It is an alternative to `GET /authorization/v2/authorize`.

        Third-party clients will need to use one or the other of these two endpoints, but they will generally not use both.
      operationId: generateDeviceCode
      parameters:
        - description: The client's ID
          in: formData
          name: client_id
          required: true
          type: string
        - description: The client's secret key
          in: formData
          name: client_secret
          required: true
          type: string
        - description: A space-separated list of scope(s) requested by the application. Required for all untrusted clients; will be ignored for trusted clients.
          in: formData
          name: scope
          required: false
          type: string
      produces:
        - application/json
      responses:
        '201':
          description: 'We have generated a unique device code and user code. These will only be valid for the amount of time specified in the `expires_in` field; if the user does not complete the login process in that amount of time, the client will need to request a new set of codes.'
          schema:
            $ref: '#/definitions/DeviceCodeData'
        '400':
          $ref: '#/responses/Simple400'
        '401':
          $ref: '#/responses/Simple401'
        '500':
          $ref: '#/responses/Simple500'
        '503':
          $ref: '#/responses/Simple503'
      summary: Initiate an OAuth2 login flow for limited input devices
      tags:
        - authorization
  /authorization/v2/token:
    post:
      consumes:
        - application/x-www-form-urlencoded
      description: |-
        Please be aware that the required parameters are contingent on the `grant_type` that you select.

        For the `authorization_code` grant type, you are **required** to pass in the `code` and `redirect_uri` parameters. `service`, `username` and `password` parameters will be ignored.

        For the `client_credentials` grant type, you do not need to pass in any additional parameters beyond the basic requirements. `code`, `redirect_uri`, `service`, `username` and `password` parameters will be ignored.

        For the `device_code` grant type, you are **required** to pass in the `code` parameter. If you are a third-party developer, you are also required to provide the `scope` parameter; see the documentation for `GET /authorization/v2/authorize` for possible values. `redirect_uri`, `service`, `username` and `password` parameters will be ignored.

        For the `password` grant type, you are **required** to pass in the `username` and `password` parameters. The `code` and `redirect_uri` parameters are ignored.
        Third-party developers do not have access to this grant type.

        For the `refresh_token` grant type, you are **required** to pass in the `refresh_token` parameter. The `scope` parameter can optionally be used to request a different set of scopes than were used in the original request, but it **cannot** contain any scopes that were not previously requested. If not specified, then `scope` will be set to whichever scopes were used for the original access token request. If trading in an old non-expiring access token for a refresh-enabled token, set the value of `refresh_token` to the access token value and `token_type_hint` must be set to `access_token`. `code`, `redirect_uri`, `service`, `username` and `password` parameters will be ignored.

        The `temporary_user` and `anonymous_user` grant types are custom grant types created by NPR to suit our needs for functionality such as our "try-before-you-buy" experience. If you are a third-party developer, you will not have access to these grant types unless we have explicitly given you permission within our system.
        For these grant types, if you are a third-party developer, you are required to provide the `scope` parameter; see the documentation for `GET /authorization/v2/authorize` for possible values. `code`, `redirect_uri`, `service`, `username` and `password` parameters will be ignored.

        The `third_party` grant type is another custom grant type created by NPR to handle login via third-party providers such as Facebook and Google. If you are a third-party developer, you will not have access to this grant types unless we have explicitly given you permission within our system.
        For this grant type, you are **required** to pass in the `service` and `token` parameters. If you are a third-party developer, you are also required to provide the `scope` parameter; see the documentation for `GET /authorization/v2/authorize` for possible values. The `code` and `redirect_uri` parameters are ignored.

        If you are unsure of which grant type to select, assume that `authorization_code` is the one you want.

        Note that at this time, refresh tokens are an opt-in feature; however, in the future, they will gradually transition to being opt-out, and ultimately required for all clients. Our general guidance at this time is that if this endpoint starts returning refresh tokens for you, you are responsible for implementing the code to handle them appropriately in accordance with the OAuth 2.0 spec. For more information about our gradual rollout of this feature, please contact the NPR One API team.
      operationId: createToken
      parameters:
        - description: The type of grant the client is requesting
          enum:
            - authorization_code
            - client_credentials
            - device_code
            - password
            - refresh_token
            - temporary_user
            - anonymous_user
            - third_party
          in: formData
          name: grant_type
          required: true
          type: string
        - description: 'The client''s ID, required for all grant types.'
          in: formData
          name: client_id
          required: true
          type: string
        - description: 'The client''s secret, required for all grant types.'
          in: formData
          name: client_secret
          required: true
          type: string
        - description: 'Required for `authorization_code` and `device_code` grant types. The authorization code from a successful call to `/authorization/v2/authorize`, or a device code from a successful call to `/authorization/v2/device`.'
          in: formData
          name: code
          required: false
          type: string
        - description: Required for `authorization_code` grant type. The requested redirect_uri.
          in: formData
          name: redirect_uri
          required: false
          type: string
        - description: Required for `password` grant type. The email address of an NPR user.
          format: email
          in: formData
          name: username
          required: false
          type: string
        - description: Required for `password` grant type. The password that matches the user specified with the username parameter.
          format: password
          in: formData
          name: password
          required: false
          type: string
        - description: Required for `third_party` grant type. The name of the third-party login provider.
          enum:
            - facebook
            - google
            - microsoft
            - janrain
            - comcast
          in: formData
          name: service
          required: false
          type: string
        - description: Required for `refresh_token` grant type. A valid refresh token from a previous successful call to `POST /authorization/v2/token`.
          in: formData
          name: refresh_token
          required: false
          type: string
        - description: 'Required for third-party developers using the `device_code`, `temporary_user`, and `third_party` grant types. Optionally used by the `refresh_token` grant type. A space-separated list of scope(s) requested by the application.'
          in: formData
          name: scope
          required: false
          type: string
        - description: 'A hint about the type of the token submitted for a new access and refresh token. If unspecified, the default value is assumed to be `refresh_token`.'
          enum:
            - access_token
            - refresh_token
          in: formData
          name: token_type_hint
          required: false
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: A new token was successfully created
          schema:
            $ref: '#/definitions/AccessTokenData'
        '400':
          $ref: '#/responses/Simple400'
        '401':
          description: 'The client credentials were invalid (any grant type), the user credentials were invalid (`password` grant type), the user has not yet logged in or has purposely denied the request (`device_code` grant type), or the authorization server denied the request.'
          schema:
            $ref: '#/definitions/SimpleError'
        '500':
          $ref: '#/responses/Simple500'
        '503':
          $ref: '#/responses/Simple503'
      summary: Create a new OAuth2 access token
      tags:
        - authorization
  /authorization/v2/token/revoke:
    post:
      consumes:
        - application/x-www-form-urlencoded
      description: |-
        Our implementation follows the proposed IETF specification [RFC-7009](https://tools.ietf.org/html/rfc7009).

        If your client application offers the ability to for a logged-in user to log out, and you have access to a long-lived
        `client_credentials` token (i.e. you have generated one that you are storing securely for the lifetime of the entire app
        install), we suggest (but do not require) that you call this endpoint and revoke the access token belonging to the
        logged-in user as part of your logout process. If you do not already have a long-lived `client_credentials` token,
        please don't generate one just for the purposes of calling this endpoint.

        If you are building a prototype application, we also recommend that you use this endpoint to clean up access tokens
        that you generate during the testing of your app and do not intend to reuse.

        Note that revoking an access token will automatically revoke any refresh tokens associated with it, and vice-versa.
      operationId: revokeToken
      parameters:
        - description: 'A `client_credentials` access token from the same client application as the token being revoked. Should start with `Bearer`, followed by a space, followed by the token.'
          in: header
          name: Authorization
          required: true
          type: string
        - description: The access token or refresh token that the client wants to have revoked.
          in: formData
          name: token
          required: true
          type: string
        - description: 'A hint about the type of the token submitted for revocation. If unspecified, the default value is assumed to be `access_token`.'
          enum:
            - access_token
            - refresh_token
          in: formData
          name: token_type_hint
          required: false
          type: string
      produces:
        - application/json
      responses:
        '200':
          description: The old token was successfully revoked
          schema:
            description: An empty JSON object
            type: object
        '400':
          $ref: '#/responses/Simple400'
        '401':
          $ref: '#/responses/Simple401'
        '403':
          description: The client associated with the access token in the header does not own the access token that this request is attempting to revoke.
          schema:
            $ref: '#/definitions/SimpleError'
        '500':
          $ref: '#/responses/Simple500'
        '503':
          $ref: '#/responses/Simple503'
      summary: Revoke an existing OAuth2 access token
      tags:
        - authorization
  /identity/v2/following:
    post:
      consumes:
        - application/json
      description: 'After a successful call, this returns a User document with an updated list of affiliations.'
      operationId: postFollowing
      parameters:
        - $ref: '#/parameters/Authorization'
        - description: 'A JSON-serialized object which contains data about a user affiliation such as the aggregation ID, affiliation rating, aggregation URL, days since last listen, and following status.'
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/Affiliation'
      responses:
        '201':
          $ref: '#/responses/IdentitySuccess'
        '400':
          $ref: '#/responses/400WithDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - identity.write
      summary: Update the following status of the logged-in user for a particular aggregation
      tags:
        - identity
  /identity/v2/stations:
    put:
      description: 'Right now, only the primary station can be changed. Previously selected stations will not be deleted, but the new station will be moved to first in the array.'
      operationId: updateStations
      parameters:
        - $ref: '#/parameters/Authorization'
        - description: A JSON-serialized array of station IDs
          in: body
          name: body
          required: false
          schema:
            items:
              type: integer
            type: array
      responses:
        '201':
          $ref: '#/responses/IdentitySuccess'
        '400':
          $ref: '#/responses/400WithDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - identity.write
      summary: Update the logged-in user's favorite station(s)
      tags:
        - identity
  /identity/v2/user:
    get:
      description: 'After a successful login, the client should send a `GET` call approximately once an hour to refresh the user data.'
      operationId: getUser
      parameters:
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          $ref: '#/responses/IdentitySuccess'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - identity.readonly
      summary: Get the latest state information about the logged-in user
      tags:
        - identity
  /identity/v2/user/inherit:
    post:
      description: |-
        This can and should only be used by clients who have access to the `temporary_user` grant type.
            Third-party developers do not have access to this grant type by default, and will not need this endpoint.
      operationId: inheritFromTempUser
      parameters:
        - $ref: '#/parameters/Authorization'
        - description: The temporary user's ID before the user registered or logged in
          in: query
          name: temp_user
          required: true
          type: integer
      responses:
        '202':
          $ref: '#/responses/IdentitySuccess'
        '400':
          $ref: '#/responses/400WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - identity.write
      summary: Copy listening data from a temporary user account to the logged-in user's account
      tags:
        - identity
  '/listening/v2/aggregation/{aggId}/recommendations':
    get:
      description: This endpoint provides a list of recent audio items associated with the aggregation along with metadata about the aggregation.
      operationId: getAggRecommendations
      parameters:
        - description: ID of an aggregation such as a program or podcast
          format: int64
          in: path
          name: aggId
          required: true
          type: integer
        - $ref: '#/parameters/Authorization'
        - default: 0
          description: 'The result to start with. Allows paging through the episodes of a podcast or program, with the default, `startNum=0`, being the most recent episode'
          format: int32
          in: query
          name: startNum
          required: false
          type: integer
      responses:
        '200':
          description: A list of audio items from the specified aggregation
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/AggregationAudioItemListDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '404':
          $ref: '#/responses/404WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get a set of recommendations for an aggregation
      tags:
        - listening
  /listening/v2/channels:
    get:
      description: These channels allow the user to specify a focus for the content returned in the recommendations endpoint.
      operationId: getChannels
      parameters:
        - $ref: '#/parameters/Authorization'
        - default: false
          description: 'If set to `true`, this call will return only channels that should be shown in the client''s `Explore` view'
          in: query
          name: exploreOnly
          required: false
          type: boolean
      responses:
        '200':
          description: A list of channels
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/ChannelsDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get the list of available channels
      tags:
        - listening
  /listening/v2/history:
    get:
      description: 'This endpoint provides the list of recently-rated audio recommendations that the logged-in user has consumed. Some rated recommendations are filtered, such as sponsorship and donation.'
      operationId: getHistory
      parameters:
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          $ref: '#/responses/ListeningSuccess'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get recent ratings the logged-in user has submitted
      tags:
        - listening
  '/listening/v2/organizations/{orgId}/categories/{category}/recommendations':
    get:
      description: This endpoint provides a list of recommendations from a category of content from  an organization.
      operationId: getOrganizationCategory
      parameters:
        - description: 'ID of an organization, such as an NPR One station'
          format: int64
          in: path
          name: orgId
          required: true
          type: integer
        - default: story
          description: 'One of the three categories of content - newscast, story, or podcast'
          enum:
            - newscast
            - story
            - podcast
          in: path
          name: category
          required: true
          type: string
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          description: A list of audio items from a category of content from an organization
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/OrganizationCategoryAudioListDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '404':
          $ref: '#/responses/404WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get a list of recommendations from a category of content from an organization
      tags:
        - listening
  '/listening/v2/organizations/{orgId}/recommendations':
    get:
      description: This endpoint provides a variety of details about an organization including various lists of recent audio items.
      operationId: getOrganizationOverview
      parameters:
        - description: 'ID of an organization, such as an NPR One station'
          format: int64
          in: path
          name: orgId
          required: true
          type: integer
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          description: A list of up to three different categories of audio items from a specific organization
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/OrganizationOverviewDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '404':
          $ref: '#/responses/404WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get a variety of details about an organization including various lists of recent audio items
      tags:
        - listening
  /listening/v2/promo/recommendations:
    get:
      description: Gets the most recently played promo for which the user has neither tapped through the promo or listened to the target story.
      operationId: getPromo
      parameters:
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          $ref: '#/responses/ListeningSuccess'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Retrieve the most recent promo audio heard by the logged-in user
      tags:
        - listening
  /listening/v2/ratings:
    post:
      consumes:
        - application/json
      description: |-
        This endpoint is the main mechanism for providing feedback from the user to NPR about the recommendations that are obtained from `GET /listening/v2/recommendations`.

        A fully-populated link to this endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the `links['recommendations']` object. The query parameters in this link should not be modified.
        Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future.

        This endpoint can return a blank JSON.doc or AudioItemDocument depending on the `recommend=true|false` parameter. The `recommend=true` flag allows this endpoint to both receive ratings and send back recommendations in the same call.
      operationId: postRating
      parameters:
        - $ref: '#/parameters/Authorization'
        - $ref: '#/parameters/X-Advertising-ID'
        - $ref: '#/parameters/channel'
        - default: true
          description: 'If set to `false`, this call will return a blank document; otherwise it will return a new recommendation object'
          in: query
          name: recommend
          required: false
          type: boolean
        - description: 'A list of RatingData objects which contains data about ratings such as the id of the content, the rating value, elapsed time and more.'
          in: body
          name: body
          required: true
          schema:
            items:
              $ref: '#/definitions/RatingData'
            type: array
      responses:
        '200':
          description: 'If the `recommend` param was set to `true`, this returns a list of audio items; otherwise, a blank document is returned.'
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/AudioItemListDocument'
        '400':
          $ref: '#/responses/400WithDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.write
      summary: Collect new ratings for media previously recommended to the logged-in user
      tags:
        - listening
  /listening/v2/recommendations:
    get:
      description: |-
        This endpoint returns a list of audio recommendations. It is designed to be used for an initial list of recommendations, and then `GET /listening/v2/ratings?recommend=true` should be used for subsequent requests for recommendations.

        A fully-populated link to the ratings endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the `links['recommendations']` object. The query parameters in this link should not be modified.
        Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future.
      operationId: getRecommendations
      parameters:
        - $ref: '#/parameters/Authorization'
        - $ref: '#/parameters/X-Advertising-ID'
        - $ref: '#/parameters/channel'
        - description: 'This media was shared directly with the user; if provided, the service will add this recommendation to the top of the list'
          in: query
          name: sharedMediaId
          required: false
          type: string
        - description: 'The user received a push notification about this media; if provided, the service will add this recommendation to the top of the list'
          in: query
          name: notifiedMediaId
          required: false
          type: string
      responses:
        '200':
          $ref: '#/responses/ListeningSuccess'
        '400':
          $ref: '#/responses/400WithDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get a list of media for the logged-in user from NPR's recommendation engine
      tags:
        - listening
  /listening/v2/search/recommendations:
    get:
      description: 'In the schema shown below, SearchItemDocument is not an actual type of returned object; the object returned by a search will be either an AggregationAudioItemListDocument or an AudioItemDocument.'
      operationId: getSearchRecommendations
      parameters:
        - $ref: '#/parameters/Authorization'
        - description: Search terms to search on; can include URL-encoded punctuation
          in: query
          name: searchTerms
          required: true
          type: string
      responses:
        '200':
          description: A list of audio and aggregation items matching the search query
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/SearchListDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      security:
        - oauth2:
            - listening.readonly
      summary: Get a list of recent audio and aggregation items associated with search terms
      tags:
        - listening
  /localactivation/v2/donate_email:
    get:
      description: This will send a station-specific donation email to the logged-in user.
      operationId: sendDonationEmail
      parameters:
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          description: On success only a blank document
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/CollectionDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
      security:
        - oauth2:
            - localactivation
      summary: Send a donation email to the logged-in user (only on request)
      tags:
        - localactivation
  /sponsorship/v2/ads:
    get:
      description: |-
        **Not** for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to request sponsorship on behalf of a user. Sponsorship units are returned in the form of DAAST XML. It is worth noting that this endpoint attempts to always return XML, even in the case of exceptions.

        The default behavior of this endpoint is asynchronous; on an initial request, a call to our external sponsorship provider is placed on a queue, which is typically processed within 3 minutes. Once the sponsorship call is received and processed, the returned sponsorship units are placed in a cache on our server for the current user. Subsequent calls to this endpoint will return DAAST sponsorship units from this cache until tracking information is submitted, which removes the ad from the cache and will automatically request additional ads asynchronously if there are fewer than a certain number remaining in the cache.

        For development purposes, it's worth noting that there is currently no way to clear a user's cache without submitting some form of tracking.
      operationId: getAds
      parameters:
        - $ref: '#/parameters/Authorization'
        - $ref: '#/parameters/X-Advertising-ID'
        - description: Whether to force a synchronous call to our external sponsorship provider; the default behavior is asynchronous.
          in: query
          name: forceResult
          required: false
          type: boolean
        - description: 'How many sponsorship units to request in one call; if left unspecified, the default behavior is to return only 1.'
          format: int32
          in: query
          maximum: 5
          minimum: 1
          name: adCount
          required: false
          type: integer
      produces:
        - application/xml
      responses:
        '200':
          description: 'Request completed successfully; a DAAST XML document is returned. Note that this response will only be returned if either `force=true` was passed in the querystring, or a call to get sponsorship was previously made, and ads now exist in the cache for this user; otherwise, the 202 response is returned.'
          schema:
            $ref: '#/definitions/DAASTXml'
        '202':
          description: Request accepted. Check back later for actual ads.
        '400':
          description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
          schema:
            $ref: '#/definitions/ErrorXmlDocument'
        '500':
          description: A server error
          schema:
            $ref: '#/definitions/ErrorXmlDocument'
      summary: Request DAAST sponsorship units
      tags:
        - sponsorship
    post:
      consumes:
        - application/json
      description: |-
        **Not** for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to submit tracking information for sponsorship units obtained from the `GET /sponsorship/v2/ads` endpoint.

        The tracking information should be submitted in the body of the request in the form of a JSON object following the Collection.Doc+JSON specification.
      operationId: receiveAdTracking
      parameters:
        - $ref: '#/parameters/Authorization'
        - $ref: '#/parameters/X-Advertising-ID'
        - description: A JSON object representing sponsorship tracking data to submit to our external provider.
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/UserAdDocument'
      responses:
        '204':
          description: 'Request completed successfully, but there is nothing that we need to return to the caller.'
        '400':
          description: 'A bad request; generally, one or more parameters passed in were incorrect or missing'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: A server error
          schema:
            $ref: '#/definitions/Error'
      summary: Record tracking data for DAAST sponsorship units
      tags:
        - sponsorship
  /stationfinder/v3/stations:
    get:
      description: |-
        This endpoint has two main use cases:

        - If no query parameters passed in, it returns a list of stations that are geographically closest to the calling client (based on GeoIP information)
        - If one or more query parameters are passed in, it performs a search of NPR stations that match those search criteria (not taking into account the client's physical location)

        Clients wanting to implement a 'Change Station' UI should use this endpoint to power their search. In most cases, you'll want to build a search interface that uses one of the 3 provided schemas: `lat` and `lon` (using e.g. the HTML5 Geolocation API), `city` and `state`, _or_ the generic `q` query which can accept a station name, call letters, network name, or zip code. Technically speaking, `q` can also take in either a city name or a state name, but using the `city` and `state` parameters together will yield more accurate geographic search results than `q={cityName}`.

        The `lat` and `lon` query parameters should always be passed in together (otherwise the API will return a 400 error), and if included in the query, they will take precedence over any other search criteria; that is, `lat` and `lon` will do a purely geographic search and not take into account `q`, `city` or `state`.

        Similarly, `city` and/or `state` will take precedence over (and ignore) `q`.

        If clients want to be able to offer multiple types of searches (e.g. 'Search for a station name, city or zipcode') using a *single* search input form, `q` should be used. But again, be aware that using `city` and `state` together will yield more accurate search results than `q={cityName}`.
      operationId: searchStations
      parameters:
        - $ref: '#/parameters/Authorization'
        - description: 'Search terms to search on; can be a station name, network name, call letters, or zipcode'
          in: query
          name: q
          required: false
          type: string
        - description: A city to look for stations from; intended to be paired with `state`
          in: query
          name: city
          pattern: '^[A-Za-z ''\.]+$'
          required: false
          type: string
        - description: A state to look for stations from (using the 2-letter abbreviation); intended to be paired with `city`
          in: query
          name: state
          pattern: '^[A-Z]{2}$'
          required: false
          type: string
        - description: A latitude value from a geographic coordinate system; only works if paired with `lon`
          format: float
          in: query
          name: lat
          required: false
          type: number
        - description: A longitude value from a geographic coordinate system; only works if paired with `lat`
          format: float
          in: query
          name: lon
          required: false
          type: number
      responses:
        '200':
          description: A list of one or more stations matching the search query
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/StationListDocument'
        '400':
          $ref: '#/responses/400WithDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      summary: List stations close to you or filter by search criteria
      tags:
        - stationfinder
  '/stationfinder/v3/stations/{stationId}':
    get:
      description: |-
        This endpoint retrieves information about a given station, based on its numeric ID, which is consistent across all of NPR's APIs.

        A typical use case for this data is for clients who want to create a dropdown menu, modal/pop-up or dedicated page displaying more information about the station the client is localized to, including, for example, links to the station's homepage and donation (pledge) page.
      operationId: getStationById
      parameters:
        - $ref: '#/parameters/Authorization'
        - description: The numeric ID of a station
          format: int64
          in: path
          name: stationId
          required: true
          type: integer
      responses:
        '200':
          description: A document describing the station with the given ID
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              type: integer
          schema:
            $ref: '#/definitions/StationDocument'
        '400':
          $ref: '#/responses/400WithDocument'
        '401':
          $ref: '#/responses/401WithDocument'
        '404':
          $ref: '#/responses/404WithDocument'
        '429':
          $ref: '#/responses/429WithDocument'
        '500':
          $ref: '#/responses/500WithDocument'
        '503':
          $ref: '#/responses/503WithDocument'
      summary: Retrieve metadata for the station with the given numeric ID
      tags:
        - stationfinder
definitions:
  AbstractCDocLink:
    allOf:
      - $ref: '#/definitions/AbstractLink'
      - properties:
          content-type:
            description: The MIME type of the response of this link
            type: string
        required:
          - content-type
  AbstractLink:
    properties:
      href:
        description: The link to be followed
        format: uri
        type: string
    required:
      - href
  AccessTokenData:
    properties:
      access_token:
        description: The access token to use for all future calls
        type: string
      expires_in:
        description: The remaining lifetime of the access token (in seconds)
        format: int32
        type: integer
      refresh_token:
        description: 'The refresh token that can be used to obtain a new access token if the old one expires; if a refresh token is returned, it is the client''s responsibility to securely cache it for future use.'
        type: string
      token_type:
        description: 'Identifies the type of token returned. At this time, this field always has the value `Bearer`.'
        enum:
          - Bearer
          - MAC
        type: string
    required:
      - access_token
      - token_type
      - expires_in
  AdTrackingData:
    description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
    properties:
      adId:
        description: 'The DAAST Ad node `id` attribute value, (e.g. AdswizzAd12345)'
        type: string
      event:
        default: start
        description: The user-interaction event to submit tracking for
        enum:
          - start
          - firstQuartile
          - midpoint
          - thirdQuartile
          - complete
        type: string
    required:
      - adId
      - event
  AdTrackingDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/AdTrackingData'
            description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
          items:
            description: Not used
            items:
              type: 'null'
            type: array
    description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
  AdXml:
    properties:
      InLine:
        $ref: '#/definitions/InLineXml'
      id:
        type: string
        xml:
          attribute: true
    type: object
    xml:
      name: Ad
      namespace: 'http://www.w3.org/2001/XMLSchema-instance'
  Affiliation:
    description: A program (aggregation) that a given user has shown an affiliation with
    properties:
      daysSinceLastListen:
        description: The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation.
        format: int32
        type: integer
      following:
        default: false
        description: 'Whether or not the user is following the aggregation. When changing affiliation status, the client is expected to toggle this value and then send the entire object back.'
        type: boolean
      href:
        description: A link to more details about the program from the NPR Story API
        type: string
      id:
        description: A unique identifier for the aggregation (program)
        format: int64
        type: integer
      notif_following:
        description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they follow.
        items:
          type: string
        type: array
      notif_rated:
        description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they have highly rated.
        items:
          type: string
        type: array
      rating:
        description: The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation.
        format: float
        type: number
      title:
        description: The title for the aggregation (program)
        type: string
    required:
      - id
      - href
      - following
  AggregationAudioItemListDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/AggregationData'
            description: The metadata which describes the aggregation
          items:
            description: An array of Audio Items (recommendations)
            items:
              $ref: '#/definitions/AudioItemDocument'
            type: array
          links:
            $ref: '#/definitions/AggregationLinks'
            description: An array of links for the aggregation. Look here for images associated with the aggregation or for a more link to get more episodes.
    description: An array of audio recommendations with additional metadata about the aggregation they are associated with
  AggregationData:
    properties:
      affiliation:
        description: A unique identifier for the aggregation
        type: string
      affiliationMeta:
        $ref: '#/definitions/Affiliation'
        description: Metadata about the logged-in user's relationship to this aggregation
      description:
        description: A short description or teaser
        type: string
      station:
        default: NPR
        description: The producer of this aggregation
        type: string
      title:
        description: The title of this aggregation
        type: string
      type:
        default: aggregation
        description: The type of list returned; will always be `aggregation`; useful for parsing search results
        enum:
          - aggregation
        type: string
    required:
      - type
      - affiliation
      - title
  AggregationLinks:
    properties:
      image:
        description: 'One or more links to an image, along with metadata for display'
        items:
          $ref: '#/definitions/ImageLink'
        type: array
      more:
        description: One or more links to more episodes for the aggregation
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      web:
        description: One or more links to a web page for the item
        items:
          $ref: '#/definitions/OtherLink'
        type: array
  AudioItemData:
    properties:
      album:
        description: Album information associated with the media
        type: string
      artist:
        description: The artist associated with the media
        type: string
      audioTitle:
        description: For first-party client use only
        type: string
      button:
        description: The text contents of an action button displayed on the client
        type: string
      date:
        description: The publication date in ISO-8601 format
        format: date-time
        type: string
      description:
        description: A short description or teaser
        type: string
      duration:
        description: The length of the audio content in seconds
        format: int32
        maximum: 9999
        minimum: 0
        type: integer
      expires:
        description: The media's expiration date in ISO-8601 format
        format: date-time
        type: string
      geofence:
        $ref: '#/definitions/Geofence'
        description: The geographic restrictions that should be applied by the client before playing this media
      label:
        description: The record label associated with the media
        type: string
      organization:
        $ref: '#/definitions/RecommendationOrganization'
        description: Data about the organization with which this media is associated
      primary:
        description: Whether the audio is the primary audio of the story to which it is associated
        type: boolean
      program:
        description: The program associated with this media
        type: string
      provider:
        default: NPR
        description: The name of the organization providing this media
        type: string
      rating:
        $ref: '#/definitions/RatingData'
        description: An object which contains all data that should be sent back to NPR when sending a rating
      rationale:
        description: A short summary of why this content was recommended
        type: string
      skippable:
        default: true
        description: Whether the client should allow this content to be skipped
        type: boolean
      slug:
        description: A tag or category for this media
        type: string
      song:
        description: The song title associated with the media
        type: string
      title:
        description: The title of this media
        type: string
      type:
        default: audio
        description: 'Help determine how content is displayed; for more information, see <a href=''http://dev.npr.org/design/general-specifications/playing-audio/''>our design guidelines</a>'
        enum:
          - audio
          - sponsorship
          - stationId
          - intro
          - donate
          - featureCardInformational
          - featureCardNotification
          - featureCardPromotion
          - featureCardExternalLink
          - featureCardAsyncRequest
        type: string
      uid:
        description: The media ID (for use in ratings objects)
        pattern: '^\d{3,}:[\w-]{5,}$'
        type: string
      unavailableText:
        description: The text contents to be displayed on the client if no media URLs are available
        type: string
    required:
      - type
      - uid
      - title
      - skippable
      - rationale
      - rating
  AudioItemDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/AudioItemData'
            description: The metadata which comprises the recommendation
          items:
            description: Not used
            items:
              type: 'null'
            type: array
          links:
            $ref: '#/definitions/AudioItemLinks'
            description: A list of links. Look here for audio files.
  AudioItemLinks:
    properties:
      action:
        description: 'One or more links to be trigged by user actions, usually when a button is clicked'
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      audio:
        description: One or more links to audio files for the item
        items:
          $ref: '#/definitions/AudioLink'
        type: array
      image:
        description: 'One or more links to an image, along with metadata for display'
        items:
          $ref: '#/definitions/ImageLink'
        type: array
      onramps:
        description: One or more shareable links for the item
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      ratings:
        description: This is an alternate URL to use to POST the ratings JSON. Difference between this and 'recommendations' is that 'ratings' will NOT return back recommendations of audio to play next.
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      recommendations:
        description: This is the URL that should be POSTed with the ratings JSON when this audio starts to play
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      up:
        description: One or more links to more details about the program or podcast with which this item is associated
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      web:
        description: One or more links to a web page for the item
        items:
          $ref: '#/definitions/OtherLink'
        type: array
  AudioItemListDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            description: Not used
            type: object
          items:
            description: An array of Audio Items (recommendations)
            items:
              $ref: '#/definitions/AudioItemDocument'
            type: array
          links:
            description: Not used
            type: object
  AudioLink:
    allOf:
      - $ref: '#/definitions/AbstractLink'
      - properties:
          content-type:
            default: audio/aac
            description: 'The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.'
            enum:
              - audio/mp3
              - audio/aac
              - audio/3gp
              - application/vnd.apple.mpegurl
              - audio/x-ms-wax
            type: string
        required:
          - content-type
    description: A link to audio files for the item
  Brand:
    description: Branding information for the organization
    properties:
      band:
        description: The radio band for the organization if they are a station (AM or FM)
        type: string
      call:
        description: The call letter for the organization if they are a station
        type: string
      frequency:
        description: The radio frequency for the organization if they are a station
        type: string
      marketCity:
        description: The market city for the organization
        type: string
      marketState:
        description: The market state for the organization
        type: string
      name:
        description: The name of the organization
        type: string
      tagline:
        description: The tagline for the organization
        type: string
    required:
      - name
      - call
      - marketCity
  CategoryData:
    properties:
      displayType:
        description: How clients should display this channel in the station profile view
        enum:
          - default
          - show
          - playable
          - newscast
        type: string
      orgId:
        description: The unique identifier for the organization
        format: int64
        type: integer
      title:
        description: The title of this category
        type: string
      type:
        default: category
        description: The type of list returned; will always be `category`
        type: string
    required:
      - type
      - orgId
      - title
  CategoryLinks:
    properties:
      more:
        description: One or more links to more episodes for the aggregation
        items:
          $ref: '#/definitions/OtherLink'
        type: array
  ChannelData:
    properties:
      description:
        description: A longer description of what this channel focuses on
        type: string
      displayType:
        description: How clients should display this channel in the explore view
        enum:
          - default
          - show
          - playable
          - newscast
        type: string
      emptyText:
        description: Text for clients to display when the channel contains no recommendations
        type: string
      fullName:
        description: A short description of what this channel focuses on
        type: string
      id:
        description: The actual value that should be sent
        type: string
      refreshRule:
        description: 'In the explore view of a client, this field indicates how this channel should be refreshed.  This is an experimental field and subject to change, but for now zero indicates the client should refresh this channel every time a START rating is sent for a type=audio recommendation, while a 1 would indicate it can be refreshed much less often, such as on a 30 minute timer. 2 would indicate even less time to update, say every hour. We are still experimenting on the number of rules necessary and the best implementation for each type of rule. '
        type: integer
    required:
      - id
      - fullName
      - description
  ChannelDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/ChannelData'
            description: The channel data
          items:
            description: Not used
            items:
              type: 'null'
            type: array
          links:
            description: Not used
            type: object
  ChannelsData:
    properties:
      defaultChannel:
        default: npr
        description: The default channel NPR recommends
        type: string
  ChannelsDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/ChannelsData'
            description: The default channel data
          items:
            description: The list of individual channels
            items:
              $ref: '#/definitions/ChannelDocument'
            type: array
          links:
            description: Not used
            type: object
  Cohort:
    description: An experimental grouping for User Experience A/B Testing
    properties:
      directory:
        description: For internal use only; represents the current configuration file being used by the Listening Service
        type: string
      id:
        description: A short ID for this cohort; ignored on a PUT
        type: string
      name:
        description: 'A text string identifying the cohort, useful for metrics; ignored on a PUT'
        type: string
    required:
      - id
      - name
  CollectionDocument:
    description: Base Collection.Doc+JSON output
    properties:
      attributes:
        type: object
      errors:
        description: 'A list of encountered errors, ignored on POST, PUT'
        items:
          type: 'null'
        type: array
      href:
        description: A URL representation of the resource; should generally be ignored by clients unless noted otherwise
        type: string
      items:
        items:
          type: 'null'
        type: array
      links:
        type: object
      version:
        default: '1.0'
        description: The version of the Collection.Doc+JSON spec being used
        type: string
    required:
      - version
      - href
      - attributes
      - items
      - links
      - errors
  CompanionXml:
    properties:
      CompanionClickThrough:
        type: string
      StaticResource:
        $ref: '#/definitions/StaticResourceXml'
      TrackingEvents:
        items:
          $ref: '#/definitions/TrackingXml'
        type: array
        xml:
          wrapped: true
      height:
        format: int32
        type: integer
        xml:
          attribute: true
      id:
        format: int32
        type: integer
        xml:
          attribute: true
      width:
        format: int32
        type: integer
        xml:
          attribute: true
    type: object
    xml:
      name: Companion
  CreativeXml:
    properties:
      CompanionAds:
        items:
          $ref: '#/definitions/CompanionXml'
        type: array
        xml:
          wrapped: true
      Linear:
        $ref: '#/definitions/LinearXml'
      id:
        format: int32
        type: integer
        xml:
          attribute: true
      sequence:
        default: 1
        format: int32
        type: integer
        xml:
          attribute: true
    required:
      - sequence
    type: object
    xml:
      name: Creative
  DAASTXml:
    description: 'Please visit <a href=''http://www.iab.net/DAAST'' target=''_blank''>http://www.iab.net/DAAST</a> for more information on the DAAST XML specification.'
    properties:
      Ad:
        $ref: '#/definitions/AdXml'
      version:
        default: '1.0'
        type: string
        xml:
          attribute: true
    required:
      - version
    type: object
    xml:
      name: DAAST
  DeviceCodeData:
    properties:
      device_code:
        description: '40-character code for the device to input into the /token endpoint, not for display to the user'
        type: string
      expires_in:
        default: 1800
        description: 'The number of seconds for which this set of codes will be valid, after which they will be purged'
        format: int32
        type: integer
      interval:
        default: 5
        description: The number of seconds the client application should maintain between requests to the /token endpoint
        format: int32
        type: integer
      user_code:
        description: '6-character alphanumeric code for the user to enter at http://npr.org/device, to be displayed by the client application'
        type: string
      verification_uri:
        default: 'http://npr.org/device'
        description: 'The URL where the user should input their code, to be displayed by the client application'
        type: string
    required:
      - device_code
      - user_code
      - verification_uri
      - expires_in
      - interval
  Error:
    description: A serialized version of any error encountered when processing this request
    properties:
      code:
        description: The error code
        format: int32
        type: integer
      debug:
        description: Additional debug information if debug mode is turned on
        type: string
      text:
        description: The error description
        type: string
    required:
      - code
  ErrorDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            description: Ignore; will be empty for errors
            type: object
          errors:
            description: 'A list of encountered errors, ignored on POST, PUT'
            items:
              $ref: '#/definitions/Error'
            type: array
          items:
            description: Ignore; will be empty for errors
            items:
              type: 'null'
            type: array
          links:
            description: Ignore; will be empty for errors
            type: object
    description: A Collection.doc+JSON representation of an error result from an API call
  ErrorXmlDocument:
    description: One or more errors represented in a DAAST XML document
    properties:
      error:
        items:
          description: 'An individual error, presented in XML format'
          type: string
          xml:
            name: error
        type: array
        xml:
          wrapped: false
      version:
        default: '1.0'
        type: string
        xml:
          attribute: true
    required:
      - version
      - error
    type: object
    xml:
      name: DAAST
  Geofence:
    description: The geographic restrictions that should be applied by the client before playing this media
    properties:
      countries:
        description: The list of countries as ISO 3166-1 abbreviations in which this media should be available if restricted is true
        items:
          type: string
        type: array
      restricted:
        default: false
        description: Whether any geographic restrictions should be applied
        type: boolean
    required:
      - restricted
      - countries
  HALDocument:
    description: Base HAL output
    properties:
      _links:
        type: object
    required:
      - _links
  ImageLink:
    allOf:
      - $ref: '#/definitions/AbstractLink'
      - properties:
          content-type:
            default: image/jpeg
            description: 'The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.'
            enum:
              - image/jpeg
              - image/png
              - image/gif
            type: string
          image:
            description: A unique identifier for the image
            type: string
          producer:
            description: The producer of the image; should be used for properly attributing the image when it exists
            type: string
          provider:
            description: The provider of the image; should be used for properly attributing the image when it exists
            type: string
          rel:
            default: logo_square
            description: 'The crop type or intended display style/size; note that the enumerated list of possible values is not exhaustive and other values could occur. The list should be treated as examples, rather than absolutes.'
            enum:
              - logo_square
              - icon
              - wide
              - standard
              - square
              - enlargement
              - custom
            type: string
        required:
          - content-type
    description: 'An image, along with metadata for display'
  ImpressionXml:
    properties:
      id:
        format: int32
        type: integer
        xml:
          attribute: true
    required:
      - id
    type: string
    xml:
      name: Impression
  InLineXml:
    properties:
      AdSystem:
        type: string
      AdTitle:
        type: string
      Category:
        type: string
      Creatives:
        items:
          $ref: '#/definitions/CreativeXml'
        type: array
        xml:
          wrapped: true
      Description:
        type: string
      Extensions:
        items:
          type: string
          xml:
            name: Extension
        type: array
        xml:
          wrapped: true
      Impression:
        items:
          $ref: '#/definitions/ImpressionXml'
        type: array
        xml:
          wrapped: false
    type: object
  LinearXml:
    properties:
      Duration:
        type: string
      MediaFiles:
        items:
          $ref: '#/definitions/MediaFileXml'
        type: array
        xml:
          wrapped: true
      TrackingEvents:
        items:
          $ref: '#/definitions/TrackingXml'
        type: array
        xml:
          wrapped: true
    type: object
    xml:
      name: Linear
  MediaFileXml:
    properties:
      bitrate:
        default: 320000
        format: int32
        type: integer
        xml:
          attribute: true
      delivery:
        default: progressive
        type: string
        xml:
          attribute: true
      type:
        type: string
        xml:
          attribute: true
    type: string
    xml:
      name: MediaFile
  Organization:
    description: A station that a user has an affiliation with
    properties:
      call:
        description: Station call letters
        type: string
      city:
        description: A short description of the station's main market city
        type: string
      displayName:
        description: 'A short displayable text field for the end user, strictly text; ignored on PUT'
        type: string
      donationUrl:
        description: Station donation page URL
        type: string
      id:
        description: Some unique identifier for the organization for the user
        type: string
      logo:
        description: Station logo image url
        type: string
      notif_org:
        description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about their localized station.
        items:
          type: string
        type: array
      smallLogo:
        description: Station logo image url
        type: string
    required:
      - id
      - displayName
      - call
      - city
  OrganizationCategoryAudioListDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/CategoryData'
            description: The metadata which describes the category of audio items
          items:
            description: An array of Audio Items (recommendations)
            items:
              $ref: '#/definitions/AudioItemDocument'
            type: array
          links:
            $ref: '#/definitions/CategoryLinks'
            description: An array of links for the category.
    description: An array of a certain category of audio recommendations from a provider
  OrganizationOverviewData:
    properties:
      brand:
        $ref: '#/definitions/Brand'
        description: Metadata about the branding for this organization
      home:
        description: Flag indicating if the current view is in the user's home network
        type: boolean
      orgId:
        description: The unique identifier for the organization
        format: int64
        type: integer
      type:
        default: organization
        description: The type of list returned; will always be `organization`
        enum:
          - organization
        type: string
    required:
      - type
      - orgId
      - brand
  OrganizationOverviewDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/OrganizationOverviewData'
            description: Metadata about the organization
          items:
            description: A list of separate documents which each include their own list of audio
            items:
              $ref: '#/definitions/OrganizationCategoryAudioListDocument'
            type: array
          links:
            $ref: '#/definitions/OrganizationOverviewLinks'
            description: 'An array of links for the organization. Look here for images associated with the organization and related links for the organization (their home page, etc).'
    description: a variety of details about an organization including various lists of recent audio items
  OrganizationOverviewLinks:
    properties:
      image:
        description: One or more links to an image that can be as for branding (logo and small logo)
        items:
          $ref: '#/definitions/ImageLink'
        type: array
      related:
        description: One or more links to related web pages for the organization (their twitter feed or facebook page for example)
        items:
          $ref: '#/definitions/OtherLink'
        type: array
      web:
        description: One or more links to main page for the organization (their homepage for example)
        items:
          $ref: '#/definitions/OtherLink'
        type: array
  OtherLink:
    allOf:
      - $ref: '#/definitions/AbstractLink'
      - properties:
          content-type:
            default: application/json
            description: 'The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.'
            enum:
              - application/json
              - application/xml
              - text/html
            type: string
        required:
          - content-type
    description: An individual link from a list of links
  RatingData:
    properties:
      affiliations:
        description: An array of IDs & other data about collections or podcasts the user has ratings for; produced by the server and should be sent back as received; used for tracking program and podcast suggestions
        items:
          type: 'null'
        type: array
      channel:
        default: npr
        description: The channel this media item was pulled from
        type: string
      cohort:
        description: The primary cohort of the current logged-in user
        type: string
      duration:
        description: Number of seconds this audio piece is expected to last
        format: int32
        maximum: 9999
        minimum: 0
        type: integer
      elapsed:
        description: 'Number of seconds since the start of playback for this media item, as an integer'
        format: int32
        maximum: 9999
        minimum: 0
        type: integer
      mediaId:
        description: The media id as given by the media object
        pattern: '^\d{3,}:[\w-]{5,}$'
        type: string
      origin:
        description: How the recommendation was generated
        pattern: '^[A-Z0-9_]{2,10}$'
        type: string
      rating:
        description: String representing the rating
        pattern: '^[A-Z0-9_]{2,10}$'
        type: string
      timestamp:
        description: ISO-8601 formatted date/time; typically replaced by the client with the actual rating time
        format: date-time
        type: string
    required:
      - mediaId
      - origin
      - rating
      - elapsed
      - duration
      - timestamp
      - channel
      - cohort
  RecommendationOrganization:
    description: Data about the organization with which this media is associated
    properties:
      donateUrl:
        description: The URL of the organization's donate page
        type: string
      homepageUrl:
        description: The URL of the organization's homepage
        type: string
      logoUrl:
        description: A URL for an image of the organization's logo
        type: string
      name:
        description: The name of the organization
        type: string
    required:
      - name
  SearchItemDocument:
    description: 'A search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument'
    properties:
      ifTypeAggregation:
        $ref: '#/definitions/AggregationAudioItemListDocument'
        description: NOT A TRUE PROPERTY. This is the schema of the SearchItemDocument for `type='aggregation'`
      ifTypeAudio:
        $ref: '#/definitions/AudioItemDocument'
        description: NOT A TRUE PROPERTY. This is the schema of the SearchItemDocument for `type='audio'`
      type:
        description: 'The type of search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument'
        enum:
          - audio
          - aggregation
        type: string
    required:
      - type
  SearchListDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/SearchMetaData'
            description: The metadata for the search itself
          items:
            description: A list of aggregation or audio items (recommendations)
            items:
              $ref: '#/definitions/SearchItemDocument'
            type: array
          links:
            description: Not used
            type: object
    description: An array of aggregation or audio recommendations
  SearchMetaData:
    properties:
      query:
        description: The search terms used in the original request
        type: string
    required:
      - query
  SimpleError:
    description: 'A simple representation of an error result from an API call, rarely used; in most cases we still return a Collection.doc+JSON document for errors'
    properties:
      message:
        description: A message describing the error that occurred
        type: string
      type:
        default: error
        description: A short string representing the type of error that occurred
        type: string
    required:
      - message
      - type
  StaticResourceXml:
    properties:
      creativeType:
        default: image/jpeg
        type: string
        xml:
          attribute: true
    type: string
    xml:
      name: StaticResource
  StationBrandData:
    description: An associative array of brand-related metadata for this station
    properties:
      band:
        default: FM
        description: The subsection of the radio spectrum -- 'AM' or 'FM' -- where this station can be heard
        enum:
          - FM
          - AM
        type: string
      call:
        description: The three-to-four-letter identifying code for this station. Please use this with caution; most stations prefer to be identified by their `name` in client applications instead of `call`.
        pattern: '^(W|K)[A-Z]{2,3}$'
        type: string
      frequency:
        description: 'Where on the radio dial the station can be heard. If the `band` is AM, the frequency will be between 540 and 1600. If the `band` is FM, the frequency will be between 87.8 and 108.0.'
        pattern: '^\d{2,3}\.?\d$'
        type: string
      marketCity:
        description: The city that the station is most closely associated with. This may or may not be the city the station is licensed in and it may or may not be the city that the station or the station's antenna is located in.
        pattern: '^[A-Za-z ''\.]+$'
        type: string
      marketState:
        description: The state that the station is most closely associated with. This may or may not be the state the station is licensed in and it may or may not be the state that the station or the station's antenna is located in.
        pattern: '^[A-Z]{2}$'
        type: string
      name:
        description: 'The display name for the station. In most cases, this will be the same as `call` letters combined with band. When returning networks, it will return the network name (e.g. Minnesota Public Radio).'
        type: string
      tagline:
        default: ''
        description: A short text-logo for the station
        type: string
    required:
      - name
      - tagline
      - marketCity
      - marketState
  StationBrandLink:
    allOf:
      - $ref: '#/definitions/AbstractCDocLink'
      - properties:
          rel:
            default: homepage
            description: A short string identifier describing the way the way the link relates to the document
            enum:
              - homepage
              - logo
              - small-logo
              - hello-id-audio
              - station-message-audio
              - twitter
              - facebook
            type: string
        required:
          - rel
    description: 'A link to a web page, logo, or audio file related to the branding of the station'
  StationData:
    properties:
      brand:
        $ref: '#/definitions/StationBrandData'
        description: An associative array of brand-related metadata for this station
      eligibility:
        $ref: '#/definitions/StationEligibilityData'
        description: An associative array of eligibility-related metadata for this station
      guid:
        description: 'The system''s internal unique identifier for a station, not typically used by other APIs or consumers'
        pattern: '^[0-9a-f]{32}$'
        type: string
      network:
        $ref: '#/definitions/StationNetworkData'
        description: 'Metadata about the network, if this station is part of a network'
      newscast:
        $ref: '#/definitions/StationNewscastData'
        description: 'Metadata about the newscast for this station; this is handled internally by other microservices such as the NPR One Listening Service, so this data should typically not be used by consumers'
      orgId:
        description: 'The system''s unique ID for this station, used across NPR One Microservices and NPR''s other APIs'
        pattern: '^\d{1,4}$'
        type: string
    required:
      - orgId
      - guid
      - brand
      - eligibility
      - network
  StationDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/StationData'
            description: The metadata for the station
          items:
            description: Not used
            items:
              type: 'null'
            type: array
          links:
            $ref: '#/definitions/StationLinks'
            description: 'A list of links consisting of logos, audio files, and external URLs related to this station.'
  StationDonationLink:
    allOf:
      - $ref: '#/definitions/StationLink'
      - properties:
          typeId:
            default: '4'
            description: 'An identifier for the type of link; ''4'' denotes a generic pledge page, while ''27'' is an NPR One-specific pledge page'
            enum:
              - '4'
              - '27'
              - '28'
            type: string
        required:
          - typeId
    description: A link to a pledge page for the station
  StationEligibilityData:
    description: An associative array of eligibility-related metadata for this station
    properties:
      format:
        default: Public Radio
        description: The format of the programming on this station
        type: string
      musicOnly:
        default: false
        description: Whether or not this station only plays music
        type: boolean
      nprOne:
        default: true
        description: Whether or not this station is considered an NPR One station
        type: boolean
      status:
        default: '1'
        description: 'The status of the station within NPR''s system, not typically used by consumers'
        enum:
          - '1'
          - '9'
          - '10'
          - '12'
          - '15'
        type: string
    required:
      - nprOne
      - format
      - musicOnly
      - status
  StationLink:
    allOf:
      - $ref: '#/definitions/AbstractLink'
      - properties:
          guid:
            description: 'The system''s internal unique identifier for a link, not typically used by consumers'
            pattern: '^[0-9a-f]{32}$'
            type: string
          title:
            default: ''
            description: 'The link text, provided by the station, for the URL'
            type: string
          typeName:
            description: The semantic name corresponding to the `typeId`
            type: string
        required:
          - typeName
          - title
    description: A link related to the station
  StationLinks:
    properties:
      brand:
        description: One or more links to a web page for the station
        items:
          $ref: '#/definitions/StationBrandLink'
        type: array
      donation:
        description: One or more links to audio files related to this station
        items:
          $ref: '#/definitions/StationDonationLink'
        type: array
      podcasts:
        description: One or more links to podcasts related to this station
        items:
          $ref: '#/definitions/StationPodcastsLink'
        type: array
      related:
        description: 'One or more links to miscellaneous related content for the station; these typically are not present, and clients should generally not need to use any of these'
        items:
          $ref: '#/definitions/StationRelatedLink'
        type: array
      streams:
        description: One or more links to audio streams related to the station
        items:
          $ref: '#/definitions/StationStreamsLink'
        type: array
    required:
      - brand
  StationListDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/StationSearchMetaData'
            description: The metadata for the search itself
          items:
            description: A list of stations
            items:
              $ref: '#/definitions/StationDocument'
            type: array
          links:
            description: Not used
            type: object
    description: A collection of stations close to you or filtered by search criteria
  StationNetworkData:
    description: 'Metadata about the network, if this station is part of a network'
    properties:
      currentOrgId:
        description: The current station being viewed. Client applications should generally ignore this field.
        pattern: '^\d{1,4}$'
        type: string
      tier1:
        $ref: '#/definitions/StationNetworkTierOneData'
        description: 'The top-level organization, if this station is part of a network'
      usesInheritance:
        description: 'Whether or not the current station inherits from a parent organization, also referred to as a network'
        type: boolean
    required:
      - currentOrgId
      - usesInheritance
  StationNetworkTierOneData:
    description: 'Metadata about the top-level organization in the network, if this station is part of a network'
    properties:
      id:
        description: The unique identifier of the top-level organization in the network
        pattern: '^\d{1,4}$'
        type: string
      name:
        description: The display name for the top-level organization in the network
        type: string
      status:
        default: '10'
        description: 'The status of the top-level organization within NPR''s system, not typically used by consumers'
        enum:
          - '1'
          - '9'
          - '10'
          - '12'
          - '15'
        type: string
      tier2:
        description: One or more stations that are hierarchical children of this organization
        items:
          $ref: '#/definitions/StationNetworkTierTwoData'
        type: array
      usesInheritance:
        description: 'Whether or not this station inherits from a parent organization, also referred to as a network'
        type: boolean
    required:
      - id
      - name
      - usesInheritance
  StationNetworkTierThreeData:
    description: 'Metadata about a tier 3 organization in the network, if this station is part of a network'
    properties:
      id:
        description: The unique identifier of a tier 3 organization in the network
        pattern: '^\d{1,4}$'
        type: string
      name:
        description: The display name for a tier 3 organization in the network
        type: string
      usesInheritance:
        description: 'Whether or not this station inherits from a parent organization, also referred to as a network'
        type: boolean
    required:
      - id
      - name
      - usesInheritance
  StationNetworkTierTwoData:
    description: 'Metadata about a tier 2 organization in the network, if this station is part of a network'
    properties:
      id:
        description: The unique identifier of a tier 2 organization in the network
        pattern: '^\d{1,4}$'
        type: string
      name:
        description: The display name for a tier 2 organization in the network
        type: string
      tier3:
        description: One or more stations that are hierarchical children of this organization
        items:
          $ref: '#/definitions/StationNetworkTierThreeData'
        type: array
      usesInheritance:
        description: 'Whether or not this station inherits from a parent organization, also referred to as a network'
        type: boolean
    required:
      - id
      - name
      - usesInheritance
  StationNewscastData:
    description: 'Metadata about the newscast for this station; newscasts are handled internally by other microservices such as the NPR One Listening Service, so this data should typically not be used by consumers'
    properties:
      id:
        description: 'The ID of the newscast that should be played for this station; this is handled internally by other microservices such as the NPR One Listening Service, so this field should typically not be used by consumers'
        pattern: '^\d{1,4}$'
        type: string
      recency:
        description: 'How often the newscast should be played, in minutes; a value of `null` implies no information is available, and sensible defaults should be used'
        format: int32
        type: integer
    required:
      - id
      - recency
  StationPodcastsLink:
    allOf:
      - $ref: '#/definitions/StationLink'
      - properties:
          typeId:
            default: '9'
            description: An identifier for the type of link
            enum:
              - '9'
            type: string
        required:
          - typeId
    description: A link to an audio podcast or podcast feed related to the station
  StationRelatedLink:
    allOf:
      - $ref: '#/definitions/StationLink'
      - properties:
          typeId:
            description: An identifier for the type of link
            type: string
        required:
          - typeId
    description: 'A link to miscellaneous related content for the station; these typically are not present, and clients should generally not need to use these'
  StationSearchMetaData:
    properties:
      city:
        description: The city searched for in the original request
        type: string
      lat:
        description: The latitude parameter used in the original request
        format: float
        type: number
      lon:
        description: The longitude parameter in the original request
        format: float
        type: number
      query:
        description: The search terms used in the original request
        type: string
      state:
        description: The state searched for in the original request
        type: string
  StationStreamsLink:
    allOf:
      - $ref: '#/definitions/StationLink'
      - properties:
          isPrimaryStream:
            default: true
            description: Whether or not this stream is considered the station's primary stream
            type: boolean
          typeId:
            default: '10'
            description: An identifier for the type of stream
            enum:
              - '10'
              - '11'
              - '12'
              - '13'
            type: string
        required:
          - typeId
    description: A link to an audio stream related to the station
  TrackingXml:
    properties:
      event:
        default: start
        enum:
          - start
          - firstQuartile
          - midpoint
          - thirdQuartile
          - complete
          - creativeView
        type: string
        xml:
          attribute: true
    type: string
    xml:
      name: Tracking
  UserAdData:
    description: All information relevant to a user who has requested sponsorship or submitted tracking information
    properties:
      ipAddress:
        description: 'The TCP/IP address of the client making the request. The server will attempt to grab this from the headers, so it probably does not need to be passed in the body unless you get back an error message stating that we were unable to determine an IP address from the request.'
        type: string
      listenerId:
        description: 'A client-designated unique identifier for the logged-in user, only used if neither an NPR.org public user ID nor an `X-Advertising-ID` header are available.'
        type: string
      userAgent:
        description: 'An identifying string for the browser making the request. The server will attempt to grab this from the headers, so it probably does not need to be passed in the body unless you get back an error message stating that we were unable to determine a User-Agent from the request.'
        type: string
  UserAdDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/UserAdData'
            description: All information relevant to a user who has requested sponsorship or submitted tracking information
          items:
            description: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
            items:
              $ref: '#/definitions/AdTrackingDocument'
            type: array
    description: All information relevant to a user who has requested sponsorship or submitted tracking information
  UserData:
    description: Object; see description of a user object below
    properties:
      affiliations:
        description: Program(s) that the user has positively interacted with
        items:
          $ref: '#/definitions/Affiliation'
        type: array
      cohort:
        $ref: '#/definitions/Cohort'
        description: Experimental groupings for User Experience A/B Testing
      email:
        description: The user's email address
        type: string
      firstName:
        description: The user's first name
        type: string
      id:
        description: Some unique identifier for the user
        type: string
      lastName:
        description: The user's last name
        type: string
      organizations:
        description: User's chosen NPR Member Station(s)
        items:
          $ref: '#/definitions/Organization'
        type: array
    required:
      - id
      - cohort
      - organizations
  UserDocument:
    allOf:
      - $ref: '#/definitions/CollectionDocument'
      - properties:
          attributes:
            $ref: '#/definitions/UserData'
            description: Object; see description of a user object below
          items:
            description: 'Not used, ignored on a PUT'
            items:
              type: 'null'
            type: array
          links:
            description: 'A list of links, not used by the Identity Service; ignored on a PUT'
            type: object

[Malligarjunan]

Hello @garydgregory

The attached swagger doc has
items: description: 'Not used, ignored on a PUT' items: type: 'null' as the schema in many places, I think type cannot be 'null' hence you see the NullPointerException. Replacing 'null' with string converts the swagger 2.0 to OpenAPI.