openapi: 3.0.0
info:
  description: |
    This is the version v1 of DAS exchange API to be used by IP Offices to exchange priority documents.
    It is supported by the WIPO Industrial Property Business Solution Division. 
  version: "0.4"
  #----------------------------------------------------------
  # - Revised on 2021-06-25 based on internal discussion 
  #----------------------------------------------------------
  title: DAS Core Service API
  #terms Of use: 'https://intranet.wipo.int/confluence'
  contact:
    email: ipas@wipo.int
  license:
   name: Apache 2.0
    #url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
    
servers:
  - url: 'https://das.wipo.int:{port}'
    description: Production DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'
  - url: 'https://das-acc.wipo.int:{port}'
    description: Test DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'
  - url: 'https://das-dev.wipo.int:{port}'
    description: Development DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'

tags:
  - name: authorization
    description: >
      Authorization to retrieve access token for the use of DAS api
  - name: information 
    description: >
      Health check of the DAS api
  - name: requests
    description: >
      Exchange requests including registration and retrieval

security: 
  - bearerAuth: [] 

paths:
  /am/v1/oauth2/access_token:
    post:
      tags:
        - authorization
      description: >
        Service to authorize use of the DAS api 
      summary: retrieve the access token
      operationId: getTokens
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: 'client_credentials'
                  description: OAuth2 client_credentials authentication flow  is used for machine to machine communication
                scope:
                  type: string
                  example: 'das-api/das-ecchange'
                  description: Scopes (=roles), if any, separated by spaces which are required to use the DAS API
                client_assertion_type:
                  type: string
                  example: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
                  description: the client_assertion_type indicates to the authorization server the method used to authenticate, private_key_jwt requires jwt-bearer
                client_assertion:
                  type: string
                  example: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkYXMtYXBpLWF1dG giLCJzdWIiOiJkYXMtYXBpLWF1dGgiLCJhdWQiOiJodHRwczovL2xvZ2luZG V2LndpcG8uaW50OjQ0My9hbS9vYXV0aDIvYWNjZXNzX3Rva2VuIiwiZXh wIjoxNjIyNDUwNzI4fQ.BLA6k2kKKFVm6AG-DPDpRU_5JDFGRF1dHjKul7saWCv5OxXGg4EY-J9e1p8Dg0ngD2dZ2grkJ2su7jaHy67YEw'
                  description: JWT token
              required:
                - grant_type
                - scope
                - client_assertion_type
                - client_assertion

      security:
        - OAuth2: [read] 
      responses:
        '200':
          description: successful with the document audit trail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
              examples:
                exampleOfToken:
                  $ref: '#/components/examples/exampleOfToken'
        '400':
          description: invalid request
          content: 
            {}
        '403':
          description: resource access not found
          content: 
            {}
        '500':
          description: Internal server error
          content: 
            {}

  /das/v1/information:
    get:
      tags:
        - information
      description: >
        service to retrieve DAS service details information
      summary: retrieve DAS service information
      operationId: readInformation
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Information'
              examples:
                exampleOfServiceInformation:
                  $ref: '#/components/examples/exampleOfServiceInformation'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
  
  /das/v1/requests/files/uploads:
    post:
      tags:
        - requests
      description: >
        create a WIPO DAS presigned URL to upload a file without any limitation in file size. File content can be uploaded using the returned URL as a http PUT request
      summary: obtain fileId and a presigned URL to upload a big size document file for registration by OFF which does not have digital library
      operationId: createFileUploadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
            examples:
              FileUploadRequest:
                $ref: '#/components/examples/example-FileUploadRequest'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
              examples:
                FileUploadResponse:
                  $ref: '#/components/examples/example-FileUploadResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileDetails:
                  $ref: '#/components/examples/exampleOfErrorFileDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/files/downloads:
    post:
      tags:
        - requests
      description: >
        create a WIPO DAS presigned URL to download a file without any limitation in file size.
      summary: obtain a presigned URL to download a big size document file
      operationId: createFileDownloadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileDownloadRequest'
            examples:
              FileDownloadRequest:
                $ref: '#/components/examples/example-FileDownloadRequest'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDownloadResponse'
              examples:
                FileDownloadResponse:
                  $ref: '#/components/examples/example-FileDownloadResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileDetails:
                  $ref: '#/components/examples/exampleOfErrorFileDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/files/{fileId}:
    get:
      tags:
        - requests
      description: >
        retrieve file details of a file content identified by the id given by the POST service of /requests/files/url
      summary: obtain file details identified by the given fileId 
      operationId: RetrieveFileDetailsById
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDetails'
              examples:
                exampleOfUploadFile:
                  $ref: '#/components/examples/example-FileDetails'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/registrations:
    post:
      tags:
        - requests
      description: >
        register a document by OFF
      summary: register a document by OFF. Registration can be made with document details but without document content or with document content to be kept in WIPO DAS.
      operationId: registerDocument
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRegistrationRequest'
            examples:
              DocumentRegistrationRequest:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequest'
      responses:
        '201':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorDocumentDetails:
                  $ref: '#/components/examples/exampleOfErrorDocumentDetails'
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
                exampleOfErrorFileIncomplet:
                  $ref: '#/components/examples/exampleOfErrorFileIncomplet'
                exampleOfErrorEmailFormat:
                  $ref: '#/components/examples/exampleOfErrorEmailFormat'
                exampleOfErrorDocumentAlreadyRegistered:
                  $ref: '#/components/examples/exampleOfErrorDocumentAlreadyRegistered'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    put:
      tags:
        - requests
      description: >
        update a registered document content with a new fileId or correct the document date and/or pareant application details.
        Note: Registered document number and DAS access code cannot be changed.
      summary: update a registered document content with a new fileId or correct the document date and/or pareant application details
      operationId: updateRegisteredDocument
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRegistrationRequest'
            examples:
              DocumentRegistrationRequest:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequest'
      parameters:
        - name: X-ACCESS-TOKEN
          in: header
          description: access token     
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorDocumentDetails:
                  $ref: '#/components/examples/exampleOfErrorDocumentDetails'
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
                exampleOfErrorFileIncomplet:
                  $ref: '#/components/examples/exampleOfErrorFileIncomplet'
                exampleOfErrorEmailFormat:
                  $ref: '#/components/examples/exampleOfErrorEmailFormat'
                exampleOfErrorDocumentUpdate:
                  $ref: '#/components/examples/exampleOfErrorDocumentUpdate'
                exampleOfErrorDASAccessCode:
                  $ref: '#/components/examples/exampleOfErrorDASAccessCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/retrievals:
    post:
      tags:
        - requests
      description: >
        create a request for document retrieval by OSF to WIPO DAS or WIPO DAS to OFF
      summary: create a document retrieval request by OSF to WIPO DAS or WIPO DAS to OFF
      operationId: createDocumentRetrievalRequest
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRetrievalRequestBag'
            examples:
              DocumentRetrievalRequests:
                $ref: '#/components/examples/exampleOfDocumentRetrievalRequestBag'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRetrievalRequestAckBag'
              examples:
                DocumentRetrievalRequestAcks:
                  $ref: '#/components/examples/exampleOfDocumentRetrievalRequestAckBag'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorRetrievalDetails:
                  $ref: '#/components/examples/exampleOfErrorRetrievalDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/retrievals/statuses:
    post:
      tags:
        - requests
      description: >
        get the statuses of recorded requests for document retrieval from OSF to WIPO DAS or WIPO DAS to OFF 
      summary: get the statuses of recorded requests for document retrieval from OSF to WIPO DAS or WIPO DAS to OFF
      operationId: getStatusDocumentRetrievalRequests
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRetrievalRequestAckIds'
            examples:
              DocumentRetrievalRequestAckIds:
                $ref: '#/components/examples/exampleOfDocumentRetrievalRequestAckIds'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRetrievalRequestAckBag'
              examples:
                DocumentRetrievalRequestAcks:
                  $ref: '#/components/examples/exampleOfDocumentRetrievalRequestAckBag'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorRetrievalDetails:
                  $ref: '#/components/examples/exampleOfErrorRetrievalDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/notifications:  
    post:
      tags:
        - requests
      description: >
        send notification of the availability of documents that have been requested from OFF or WIPO DAS
      summary:  send notification of the availability of documents by OFF or WIPO DAS
      operationId: notifyOfDocumentAvailability
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentNotifications'
            examples:
              exampleOfDocumentNotifications:
                $ref: '#/components/examples/exampleOfDocumentNotifications'  
      responses:
        '200':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorNotificationDetails:
                  $ref: '#/components/examples/exampleOfErrorNotificationDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests:
    get:
      tags:
        - requests
      description: >
        retrieve a collection of document requests by OFF or by OSF
      summary: retrieve a collection of recorded document requests (registration or retrieval) based on filter options
      operationId: retrieveDocumentRequests
      security:
        - bearerAuth: []
      parameters:
        - name: officeCode
          in: query
          required: false
          schema:
            type: string 
            description: "two-letter office code"
        - name: operation
          in: query
          schema:
            type: string 
            enum: [registration,retrieval]
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: date format in the format of yyyy-mm-dd
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: date format in the format of yyyy-mm-dd
        - name: documentKindCategory
          in: query
          schema:
            type: string 
            enum: [design,patent,trademark,utility model]
        - name: documentNumber
          in: query
          required: false
          schema:
            type: string
            description: priority document number starting with the two-letter office code, but it may contain wildcard characters '*' and '?' 
        - name: requestStatusCategory
          in: query
          schema:
            type: string
            enum: [successful,awaiting off response, document awaiting security clearance,document number not available,document incomplete,unmatched document date, unmatched access code, unmatched document date and access code, invalid document details]
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            default: 1000
            description: number of documents to be provided in response if available
        - name: offset
          in: query
          schema:
            type: integer
            format: int32
            default: 0
            description: position of the collection of documents to retrieve
        - name: countOnly
          in: query
          schema:
            type: boolean
            default: true
            description: number of documents matching the given filter
        - name: sortedBy
          in: query
          schema:
            type: string
            enum: ['date:asc','date:desc']
            default: 'date:desc'
      
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordedDocumentRequestBag'
              examples:
                exampleOfRecordedDocumentRequests:
                  $ref: '#/components/examples/exampleOfRecordedDocumentRequests'
                exampleOfRecordedDocumentRequestCount:
                  $ref: '#/components/examples/exampleOfRecordedDocumentRequestCount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFilter:
                  $ref: '#/components/examples/exampleOfErrorFilter'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/statistics:  
    get:
      tags:
        - requests
      description: >
        retrieve exchange statistics of offices. Statistics data of the consumer office can be retrieved by the office. Statistics of all offices can be retrieved by WIPO DAS.
        If no filter is specfied for operationCategory, statistics includes registrations and retrievals
      summary:  retrieve exchange statistics of offices. 
      operationId: getRequestStatistics
      security:
        - bearerAuth: []
      parameters:
        - name: operationCategory
          in: query
          required: false
          schema:
            type: string
            enum: [regstration,retrieval]
        - name: documentKindCategory
          in: query
          required: false
          schema:
            type: string
            enum: [design,patent,trademark,utility model]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestStatistcis'
              examples:
                exampleOfDocumentRequestStatistcis:
                  $ref: '#/components/examples/exampleOfDocumentRequestStatistcis'  
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorNotificationDetails:
                  $ref: '#/components/examples/exampleOfErrorNotificationDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'
  
components:
  schemas:

    Information:
      type: object
      properties:
        applicationName: 
          type: string
        applicationVersion:
          type: string
        buildDate:
          type: string
          format: date
        buildTime:
          type: string
        codeBranch: 
          type: string
        codeRevision:
          type: string

    DocumentRegistrationRequestStatistcis:
      type: object
      properties:
        officeFirstFiling:
          type: string
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        year:
          type: integer
          format: int32
        month:
          type: integer
          format: int32
        totalQuantity:
          type: integer
          format: int32

    DocumentRetrievalRequestStatistcis:
      type: object
      properties:
        officeFirstFiling:
          type: string
        officeSecondFiling:
          type: string
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        year:
          type: integer
          format: int32
        month:
          type: integer
          format: int32
        totalQuantity:
          type: integer
          format: int32

    DocumentRequestStatistcis:
      type: object
      properties:
        registrations:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRegistrationRequestStatistcis'
        retrievals:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalRequestStatistcis'

    DocumentRequest:
      type: object
      properties:
        operationCategory:
          type: string
          enum: [registration,retrieval]
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        documentNumber:
          type: string
          description: in case of priority document, it contains the two-letter office code and the application number of which the certified copy should be made available
        documentDate:
          type: string
          format: date
          example: "2020-05-01"
          description: timestamp in the form of yyyy-mm-dd (i.e. filing date)
        dasAccessCode:
          type: string
          description: provided by office of first filing. Otherwise it will be issued by WIPO DAS
        applicationCategory:
          type: string
          enum: [design,patent,trademark,utility model]
          description: In case of registration, this may be used as IP type of the application in OFF which holds the foreign priority document. In case of retrieval, this may be used as IP type of the reference application in OSF for which the priority document is retrieved 
        applicationNumber:
          type: string
          description: In case of registration, this may be used as the application number in OFF which holds the foreign document. In case of retrieval, this may be used as the reference application number in OSF for which the priority document is retrieved
        applicationFilingDate:
          type: string
          format: date
          example: "2020-05-01"
          description: In case of registration, this may be used as the filing date of the application in OFF which holds the foreign document. In case of retrieval, this may be used as the reference application filing date in OSF for which the priority document is retrieved

    DocumentRegistrationRequest:
      allOf:
        - $ref: '#/components/schemas/DocumentRequest'
        - type: object
      type: object
      properties:
        email:
          type: string
          description: email becomes mandatory to receive the DAS access code if the DAS access code is not provided by the caller in the registration request
        fileId:
          type: string
          description: the is the document content for registration which can be securely accessed in the transit area of WIPO DAS.

    DocumentRetrievalRequest:
      $ref: '#/components/schemas/DocumentRequest'
        
    DocumentRetrievalRequestBag:
      type: array
      items:
        $ref: '#/components/schemas/DocumentRetrievalRequest'

    DocumentRetrievalRequestAck:
      allOf:
        - $ref: '#/components/schemas/DocumentRetrievalRequest'
        - type: object
      properties:
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00:08Z'
          description: operation date and time recorded and provided in response only

    DocumentRetrievalRequestAckBag:
      type: array
      items:
        $ref: '#/components/schemas/DocumentRetrievalRequestAck'

    RecordedDocumentRequest:
      allOf:
        - $ref: '#/components/schemas/DocumentRequest'
        - type: object
      type: object
      properties:
        email:
          type: string
          description: email becomes mandatory to receive the DAS access code if the DAS access code is not provided by the caller in the registration request
        fileId:
          type: string
          description: the is the document content which can be securely accessed in the transit area of WIPO DAS by the authorized requestor.
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00:08Z'
          description: operation date and time recorded and provided in response only
        fileLocationUrl:
          type: string
          description: url to download the document content in the transit area of WIPO DAS by the authorized requestor. File is made available for download with a given period (e.g. 1 week). After the fileLocationUrl is expired, the http error 403 will be raised
        requestStatusCategory:
          type: string
          enum: [successful,awaiting off response, document awaiting security clearance,document number not available,document incomplete,unmatched document date, unmatched access code, unmatched document date and access code, invalid document details]

    DocumentRetrievalRequestAckIds:
      type: object
      properties:
        requestAckIdBag:
          type: array
          items:
            type: string

    RecordedDocumentRequestFilter:
      type: object
      properties:
        officeCode:
          type: string
          description: two-letter office code
        operationCategory:
          type: string
          enum: [registration,retrieval]
        startDate:
          type: string
          format: date
          description: date format in the format of yyyy-mm-dd
        endDate:
          type: string
          format: date
          description: date format in the format of yyyy-mm-dd
        documentKindCategory:
          enum: [design,patent,trademark,utility model]
        documentNumber:
          type: string
        requestStatusCategory:
          type: string
          enum: [successful,awaiting off response, document awaiting security clearance,document number not available,document incomplete,unmatched document date, unmatched access code, unmatched document date and access code, invalid document details]
        limit: 
          type: integer
          format: int32
          default: 1000
          description: number of documents to be provided in response if available, used only when output=documents
        offset: 
          type: integer
          format: int32
          default: 0
          description: position of the collection of documents to retrieve, used only when output=documents
        countOnly:
          type: boolean
          description: position of the collection of documents to retrieve, used only when output=documents
        sortedBy: 
          type: string
          enum: ['date:asc','date:desc']
          default: 'date:desc'

    RecordedDocumentRequestBag:
      type: object
      properties:
        filter: 
          $ref: '#/components/schemas/RecordedDocumentRequestFilter'
        totalQuantity:
          type: integer
          description: total number of requests matching the filter options
        recordedDocumentRequestBag:
          type: array
          items:
            $ref: '#/components/schemas/RecordedDocumentRequest'

    DocumentRetrievalResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentRetrievalRequestAck'
        - type: object
      properties:
        fileLocationUrl:
          type: string
          description: url to download the document content in the transit area of WIPO DAS by the authorized requestor.
        requestStatusCategory:
          type: string
          enum: [successful,awaiting off response, document awaiting security clearance,document number not available,document incomplete,unmatched document date, unmatched access code, unmatched document date and access code, invalid document details]

    DocumentNotifications:
      type: object
      properties:
        systemId:
          type: string
          example: "WIPO DAS"
        notificationCategory:
          type: string
          enum: [document availability]
          description: type of notification
        dateTime:
          type: string
          format: date-time
          description: "date and time when the notification was sent"
        documentRetrievalResponseBag:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalResponse'

    FileUploadRequest:
      type: object
      properties:
        fileReference:
          type: string
          description: reference used by the service consumer to identify the file
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file

    FileUploadResponse:
      type: object
      properties:
        fileReference:
          type: string
          description: reference used by the service consumer to identify the file
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file
        fileId:
          type: string
          description: "unique id to be issued by WIPO DAS"
        fileUploadUrl:
          type: string
          description: the pre-signed url created by WIPO DAS to upload file content 

    FileDetails:
      type: object
      properties:
        fileReference:
          type: string
          description: reference used by the service consumer to identify the file in the WIPO DAS transit area
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file
        fileId:
          type: string
          description: "unique id to be issued by WIPO DAS"
        fileDateTime:
          type: string
          format: date-time
          description: "date and time when the file was created. It is empty if the file is not yet available"
        fileSizeQuantity:
          type: integer
          format: int64
          example: "size of the file in bytes"
        fileStatusCategory:
          type: string
          enum: [empty,pending,incomplet,validated]
          description: content of the file has been validated by WIPO DAS with the expected checksum as specified in the upload request. File details can only be read or file content can be written or downloaded by the requestor.

    FileDownloadRequest:
      type: object
      properties:
        fileId:
          type: string
          description: "unique id issued by WIPO DAS to identify the file that has been uploaded in the transit area"
        requestAckId:
          type: string
          description: request acknowledgement id issued by the OFF upon reception of the document retireval request

    FileDownloadResponse:
      type: object
      properties:
        fileId:
          type: string
          description: "unique id issued by WIPO DAS to identify the file that has been uploaded in the transit area"
        requestAckId:
          type: string
          description: request acknowledgement id issued by the OFF upon reception of the document retireval request
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file
        fileDownloadUrl:
          type: string
          description: the pre-signed url created by WIPO DAS to download file content 

    Token:
      type: object
      properties:
        access_token:
          type: string
          description: JWT in base64
        scope:
          type: string
          description: das-api/das-exchange
        token:_type:
          type: string
          description: type of token (e.g. Bearer)
        expires_in:
          type: integer
          format: int32
          description: expiration time in secondes

#-------------------------------Error Schemas------------------------------
    ServiceError:
      type: object
      example: ServiceError
      properties:
        code:
          type: integer
          format: int32
          example: 3010
          description: error code
        details:
          type: string
          example: 'document number does not exist: XX-TM-2020-299992' 
          description: error description
        moreInfo:
          type: array
          items:
            type: string
            example: 'Please give a correct document number'
            description: possible resolution to overcome the error

#---------------------------------------------------------------
#                Examples
#---------------------------------------------------------------
  examples:
    exampleOfToken:
      value:
        access_token: 'eyJ0eXAiOiJKV1QiLCJraWQiOiJmVWRmbEJSa3c5bm1tejcrL3BmMWM5d2RYdXc9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkYXMtYXBpLWF1dGgiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiMTQyYjMwODEtZDNjNy00MjJjLWI4ZDQtNjU4NjkwNjVmMzQ4LTU0OTkxIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbmRldi53aXBvLmludDo0NDMvYW0vb2F1dGgyIiwidG9rZW5OYW1lIjoiYWNjZXNzX3Rva2VuIiwidG9rZW5fdHlwZSI6IkJlYXJlciIsImF1dGhHcmFudElkIjoibko4bmh5bEM4S3g5RFk4bDJTSGxvcHdDZmJnIiwiYXVkIjoiZGFzLWFwaS1hdXRoIiwibmJmIjoxNjIyNDU0OTUzLCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwic2NvcGUiOlsiZGFzLWFwaS9kYXMtYWNjZXNzIl0sImF1dGhfdGltZSI6MTYyMjQ1NDk1MywicmVhbG0iOiIvIiwiZXhwIjoxNjIyNDU4NTUzLCJpYXQiOjE2MjI0NTQ5NTMsImV4cGlyZXNfaW4iOjM2MDAsImp0aSI6InJvRzhtcWE4WjFaM0YwME1kMjB2VW95aEEwSSJ9.d1EEdioprD2AxQxQcVj0zlN8hvSaIdtub0Lk887m52qEKFt9YiW3uGhpw8bMnhwsUyBbbdFq1flA3pVdKYAdNhQ2dRBIemTH8_NjA4l4giGpLeKJ7WRQA-ldsWrrLkLkVu7gbx7TmMLrTkXgL17kiLdPQ44S1O6LKX52v3KkT0XYEyMYIuzYlnMBs1GQWkoJEALZVIH3TtaAG22o4dxlCcMVxUCo-SyOctjRkfmLvuKEXpDvAG2F93o61Mz1sOtSC2m6nBQA9zd3MxtNd5vd0791QH16Of53IozPj7jRXblYCYq9SJyXzdHN7IEJWrT7C1vvwFVnq8c8QArKsMmgBw'
        scope: das-api/das-exchange
        token_type: Bearer
        expires_in: 3526

    exampleOfDocumentRequestStatistcis:
      value:
        registrations:
          - officeFirstFiling: US
            documentKindCategory: design
            year: 2021
            month: 3
            totalQuantity: 10
          - officeFirstFiling: US
            documentKindCategory: design
            year: 2021
            month: 2
            totalQuantity: 15
          - officeFirstFiling: US
            documentKindCategory: design
            year: 2021
            month: 1
            totalQuantity: 23
        retrievals:
          - officeFirstFiling: US
            officeSecondFiling: IN
            documentKindCategory: design
            year: 2021
            month: 54
            totalQuantity: 10
          - officeFirstFiling: US
            officeSecondFiling: IN
            documentKindCategory: design
            year: 2021
            month: 2
            totalQuantity: 57
          - officeFirstFiling: US
            officeSecondFiling: IN
            documentKindCategory: design
            year: 2021
            month: 1
            totalQuantity: 62

    exampleOfServiceInformation:
      value:
        applicationName: "DAS business service"
        applicationVersion: "3.2.2"
        buildDate: "2020-11-17"
        buildTime: "14:53:10Z"
        codeBranch: "3.2.2"
        codeRevision: "#109" 

    exampleOfDocumentRegistrationRequest:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751

    exampleOfDocumentRetrievalRequestBag:
      value:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-23"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:

    exampleOfDocumentRetrievalRequestAckBag:
      value:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-23"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          requestAckId: USIB20210523120902201
          operationDateTime: "2020-05-23T12:23:24Z"
        
    exampleOfRecordedDocumentRequests:
      value:
        filter:
          officeCode:
          operationCategory: 
          startDate:
          endDate:
          documentKindCategory: 
          documentNumber:
          requestStatusCategory:
          limit: 50
          offset: 0
          countOnly: false
          sortedBy: 'date:desc'
        totalQuantity: 3
        recordedDocumentRequestBag:
        - operationCategory: registration
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
          requestAckId: ESIB202105231120902201
          operationDateTime: "2020-05-23T12:23:24Z"
          fileLocationUrl:
          requestStatusCategory: successful
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: 
          requestAckId: USIB20210323120902201
          operationDateTime: "2020-03-23T12:23:24Z"
          fileLocationUrl: https://s3.amazonaws.com/<your-bucket-id>/...
          requestStatusCategory: successful
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: 
          requestAckId: JPIB20210123120902201
          operationDateTime: "2020-01-23T12:23:24Z"
          fileLocationUrl: https://s3.amazonaws.com/<your-bucket-id>/...
          requestStatusCategory: successful

    exampleOfRecordedDocumentRequestCount:
      value:
        filter:
          officeCode:
          operationCategory: 
          startDate:
          endDate:
          documentKindCategory: 
          documentNumber:
          requestStatusCategory:
          limit: 50
          offset: 0
          countOnly: true
          sortedBy: 'date:desc'
        total: 56
        recordedDocumentRequestBag:

    exampleOfDocumentRetrievalRequestAckIds:
      value:
        requestAckIdBag:
        - USIB20210523120902201

    exampleOfDocumentNotifications:
      value:
        systemId: WIPO DAS
        notificationCategory: Document availability
        dateTime: '2020-01-23T12:23:24Z'
        documentRetrievalResponseBag:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-23"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          requestAckId: USIB20210523120902201
          operationDateTime: "2020-05-23T12:23:24Z"
          fileLocationUrl: https://s3.amazonaws.com/<your-bucket-id>/...
          requestStatusCategory: successful

  # 2 file upload for subsequest registration
    example-FileDetails:
      value:  
        fileReference: 2021060129292992020
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileId: JP-bf5f35ff-2a94-4082-8c1c-02e321178232
        fileDateTime: "2021-04-23T12:23:24Z"
        fileSizeQuantity: 419430400
        fileStatusCategory: validated

    example-FileUploadRequest:
      value:  
        fileReference: 2021060129292992020
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
          
    example-FileUploadResponse:
      value:  
        fileReference: 2021060129292992020
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileId: JP-bf5f35ff-2a94-4082-8c1c-02e321178232
        fileUploadUrl: https://s3.amazonaws.com/<your-bucket-id>/...

    example-FileDownloadRequest:
      value:  
        fileId: US-bf5f35ff-2a94-4082-8c1c-02e321178232
        requestAckId: USIB20210523120902201
          
    example-FileDownloadResponse:
      value:  
        fileId: US-bf5f35ff-2a94-4082-8c1c-02e321178232
        requestAckId: USIB20210523120902201
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileDownloadUrl: https://s3.amazonaws.com/<your-bucket-id>/...

#----------------------Error Examples-----------------------        
    exampleOfErrorDocumentDetails:
      value:
        code: 100
        details: 'Invalid document number or date format'
        moreInfo:

    exampleOfErrorFileIncomplet:
      value:
        code: 101
        details: 'File content incomplete'
        moreInfo:

    exampleOfErrorEmailFormat:
      value:
        code: 102
        details: 'Invalid email format'
        moreInfo:

    exampleOfErrorDocumentAlreadyRegistered:
      value:
        code: 103
        details: 'Document already registered'
        moreInfo: 
        - 'For content replacement, please use the PUT operation'

    exampleOfErrorDocumentUpdate:
      value:
        code: 104
        details: 'Document not yet registered'
        moreInfo: 
        - 'For regitration, please use the POST operation'

    exampleOfErrorDASAccessCode:
      value:
        code: 104
        details: 'DAS access code cannot be changed'
        moreInfo: 

    exampleOfErrorFilter:
      value:
        code: 1
        details: "Invalid filter values - sortedBy='date'&countOnly="
        moreInfo:

    exampleOfErrorNotificationDetails:
      value:
        code: 2
        details: 'Invalid notification details'
        moreInfo:

    exampleOfErrorFileId:
      value:
        code: 3
        details: 'Invalid file Id'
        moreInfo:

    exampleOfErrorRetrievalDetails:
      value:
        code: 200
        details: 'Invalid retrieval details'
        moreInfo:

    exampleOfErrorFileDetails:
      value:
        code: 201
        details: 'Invalid file format or checksum'
        moreInfo:

    exampleOfError401:
      value:
        code: 20
        details: 'Authentication is missing or invalid'
        moreInfo:
        - 'Please give a valid authentication token'

    exampleOfError500:
      value:
        code: 20
        details: 'Internal server error'
        moreInfo:
        - 'Please try this operation again later'
    
  
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows: 
        clientCredentials: 
          tokenUrl: https://login.wipo.int/am/v1/oauth2/access_token
          scopes: {} # Getty Images does not use scopes
