openapi.yaml

# Copyright 2023 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

openapi: '3.0.4'
info:
  title: webstatus.dev API
  version: 0.1.0
  description: >
    A tool to monitor and track the status of all Web Platform features across
    dimensions that are related to availability and implementation quality
    across browsers, and adoption by web developers.
servers:
  - url: https://api.webstatus.dev
    description: Production
paths:
  /v1/features:
    get:
      summary: List features
      operationId: listFeatures
      parameters:
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - in: query
          name: wpt_metric_view
          schema:
            $ref: '#/components/schemas/WPTMetricView'
        - in: query
          name: q
          description: >
            A query string to represent the filters to apply the datastore while searching.
            The query must follow the ANTLR grammar. Please read the query readme at antlr/FeatureSearch.md.
            The query must be url safe.
          required: false
          schema:
            type: string
            minLength: 1
        - in: query
          name: sort
          description: >
            Field to sort by, with 'asc' for ascending and 'desc' for descending order.
            Defaults to sorting by 'name' in ascending order (e.g., 'name_asc').
          required: false
          schema:
            type: string
            enum:
              - name_asc
              - name_desc
              - baseline_status_asc
              - baseline_status_desc
              - stable_chrome_asc
              - stable_chrome_desc
              - stable_safari_asc
              - stable_safari_desc
              - stable_edge_asc
              - stable_edge_desc
              - stable_firefox_asc
              - stable_firefox_desc
              - stable_chrome_android_asc
              - stable_chrome_android_desc
              - stable_firefox_android_asc
              - stable_firefox_android_desc
              - stable_safari_ios_asc
              - stable_safari_ios_desc
              - experimental_chrome_asc
              - experimental_chrome_desc
              - experimental_safari_asc
              - experimental_safari_desc
              - experimental_edge_asc
              - experimental_edge_desc
              - experimental_firefox_asc
              - experimental_firefox_desc
              - experimental_chrome_android_asc
              - experimental_chrome_android_desc
              - experimental_firefox_android_asc
              - experimental_firefox_android_desc
              - experimental_safari_ios_asc
              - experimental_safari_ios_desc
              - chrome_usage_asc
              - chrome_usage_desc
              - developer_signal_upvotes_asc
              - developer_signal_upvotes_desc
              # availability_{browser}_{direction}
              - availability_chrome_asc
              - availability_chrome_desc
              - availability_edge_asc
              - availability_edge_desc
              - availability_firefox_asc
              - availability_firefox_desc
              - availability_safari_asc
              - availability_safari_desc
              - availability_chrome_android_asc
              - availability_chrome_android_desc
              - availability_firefox_android_asc
              - availability_firefox_android_desc
              - availability_safari_ios_asc
              - availability_safari_ios_desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturePage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
      - in: query
        name: wpt_metric_view
        schema:
          $ref: '#/components/schemas/WPTMetricView'
    get:
      summary: Get Feature
      operationId: getFeature
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '301':
          description: Moved Permanently
          headers:
            Location:
              description: The URL of the new, permanent location for the feature.
              schema:
                type: string
                format: uri
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '410':
          description: Gone (Feature is no longer available at this URI due to evolution)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureGoneError'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}/feature-metadata:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
    get:
      summary: Get metadata for a given feature from github.com/web-platform-dx/web-features
      operationId: getFeatureMetadata
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureMetadata'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}/stats/wpt/browsers/{browser}/channels/{channel}/{metric_view}:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/browserPathParam'
      - $ref: '#/components/parameters/channelPathParam'
      - $ref: '#/components/parameters/metricViewPathParam'
    get:
      summary: Retrieve the wpt stats for a particular feature.
      operationId: listFeatureWPTMetrics
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPTRunMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}/stats/usage/chrome/daily_stats:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
    get:
      summary: Get Chrome daily usage metrics for a given feature
      operationId: listChromeDailyUsageStats
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChromeDailyStatsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/features/browsers/{browser}/feature_counts:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
    get:
      summary: >
        Returns the count of features supported for a specified browser over time.
        The timestamps for the individual metrics represent the releases of the
        specified browser.
      operationId: listAggregatedFeatureSupport
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - $ref: '#/components/parameters/includeBaselineMobileBrowsersParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserReleaseFeatureMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/features/browsers/{browser}/missing_one_implementation_counts:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
    get:
      summary: >
        Returns the count of features that are supported by all of the specified
        comparison browsers but not supported by the specified target browser,
        as of each browser's (target browser or comparison browser) release
        date.
      operationId: listMissingOneImplementationCounts
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - $ref: '#/components/parameters/includeBaselineMobileBrowsersParam'
        - in: query
          name: browser
          description: >
            A list of browsers to check if {browser} is lagging behind on
            features. The list is provided by specifying repeating query parameters.
            Example: ?browser=fooBrowser&browser=bazBrowser
          required: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SupportedBrowsers'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserReleaseFeatureMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/features/browsers/{browser}/missing_one_implementation_counts/{date}/features:
    get:
      summary: >
        Returns the list of feature IDs that were counted as missing one
        implementation on a specific date for the given browser.
      operationId: listMissingOneImplementationFeatures
      parameters:
        - $ref: '#/components/parameters/browserPathParam'
        - in: path
          name: date
          schema:
            type: string
            format: date
          required: true
          description: The date for which to retrieve the feature IDs.
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - $ref: '#/components/parameters/includeBaselineMobileBrowsersParam'
        - in: query # Add otherBrowsers parameter
          name: browser
          description: >
            A list of browsers to check if {browser} is lagging behind on
            features. The list is provided by specifying repeating query parameters.
            Example:?browser=fooBrowser&browser=bazBrowser
          required: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SupportedBrowsers'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingOneImplFeaturesPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/wpt/browsers/{browser}/channels/{channel}/{metric_view}:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
      - $ref: '#/components/parameters/channelPathParam'
      - $ref: '#/components/parameters/metricViewPathParam'
    get:
      summary: >
        Gets aggregated WPT test counts for a specified browser and channel. Optionally filter by feature IDs.
      operationId: listAggregatedWPTMetrics
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - in: query
          # TODO: Create a feature_id version of this parameter
          name: featureId
          description: >
            A list of feature IDs to filter results. TThe list is provided by
            specifying repeating query parameters.
            Example: ?featureId=id1&featureId=id2
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPTRunMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/baseline_status/low_date_feature_counts:
    get:
      summary: >
        Returns the count of features supported that have reached baseline
        according to the specified date type (currently only low_date).
      operationId: listAggregatedBaselineStatusCounts
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaselineStatusMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/ping:
    post:
      summary: Signal user login and refresh profile
      description: |
        Signals to the backend that a user has just authenticated.
        This allows the backend to perform tasks like creating or updating the user's profile
        with the latest information from the identity provider (e.g., refreshing their email address).

        This endpoint should be called by clients once, immediately after a successful login.
      operationId: pingUser
      security:
        - bearerAuth: []
      requestBody:
        description: Optional payload containing transient third-party tokens for profile syncing.
        # Only required because our code generator currently needs a valid JSON object.
        # https://github.com/oapi-codegen/oapi-codegen/issues/1584
        # It can be an empty object.
        # Once that bug is solved, we can set this back to false.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                github_token:
                  type: string
                  description: >
                    The GitHub OAuth access token obtained by the frontend during interactive sign-in.
                    Used by the backend to perform a one-time sync of user profile data (like email)
                    directly from GitHub. This token is not stored by the backend.
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/notification-channels:
    get:
      summary: List user notification channels
      operationId: listNotificationChannels
      parameters:
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    post:
      summary: Create a new notification channel
      operationId: createNotificationChannel
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotificationChannelRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          description: Bad Request (e.g., invalid URL, type/config mismatch)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden (e.g., reached maximum number of channels)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit (e.g., too many channels)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/notification-channels/{channel_id}:
    parameters:
      - name: channel_id
        in: path
        description: Notification Channel ID
        required: true
        schema:
          type: string
    get:
      summary: Get notification channel by ID
      operationId: getNotificationChannel
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found (channel does not exist or user does not own it)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    patch:
      summary: Update notification channel
      operationId: updateNotificationChannel
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationChannelRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found (channel does not exist or user does not own it)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    delete:
      summary: Delete notification channel
      operationId: deleteNotificationChannel
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No Content (successful deletion)
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found (channel does not exist or user does not own it)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/saved-searches:
    get:
      summary: List user saved searches
      operationId: listUserSavedSearches
      parameters:
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSavedSearchPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/saved-searches/{search_id}/bookmark_status:
    parameters:
      - name: search_id
        in: path
        description: Saved Search ID
        required: true
        schema:
          type: string
    put:
      summary: Add bookmark status for a particular saved search.
      operationId: putUserSavedSearchBookmark
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found (saved search does not exist)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    delete:
      summary: Remove bookmark status for a particular saved search.
      operationId: removeUserSavedSearchBookmark
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found (saved search does not exist)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/saved-searches:
    post:
      summary: Create a saved search
      operationId: createSavedSearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearch'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearchResponse'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/saved-searches/{search_id}:
    parameters:
      - name: search_id
        in: path
        description: Saved Search ID
        required: true
        schema:
          type: string
    get:
      summary: Get saved search
      operationId: getSavedSearch
      security:
        - bearerAuth: []
        # User can opt out of providing a bearer token.
        # They just won't get bookmark and role information.
        - noAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearchResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    patch:
      operationId: updateSavedSearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearchResponse'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    delete:
      operationId: removeSavedSearch
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No Content (successful deletion)
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found (saved search does not exist)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/subscriptions:
    description: Operations for managing user subscriptions to saved searches.
    # POST operation to create a new subscription
    post:
      summary: Create a subscription for a saved search
      operationId: createSubscription
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    # GET operation to list user's subscriptions
    get:
      summary: List subscriptions for a saved search
      operationId: listSubscriptions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/users/me/subscriptions/{subscription_id}:
    description: Operations for managing a specific user subscription.
    parameters:
      - name: subscription_id
        in: path
        description: Subscription ID
        required: true
        schema:
          type: string
    # GET operation to retrieve a specific subscription
    get:
      summary: Get a subscription for a saved search
      operationId: getSubscription
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    # PATCH operation to update a specific subscription
    patch:
      summary: Update a subscription for a saved search
      operationId: updateSubscription
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
    # DELETE operation to delete a specific subscription
    delete:
      summary: Delete a subscription for a saved search
      operationId: deleteSubscription
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/subscriptions/{subscription_id}/rss:
    description: Public RSS feed for a specific subscription.
    parameters:
      - name: subscription_id
        in: path
        description: Subscription ID
        required: true
        schema:
          type: string
    get:
      summary: Get RSS feed for a subscription
      operationId: getSubscriptionRSS
      parameters:
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      security:
        - noAuth: []
      responses:
        '200':
          description: OK
          content:
            application/rss+xml:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
components:
  parameters:
    browserPathParam:
      in: path
      name: browser
      description: Browser name
      required: true
      schema:
        $ref: '#/components/schemas/SupportedBrowsers'
    channelPathParam:
      in: path
      name: channel
      description: Browser name
      required: true
      schema:
        type: string
        # List of supported channels that webstatus.dev currently ingests
        enum:
          - stable
          - experimental
    metricViewPathParam:
      in: path
      name: metric_view
      description: Specified metric view of the WPT data.
      required: true
      schema:
        $ref: '#/components/schemas/WPTMetricView'
    # TODO: Create a start_at version of this parameter
    startAtParam:
      in: query
      name: startAt
      schema:
        type: string
        format: date
      description: Start date (RFC 3339, section 5.6, for example, 2017-07-21). The date is inclusive.
      required: true
    # TODO: Create a end_at version of this parameter
    endAtParam:
      in: query
      name: endAt
      schema:
        type: string
        format: date
      description: End date (RFC 3339, section 5.6, for example, 2017-07-21). The date is exclusive.
      required: true
    paginationTokenParam:
      in: query
      name: page_token
      schema:
        type: string
      description: Pagination token
      required: false
    paginationSizeParam:
      in: query
      name: page_size
      schema:
        type: integer
        maximum: 100
        minimum: 1
        default: 1
      required: false
      description: Number of results to return
    includeBaselineMobileBrowsersParam:
      in: query
      name: include_baseline_mobile_browsers
      schema:
        type: boolean
      description: >
        Include baseline mobile browsers in the response. This is only applicable
        for desktop browsers with a corresponding mobile browser.
      required: false
  schemas:
    SupportedBrowsers:
      type: string
      description: List of supported browsers that webstatus.dev currently ingests
      enum:
        - chrome
        - firefox
        - safari
        - edge
        - chrome_android
        - firefox_android
        - safari_ios
    WPTMetricView:
      type: string
      description: The desired view of the WPT Data
      enum:
        - test_counts
        - subtest_counts
    BrowserReleaseFeatureMetric:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: >
            The timestamp that correlates to an event that may influence the
            count of features for a browser. This may be the release of the
            browser itself (when a browser may support a new set of features),
            or the release of another browser (when another browser supports
            a feature but our specified browser is now lagging behind with a new
            feature). Refer to the individual endpoint for more context on the
            use of this component.
        count:
          type: integer
          description: Total count of features.
          format: int64
      required:
        # For now, only require timestamp in case the definition
        # of the metric needs to change. Similar to WPTRunMetric.
        - timestamp
    BrowserReleaseFeatureMetricsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BrowserReleaseFeatureMetric'
      required:
        - data
    BaselineStatusMetric:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        count:
          type: integer
          description: Total count of features.
          format: int64
      required:
        # For now, only require timestamp in case the definition
        # of the metric needs to change. Similar to WPTRunMetric.
        - timestamp
    BaselineStatusMetricsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BaselineStatusMetric'
      required:
        - data
    WPTRunMetric:
      type: object
      properties:
        run_timestamp:
          type: string
          format: date-time
          description: The start timestamp of the run.
        total_tests_count:
          type: integer
          description: Total number of tests
          format: int64
        test_pass_count:
          type: integer
          description: Number of passing tests
          format: int64
      required:
        - run_timestamp
    ChromeUsageStat:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: The usage timestamp
        usage:
          type: number
          description: >
            Snapshot of the usage metric for the given feature
          format: double
          minimum: 0.0
          maximum: 100.0
      required:
        - timestamp
    WPTRunMetricsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/WPTRunMetric'
      required:
        - data
    ChromeDailyStatsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChromeUsageStat'
      required:
        - data
    WPTFeatureData:
      type: object
      properties:
        score:
          type: number
          format: double
        metadata:
          type: object
          description: >
            Contains optional metadata about the metric. This key-value pair is to be considered unstable and can change
            at any moment. If a field here becomes mature, we can add it to the main WPTFeatureData definition.
          additionalProperties: true
    BrowserImplementation:
      type: object
      properties:
        status:
          type: string
          enum:
            - unavailable
            - available
          # Go enum names
          x-enum-varnames:
            - Unavailable
            - Available
        date:
          type: string
          format: date
          description: The date on which the feature was implemented in a browser. (RFC 3339, section 5.6, for example, 2017-07-21)
        version:
          type: string
          description: The browser version in which the feature became available.
    PageMetadata:
      type: object
      properties:
        next_page_token:
          type: string
    PageMetadataWithTotal:
      type: object
      properties:
        next_page_token:
          type: string
        total:
          type: integer
          format: int64 # Currently, 'count(*)' from spanner comes as int64 https://cloud.google.com/spanner/docs/reference/standard-sql/data-types
      required:
        - total
    FeatureDeveloperSignals:
      type: object
      properties:
        upvotes:
          type: integer
          description: Count of positive feedback for a feature
          format: int64 # To match the value type from Spanner as it only supports int64.
        link:
          type: string
          description: Link to the issue tracking developer signal for a feature.
    FeatureDiscouragedInfo:
      type: object
      properties:
        according_to:
          type: array
          items:
            $ref: '#/components/schemas/FeatureDiscouragedAccordingTo'
        alternatives:
          type: array
          items:
            $ref: '#/components/schemas/FeatureDiscouragedAlternative'
    FeatureDiscouragedAccordingTo:
      type: object
      properties:
        link:
          type: string
      required:
        - link
    FeatureDiscouragedAlternative:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    FeaturePage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadataWithTotal'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
      required:
        - data
        - metadata
    FeatureWPTSnapshots:
      type: object
      properties:
        stable:
          type: object
          description: >
            Contains snapshot of the stable WPT data. The keys for the
            object comes from the different cases in
            https://github.com/web-platform-tests/wpt.fyi/blob/fb5bae7c6d04563864ef1c28a263a0a8d6637c4e/shared/product_spec.go#L71-L104
          additionalProperties:
            $ref: '#/components/schemas/WPTFeatureData'
        experimental:
          type: object
          description: >
            Contains snapshot of the experimental WPT data. The keys for the
            object comes from the different cases in
            https://github.com/web-platform-tests/wpt.fyi/blob/fb5bae7c6d04563864ef1c28a263a0a8d6637c4e/shared/product_spec.go#L71-L104
          additionalProperties:
            $ref: '#/components/schemas/WPTFeatureData'
    BaselineInfo:
      type: object
      description: Contains baseline information for a feature.
      properties:
        status:
          type: string
          enum:
            - limited
            - newly
            - widely
        low_date:
          type: string
          format: date
        high_date:
          type: string
          format: date
    FeatureSpecInfo:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/SpecLink'
    SpecLink:
      type: object
      properties:
        link:
          type: string
    FeatureMetadata:
      type: object
      properties:
        can_i_use:
          $ref: '#/components/schemas/CanIUseInfo'
        description:
          type: string
    CanIUseInfo:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CanIUseItem'
    CanIUseItem:
      properties:
        id:
          type: string
    GenericUpdatableUniqueModel:
      type: object
      properties:
        id:
          type: string
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - created_at
        - updated_at
    SavedSearch:
      type: object
      description: |
        Represents a saved search with a name and a query.
        Both `name` and `query` are required when creating a new saved search.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 32
        description:
          type: string
          minLength: 1
          maxLength: 1024
        query:
          type: string
          minLength: 1
          maxLength: 256
      required:
        - name
        - query
    SavedSearchUpdateRequest:
      type: object
      description: |
        Represents the data required to update a saved search.
        Only the fields that need to be modified need to be included in the request.
        To clear a field, include the field in `update_mask` and set the corresponding value to null.
        Only fields with nullable set to true can be cleared.
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
          nullable: true
          minLength: 1
        query:
          type: string
          minLength: 1
        update_mask:
          type: array
          description: >
            A list of fields to update. Required. Allowed values are: `name`, `description`, `query`.
          items:
            type: string
            enum:
              - name
              - description
              - query
            # Custom field used by https://github.com/oapi-codegen/oapi-codegen
            # Otherwise, the constant name will be Name, Description and Query
            x-enumNames:
              - SavedSearchUpdateRequestMaskName
              - SavedSearchUpdateRequestMaskDescription
              - SavedSearchUpdateRequestMaskQuery
          minItems: 1
          uniqueItems: true
      required:
        - update_mask
    UserSavedSearchBookmarkStatus:
      type: string
      description: |
        The bookmark status for a saved search for a user.
      enum:
        - bookmark_none
        - bookmark_active
    UserSavedSearchBookmark:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/UserSavedSearchBookmarkStatus'
      required:
        - status
    SavedSearchResponse:
      allOf:
        - $ref: '#/components/schemas/GenericUpdatableUniqueModel'
        - $ref: '#/components/schemas/SavedSearch'
        - type: object
          properties:
            permissions:
              $ref: '#/components/schemas/UserSavedSearchPermissions'
            bookmark_status:
              $ref: '#/components/schemas/UserSavedSearchBookmark'
    UserSavedSearchRole:
      type: string
      enum:
        - saved_search_owner
    UserSavedSearchPermissions:
      type: object
      properties:
        role:
          $ref: '#/components/schemas/UserSavedSearchRole'
    WebhookConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - webhook
        url:
          type: string
          format: uri
          description: The webhook URL. Currently, only Slack URLs are supported.
      required:
        - type
        - url
    EmailConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - email
        address:
          type: string
          format: email
          description: The email address.
      required:
        - type
        - address
    RSSConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - rss
      required:
        - type
    CreateNotificationChannelRequest:
      type: object
      required:
        - name
        - config
      properties:
        name:
          type: string
          description: A user-defined name for the channel.
        config:
          description: Configuration specific to the channel type.
          oneOf:
            - $ref: '#/components/schemas/WebhookConfig'
            - $ref: '#/components/schemas/RSSConfig'
          discriminator:
            propertyName: type
            mapping:
              webhook: '#/components/schemas/WebhookConfig'
              rss: '#/components/schemas/RSSConfig'
    NotificationChannel:
      type: object
      properties:
        type:
          type: string
          enum:
            - email
            - webhook
            - rss
        name:
          type: string
          description: The name of the channel.
        config:
          description: Configuration specific to the channel type.
          oneOf:
            - $ref: '#/components/schemas/EmailConfig'
            - $ref: '#/components/schemas/WebhookConfig'
            - $ref: '#/components/schemas/RSSConfig'
          discriminator:
            propertyName: type
            mapping:
              email: '#/components/schemas/EmailConfig'
              webhook: '#/components/schemas/WebhookConfig'
              rss: '#/components/schemas/RSSConfig'
      required:
        - type
        - name
        - config
    NotificationChannelResponse:
      allOf:
        - $ref: '#/components/schemas/GenericUpdatableUniqueModel'
        - $ref: '#/components/schemas/NotificationChannel'
        - type: object
          properties:
            status:
              type: string
              enum:
                - enabled
                - disabled
              x-enumNames:
                - NotificationChannelStatusEnabled
                - NotificationChannelStatusDisabled
          required:
            - status
    NotificationChannelPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/NotificationChannelResponse'
    UpdateNotificationChannelRequest:
      type: object
      properties:
        name:
          type: string
        config:
          description: Configuration specific to the channel type.
          oneOf:
            - $ref: '#/components/schemas/WebhookConfig'
            - $ref: '#/components/schemas/RSSConfig'
          discriminator:
            propertyName: type
            mapping:
              webhook: '#/components/schemas/WebhookConfig'
              rss: '#/components/schemas/RSSConfig'
        update_mask:
          type: array
          description: >
            A list of fields to update. Required. Allowed values are: `name`, `config`.
          items:
            type: string
            enum:
              - name
              - config
            x-enumNames:
              - UpdateNotificationChannelRequestMaskName
              - UpdateNotificationChannelRequestMaskConfig
          minItems: 1
          uniqueItems: true
      required:
        - update_mask
    EnumUnknown:
      type: string
      description: Represents an unknown, unsupported, or deprecated enum value.
      enum:
        - unknown
      x-enumNames:
        - EnumUnknownValue
    SubscriptionFrequency:
      type: string
      description: The frequency for a subscription.
      enum:
        - immediate
        - weekly
        - monthly
      x-enumNames:
        - SubscriptionFrequencyImmediate
        - SubscriptionFrequencyWeekly
        - SubscriptionFrequencyMonthly
    SubscriptionTriggerWritable:
      type: string
      description: The set of valid, user-selectable triggers for a subscription.
      enum:
        - feature_baseline_to_newly
        - feature_baseline_to_widely
        - feature_browser_implementation_any_complete
        - feature_baseline_regression_to_limited
      x-enumNames:
        - SubscriptionTriggerFeatureBaselineToNewly
        - SubscriptionTriggerFeatureBaselineToWidely
        - SubscriptionTriggerFeatureBrowserImplementationAnyComplete
        - SubscriptionTriggerFeatureBaselineRegressionToLimited
    SubscriptionTriggerResponseValue:
      description: >
        Represents a subscription trigger value. Includes 'unknown' for handling deprecated triggers.
      oneOf:
        - $ref: '#/components/schemas/SubscriptionTriggerWritable'
        - $ref: '#/components/schemas/EnumUnknown'
    SubscriptionTriggerResponseItem:
      type: object
      description: Represents a single trigger in a subscription response, indicating its status.
      properties:
        value:
          $ref: '#/components/schemas/SubscriptionTriggerResponseValue'
        raw_value:
          type: string
          description: >
            The original, raw value from the database. Only present if the 'value'
            is 'unknown', allowing clients to identify and manage deprecated triggers.
      required:
        - value
    Subscription:
      type: object
      properties:
        saved_search_id:
          type: string
        channel_id:
          type: string
        frequency:
          $ref: '#/components/schemas/SubscriptionFrequency'
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionTriggerWritable'
      required:
        - saved_search_id
        - channel_id
        - frequency
        - triggers
    SavedSearchInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name

    SubscriptionResponse:
      allOf:
        - $ref: '#/components/schemas/GenericUpdatableUniqueModel'
        - type: object
          properties:
            # We're calling this 'subscribable' to be generic for the future,
            # even though it will only contain SavedSearchInfo for now.
            subscribable:
              $ref: '#/components/schemas/SavedSearchInfo'
            channel_id:
              type: string
            frequency:
              $ref: '#/components/schemas/SubscriptionFrequency'
            triggers:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionTriggerResponseItem'
          required:
            - triggers
            - frequency
            - subscribable
            - channel_id
    SubscriptionPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
    UpdateSubscriptionRequest:
      type: object
      properties:
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionTriggerWritable'
        frequency:
          $ref: '#/components/schemas/SubscriptionFrequency'
        update_mask:
          type: array
          description: >
            A list of fields to update. Required. Allowed values are: `triggers`, `frequency`.
          items:
            type: string
            enum:
              - triggers
              - frequency
            x-enumNames:
              - UpdateSubscriptionRequestMaskTriggers
              - UpdateSubscriptionRequestMaskFrequency
          minItems: 1
          uniqueItems: true
      required:
        - update_mask
    UserSavedSearchPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/SavedSearchResponse'
    VendorPosition:
      type: object
      description: >
        A loosely defined object representing a single vendor's standards position.
        The schema is intentionally open-ended (`additionalProperties: true`) to
        accommodate the evolving structure of the upstream web-features-mappings data source.
      additionalProperties: true
    Feature:
      type: object
      properties:
        feature_id:
          type: string
        system_managed_saved_search_id:
          type: string
          nullable: true
          readOnly: true
          description: The ID of the system-managed saved search for this feature.
        name:
          type: string
          description: >
            Short name that is intended to be human friendly.
            Comes from FeatureData's 'name' field in
            https://github.com/web-platform-dx/web-features/blob/main/schemas/data.schema.json
        spec:
          $ref: '#/components/schemas/FeatureSpecInfo'
        browser_implementations:
          type: object
          description: >
            Describes the implementation status of the feature. The keys for the object come
            from https://github.com/web-platform-dx/web-features/blob/f630e000a15eaff23f41d6b8c4a44cca64a4a7e4/schemas/data.schema.json#L261-L289
          additionalProperties:
            $ref: '#/components/schemas/BrowserImplementation'
        baseline:
          $ref: '#/components/schemas/BaselineInfo'
        usage:
          $ref: '#/components/schemas/BrowserUsage'
        wpt:
          $ref: '#/components/schemas/FeatureWPTSnapshots'
        developer_signals:
          description: >
            The absence of this object means the feature does not have an active issue
            in https://github.com/web-platform-dx/developer-signals.
          $ref: '#/components/schemas/FeatureDeveloperSignals'
        discouraged:
          $ref: '#/components/schemas/FeatureDiscouragedInfo'
        vendor_positions:
          type: array
          description: >
            Contains standards positions from various vendors.
          items:
            $ref: '#/components/schemas/VendorPosition'
      required:
        - feature_id
        - name
        - baseline_status
    FeatureSplitInfo:
      type: object
      properties:
        id:
          type: string
          description: The ID of a feature that resulted from a split.
      required:
        - id
    FeatureEvolutionSplit:
      type: object
      description: >
        Details if this feature's scope has been narrowed and parts
        of it have been spun off into new, distinct features.
      properties:
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureSplitInfo'
      required:
        - features
    FeatureGoneError:
      description: |
        Represents various reasons a feature might be gone due to evolution.
        Clients should check the 'type' field to determine the specific error structure.
      $ref: '#/components/schemas/FeatureGoneSplit'
      # Cannot use oneOf until this bug is fixed
      # https://github.com/oapi-codegen/oapi-codegen/issues/970
      # oneOf:
      #   - $ref: '#/components/schemas/FeatureGoneSplit'
      # discriminator:
      #   propertyName: type
      #   mapping:
      #     split: '#/components/schemas/FeatureGoneSplit'
    FeatureGoneSplit:
      allOf:
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          properties:
            type:
              type: string
              enum:
                - split
              description: Indicates the feature was removed due to a split.
            new_features:
              type: array
              description: >
                A list of feature IDs that have completely replaced the original,
                now-gone feature, as a result of a full split.
              items:
                $ref: '#/components/schemas/FeatureSplitInfo'
          required:
            - type
            - new_features
    BrowserUsage:
      type: object
      properties:
        chrome:
          $ref: '#/components/schemas/ChromeUsageInfo'
    ChromeUsageInfo:
      type: object
      properties:
        daily:
          type: number
          format: double
          description: >
            Latest snapshot of the usage metric for the given feature.
          minimum: 0.0
          maximum: 100.0
    BasicErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf: # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          required:
            - errors
          properties:
            errors:
              type: object
              additionalProperties:
                type: string
    MissingOneImplFeature: # Schema for a single feature object
      type: object
      properties:
        feature_id:
          type: string
          description: The ID of a feature.
    MissingOneImplFeaturesPage: # Schema for the paginated response
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/MissingOneImplFeature'
      required:
        - data
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT