CPUB-274 DVP Data API doc improvements (#15366)

* CPUB-274 DVP Data API doc improvements

* Update docker-hub/api/dvp.yaml

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* Update docker-hub/api/dvp.yaml

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* Update docker-hub/api/dvp.yaml

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* Update docker-hub/api/dvp.yaml

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>

* Update docker-hub/api/dvp.yaml

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* Update docker-hub/api/dvp.yaml

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* Update docker-hub/api/dvp.yaml

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
Co-authored-by: jerae-duffin <83294991+jerae-duffin@users.noreply.github.com>

docker-hub/api/dvp.yaml

@@ -6,7 +6,36 @@ info:
     url: https://docs.docker.com/images/logo-docker-main.png
     href: /reference
   description: |
-     The Docker DVP Data API allows [Docker Verified Publishers](https://docs.docker.com/docker-hub/publish/) to view image pull analytics data for their namespaces
+     The Docker DVP Data API allows [Docker Verified Publishers](https://docs.docker.com/docker-hub/publish/) to view image pull analytics data for their namespaces. Analytics data can be retrieved as raw data, or in a summary format.
+       
+     #### Summary data
+
+     In your summary data CSV, you will have access to the data points listed below. You can request summary data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). 
+
+     - For every namespace, repository, and reference (tag or digest):
+       - Unique IP address count
+       - Pulls by tag count
+       - Pulls by digest count
+       - Version check count
+
+     #### Raw data
+
+     In your raw data CSV you will have access to the data points listed below. You can request raw data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). **Note:** each action is represented as a single row.
+
+     - Type (industry)
+     - Host (cloud provider)
+     - Country (geolocation)
+     - Timestamp
+     - Namespace
+     - Repository
+     - Reference (digest is always included, tag is provided when available)
+     - HTTP request method
+     - Action, one of the following:
+       - Pull by tag
+       - Pull by digest
+       - Version check
+     - User-Agent
+
 servers:
   - url: https://hub.docker.com/api/dvp/v1
 security:
@@ -16,10 +45,14 @@ features.openapi:
   schemaDefinitionsTagName: Schemas
 
 tags:
+  - name: authentication
+    x-displayName: Authentication Endpoints
   - name: namespaces
     x-displayName: Namespace data
   - name: repos
     x-displayName: Repository data
+    description: |
+      Repository data is only available for specific additional repositories.
   - name: discovery
     x-displayName: Discovery
   - name: responseDataFile
@@ -42,6 +75,7 @@ tags:
 x-tagGroups:
   - name: API
     tags:
+      - authentication
       - discovery
       - namespaces
       - repos
@@ -53,6 +87,84 @@ x-tagGroups:
       - weekModel
 
 paths:
+  /v2/users/login:
+    security: []
+    servers:
+      - url: https://hub.docker.com
+    post:
+      security: []
+      tags:
+        - authentication
+      summary: Create an authentication token
+      operationId: PostUsersLogin
+      description: |
+        Creates and returns a bearer token in JWT format that you can use to
+        authenticate with Docker Hub APIs.
+
+        The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
+
+        Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UsersLoginRequest"
+        description: Login details.
+        required: true
+      responses:
+        200:
+          description: Authentication successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PostUsersLoginSuccessResponse"
+        401:
+          description: Authentication failed or second factor required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PostUsersLoginErrorResponse"
+  /v2/users/2fa-login:
+    security: []
+    servers:
+      - url: https://hub.docker.com
+    post:
+      security: []
+      tags:
+        - authentication
+      summary: Second factor authentication.
+      operationId: PostUsers2FALogin
+      description: |
+        When a user has 2FA enabled, this is the second call to perform after
+        `/v2/users/login` call.
+
+        Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.
+
+        The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
+
+        Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Users2FALoginRequest"
+        description: Login details.
+        required: true
+      responses:
+        200:
+          description: Authentication successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PostUsersLoginSuccessResponse"
+        401:
+          description: Authentication failed or second factor required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PostUsers2FALoginErrorResponse"
+
+
   /data:
     get:
       tags: [discovery]
@@ -106,64 +218,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/YearData'
-  /data/namespaces/{namespace}/years/{year}/months:
+  /data/namespaces/{namespace}/years/{year}/{timespantype}:
     get:
       tags: [namespaces]
-      summary: Get months with data
+      summary: Get timespans with data
-      description: Gets a list of months that have data for the given namespace and year
+      description: Gets a list of timespans of the given type that have data for the given namespace and year
-      operationId: getNamespaceMonths
+      operationId: getNamespaceTimespans
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MonthData'
-  /data/namespaces/{namespace}/years/{year}/weeks:
-    get:
-      tags: [namespaces]
-      summary: Get weeks with data
-      description: Gets a list of weeks that have data for the given namespace and year
-      operationId: getNamespaceWeeks
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/WeekData'
-  /data/namespaces/{namespace}/years/{year}/months/{month}:
-    get:
-      tags: [namespaces]
-      summary: Get namespace metadata for month
-      description: Gets info about data for the given namespace and month
-      operationId: getNamespaceMonthMetadata
       parameters:
         - in: path
           name: namespace
@@ -178,26 +238,64 @@ paths:
           required: true
           description: Year to fetch data for
         - in: path
-          name: month
+          name: timespantype
           schema:
-            type: integer
+            $ref: '#/components/schemas/TimespanType'
           required: true
-          description: Month to fetch data for
+          description: Type of timespan to fetch data for
       responses:
         '200':
           description: Success
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MonthModel'
+                $ref: '#/components/schemas/TimespanData'
+  /data/namespaces/{namespace}/years/{year}/{timespantype}/{timespan}:
+    get:
+      tags: [namespaces]
+      summary: Get namespace metadata for timespan
+      description: Gets info about data for the given namespace and timespan
+      operationId: getNamespaceTimespanMetadata
+      parameters:
+        - in: path
+          name: namespace
+          schema:
+            type: string
+          required: true
+          description: Namespace to fetch data for
+        - in: path
+          name: year
+          schema:
+            type: integer
+          required: true
+          description: Year to fetch data for
+        - in: path
+          name: timespantype
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: true
+          description: Type of timespan to fetch data for
+        - in: path
+          name: timespan
+          schema:
+            type: integer
+          required: true
+          description: Timespan to fetch data for
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TimespanModel'
         '404':
           description: Not Found
-  /data/namespaces/{namespace}/years/{year}/months/{month}/raw:
+  /data/namespaces/{namespace}/years/{year}/{timespantype}/{timespan}/raw:
     get:
       tags: [namespaces]
-      summary: Get namespace data for month
+      summary: Get namespace data for timespan
-      description: Gets a list of URLs that can be used to download the raw pull data for the given namespace and month
+      description: Gets a list of URLs that can be used to download the raw pull data for the given namespace and timespan
-      operationId: getNamespaceDataByMonth
+      operationId: getNamespaceDataByTimespan
       parameters:
         - in: path
           name: namespace
@@ -212,11 +310,17 @@ paths:
           required: true
           description: Year to fetch data for
         - in: path
-          name: month
+          name: timespantype
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: true
+          description: Type of timespan to fetch data for
+        - in: path
+          name: timespan
           schema:
             type: integer
           required: true
-          description: Month to fetch data for
+          description: Timespan to fetch data for
       responses:
         '200':
           description: Success
@@ -224,12 +328,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ResponseData'
-  /data/namespaces/{namespace}/years/{year}/weeks/{week}:
+  /data/namespaces/{namespace}/years/{year}/{timespantype}/{timespan}/summary:
     get:
       tags: [namespaces]
-      summary: Get namespace metadata for week
+      summary: Get namespace summary data for timespan
-      description: Gets info about data for the given namespace and week
+      description: Gets a list of URLs that can be used to download the summary pull data for the given namespace and timespan
-      operationId: getNamespaceWeekMetadata
+      operationId: getNamespaceSummaryByTimespan
       parameters:
         - in: path
           name: namespace
@@ -244,109 +348,17 @@ paths:
           required: true
           description: Year to fetch data for
         - in: path
-          name: week
+          name: timespantype
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: true
+          description: Type of timespan to fetch data for
+        - in: path
+          name: timespan
           schema:
             type: integer
           required: true
-          description: Week to fetch data for
+          description: Timespan to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/WeekModel'
-        '404':
-          description: Not Found
-  /data/namespaces/{namespace}/years/{year}/weeks/{week}/raw:
-    get:
-      tags: [namespaces]
-      summary: Get namespace data for week
-      description: Gets a list of URLs that can be used to download the raw pull data for the given namespace and week
-      operationId: getNamespaceDataByWeek
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-        - in: path
-          name: week
-          schema:
-            type: integer
-          required: true
-          description: Week to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ResponseData'
-  /data/namespaces/{namespace}/years/{year}/months/{month}/summary:
-    get:
-      tags: [namespaces]
-      summary: Get namespace summary data for month
-      description: Gets a list of URLs that can be used to download the summary pull data for the given namespace and month
-      operationId: getNamespaceSummaryByMonth
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-        - in: path
-          name: month
-          schema:
-            type: integer
-          required: true
-          description: Month to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ResponseData'
-  /data/namespaces/{namespace}/years/{year}/weeks/{week}/summary:
-    get:
-      tags: [namespaces]
-      summary: Get namespace summary data for week
-      description: Gets a list of URLs that can be used to download the summary pull data for the given namespace and week
-      operationId: getNamespaceSummaryByWeek
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-        - in: path
-          name: week
-          schema:
-            type: integer
-          required: true
-          description: Week to fetch data for
       responses:
         '200':
           description: Success
@@ -380,76 +392,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/YearData'
-  /data/repos/{namespace}/{repo}/years/{year}/months:
+  /data/repos/{namespace}/{repo}/years/{year}/{timespantype}:
     get:
       tags: [repos]
-      summary: Get months with data
+      summary: Get timespans with data
-      description: Gets a list of months that have data for the given repository and year
+      description: Gets a list of timespans of the given type that have data for the given repository and year
-      operationId: getRepoMonths
+      operationId: getRepoTimespans
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: repo
-          schema:
-            type: string
-          required: true
-          description: Repo to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MonthData'
-  /data/repos/{namespace}/{repo}/years/{year}/weeks:
-    get:
-      tags: [repos]
-      summary: Get weeks with data
-      description: Gets a list of weeks that have data for the given repository and year
-      operationId: getRepoWeeks
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: repo
-          schema:
-            type: string
-          required: true
-          description: Repo to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/WeekData'
-  /data/repos/{namespace}/{repo}/years/{year}/months/{month}:
-    get:
-      tags: [repos]
-      summary: Get repository metadata for month
-      description: Gets info about data for the given repository and month
-      operationId: getRepoMonthMetadata
       parameters:
         - in: path
           name: namespace
@@ -470,26 +418,70 @@ paths:
           required: true
           description: Year to fetch data for
         - in: path
-          name: month
+          name: timespantype
           schema:
-            type: integer
+            $ref: '#/components/schemas/TimespanType'
           required: true
-          description: Month to fetch data for
+          description: Type of timespan to fetch data for
       responses:
         '200':
           description: Success
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MonthModel'
+                $ref: '#/components/schemas/TimespanData'
+  /data/repos/{namespace}/{repo}/years/{year}/{timespantype}/{timespan}:
+    get:
+      tags: [repos]
+      summary: Get repository metadata for timespan
+      description: Gets info about data for the given repository and timespan
+      operationId: getRepoTimespanMetadata
+      parameters:
+        - in: path
+          name: namespace
+          schema:
+            type: string
+          required: true
+          description: Namespace to fetch data for
+        - in: path
+          name: repo
+          schema:
+            type: string
+          required: true
+          description: Repo to fetch data for
+        - in: path
+          name: year
+          schema:
+            type: integer
+          required: true
+          description: Year to fetch data for
+        - in: path
+          name: timespantype
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: true
+          description: Type of timespan to fetch data for
+        - in: path
+          name: timespan
+          schema:
+            type: integer
+          required: true
+          description: Timespan to fetch data for
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TimespanModel'
         '404':
           description: Not Found
-  /data/repos/{namespace}/{repo}/years/{year}/months/{month}/raw:
+  /data/repos/{namespace}/{repo}/years/{year}/{timespantype}/{timespan}/raw:
     get:
       tags: [repos]
-      summary: Get repository data for month
+      summary: Get repository data for timespan
-      description: Gets a list of URLs that can be used to download the raw pull data for the given repository and month
+      description: Gets a list of URLs that can be used to download the raw pull data for the given repository and timespan
-      operationId: getRepoDataByMonth
+      operationId: getRepoDataByTimespan
       parameters:
         - in: path
           name: namespace
@@ -510,11 +502,17 @@ paths:
           required: true
           description: Year to fetch data for
         - in: path
-          name: month
+          name: timespantype
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: true
+          description: Type of timespan to fetch data for
+        - in: path
+          name: timespan
           schema:
             type: integer
           required: true
-          description: Month to fetch data for
+          description: Timespan to fetch data for
       responses:
         '200':
           description: Success
@@ -522,12 +520,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ResponseData'
-  /data/repos/{namespace}/{repo}/years/{year}/weeks/{week}:
+  /data/repos/{namespace}/{repo}/years/{year}/{timespantype}/{timespan}/summary:
     get:
       tags: [repos]
-      summary: Get repository metadata for week
+      summary: Get repository summary data for timespan
-      description: Gets info about data for the given repository and week
+      description: Gets a list of URLs that can be used to download the summary pull data for the given repository and timespan
-      operationId: getRepoWeekMetadata
+      operationId: getRepoSummaryByTimespan
       parameters:
         - in: path
           name: namespace
@@ -548,127 +546,17 @@ paths:
           required: true
           description: Year to fetch data for
         - in: path
-          name: week
+          name: timespantype
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: true
+          description: Type of timespan to fetch data for
+        - in: path
+          name: timespan
           schema:
             type: integer
           required: true
-          description: Week to fetch data for
+          description: Timespan to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/WeekModel'
-        '404':
-          description: Not Found
-  /data/repos/{namespace}/{repo}/years/{year}/weeks/{week}/raw:
-    get:
-      tags: [repos]
-      summary: Get repository data for week
-      description: Gets a list of URLs that can be used to download the raw pull data for the given repository and week
-      operationId: getRepoDataByWeek
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: repo
-          schema:
-            type: string
-          required: true
-          description: Repo to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-        - in: path
-          name: week
-          schema:
-            type: integer
-          required: true
-          description: Week to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ResponseData'
-  /data/repos/{namespace}/{repo}/years/{year}/months/{month}/summary:
-    get:
-      tags: [repos]
-      summary: Get repository summary data for month
-      description: Gets a list of URLs that can be used to download the summary pull data for the given repository and month
-      operationId: getRepoSummaryByMonth
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: repo
-          schema:
-            type: string
-          required: true
-          description: Repo to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-        - in: path
-          name: month
-          schema:
-            type: integer
-          required: true
-          description: Month to fetch data for
-      responses:
-        '200':
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ResponseData'
-  /data/repos/{namespace}/{repo}/years/{year}/weeks/{week}/summary:
-    get:
-      tags: [repos]
-      summary: Get repository summary data for week
-      description: Gets a list of URLs that can be used to download the summary pull data for the given repository and week
-      operationId: getRepoSummaryByWeek
-      parameters:
-        - in: path
-          name: namespace
-          schema:
-            type: string
-          required: true
-          description: Namespace to fetch data for
-        - in: path
-          name: repo
-          schema:
-            type: string
-          required: true
-          description: Repo to fetch data for
-        - in: path
-          name: year
-          schema:
-            type: integer
-          required: true
-          description: Year to fetch data for
-        - in: path
-          name: week
-          schema:
-            type: integer
-          required: true
-          description: Week to fetch data for
       responses:
         '200':
           description: Success
@@ -679,6 +567,81 @@ paths:
 
 components:
   schemas:
+    UsersLoginRequest:
+      description: User login details
+      type: object
+      required:
+        - username
+        - password
+      properties:
+        username:
+          description: The username of the Docker Hub account to authenticate with.
+          type: string
+          example: myusername
+        password:
+          description:
+            The password or personal access token (PAT) of the Docker Hub
+            account to authenticate with.
+          type: string
+          example: hunter2
+    PostUsersLoginSuccessResponse:
+      description: successful user login response
+      type: object
+      properties:
+        token:
+          description: |
+            Created authentication token.
+
+            This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs.
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+          nullable: false
+    PostUsersLoginErrorResponse:
+      description: failed user login response or second factor required
+      type: object
+      required:
+        - detail
+      properties:
+        detail:
+          description: Description of the error.
+          type: string
+          example: Incorrect authentication credentials
+          nullable: false
+        login_2fa_token:
+          description:
+            Short time lived token to be used on `/v2/users/2fa-login` to
+            complete the authentication. This field is present only if 2FA is
+            enabled.
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+          nullable: true
+    Users2FALoginRequest:
+      description: Second factor user login details
+      type: object
+      required:
+        - login_2fa_token
+        - code
+      properties:
+        login_2fa_token:
+          description: The intermediate 2FA token returned from `/v2/users/login` API.
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+        code:
+          description:
+            The Time-based One-Time Password of the Docker Hub account to
+            authenticate with.
+          type: string
+          example: 123456
+    PostUsers2FALoginErrorResponse:
+      description: failed second factor login response.
+      type: object
+      properties:
+        detail:
+          description: Description of the error.
+          type: string
+          example: Incorrect authentication credentials
+          nullable: false
+
     ResponseData:
       properties:
         data:
@@ -740,11 +703,26 @@ components:
       properties:
         week:
           type: integer
+    TimespanType:
+      type: string
+      enum: [months,weeks]
+    TimespanModel:
+      oneOf:
+        - $ref: '#/components/schemas/MonthModel'
+        - $ref: '#/components/schemas/WeekModel'
+    TimespanData:
+      oneOf:
+        - $ref: '#/components/schemas/MonthData'
+        - $ref: '#/components/schemas/WeekData'
   securitySchemes:
     HubAuth:
       type: https
       scheme: bearer
       bearerFormat: JWT
-      description: >
+      description: |
-        See [Hub API Authentication docs](https://docs.docker.com/docker-hub/api/latest/#tag/authentication)
+        JWT Bearer Authentication is required to access the Docker DVP Data API.  
+          
+        Note - PATs are not supported on this API  
+          
+        This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/docker-hub/api/latest/#tag/authentication)
       x-displayName: Docker Hub Authentication