# ------------------
# Disclaimer:
# ------------------
# This Open API specification document is work in progress. This document will continue 
# to be updated until our Public API v4 is finalized.
#--------------------
openapi: 3.0.0
info:
  title: Regulations.gov API
  description: >-
    Public API for Regulations.gov
  version: "4.0"
servers:
  - url: 'https://api.regulations.gov/v4'
    description: Production endpoint for Regulations.gov API
security: 
  - ApiKeyAuth: []
paths:
  /documents:
    get:
      summary: List of documents
      description: This endpoint returns list of documents
      tags:
        - documents
      parameters: 
        - name: filter[agencyId]
          in: query
          description: >-
            'Filters results for the agency acronym specified in the value. Example: ''EPA'''
          required: false
          schema:
            type: string
        - name: filter[commentEndDate]
          in: query
          description: >-  
            Filters results relative to the comment end date.  The value must be formatted as `yyyy-MM-dd`.<br/><br/> Omission of a parameter modifier will match results to the exact date provided, otherwise, one of the parameter modifiers below may be used. <br/> `ge` - greater than or equal <br/> `le` - less than or equal
          required: false
          schema:
            type: string
            format: date
        - name: filter[docketId]
          in: query
          description: >-
            Filters results on the specified docket ID.
          required: false
          schema:
            type: string
        - name: filter[documentType]
          in: query
          description: >-
            Filters results on the specified document type.
          required: false
          schema:
            $ref: '#/components/schemas/DocumentType'
        - name: filter[frDocNum]
          in: query
          description: >-
            Filters results on the specified frDocNum.
          required: false
          schema:
            type: string
        - name: filter[searchTerm]
          in: query
          description: >-
            Filters results on the given term.
          required: false
          schema:
            type: string
        - name: filter[postedDate]
          in: query
          description: >-  
            Filters results relative to the posted date.  The value must be formatted as `yyyy-MM-dd`.<br/><br/> Omission of a parameter modifier will match results to the exact date provided, otherwise, one of the parameter modifiers below may be used. <br/> `ge` - greater than or equal <br/> `le` - less than or equal
          required: false
          schema:
            type: string
            format: date
        - name: filter[lastModifiedDate]
          in: query
          description: >-  
            Filters results relative to the last modified date.  The value must be formatted as `yyyy-MM-dd HH:mm:ss`.<br/><br/> Omission of a parameter modifier will match results to the exact date provided, otherwise, one of the parameter modifiers below may be used. <br/> `ge` - greater than or equal <br/> `le` - less than or equal
          required: false
          schema:
            type: string
            format: date            
        - name: filter[subtype]
          in: query
          description: >-
            Filters results on the supplied document subtype
          required: false
          schema:
            type: string
        - name: filter[withinCommentPeriod]
          in: query
          description: >-
            Filters results for documents that are open for comment by setting the value to `true`. <br/><br/> _`False` is not an acceptable value for this parameter, hence it should be removed when not being used._          
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          description: >-
            Sorts the results on the field specified in the value.  The default behavior will sort the results in ascending order; to sort in descending order, prepend a minus sign to the value. <br/><br/> Supported values are `commentEndDate`, `postedDate`, `lastModifiedDate`, `documentId` and `title`. Multiple sort options can be passed in as a comma separated list to sort results by multiple fields.         
          required: false
          schema:
            type: string
        - name: page[number]
          in: query
          description: >-
            Specifies the number for the page of results that will be returned from the query. <br/><br/> Acceptable values are numerical between, and including, 1 and 20.          
          required: false
          schema:
            type: integer
        - name: page[size]
          in: query
          description: >-
            Specifies the size per page of results that will be returned from the query. <br/><br/> Acceptable values are numerical between, and including, 5 and 250.           
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A JSON\:API document with the a list of documents
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DocumentFindAllResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError' 
  /documents/{documentId}:
    get:
      tags:
        - documents
      summary: Get detailed information for specified documentId
      description: Gets the detailed information of a specific document with the passed documentId.
      parameters:
        - name: documentId
          in: path
          description: ID of document to return
          required: true
          schema:
            type: string
        - name: include #Only supported value for include is attachments.
          in: query
          description: resources to include
          required: false
          schema:
            type: string
          example: attachments
      responses:
        '200':
          description: successful operation
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DocumentFindOneResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '404':
          description: Document not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
  /comments:
    get:
      summary: List of comments
      description: This endpoint returns list of comments 
      tags:
        - comments
      parameters: 
        - name: filter[agencyId]
          in: query
          description: >-
            'Filters results for the agency acronym specified in the value. Example: ''EPA'''
          required: false
          schema:
            type: string
        - name: filter[searchTerm]
          in: query
          description: >-
            Filters results on the given term.
          required: false
          schema:
            type: string
        - name: filter[postedDate]
          in: query
          description: >-
            Filters results relative to the posted date.  The value must be formatted as `yyyy-MM-dd`.<br/><br/> Omission of a parameter modifier will match results to the exact date provided, otherwise, one of the parameter modifiers below may be used. <br/> `ge` - greater than or equal <br/> `le` - less than or equal
          required: false
          schema:
            type: string
            format: date
        - name: filter[lastModifiedDate]
          in: query
          description: >-  
            Filters results relative to the last modified date.  The value must be formatted as `yyyy-MM-dd HH:mm:ss`.<br/><br/> Omission of a parameter modifier will match results to the exact date provided, otherwise, one of the parameter modifiers below may be used. <br/> `ge` - greater than or equal <br/> `le` - less than or equal
          required: false
          schema:
            type: string
            format: date
        - name: filter[commentOnId]
          in: query
          description: >-
            Filters results on the supplied commentOnId
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: >-
            Sorts the results on the field specified in the value.  The default behavior will sort the results in ascending order; to sort in descending order, prepend a minus sign to the value. <br/><br/> The only supported values are `postedDate`, `lastModifiedDate` and `documentId`. Multiple sort options can be passed in as a comma separated list to sort results by multiple fields.          
          required: false
          schema:
            type: string
        - name: page[number]
          in: query
          description: >-
            Specifies the number for the page of results that will be returned from the query. <br/><br/> Acceptable values are numerical between, and including, 1 and 20.          
          required: false
          schema:
            type: integer
        - name: page[size]
          in: query
          description: >-
            Specifies the size per page of results that will be returned from the query. <br/><br/> Acceptable values are numerical between, and including, 5 and 250.           
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A JSON\:API document with the a list of comments
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CommentFindAllResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
    post:
      summary: Creates a new comment.
      tags:
        - comments
      requestBody:
        description: A JSON object containing comment information
        required: true
        content:
          application/vnd.api+json:
            schema:
                $ref: '#/components/schemas/JSONResourcePostRequestObject'
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONResourcePostResponseObject'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '404':
          description: Document not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
  /comments/{commentId}:
    get:
      summary: Get detailed information for specified commentId
      description: Gets the detailed information of a specific comment with the passed commentId.
      tags:
        - comments
      parameters:
        - name: commentId
          in: path
          description: ID of comment to return
          required: true
          schema:
            type: string
        - name: include #Only supported value for include is attachments.
          in: query
          description: resources to include
          example: attachments
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CommentFindOneResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '404':
          description: Document not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
  /dockets:
    get:
      summary: List of dockets
      description: This endpoint returns list of dockets 
      tags:
        - dockets
      parameters:
        - name: filter[agencyId]
          in: query
          description: >-
            'Filters results for the agency acronym specified in the value. Example: ''EPA'''
          required: false
          schema:
            type: string
        - name: filter[searchTerm]
          in: query
          description: >-
            Filters results on the given term.
          required: false
          schema:
            type: string
        - name: filter[lastModifiedDate]
          in: query
          description: >-  
            Filters results relative to the last modified date.  The value must be formatted as `yyyy-MM-dd HH:mm:ss`.<br/><br/> Omission of a parameter modifier will match results to the exact date provided, otherwise, one of the parameter modifiers below may be used. <br/> `ge` - greater than or equal <br/> `le` - less than or equal
          required: false
          schema:
            type: string
            format: date
        - name: filter[docketType]
          in: query
          description: >-
            Filters results on the specified docket type.
          required: false
          schema:
            $ref: '#/components/schemas/DocketType'
        - name: sort
          in: query
          description: >-
            Sorts the results on the field specified in the value.  The default behavior will sort the results in ascending order; to sort in descending order, prepend a minus sign to the value. <br/><br/> The only supported values are `title`, `docketId` and `lastModifiedDate`. Multiple sort options can be passed in as a comma separated list to sort results by multiple fields.          
          required: false
          schema:
            type: string
        - name: page[number]
          in: query
          description: >-
            Specifies the number for the page of results that will be returned from the query. <br/><br/> Acceptable values are numerical between, and including, 1 and 20.          
          required: false
          schema:
            type: integer
        - name: page[size]
          in: query
          description: >-
            Specifies the size per page of results that will be returned from the query. <br/><br/> Acceptable values are numerical between, and including, 5 and 250.           
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A JSON\:API document with the a list of dockets
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DocketFindAllResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
  /dockets/{docketId}:
    get:
      tags:
        - dockets
      summary: Get detailed information for specified docketId
      description: Gets the detailed information of a specific docket with the passed docketId.
      parameters:
        - name: docketId
          in: path
          description: ID of docket to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DocketFindOneResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '404':
          description: Document not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
  /agency-categories:
    get:
      summary: Returns a list of categories
      description: This endpoint returns list of categories
      tags:
        - comment submission utilities
      parameters:
        - name: filter[acronym]
          in: query
          description: >-
            'Filters results for the agency acronym specified in the value. Example: ''EPA'''
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of agency categories
          content:
            application/vnd.api+json:
             schema: # TODO: Pull this object out into a component
                type: object 
                properties: 
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        default:
                          type: boolean
                          description: Defines if its the default category value
                        acronym:
                          type: string
                          description: Agency acronym
                        categories:
                          type: string
                          description: The name of the category
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
  /submission-keys:
    post:
      summary: Creates the unique submission key
      operationId: GetSubmitterKey
      tags:
        - comment submission utilities
      requestBody:
        content: 
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      example: 'submissionKeys'
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                        id:
                          type: string
                          description: the newly created submission key
                        type:
                          type: string
                          example: 'submission-keys'
                        links:
                          $ref: '#/components/schemas/SelfLink'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'      
  /file-upload-urls:
    post:
      summary: Creates a presigned url to upload file
      tags:
        - comment submission utilities
      description: 'Returns a pre-signed URL to upload a file to the S3 bucket'
      requestBody:
        required: true
        content: 
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      example: 'file-upload-urls'
                    attributes:
                      type: object
                      properties: 
                        submissionKey:
                          type: string
                          description: submission key for the submission
                        fileName:
                          type: string
                          description: name of the file to upload
                        contentType:
                          type: string
                          description: content type of the file
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uri
                        description: The pre-signed url to upload the file
                      type:
                        type: string
                        example: 'file-upload-urls'
                      attributes:
                        type: object
                        properties: 
                          submissionKey:
                            type: string
                            description: submission key for the submission
                          fileName:
                            type: string
                            description: name of the file to upload
                          contentType:
                            type: string
                            description: content type of the file
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '403':
           description: API key is missing or invalid
           content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONError'
components:
  securitySchemes:
    ApiKeyAuth:          # arbitrary name for the security scheme
        type: apiKey
        in: header       # can be "header", "query" or "cookie"
        name: X-Api-Key  # name of the header, query parameter or cookie
  schemas:
    #JSON:API Specific documentation
    DocumentFindAllResponse:
      description: A JSON:API document with a list of resources
      properties:
        data:
          description: The list of documents where each document is a JSON:API document
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/DocumentFindAllItem'
        meta:
          $ref: '#/components/schemas/FindAllResponseMetadata'
    CommentFindAllResponse:
      description: A JSON:API document with a list of resources
      properties:
        data:
          description: The list of comments where each comment is a JSON:API document
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/CommentFindAllItem'
        meta:
          $ref: '#/components/schemas/FindAllResponseMetadata'
    DocketFindAllResponse:
      description: A JSON:API document with a list of resources
      properties:
        data:
          description: The list of dockets where each docket is a JSON:API document
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/DocketFindAllItem'
        meta:
          $ref: '#/components/schemas/FindAllResponseMetadata'
    DocumentFindAllItem:
      description: A JSON:API document which represents a single document in the list
      properties:
        id:
          description: The JSON:API resource ID `documentId`
          type: string
        type:
          description: The JSON:API resource type `documents`
          type: string
        attributes: 
          $ref: '#/components/schemas/Document'
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
    CommentFindAllItem:
      description: A JSON:API document which represents a single document in the list
      properties:
        id:
          description: The JSON:API resource ID `documentId`
          type: string
        type:
          description: The JSON:API resource type `comments`
          type: string
        attributes: 
          $ref: '#/components/schemas/Comment'
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
    DocketFindAllItem:
      description: A JSON:API document which represents a single document in the list
      properties:
        id:
          description: The JSON:API resource ID `docketId`
          type: string
        type:
          description: The JSON:API resource type `dockets`
          type: string
        attributes: 
          $ref: '#/components/schemas/Docket'
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
    AttachmentFindAllItem:
      description: A JSON:API document which represents a single document in the list
      properties:
        id:
          description: The JSON:API resource ID `attachmentId`
          type: string
        type:
          description: The JSON:API resource type `attachments`
          type: string
        attributes: 
          $ref: '#/components/schemas/Attachment'
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
    FindAllResponseMetadata:
      description: A JSON:API document
      properties:
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        numberOfElements:
          type: integer
        pageNumber: 
          type: integer
        pageSize:
          type: integer
        totalElements:
          type: integer
        totalPages:
          type: integer
        firstPage:
          type: boolean
        lastPage:
          type: boolean
    DocumentFindOneResponse:
      description: A JSON:API document which represents a single document
      type: object
      properties:
        id:
          description: The JSON:API resource ID (documentId of the document)
          type: string
        type:
          description: The JSON:API resource type `documents`
          type: string
        attributes: 
          $ref: "#/components/schemas/DocumentDetail"
        relationships:
          $ref: "#/components/schemas/Relationship"
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
        included:
          description: The list of documents where each document is a JSON:API document
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AttachmentFindAllItem'
    CommentFindOneResponse:
      description: A JSON:API document which represents a single document
      type: object
      properties:
        id:
          description: The JSON:API resource ID (documentId of the comment). DocumentId field is always returned in JSON response. This is an agency configurable field. Each agency has option to configure the format of the field. 
          type: string
        type:
          description: The JSON:API resource type `comments`
          type: string
        attributes: 
          $ref: "#/components/schemas/CommentDetail"
        relationships:
          type: array
          items:
            $ref: "#/components/schemas/Relationship"
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
        included:
          description: The list of documents where each document is a JSON:API document
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AttachmentFindAllItem'
    DocketFindOneResponse:
      description: A JSON:API document which represents a single document
      type: object
      properties:
        id:
          description: The JSON:API resource ID (docketId of the docket)
          type: string
        type:
          description: The JSON:API resource type `dockets`
          type: string
        attributes: 
          $ref: "#/components/schemas/DocketDetail"
        links: 
          type: array
          items:
            $ref: '#/components/schemas/SelfLink'
    Relationship:
      description: A single relationship object
      type: object
      properties:
        data:
          $ref: "#/components/schemas/RelationshipToAttachment"
        links:
          $ref: "#/components/schemas/RelationshipLinks"
      additionalProperties: false
    RelationshipToAttachment:
      description: >-
        An array of attachment objects as relationship resources.
      type: array
      items:
        type: object
        properties:
          type:
            type: string
          id:
            type: string
    RelationshipLinks:
      description: >-
        Relationship links to other related resources (`attachments`)
      type: object
      properties:
        self:
          $ref: "#/components/schemas/Link"
        related:
          $ref: "#/components/schemas/Link"
      additionalProperties: false
    SelfLink:
      description: Link to self
      type: object
      properties:
        self:
          $ref: "#/components/schemas/Link"
    Link:
      description: A string containing the link URL.
      type: string
      format: uri-reference
      uniqueItems: true
    JSONResourcePostRequestObject:
      description: A JSON:API document which represents a single document being posted
      type: object
      properties:
        type:
          description: The JSON:API resource type `comments`
          type: string
        attributes: 
          type: object
          oneOf:
            - $ref: "#/components/schemas/IndividualComment"
            - $ref: "#/components/schemas/OrganizationComment"
            - $ref: "#/components/schemas/AnonymousComment"
    JSONResourcePostResponseObject:
      description: A JSON:API document which represents the response from post
      type: object
      properties:
        id:
          description: The comment tracking number
          type: string
        type:
          description: The JSON:API resource type `comments`
          type: string
        attributes:
          $ref: "#/components/schemas/CommentPostResponse"
    JSONError:
      description: A JSON:API document
      type: object
      properties:
        errors:
          description: List of JSON:API Error
          type: array
          items:
            $ref: "#/components/schemas/Error" 
    #Regulations.gov documentation        
    DocumentType:
      type: string
      description: type of document. This field is always returned in JSON response
      enum:
        - Notice
        - Rule
        - Proposed Rule
        - Supporting & Related Material
        - Other
    DocketType:
      type: string
      description: the type of docket
      enum:
        - Rulemaking
        - Nonrulemaking 
    SubmitterType:
      type: string
      description: the submitter type
      enum:
        - Anonymous
        - Individual
        - Organization
    FileFormat:
      type: object
      properties: 
        fileUrl:
          type: string
          description: URL of the file on S3
        format:
          type: string
          description: The format of the file such as `pdf`
        size:
          type: integer
          description: The file size
    #Relationship model for attachments
    Attachment:
      type: object
      properties:
        agencyNote:
          type: string
          description: The note by agency
        authors:
          type: array
          items:
            type: string
          description: The individual, organization, or group of collaborators that contributed to the creation of the attachment.
        docAbstract:
          type: string
          description: The detailed description of the attachment.
        docOrder:
          type: integer
          description: The order of the attachment
        fileFormats:
          type: array
          description: list of file formats
          items:
              $ref: '#/components/schemas/FileFormat'
        modifyDate:
          type: string
          format: date-time
          description: The date when the attachment was last modified.
        publication:
          type: string
          description: The publication date
        restrictReason:
          type: string
          description: If the attachment is restricted, this field will state the reason.
        restrictReasonType:
          type: string
          description: If the attachment is restricted, this field will state the type of restriction.
        title:
          type: string
          description: The formal title of the attachment
    #Search components     
    Document:
      type: object
      properties: 
        agencyId:
          type: string
          description: The acronym used to abbreviate the name of the agency associated with the document.
        commentEndDate:
          type: string
          nullable: true
          format: date-time
          description: The date that closes the period when public comments may be submitted on the document.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        commentStartDate:
          type: string
          nullable: true
          format: date-time
          description: The date that begins the period when public comments may be submitted on the document.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        docketId:
          type: string
          description: The ID of the docket to which the document corresponds.
        documentType:
          $ref: '#/components/schemas/DocumentType'
        frDocNum:
          type: string
          description: The federal register document number of the document.
        highlightedContent:
          type: string
          nullable: true
          description: Content highlighted by search engine for the searchTerm. Only returned for searches with searchTerm.
        lastModifiedDate:
          type: string
          format: date-time
          description: The date document was last modified in the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        objectId:
          type: string
          description: The internal ID of the document in our system.
        openForComment:
          type: boolean
          description: Conveys if the document is open for comment
        postedDate:
          type: string
          description: The date that the document was posted by the agency to the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        subtype:
          type: string
          nullable: true
          description: An agency-specific attribute to further categorize a document beyond the type (`documentType`).
        title:
          type: string
          description: The formal title of the document.
        withdrawn:
          type: boolean
          description: Conveys if the document is withdrawn
    Comment:
      type: object
      properties:
        agencyId:
          type: string
          description: The acronym used to abbreviate the name of the agency associated with the document.
        documentType:
          $ref: '#/components/schemas/DocumentType'
        highlightedContent:
          type: string
          nullable: true
          description: Content highlighted by search engine for the searchTerm. Only returned for searches with searchTerm.
        lastModifiedDate:
          type: string
          format: date-time
          description: The date comment was last modified in the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        objectId:
          type: string
          description: The internal ID of the comment in our system.
        postedDate:
          type: string
          description: The date that the document was posted by the agency to the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        title:
          type: string
          description: The formal title of the document.
        withdrawn:
          type: boolean
          description: Conveys if the document is withdrawn
    Docket:
      type: object
      properties:
        agencyId:
          type: string
          description: The acronym used to abbreviate the name of the agency associated with the docket.
        docketType:
          $ref: '#/components/schemas/DocketType'
        highlightedContent:
          type: string
          nullable: true
          description: Content highlighted by search engine for the searchTerm. Only returned for searches with searchTerm.
        lastModifiedDate:
          type: string
          format: date-time
          description: The date docket was last modified in the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        objectId:
          type: string
          description: The internal ID of the docket in our system.
        title:
          type: string
          description: The formal title of the docket.
    #Detail components
    BasicDetailModel:
      type: object
      properties:
        address1:
          type: string
          nullable: true
          description: The first line of the submitter's address. 
        address2:
          type: string
          nullable: true
          description: The second line of the submitter's address.
        agencyId:
          type: string
          description: The acronym used to abbreviate the name of the agency associated with the document. This field is always returned in JSON response.
        city:
          type: string
          nullable: true
          description: The city associated with the submitter's address. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        category:
          type: string
          nullable: true
          description: An agency-specific category allowing agencies to group comments according to their type.
        comment:
          type: string
          description: The comment text associated with the comment submission. This field is always returned in JSON response.
        country:
          type: string
          nullable: true
          description: The country associated with the submitter's address. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        docAbstract:
          type: string
          description: The detailed description of the document. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        docketId:
          type: string
          description: The ID of the docket to which the document corresponds. This field is always returned in JSON response. 
        documentType:
          $ref: '#/components/schemas/DocumentType'
        email:
          type: string
          nullable: true
          description: The submitter's e-mail address.
        fax:
          type: string
          nullable: true
          description: The submitter's fax number.
        field1:
          type: string
          nullable: true
          description: An agency-specific field used for storing additional data with the document. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        field2:
          type: string
          nullable: true
          description: An agency-specific field used for storing additional data with the document. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        fileFormats:
          type: array
          description: list of file formats
          items:
            $ref: '#/components/schemas/FileFormat'
        firstName:
          type: string
          nullable: true
          description: The submitter's first name. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        govAgency:
          type: string
          nullable: true
          description: The name of the government agency that the submitter represents. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        govAgencyType:
          type: string
          nullable: true
          description: The type of government agency that the submitter represents. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        lastName:
          type: string
          nullable: true
          description: The submitter's last name. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        legacyId:
          type: string
          nullable: true
          description: An agency-specific identifier that was given to the document in the legacy system. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        modifyDate:
          type: string
          format: date-time
          description: The date when the document was last modified.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        objectId:
          type: string
          description: The internal ID of the document in our system.
        openForComment:
          type: boolean
          description: Conveys if the document is open for commenting.
        organization:
          type: string
          nullable: true
          description: The organization that the submitter represents. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        originalDocumentId:
          type: string
          description: The document ID that was assigned when first entered into the system should a change occur that requires a new document ID to be assigned.
        pageCount:
          type: string
          nullable: true
          description: Conveys the number of pages contained in the document. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        phone:
          type: string
          nullable: true
          description: The submitter's phone number.
        postedDate:
          type: string
          format: date-time
          description: The date that the document was posted by the agency to the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`. This field is always returned in JSON response.
        postmarkDate:
          type: string
          nullable: true
          format: date-time
          description: The postmark date of a document that was sent by mail.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        reasonWithdrawn:
          type: string
          nullable: true
          description: If the document is withdrawn, this field will state the reason. If data exists, it is always returned in JSON response.
        receiveDate:
          type: string
          format: date-time
          description: The date that the document was received by the agency to the system.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2018-06-29T04:00:00Z`. This field is always returned in JSON response.
        restrictReason:
          type: string
          description: If the document is restricted, this field will state the reason. If data exists, it is always returned in JSON response.
        restrictReasonType:
          type: string
          description: If the document is restricted, this field will state the type of restriction. If data exists, it is always returned in JSON response.
        stateProvinceRegion:
          type: string
          nullable: true
          description: The submitter's state,province or region. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        subtype:
          type: string
          nullable: true
          description: An agency-specific attribute to further categorize a document beyond the documentType. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
        title:
          type: string
          description: The formal title of the document. This field is always returned in JSON response.
        trackingNbr:
          type: string
          description: The tracking number of the submission. This field is always returned in JSON response.
        withdrawn:
          type: boolean
          description: Conveys if the document is withdrawn. This field is always returned in JSON response.
        zip:
          type: string
          description: The zip associated with the submitter's address. This is an agency configurable field. An agency can configure this field to make it not publicly accessible.
    DocumentDetail:
      allOf:     # Combines the BasicDetailModel and the inline model
        - $ref: '#/components/schemas/BasicDetailModel'
        - type: object
          required:
            - documentId
          properties: 
            additionalRins:
              type: array
              nullable: true
              items:
                type: string
              description: One or more Regulatory Information Numbers (RINs) to which the document relates.
            allowLateComments:
              type: boolean
              description: Indicates whether the owning agency will accept comments on the document after the due date.
            authorDate:
              type: string
              nullable: true
              format: date-time
              description: The date that the authors wrote or published the document.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
            authors:
              type: array
              nullable: true
              items:
                type: string
              description: The individual, organization, or group of collaborators that contributed to the creation of the document.
            cfrPart:
              type: string
              nullable: true
              description: The Code of Federal Regulations (CFR) Citation applicable to the document.
            commentEndDate:
              type: string
              nullable: true
              format: date-time
              description: The date that closes the period when public comments may be submitted on the document.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
            commentStartDate:
              type: string
              nullable: true
              format: date-time
              description: The date that begins the period when public comments may be submitted on the document.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
            effectiveDate:
              type: string
              nullable: true
              format: date-time
              description: The date the document is put into effect.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
            exhibitLocation:
              type: string
              nullable: true
              description: The physical location of an exhibit to which a document refers.
            exhibitType:
              type: string
              nullable: true
              description: The type of exhibit to which a document refers.
            frDocNum:
              type: string
              nullable: true
              description: The unique identifier of a document originating in the [Federal Register](https://www.federalregister.gov/).
            frVolNum:
              type: string
              nullable: true
              description: The [Federal Register](https://www.federalregister.gov/) volume number where the document was published.
            implementationDate:
              type: string
              nullable: true
              format: date-time
              description: The date the document is to be implemented.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
            openForComment:
              type: boolean
              description: Conveys if a document is open for comment.
            media:
              type: string
              nullable: true
              description: The media in which the document is stored.
            ombApproval:
              type: string
              nullable: true
              description: The control number assigned when approval is given by the Office of Management and Budget (OMB) in accordance with the Paperwork Reduction Act (PRA).
            paperLength:
              type: integer
              description: When the document is in paper format, indicates the length of the paper.
            paperWidth:
              type: integer
              description: When the document is in paper format, indicates the width of the paper.
            regWriterInstruction:
              type: string
              nullable: true
              description: Additional instructions provided by the writer of the regulation.
            sourceCitation:
              type: string
              nullable: true
              description: The citation for the source that published the document.
            startEndPage:
              type: string
              nullable: true
              description: The starting and ending pages where the document was published.
            subject:
              type: string
              nullable: true
              description: The subject of the document.
            topics:
              type: array
              nullable: true
              items:
                type: string
              description: The principal topics to which the document pertains.
    CommentDetail: 
      allOf:     # Combines the BasicDetailModel and the inline model
        - $ref: '#/components/schemas/BasicDetailModel'
        - type: object
          required:
            - documentId
          properties: 
            commentOnDocumentId:
              type: string
              description: documentId of the parent document. This field is always returned in JSON response.
            duplicateComments:
              type: integer
              description: Number of duplicate comments
    DocketDetail:
      type: object
      properties:
        agencyId:
          type: string
          description: The acronym used to abbreviate the name of the agency associated with the docket.
        category:
          type: string
          nullable: true
          description: Agency specific docket category providing regulatory action details, status, and the agency program and or office.
        dkAbstract:
          type: string
          description: The detailed description of the docket.
        docketType:
          $ref: '#/components/schemas/DocketType'
        effectiveDate:
          type: string
          format: date-time
          description: The date the docket is put into effect.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        field1:
          type: string
          nullable: true
          description: An agency-specific field used for storing additional data with the docket.
        field2:
          type: string
          nullable: true
          description: An agency-specific field used for storing additional data with the docket.
        generic:
          type: string
          nullable: true
          description: An agency-specific field used for storing additional data with the docket.
        keywords:
          type: array
          nullable: true
          items:
            type: string
            description: Agency selected keywords associated with a docket to improve its searchability by the public.
        legacyId:
          type: string
          nullable: true
          description: An agency-specific identifier that was given to the docket in the legacy system.
        modifyDate:
          type: string
          format: date-time
          description: The date when the docket was last modified.<br/><br/>The date is formatted as ISO 8601 with an offset such as `2019-01-20T13:15:45Z`.
        objectId:
          type: string
          description: The internal ID of the document in our system.
        organization:
          type: string
          nullable: true
          description: Identifies docket's (a regulatory action) orginating agency and/or department.
        petitionNbr:
          type: string
          nullable: true
          description: Agency specific identifier associated with a docket.
        program:
          type: string
          nullable: true
          description: The agency specific program associated with the docket.
        rin:
          type: string
          nullable: true
          description: OMB issued Regulation Identifier Number (RIN) uniquely identifies a docket and its documents.
        shortTitle:
          type: string
          nullable: true
          description: A combination of letters and or numbers assigned to an agency's regulatory action for purposes of brevity.
        subType:
          type: string
          nullable: true
          description: This agency specific attribute characterizes a docket (regulatory action) beyond its assigned docket type, e.g., Rulemaking.
        subType2:
          type: string
          nullable: true
          description: This agency specific attribute characterizes a docket (regulatory action) beyond the designated docket subtype.
        title:
          type: string
          description: A name or descriptive heading given to an agency's docket.
    #Comment Submission Related components
    BaseCommentPayload:
      type: object
      required:
        - comment
        - commentOnDocumentId
        - submissionType #user should set submission Type to API
      properties:
        category:
          type: string
          description: An agency-specific category allowing agencies to group comments according to their type.
        comment:
          type: string
          maxLength: 5000
          description: The comment text
        commentOnDocumentId:
          type: string
          description: documentId of the parent document
        email:
          type: string
          maxLength: 100
          description: The email address to receive email receipt for the commenrt
        files:
          type: array
          items:
            type: string
            description: The names of the files submitted with the submission
        numItemsReceived:
          type: integer
          description: The number of items included in the submission          
        sendEmailReceipt:
          type: boolean
          description: Conveys if the user would like to receive an email receipt for the comment
        submissionKey:
          type: string
          description: The unique identifier associated with the submission
        submissionType:
          type: string
          description: The submitter type - Its always going to be `API` for comments submitted via API 
    IndividualComment:
      allOf:     # Combines the BasicCommentPayLoad and the inline model
        - $ref: '#/components/schemas/BaseCommentPayload'
        - type: object
          required:
            - submitterType
            - firstName
            - lastName
          properties:
            city:
              type: string
              maxLength: 50
              description: The city associated with the submitter's address.
            country:
              type: string
              maxLength: 50
              description: The country associated with the submitter's address.
            firstName:
              type: string
              maxLength: 25
              description: The submitter's first name.
            lastName:
              type: string
              maxLength: 25
              description: The submitter's last name.
            phone:
              type: string
              maxLength: 50
              description: The submitter's phone number.
            stateProvinceRegion:
              type: string
              maxLength: 50
              description: The email associated with the submitter's address.
            submitterType: #submitter type should be set to Individual
              $ref: '#/components/schemas/SubmitterType'
            zip:
              type: string
              maxLength: 10
              description: The zip associated with the submitter's address.
    OrganizationComment: 
      allOf:     # Combines the BasicCommentPayLoad and the inline model
        - $ref: '#/components/schemas/BaseCommentPayload'
        - type: object
          required:
            - submitterType
            - organization
            - organizationType
          properties:
            organization:
              type: string
              maxLength: 120
              description: The organization that the submitter represents.          
            organizationType:
              type: string
              description: The agency specific organization type that the submitter represents.          
            submitterType: #submitter type should be set to Organization
              $ref: '#/components/schemas/SubmitterType'
    AnonymousComment: 
      allOf:     # Combines the BasicCommentPayLoad and the inline model
        - $ref: '#/components/schemas/BaseCommentPayload'
        - type: object
          required:
            - submitterType
          properties: 
            submitterType: #submitter type should be set to Anonymous
              $ref: '#/components/schemas/SubmitterType'
    CommentPostResponse:
      allOf:
        - oneOf:     # Returns the created comment
          - $ref: '#/components/schemas/IndividualComment'
          - $ref: '#/components/schemas/OrganizationComment'
          - $ref: '#/components/schemas/AnonymousComment'
        - type: object
          properties:
            numItemsReceived:
              type: integer
              description: The number of items included in the submission          
            receiveDate: 
              type: string
              description: The date comment was received.
    Error:
      type: object
      properties:
        status:
          type: integer #http status code
        title:
          type: string
        detail:
          type: string