openapi: 3.0.0
info:
  description: |
    This is the draft version 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. 

    Revision History:

    Changes on 2024-12-12
    - corrected the successful response of the notification service to use the http code of 204 instead of 201 because there is no content in the response body
    - added a new service to allow finding existing registered documents by using document number only   

    Changes on 2024-03-04
    - corrected the examples of application error responses by removing the wrapper error element   

    Changes on 2024-01-14
    - restructured requestStatusCategory to 2 or 3 possible values 
      only (pending,success,error) based on the type of operations (registration or retrieval) 
      to provide in case of pending and error more details in two other attributes 
      errorCode and statusMessage 
    - included error details in the notification of the retrieval result to OSF 
    - added documentAvailabilityDate attribute 
    - renamed notification data element from DocumentRegistrationStatus to DocumentAvailability
    - renamed data element DocumentRetrievalBag to DocumentRetrievalResponseBag
    - renamed data element DocumentRetrievalRequestStatus to DocumentNotificationRetrievalStatus to include more attributes for details
    - added a provision to support withdrawal of registered documents 
   
    Changes on 2023-05-30
    - updated with a service to check document availability for integration with external systems, 
      system error code range, URLs to align with WIPO cloud environments 
    - added a service to retrieve registration certificate and an example fo 500 error details  
    - corrected a few paragraphs in description  
    - updated to handle error encountered in file upload using url-uploads service
    - updated to handle registration error details in response to the registration status check    
    - updated to add service to find retrievals that are in process or newly completed with details to download document 
  version: "1.0"
  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.ipobs.acc.web1.wipo.int:{port}'
    description: Test DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'
  - url: 'https://das.ipobs.dev.web1.wipo.int:{port}'
    description: Development DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'

tags:
  - name: information 
    description: >
      Health check of the DAS api
  - name: requests
    description: >
      Document Requests 

security: 
  - bearerAuth: [] 

paths:
  /am/v1/oauth2/access_token:
    post:
      tags:
        - authorization
      description: >
        Service to authorize use of the DAS api. This is the endpoint of a third party product that supports **OpenID Connect (OIDC)** authentication protocol based on the OAuth 2.0 family of specifications
      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/office-exchange'
                  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: private key of the 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 system error
          content: 
            {}

  /das-api/v1/services:
    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'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
  
  /das-api/v1/requests/files/url-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
        In the initial implementation, the flow for registration with document content consists of 3 service calls:
        - (POST) /das-api/v1/requests/files/url-uploads
        - (PUT) {presigned-url}
        - (POST) /das-api/v1/requests/registrations

        The alternative flow can be used in future in the following order. 
        - (POST) /das-api/v1/requests/registrations
        - (POST) /das-api/v1/requests/files/url-uploads
        - (PUT) {presigned-url}
        
        In these two flows, the requestAckId should be the ackId received in response of the first registration service call by OFF
        The document is permanently stored in WIPO DAS.
        
        This service can also be used to upload the requested document in response to a particular OFF request identified issued by the OFF when 
        the request is forwarded by WIPO DAS. In this flow, the document is not permanently stored in WIPO DAS. 
      summary: obtain file Id 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-Offices:
                $ref: '#/components/examples/example-FileUploadRequestOffices'
              FileUploadRequest-OfficePortal:
                $ref: '#/components/examples/example-FileUploadRequestOfficePortal'
              FileUploadRequest-TDA:
                $ref: '#/components/examples/example-FileUploadRequestTDA'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
              examples:
                FileUploadResponse:
                  $ref: '#/components/examples/example-FileUploadResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400MissingFileChecksum:
                  $ref: '#/components/examples/error400MissingFileChecksum'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    put:
      tags:
        - requests
      description: >
        update an existing upload request with a new 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 a new presigned URL related to an existing fileId to upload a big size document file for registration by OFF which does not have digital library
      operationId: updateFileUploadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileId'
            examples:
              FileId:
                $ref: '#/components/examples/example-FileId'
      responses:
        '204':
          description: successful operation
          headers:
            Location:
              schema:
                type: string
              description: New presigned url for updating the file content to WIPO DAS
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400FileId:
                  $ref: '#/components/examples/error400FileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/v1/requests/files/url-downloads:
    post:
      tags:
        - requests
      description: >
        retrieve WIPO DAS URLs to download document file contents without any limitation in file sizes.
      summary: retrieve WIPO DAS URLs to download document file contents 
      operationId: getFileDownloadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileDownloadRequest'
            examples:
              FileDownloadRequest:
                $ref: '#/components/examples/example-FileDownloadRequest'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDownloadResponse'
              examples:
                FileDownloadResponse:
                  $ref: '#/components/examples/example-FileDownloadResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created download presigned URL
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400MissingFileChecksum:
                  $ref: '#/components/examples/error400MissingFileChecksum'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/v1/requests/files:
    get:
      tags:
        - requests
      description: >
        retrieve file details of a file content identified by the id given by the POST service of /requests/files/uploads
      summary: obtain file details identified by the given fileId 
      operationId: RetrieveFileDetailsById
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: query
          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:
                error400FileId:
                  $ref: '#/components/examples/error400FileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    delete:
      tags:
        - requests
      description: >
        delete the file from DAS transit identified by the id given by the POST service of /requests/files/uploads
      summary: delete from DAS transit the file by the given fileId 
      operationId: DeleteFileById
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400FileId:
                  $ref: '#/components/examples/error400FileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '403':
          description: Forbidden operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error403OperationForbidden:
                  $ref: '#/components/examples/error403OperationForbidden'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/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-offices:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequestOffices'
              DocumentRegistrationRequest-SFTP:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequestSFTP'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRegistrationResponse'
              examples:
                DocumentRegistrationResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationRecordedResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400DocumentDetails:
                  $ref: '#/components/examples/error400DocumentDetails'
                error400FileId:
                  $ref: '#/components/examples/error400FileId'
                error400FileCorrupted:
                  $ref: '#/components/examples/error400FileCorrupted'
                error400EmailFormat:
                  $ref: '#/components/examples/error400EmailFormat'
                error400FileAlreadyRegistered:
                  $ref: '#/components/examples/error400FileAlreadyRegistered'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system 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 and/or correct the document date and/or parent application details.
        Note: Document number and DAS access code cannot be changed once the document is registered in WIPO DAS.
      summary: update a registered document content with a new fileId and/or correct the document date and/or parent application details
      operationId: updateRegisteredDocument
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRegistrationRequest'
            examples:
              DocumentRegistrationRequest-offices:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequestOffices'
              DocumentRegistrationRequestSFTP:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequestSFTP'
      responses:
        '204':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400DocumentDetails:
                  $ref: '#/components/examples/error400DocumentDetails'
                error400FileId:
                  $ref: '#/components/examples/error400FileId'
                error400FileCorrupted:
                  $ref: '#/components/examples/error400FileCorrupted'
                error400EmailFormat:
                  $ref: '#/components/examples/error400EmailFormat'
                error400DocumentNotAvailable:
                  $ref: '#/components/examples/error400DocumentNotAvailable'
                error400MismatchedDASAccessCode:
                  $ref: '#/components/examples/error400MismatchedDASAccessCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    delete:
      tags:
        - requests
      description: >
        withdraw a registered document (implementation in the second quarter of 2024)
      summary: withdraw a registered document (can only be performed by the same depositing office that registered it)
      operationId: WithdrawRegistration
      security:
        - bearerAuth: []
      parameters:
        - name: documentKindCategory
          in: query
          required: true
          schema:
            type: string
        - name: documentCodeCategory
          in: query
          required: false
          schema:
            type: string
        - name: documentNumber
          in: query
          required: true
          schema:
            type: string
        - name: documentDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: dasAccessCode
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRegistrationResponse'
              examples:
                DocumentRegistrationWithdrawalResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationWithdrawalResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400FileId:
                  $ref: '#/components/examples/error400FileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '403':
          description: Forbidden operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error403OperationForbidden:
                  $ref: '#/components/examples/error403OperationForbidden'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    get:
      tags:
        - requests
      description: >
        get the status of a recorded request for document registration from OFF to WIPO DAS 
      summary: get the status of a recorded request for document registration from OFF to WIPO DAS 
      operationId: getStatusDocumentRegistrationRequest
      security:
        - bearerAuth: []
      parameters:
        - name: requestAckId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRegistrationResponse'
              examples:
                DocumentRegistrationRecordedResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationRecordedResponse'
                DocumentRegistrationUpdatedResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationUpdatedResponse'
                DocumentRegistrationFailedResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationFailedResponse'
        '303':
          description: see other
          headers:
            Location:
              schema:
                type: string
              description: URI to download the document
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400InvalidAckId:
                  $ref: '#/components/examples/error400InvalidAckId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/v1/requests/registrations/certificates:
    get:
      tags:
        - requests
      description: >
        retrieve the certificate of availability of the specified document 
      summary: retrieve the certificate of availability of the specified document 
      operationId: retrieveDocumentCertificate
      parameters:
        - name: documentKindCategory
          in: query
          required: true
          schema:
            type: string
        - name: documentCodeCategory
          in: query
          required: false
          schema:
            type: string
        - name: documentNumber
          in: query
          required: true
          schema:
            type: string
        - name: documentDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: dasAccessCode
          in: query
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400DocumentNotAvailable:
                  $ref: '#/components/examples/error400DocumentNotAvailable'
                error400DocumentDetails:
                  $ref: '#/components/examples/error400DocumentDetails'
                error400MismatchedDASAccessCode:
                  $ref: '#/components/examples/error400MismatchedDASAccessCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '403':
          description: Operation forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error403DocumentWithdrawn:
                  $ref: '#/components/examples/error403DocumentWithdrawn'
                error403ClearanceNotGranted:
                  $ref: '#/components/examples/error403ClearanceNotGranted'
                error403DocumentIncomplet:
                  $ref: '#/components/examples/error403DocumentIncomplet'
                error403OperationForbidden:
                  $ref: '#/components/examples/error403OperationForbidden'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/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/DocumentRetrievalRequest'
            examples:
              DocumentRetrievalRequest:
                $ref: '#/components/examples/exampleOfDocumentRetrievalRequest'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRetrievalResponse'
              examples:
                DocumentRetrievalResponsePending:
                  $ref: '#/components/examples/exampleOfDocumentRetrievalResponsePending'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400DocumentNotAvailable:
                  $ref: '#/components/examples/error400DocumentNotAvailable'
                error400DocumentDetails:
                  $ref: '#/components/examples/error400DocumentDetails'
                error400MismatchedDASAccessCode:
                  $ref: '#/components/examples/error400MismatchedDASAccessCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '403':
          description: Operation forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error403DocumentWithdrawn:
                  $ref: '#/components/examples/error403DocumentWithdrawn'
                error403ClearanceNotGranted:
                  $ref: '#/components/examples/error403ClearanceNotGranted'
                error403DocumentIncomplet:
                  $ref: '#/components/examples/error403DocumentIncomplet'
                error403OperationForbidden:
                  $ref: '#/components/examples/error403OperationForbidden'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    get:
      tags:
        - requests
      description: >
        get the recorded requests for document retrievals from OSF to WIPO DAS or WIPO DAS to OFF 
      summary: get the recorded requests for document retrievals from OSF to WIPO DAS or WIPO DAS to OFF
      operationId: getDocumentRetrievals
      security:
        - bearerAuth: []
      parameters:
        - name: requestAckId
          in: query
          required: true
          schema:
            type: string
        - name: documentKindCategory
          in: query
          required: true
          schema:
            type: string
            enum: [design,patent,trademark,utility model]
        - name: documentNumber
          in: query
          required: true
          schema:
            type: string
            description: priority document number starting with the two-letter office code, but it may contain wildcard characters '*' and '?' 
        - name: documentDate
          in: query
          required: true
          schema:
            type: string
            format: date
            description: date format in the format of yyyy-mm-dd            
      responses:
        '200':
          description: successful operation if requestAckId is provided but the requested document is not yet available for download or if status is provided in order to retrieve newly available document details or pending retrievals 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRetrievalResponseBag'
              examples:
                DocumentRetrievalResponseBag:
                  $ref: '#/components/examples/exampleOfDocumentRetrievalResponseBag'
        '303':
          description: successful operation with redirection to download the document
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the URL to download the document 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400InvalidAckId:
                  $ref: '#/components/examples/error400InvalidAckId'
                error400DocumentDetails:
                  $ref: '#/components/examples/error400DocumentDetails'
                error400DocumentNotAvailable:
                  $ref: '#/components/examples/error400DocumentNotAvailable'
        '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 retrieval request with a new fileId by OSF.
      summary: update a retrieval request with a new fileId by OsfAckId
      operationId: updateRetrievalRequest
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRetrievalRequest'
            examples:
              ExampleUpdateRetrievalRequest:
                $ref: '#/components/examples/ExampleUpdateRetrievalRequest'
      responses:
        '204':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400InvalidAckId:
                  $ref: '#/components/examples/error400InvalidAckId'
                error400FileId:
                  $ref: '#/components/examples/error400FileId'

        '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-api/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:
        '204':
          description: successful operation when all provided ack-ids are valid
        '400':
          description: Bad request. It might be possible that some of the provided ack-ids are not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400NotificationDetails:
                  $ref: '#/components/examples/error400NotificationDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/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: true
          schema:
            type: string 
            description: "two-letter office code"
        - name: operationCategory
          in: query
          required: true
          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: [pending,success,error]
        - name: userName
          in: query
          required: false
          schema:
            type: string
            description: user name. records created by provided user will be returned.
        - 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: string
            default: 
            description: key of the last evaluated item. System will search records after this record.
        - 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:
                error400FilterCriteria:
                  $ref: '#/components/examples/error400FilterCriteria'
                error400InvalidOfficeCode:
                  $ref: '#/components/examples/error400InvalidOfficeCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/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 specified for operationCategory, statistics includes registrations and retrievals
      summary:  retrieve exchange statistics of offices. 
      operationId: getRequestStatistics
      security:
        - bearerAuth: []
      parameters:
        - name: officeCode
          in: query
          required: true
          schema:
            type: string 
            description: "two-letter office code"
        - name: operationCategory
          in: query
          required: false
          schema:
            type: string 
            enum: [registration,retrieval]
        - name: startYear
          in: query
          required: false
          schema:
            type: integer
            format: int8
            description: year format in the format of yyyy
        - name: endYear
          in: query
          required: false
          schema:
            type: integer
            format: int8
            description: year format in the format of yyyy
        - name: documentKindCategory
          in: query
          schema:
            type: string 
            enum: [design,patent,trademark,utility model]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestStatistics'
              examples:
                exampleOfDocumentRequestStatistics:
                  $ref: '#/components/examples/exampleOfDocumentRequestStatistics'  
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400MissingOfficeCode:
                  $ref: '#/components/examples/error400MissingOfficeCode'  
                error400InvalidOfficeCode:
                  $ref: '#/components/examples/error400InvalidOfficeCode'             
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/v1/services/das-offices:  
    get:
      tags:
        - information
      description: >
        get DAS office or list of offices with their access scope information
      summary:  get DAS office or list of offices with their access scope information
      operationId: getDasOffices
      security:
        - bearerAuth: []
      parameters:
        - name: officeCode
          in: query
          required: false
          schema:
            type: string 
            description: "two-letter office code"
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DASOfficeResponse'
              examples:
                exampleOfDASOfficeResponse:
                  $ref: '#/components/examples/exampleOfDASOfficeResponse'  
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400InvalidOfficeCode:
                  $ref: '#/components/examples/error400InvalidOfficeCode'                
        '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-api/v1/documents/numbers:  
    get:
      tags:
        - documents
      description: >
        Get the list of available application types (IP rights) and number formats
      summary: Get the list of available application types (IP rights) and number formats
      operationId: readNumberFormats
      parameters:
        - name: officeCode
          in: query
          required: true
          schema:
            type: string
        - name: documentKindCategory
          in: query
          required: false
          schema:
            type: string
        - name: input
          in: query
          required: false
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentNumberFormats'
              examples:
                exampleOfDocumentNumberFormats:
                  $ref: '#/components/examples/exampleOfDocumentNumberFormats'
                exampleOfInvalidDocumentNumberFormat:
                  $ref: '#/components/examples/exampleOfInvalidDocumentNumberFormat'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400InvalidOfficeCode:
                  $ref: '#/components/examples/error400InvalidOfficeCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/v1/documents/registrations:  
    get:
      tags:
        - documents
      description: >
        lookup registered documents by document number
      summary: Check the availability of priority documents in WIPO DAS by document number 
      operationId: queryDocumentsByNumber
      parameters:
        - name: documentNumber
          in: query
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredDocuments'
              examples:
                exampleOfRegisteredDocuments:
                  $ref: '#/components/examples/exampleOfRegisteredDocuments'
            application/xml:
              schema:
                type: string
                format: binary
        '400':
          description: Bad input parameters. It includes also the case when specified documentNumber parameter matches existing records in WIPO DAS, but other parameters are wrong or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400DocumentNotAvailable:
                  $ref: '#/components/examples/error400DocumentNotAvailable'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das-api/v1/documents/registrations/statuses:  
    get:
      tags:
        - documents
      description: >
        Check whether a document is available in WIPO DAS
      summary: Check the availability of a priority document in WIPO DAS 
      operationId: checkDocumentAvailability
      parameters:
        - name: documentNumber
          in: query
          required: true
          schema:
            type: string
        - name: documentKindCategory
          in: query
          required: false
          schema:
            type: string
        - name: documentDate
          in: query
          required: false
          schema:
            type: string
        - name: dasAccessCode
          in: query
          required: false
          schema:
            type: string
        - name: documentCodeCategory
          in: query
          required: false
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentAvailability'
              examples:
                exampleOfRegisteredDocument:
                  $ref: '#/components/examples/exampleOfRegisteredDocument'
            application/xml:
              schema:
                type: string
                format: binary
        '400':
          description: Bad input parameters. It includes also the case when specified documentNumber parameter matches existing records in WIPO DAS, but other parameters are wrong or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                error400SeveralInputData:
                  $ref: '#/components/examples/error400SeveralInputData'
                error400DocumentDetails:
                  $ref: '#/components/examples/error400DocumentDetails'
                error400MismatchedDASAccessCode:
                  $ref: '#/components/examples/error400MismatchedDASAccessCode'
                error400DocumentNotAvailable:
                  $ref: '#/components/examples/error400DocumentNotAvailable'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system 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
        codeBranch: 
          type: string
        buildNumber:
          type: string

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

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

    DocumentRequestStatistics:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/StatisticsFilter'
        registrations:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRegistrationRequestStatistics'
        retrievals:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalRequestStatistics'

    StatisticsFilter:
      type: object
      properties:
        officeCode:
          type: string
          description: two-letter office code
        operationCategory:
          type: string
          enum: [registration,retrieval]
        startYear:
          type: integer
          format: int8
          description: year format in the format of yyyy
        endDate:
          type: integer
          format: int8
          description: year format in the format of yyyy
        documentKindCategory:
          enum: [design,patent,trademark,utility model]

    DASOfficeOperationCategory:
      type: object
      properties:
        depositingOffice:
          type: boolean      
        accessingOffice:
          type: boolean      

    DASDocumentKindCategory:
      type: object
      properties:
        officeCode:
          type: string       
        operationCategory:
          $ref: '#/components/schemas/DASOfficeOperationCategory'       


    DASOffice:
      type: object
      properties:
        officeCode:
          type: string       
        documentKindCategories:
          type: array
          items:
            $ref: '#/components/schemas/DASDocumentKindCategory'


    DASOfficeResponse:
      type: array
      items:
        $ref: '#/components/schemas/DASOffice'

    DocumentRequest:
      type: object
      properties:
        operationCategory:
          type: string
          enum: [registration,retrieval]
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        documentCodeCategory:
          type: string
          description: 'priority document'
        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: date 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
        revocationDate:
          type: string
          format: date
          example: "2020-05-01"
          description: timestamp in the form of yyyy-mm-dd. Date of revocation of the document.
          
    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: file Id of the requested document content which can be securely accessed in the transit area of WIPO DAS.
        requestAckId:
          type: string
          description: <b>For DAS participating offices:</b></br><tab>requestAckId is not required to be sent.</br></br> <b>For internal use by WIPO DAS:</b></br> For SFTP calls- requestAckId generated by offices is required in SFTP requests. This requestAckId is referred as OffAckId in registration.         

    DocumentRegistrationResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentRegistrationRequest'
        - type: object
      properties:
        documentAvailabilityDate:
          type: string
          format: date
          example: '2020-05-01'
          description: date of availability of the document through WIPO DAS
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00:08Z'
          description: operation date and time recorded and provided in response only
        requestStatusCategory:
          type: string
          enum: [success,error]
        errorCode:
          type: string
          description: type of errors
        statusMessage:
          type: string
          description: more details 

    RegisteredDocuments:
      type: array
      items:
        $ref: '#/components/schemas/DocumentAvailability'
      
    DocumentAvailability:
      type: object
      properties:
        officeCode:
          type: string
          description: two-letter office code
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        documentCodeCategory:
          type: string
          description: 'priority document'
        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: date 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
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00:08Z'
          description: registration date and time recorded in WIPO DAS
        documentStatusCodeCategory:
          type: string
          enum: [document registered,document not registered]
          description: 'document registered'
        documentAvailabilityDate:
          type: string
          format: date
          example: '2020-05-01'
          description: date of availability of the document through WIPO DAS

    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: file Id of the requested 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
        requestStatusCategory:
          type: string
          enum: [pending,success,error]
        errorCode:
          type: string
          description: error details -> document withdrawn, 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
        statusMessage:
          type: string
          description: error details -> document withdrawn, 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

    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: [pending,success,error]
        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
        lastEvaluatedKey:
          type: string
          description: When there are many records out of which few records are fetched, response will contain lastEvaluatedKey=PK of the last item retrieved from DB. This will be used in next query to fetch next records (pagination). This parameter is applicable only if countOnly request parameter is 'false'        
        recordedDocumentRequestBag:
          type: array
          items:
            $ref: '#/components/schemas/RecordedDocumentRequest'

    UpdateRetrievalRequest:
      properties:
        requestAckId:
          type: string
          description: OSFAckId of the retrieval request intended to update.         
        fileId:
          type: string
          description: New file Id that needs to be updated.

    DocumentRetrievalRequest:
      $ref: '#/components/schemas/DocumentRequest'
        
    DocumentRetrievalResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentRetrievalRequest'
        - type: object
      properties:
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        documentAvailabilityDate:
          type: string
          format: date
          example: '2020-05-01'
          description: date of availability of the document through WIPO DAS
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00.00.000Z'
          description: operation date and time recorded and provided in response only
        requestStatusCategory:
          type: string
          enum: [pending,success,error]
        fileDownloadUrl:
          type: string
          description: the pre-signed url created by WIPO DAS to download file content 
        errorCode:
          type: string
          description: type of errors
        statusMessage:
          type: string
          description: 'more details (ex: delivered,ready for download,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, etc.)'

    DocumentRetrievalResponseBag:
      type: object
      properties:
        officeCode:
          type: string
        documentQuantity:
          type: integer
          format: int8
        documentRetrievalResponses:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalResponse'          

    DocumentNotificationRetrievalStatus:
      type: object
      properties:
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        requestStatusCategory:
          type: string
          enum: [pending,success,error]
        errorCode:
          type: string
          description: type of errors
        statusMessage:
          type: string
          description: 'more details (ex: delivered,ready for download,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, etc.)'

    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"
        totalQuantity:
          type: integer
          format: int8
        documentNotificationRetrievalStatusBag:
          type: array
          items:
            $ref: '#/components/schemas/DocumentNotificationRetrievalStatus'

    FileId:
      type: object
      properties:
        fileId:
          type: string
          description: fileId of an existing upload request

    FileUploadRequest:
      type: object
      properties:
        fileReference:
          type: string
          description: <b>For DAS participating offices:</b></br> optional reference used by the service consumer to identify the file.</br></br> <b>For internal use by WIPO DAS:</b></br> 1. For office portal calls- It will contain file name to identify the uploaded file name<br>2. For TDA calls- It will contain "documentKindCategory#documentNumber" to identify the document number for which file is uploaded.
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
          description: this attribute is optional
        fileChecksum:
          type: string
          description: mandatory checksum of the file to upload for validation purpose 
        requestAckId:
          type: string
          description: This attribute should only be specified if the upload file is related to an existing DAS request identified by requestAckId. For example, the OFF uploads the file to WIPO DAS for exchange with another requestor office OSF

    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 
        requestAckId:
          type: string
          description: ackId is provided for upload of a document hosted by the digital library of the OFF, which is requested by an OSF

    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: [error,validated,registered]
          description: empty value when the record is created, validated value if the content of the file has been validated by WIPO DAS with the expected checksum as specified in the upload request, registered value once the fildId is used in a registration request. File details can only be read or file content can be written or downloaded by the requestor.
        error:
          type: string
          description: error details if fileStatusCategory is error

    FileDownloadRequest:
      type: object
      properties:
        documentKindCategory:
          type: string
        documentNumber: 
          type: string
        documentDate:
          type: string
        osfAckId:
          type: string
          description: request acknowledgement id issued by WIPO upon reception of the document retrieval request from OSF

    FileDownloadResponse:
      allOf:
        - $ref: '#/components/schemas/FileDownloadRequest'
        - type: object
      type: object
      properties:
        fileDownloadUrl:
          type: string
          description: the pre-signed url created by WIPO DAS to download file content 
        offAckId:
          type: string
          description: request acknowledgement id issued by the OFF upon reception of the document retrieval request from WIPO
        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: [error,validated,registered]
          description: empty value when the record is created, validated value if the content of the file has been validated by WIPO DAS with the expected checksum as specified in the upload request, registered value once the fildId is used in a registration request. File details can only be read or file content can be written or downloaded by the requestor.
        error:
          type: string
          description: error details if fileStatusCategory is error

    NumberFormat:
      type: object
      properties:
        value:
          type: string
        regex:
          type: string
        example:
          type: string

    DocumentNumberFormat:
      type: object
      properties:
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        numberFormats:
          type: array
          items:
            $ref: '#/components/schemas/NumberFormat'

    DocumentNumberFormats:
      type: object
      properties:
        officeCode:
          type: string
        input:
          type: string
        valid:
          type: boolean
        documentNumberFormats:
          type: array
          items:
            $ref: '#/components/schemas/DocumentNumberFormat'

    Token:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT in base64
        scope:
          type: string
          description: das-api/office-exchange
        tokenType:
          type: string
          description: type of token (e.g. Bearer)
        expiresIn:
          type: integer
          format: int32
          description: expiration time in seconds

#-------------------------------Error Schemas------------------------------
    ServiceError:
      type: object
      example: ServiceError
      properties:
        code:
          type: string
        message:
          type: string
          example: 'consolidated error message if any' 
          description: error description
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'

    ErrorDetails:
      type: object
      example: ErrorDetails
      properties:
        code:
          type: integer
        message:
          type: string
          example: 'document number does not exist: XX-TM-2020-299992' 
          description: error description

#---------------------------------------------------------------
#                Examples
#---------------------------------------------------------------
  examples:
    exampleOfToken:
      value:
        accessToken: 'eyJ0eXAiOiJKV1QiLCJraWQiOiJmVWRmbEJSa3c5bm1tejcrL3BmMWM5d2RYdXc9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkYXMtYXBpLWF1dGgiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiMTQyYjMwODEtZDNjNy00MjJjLWI4ZDQtNjU4NjkwNjVmMzQ4LTU0OTkxIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbmRldi53aXBvLmludDo0NDMvYW0vb2F1dGgyIiwidG9rZW5OYW1lIjoiYWNjZXNzX3Rva2VuIiwidG9rZW5fdHlwZSI6IkJlYXJlciIsImF1dGhHcmFudElkIjoibko4bmh5bEM4S3g5RFk4bDJTSGxvcHdDZmJnIiwiYXVkIjoiZGFzLWFwaS1hdXRoIiwibmJmIjoxNjIyNDU0OTUzLCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwic2NvcGUiOlsiZGFzLWFwaS9kYXMtYWNjZXNzIl0sImF1dGhfdGltZSI6MTYyMjQ1NDk1MywicmVhbG0iOiIvIiwiZXhwIjoxNjIyNDU4NTUzLCJpYXQiOjE2MjI0NTQ5NTMsImV4cGlyZXNfaW4iOjM2MDAsImp0aSI6InJvRzhtcWE4WjFaM0YwME1kMjB2VW95aEEwSSJ9.d1EEdioprD2AxQxQcVj0zlN8hvSaIdtub0Lk887m52qEKFt9YiW3uGhpw8bMnhwsUyBbbdFq1flA3pVdKYAdNhQ2dRBIemTH8_NjA4l4giGpLeKJ7WRQA-ldsWrrLkLkVu7gbx7TmMLrTkXgL17kiLdPQ44S1O6LKX52v3KkT0XYEyMYIuzYlnMBs1GQWkoJEALZVIH3TtaAG22o4dxlCcMVxUCo-SyOctjRkfmLvuKEXpDvAG2F93o61Mz1sOtSC2m6nBQA9zd3MxtNd5vd0791QH16Of53IozPj7jRXblYCYq9SJyXzdHN7IEJWrT7C1vvwFVnq8c8QArKsMmgBw'
        scope: das-api/office-exchange
        tokenType: Bearer
        expiresIn: 3600

    exampleOfDocumentRequestStatistics:
      value:
        filter:
          officeCode:
          operationCategory:
          startYear:
          endYear:
          documentKindCategory:
        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

    exampleOfDASOfficeResponse:
      value:
        - officeCode: us
          documentKindCategories: 
            - documentKindCategory: design
              operationCategory: 
                depositingOffice: true
                accessingOffice: true
            - documentKindCategory: trademark
              operationCategory: 
                depositingOffice: false
                accessingOffice: true        
        - officeCode: ca
          documentKindCategories: 
            - documentKindCategory: design
              operationCategory: 
                depositingOffice: true
                accessingOffice: true
            - documentKindCategory: patent
              operationCategory: 
                depositingOffice: true
                accessingOffice: true
                
    exampleOfServiceInformation:
      value:
        applicationName: "DAS business service"
        applicationVersion: "1.0.85"
        buildDate: "2022-07-20T09:21:04.815+02:00"
        codeBranch: "DAS_Rest_API-develop"
        buildNumber: "85" 
        
    exampleOfDocumentRegistrationRequestOffices:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751

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

    exampleOfDocumentRegistrationRecordedResponse:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2012-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
        requestAckId: ESIB20210523120902201
        documentAvailabilityDate: "2012-05-23"
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "success"
        errorCode:
        statusMessage:

    exampleOfDocumentRegistrationUpdatedResponse:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2012-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
        requestAckId: ESIB20210523120902201
        documentAvailabilityDate: "2012-05-23"
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "success"
        errorCode:
        statusMessage: document content updated

    exampleOfDocumentRegistrationFailedResponse:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2012-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
        requestAckId: ESIB20210523120902201
        documentAvailabilityDate: 
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "error"
        errorCode: INVALID_INPUT_DATA
        statusMessage: 'invalid file checksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9'

    exampleOfDocumentRegistrationWithdrawalResponse:
      value:
        operationCategory: registration
        documentKindCategory: 'patent'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES 201430131'
        documentDate: "2014-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate: "2014-05-25"
        email:
        fileId: 
        requestAckId: ESIB20210523120902201
        documentAvailabilityDate: 
        operationDateTime: "2012-05-23T12:23:24Z"
        requestStatusCategory: "success"
        errorCode: 
        statusMessage: 'document withdrawn'

    exampleOfRegisteredDocument:
      value:
        officeCode: ES
        documentKindCategory: 'patent'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES 201630131'
        documentDate: "2016-01-23"
        dasAccessCode: ABCD
        operationDateTime: "2020-05-23T12:23:24Z"
        documentStatusCategory: "document registered"
        documentAvailabilityDate: '2016-03-23'

    exampleOfRegisteredDocuments:
      value:
        - officeCode: CL
          documentKindCategory: 'patent'
          documentCodeCategory: 'priority document'
          documentNumber: 'CL 2016-0131'
          documentDate: "2016-01-23"
          dasAccessCode: ABCD
          operationDateTime: "2020-05-23T12:23:24Z"
          documentStatusCategory: "document registered"
          documentAvailabilityDate: '2016-03-23'
        - officeCode: CL
          documentKindCategory: 'design'
          documentCodeCategory: 'priority document'
          documentNumber: 'CL 2016-0131'
          documentDate: "2015-12-23"
          dasAccessCode: ABCD
          operationDateTime: "2020-05-23T12:23:24Z"
          documentStatusCategory: "document registered"
          documentAvailabilityDate: '2015-05-13'

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

    exampleOfDocumentRetrievalResponseSuccess:
      value:
        operationCategory: retrieval
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U202030131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        requestAckId: USIB20210523120902201
        documentAvailabilityDate: "2020-02-23"
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "success"
        downloadUrl: "https://s3.amazonaws.com/<your-bucket-id>/..."
        errorCode:
        statusMessage:

    exampleOfDocumentRetrievalResponsePending:
      value:
        operationCategory: retrieval
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U202030131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        requestAckId: USIB20210523120902201
        documentAvailabilityDate: "2020-05-23"
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "pending"
        downloadUrl: "https://s3.amazonaws.com/<your-bucket-id>/..."
        errorCode: 
        statusMessage: processing in progress

    exampleOfDocumentRetrievalResponseError:
      value:
        operationCategory: retrieval
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U200230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        requestAckId: USIB20210523120902201
        documentAvailabilityDate: "2020-05-23"
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "error"
        downloadUrl: "https://s3.amazonaws.com/<your-bucket-id>/..."
        errorCode: INVALID_INPT_DATA
        statusMessage: mismatched access code

    ExampleUpdateRetrievalRequest:
      value:
        requestAckId: USIB20210523120902201
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
        
    exampleOfDocumentRetrievalResponseBag:
      value:
        officeCode: us
        documentQuantity: 1
        documentRetrievalResponses:
          - operationCategory: retrieval
            documentKindCategory: 'design'
            documentCodeCategory: 'priority document'
            documentNumber: 'ES U201230131'
            documentDate: "2012-01-23"
            dasAccessCode: ABCD
            applicationCategory:
            applicationNumber:
            applicationFilingDate:
            requestAckId: ESIB20210523120902201
            documentAvailabilityDate: "2012-02-23"
            operationDateTime: "2020-05-23T12:23:24Z"
            requestStatusCategory: "pending"
            errorCode: 
            statusMessage: awaiting off response

    exampleOfRecordedDocumentRequests:
      value:
        filter:
          officeCode: us
          operationCategory: registration
          startDate:
          endDate:
          documentKindCategory: 
          documentNumber:
          requestStatusCategory:
          limit: 50
          offset: 
          userName: 
          countOnly: false
          sortedBy: 'date:desc'
        totalQuantity: 3
        lastEvaluatedKey: '#REGISTRATION#wo#patent#WO33192022'
        recordedDocumentRequestBag:
        - operationCategory: registration
          documentKindCategory: 'design'
          documentNumber: 'ES U202030131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
          requestAckId: ESIB202105231120902201
          documentAvailabilityDate: "2020-02-21"
          operationDateTime: "2020-05-23T12:23:24Z"
          requestStatusCategory: success
          userName: 
          error:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U202030131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: 
          requestAckId: USIB20210323120902201
          documentAvailabilityDate: "2020-02-21"
          operationDateTime: "2020-03-23T12:23:24Z"
          requestStatusCategory: success
          userName: 
          error:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U202030131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: 
          requestAckId: JPIB20210123120902201
          documentAvailabilityDate: "2020-02-21"
          operationDateTime: "2020-01-23T12:23:24Z"
          requestStatusCategory: success
          userName: 
          error:

    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'
        totalQuantity: 2
        documentNotificationRetrievalStatusBag:
        - requestAckId: ESIB20210523120902201
          requestStatusCategory: success
          errorCode:
          statusMessage:
        - requestAckId: USIB20210523120902201
          requestStatusCategory: error
          errorCode: INVALID_INPUT_DATA
          statusMessage: document incomplete

  # 2 file upload for subsequent 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
        error:

    example-FileId:
      value:  
        fileId: JP-bf5f35ff-2a94-4082-8c1c-02e321178232

    example-FileUploadRequestOfficePortal:
      value:  
        fileReference: "test.zip"
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        requestAckId:

    example-FileUploadRequestTDA:
      value:  
        fileReference: "patent#CA 1234-2022"
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        requestAckId:

    example-FileUploadRequestOffices:
      value:  
        fileReference: "12345678"
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        requestAckId:

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

    example-FileDownloadRequest:
      value:  
        documentKindCategory: 'design'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-21"
        osfAckId: "KRIB20120121001111"

    example-FileDownloadResponse:
      value:  
        documentKindCategory: 'design'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-21"
        fileReference: "US 12/282,110 2012-01-22"
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileId: US-bf5f35ff-2a94-4082-8c1c-02e321178232
        fileDownloadUrl: https://s3.amazonaws.com/<your-bucket-id>/...
        offAckId: "IBUS20130121001234"
        osfAckId: "KRIB20120121001111"
        fileDateTime: "2013-01-12T13:21:00Z"
        fileSizeQuantity: 328238821
        fileStatusCategory: validated
        error:

    exampleOfDocumentNumberFormats:
      value:
        officeCode: CL
        input:
        valid:
        documentNumberFormats:
        - documentKindCategory: 'design'
          numberFormats:
          - number: NNNN-YYYY
            regex: "^[0-9]{1,4}'-'(19|20)[0-9]{2}$"
            example: 1234-2018
        - documentKindCategory: 'patent'
          numberFormats:
          - number: NNNN-YYYY
            regex: "^[0-9]{1,4}'-'(19|20)[0-9]{2}$"
            example: 1234-2018
          - number: "PCT/CLYYYY/NNNNNN"
            regex: ^PCT\/CL(19|20)[0-9]{2}\/[0-9]{6}$"
            example: PCT/CL2018/123456

    exampleOfInvalidDocumentNumberFormat:
      value:
        officeCode: CL
        input: 2024/28292
        valid: false
        documentNumberFormats:
        - documentKindCategory: 'design'
          numberFormats:
          - number: NNNN-YYYY
            regex: "^[0-9]{1,4}'-'(19|20)[0-9]{2}$"
            example: 1234-2018
        - documentKindCategory: 'patent'
          numberFormats:
          - number: NNNN-YYYY
            regex: "^[0-9]{1,4}'-'(19|20)[0-9]{2}$"
            example: 1234-2018
          - number: "PCT/CLYYYY/NNNNNN"
            regex: ^PCT\/CL(19|20)[0-9]{2}\/[0-9]{6}$"
            example: PCT/CL2018/123456
        
#---------------------- Possible errors and examples -----------------------    

#
# INVALID_INPUT_DATA error can be caused by one of the following cases:  
  # code=-1, message="Duplicate document received"
  # code=-2, message="Invalid document file format: received fileFormatCategory=jpg -> expected fileFormatCategory=[pdf, zip]"
  # code=-3, message="Corrupted file content: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232"
  # code=-3, message="File not available: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232"
  # code=-3, message="Invalid ST26 package: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232"
  # code=-3, message="File checksum does not match the value provided in the upload request: received fileChecksum=EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9 -> expected fileChecksum=11C0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9"
  # code=-3, message="File is virus infected: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232"
  # code=-4, message="Invalid input data: documentDate=2022-02-30"
  # code=-7, message="The requested document is not registered in the system: documentNumber=US64/282,001, documentKindCategory=patent"
  # code=-12, message="Mismatched priority filing date: documentDate=2022-10-10, expected documentDate=2022-10-01"
  # code=-13, message="Missing priority filing date and/or access code: dasAccessCode, documentDate"
  # code=-13, message="Missing required field: officeCode"
  # code=-14, message="Mismatched access code: dasAccessCode=1234 -> expected dasAccessCode=AB46"
  # code=-15, message="Mismatched access code and priority filing date: documentDate=2022-10-10, dasAccessCode=1234 ->    # code=-16, message="Mismatched document kind category: documentKindCategory=patent, expected documentKindCategory=design"
#
#
# The -1 code of duplciate document is used 
# to track exchange error betwween WIPO DAS and OFF operating DAS services 
# using the IP5 Trinet Document Access service only.

    error400SeveralInputData:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -4
            message: 'Invalid input data: documentDate=2022-02-30'
          - code: -13
            message: 'Missing required field: documentKindCategory'

    error400MissingOfficeCode:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -13
            message: 'Missing required field: officeCode'

    error400MissingFileChecksum:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -13
            message: 'Missing required field: fileChecksum'

    error400DocumentDetails:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
        - code: -4
          message: 'Invalid input value: documentDate=2021-02-30'

    error400FileId:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
        - code: -3
          message: 'File not available: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232'

    error400EmailFormat:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
        - code: -4
          message: 'Invalid email format: email=jjduffy@example'

    error400FileCorrupted:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
        - code: -3
          message: 'Corrupted file content: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232'

    error400FileAlreadyRegistered:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
        - code: -3
          message: 'File already registered: fileId=US-bf5f35ff-2a94-4082-8c1c-02e321178232'

    error400MismatchedDASAccessCode:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -4
            message: 'Mismatched access code: dasAccessCode=1234 -> expected dasAccessCode=AB46'

    error400FilterCriteria:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -4
            message: 'Invalid input data: operationCategory=all'

    error400NotificationDetails:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -4
            message: 'Invalid input data: dateTime=2020-01-23T12:23'

    error400InvalidAckId:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -4
            message: 'Invalid input data: requestAckId=USIB2022010101'

    error400InvalidOfficeCode:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
          - code: -4
            message: 'Invalid input data: officeCode=xx'

    error400DocumentNotAvailable:
      value:
        code: "INVALID_INPUT_DATA"
        message: 'Invalid input data or document'
        details:
        - code: -7
          message: 'The requested document is not registered in the system: documentNumber=US64/282,001, documentKindCategory=patent'

#
# INVALID_TOKEN error can be caused by one of the following cases: missing access-token, 
  # code=-106, message="Missing token"
  # code=-106, message="Expired token: eyJ0eXAiOiJKV1QiLCJraWQiOiJmVWRmbEJSa3c5bm1tejcrL3BmMWM5d2RYdXc9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkYXMtanAtYXBpLWlkMSIsImN0cyI6Ik9BVVRIMl9TVEFURUxFU1NfR1JBTlQiLCJhdWRpdFRyYWNraW5nSWQiOiJiNjMxOGEyZi0xYTQ0LTQ4ZjQtOWM4ZC1kYmEyNjMwZDU0NWMtNzI0NjkzIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbmRldi53aXBvLmludDo0NDMvYW0vb2F1dGgyIiwidG9rZW5OYW1lIjoiYWNjZXNzX3Rva2VuIiwidG9rZW5fdHlwZSI6IkJlYXJlciIsImF1dGhHcmFudElkIjoieHVGOW1JNENiMElRRWJoeXZxd0s1d3hyTkRZIiwiYXVkIjoiZGFzLWpwLWFwaS1pZDEiLCJuYmYiOjE2NjgwMDYyNTQsImdyYW50X3R5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJzY29wZSI6WyJkYXMtYXBpL29mZmljZS1leGNoYW5nZSJdLCJhdXRoX3RpbWUiOjE2NjgwMDYyNTQsInJlYWxtIjoiLyIsImV4cCI6MTY2ODAwOTg1NCwiaWF0IjoxNjY4MDA2MjU0LCJleHBpcmVzX2luIjozNjAwLCJqdGkiOiIxOGhNZ2Q0bGZCWGhnZEQ3dXN4aTA4YzlNZ0UifQ.tdHY4okCH5yFBU85D47KapBxAQ1WoQbrrWKUMQ6GJ3T_1pfwkg-dMivGgi_Nlj-yWa28-BGFbLz6j-TRjyC2sZ6K_jIhfuU9GNyBokCSyCddFGerXU8lNPPF_6gNpUOFFBjNMOQ5RuLibyc2rW5_FB7GslLmIp_sFW74rJsQoPSSMW0qxhxnEswN_oHuKRcTWbvkOlvfnXJoF2qCdjHF104soew4SSQ9kUSejbehXRgu5gWR2MkIs_qcEs5AtMDhB08RkCSnapUfldjWj6wPAgsCzy-VBlPXTdpAESALXn6BT6SX_XP2lOagYHYw2pWDhF_6aI7NgJSSFbuBs3TdQw"
  # code=-106, message="Invalid token: eyJ0eXAiOiJKV1QiLCJraWQiOiJmVWRmbEJSa3c5bm1tejcrL3BmMWM5d2RYdXc9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkYXMtanAtYXBpLWlkMSIsImN0cyI6Ik9BVVRIMl9TVEFURUxFU1NfR1JBTlQiLCJhdWRpdFRyYWNraW5nSWQiOiJiNjMxOGEyZi0xYTQ0LTQ4ZjQtOWM4ZC1kYmEyNjMwZDU0NWMtNzI0NjkzIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbmRldi53aXBvLmludDo0NDMvYW0vb2F1dGgyIiwidG9rZW5OYW1lIjoiYWNjZXNzX3Rva2VuIiwidG9rZW5fdHlwZSI6IkJlYXJlciIsImF1dGhHcmFudElkIjoieHVGOW1JNENiMElRRWJoeXZxd0s1d3hyTkRZIiwiYXVkIjoiZGFzLWpwLWFwaS1pZDEiLCJuYmYiOjE2NjgwMDYyNTQsImdyYW50X3R5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJzY29wZSI6WyJkYXMtYXBpL29mZmljZS1leGNoYW5nZSJdLCJhdXRoX3RpbWUiOjE2NjgwMDYyNTQsInJlYWxtIjoiLyIsImV4cCI6MTY2ODAwOTg1NCwiaWF0IjoxNjY4MDA2MjU0LCJleHBpcmVzX2luIjozNjAwLCJqdGkiOiIxOGhNZ2Q0bGZCWGhnZEQ3dXN4aTA4YzlNZ0UifQ.tdHY4okCH5yFBU85D47KapBxAQ1WoQbrrWKUMQ6GJ3T_1pfwkg-dMivGgi_Nlj-yWa28-BGFbLz6j-TRjyC2sZ6K_jIhfuU9GNyBokCSyCddFGerXU8lNPPF_6gNpUOFFBjNMOQ5RuLibyc2rW5_FB7GslLmIp_sFW74rJsQoPSSMW0qxhxnEswN_oHuKRcTWbvkOlvfnXJoF2qCdjHF104soew4SSQ9kUSejbehXRgu5gWR2MkIs_qcEs5AtMDhB08RkCSnapUfldjWj6wPAgsCzy-VBlPXTdpAESALXn6BT6SX_XP2lOagYHYw2pWDhF_6aI7NgJSSFbuBs3TdQw"
  # code=-106, message="Incorrect token scope: das-scope"
#
    exampleOfError401:
      value:
        code: "INVALID_TOKEN"
        message: 'Authentication/authorization details are missing, invalid, expired or incorrect'
        details:
        - code: '-106'
          message: 'Missing token'

#
# OPERATION_FORBIDDEN error can be caused by a service call to perform an operation which is 
# not allowed due to inconsistency of data or request being processed by WIPO DAS
  # code=-5, message="Requested document has been withdrawn by OFF"
  # code=-6, message="Document retrieval is not authorized"
  # code=-8, message="National security clearance has not been granted for dissemination"
  # code=-9, message="Some part(s) of the document has(have) not been received by OFF"
  # code=-11, message="Document cannot be withdrawn because it was already retrieved by OSF"
  # code=-107, message="Operation not allowed because of data inconsistency"
#
    error403DocumentWithdrawn:
      value:
        code: "OPERATION_FORBIDDEN"
        message: 'Operation could not be performed/recorded due to inconsistency of data or request being processed by WIPO DAS'
        details:
        - code: '-5'
          message: 'Requested document has been withdrawn by OFF'

    error403NotAuthorized:
      value:
        code: "OPERATION_FORBIDDEN"
        message: 'Operation could not be performed/recorded due to inconsistency of data or request being processed by WIPO DAS'
        details:
        - code: '-6'
          message: 'Document retrieval is not authorized'

    error403ClearanceNotGranted:
      value:
        code: "OPERATION_FORBIDDEN"
        message: 'Operation could not be performed/recorded due to inconsistency of data or request being processed by WIPO DAS'
        details:
        - code: '-8'
          message: 'National security clearance has not been granted for dissemination'

    error403DocumentIncomplet:
      value:
        code: "OPERATION_FORBIDDEN"
        message: 'Operation could not be performed/recorded due to inconsistency of data or request being processed by WIPO DAS'
        details:
        - code: '-9'
          message: 'Some part(s) of the document has(have) not been received by OFF'

    error403WithdrawalNotAllowed:
      value:
        code: "OPERATION_FORBIDDEN"
        message: 'Operation could not be performed/recorded due to inconsistency of data or request being processed by WIPO DAS'
        details:
        - code: '-11'
          message: 'Document cannot be withdrawn because it was already retrieved by OSF'

    error403OperationForbidden:
      value:
        code: "OPERATION_FORBIDDEN"
        message: 'Operation could not be performed/recorded due to inconsistency of data or request being processed by WIPO DAS'
        details:
        - code: '-107'
          message: 'Operation not allowed because of data inconsistency'
  #
  # Except the first 'unknown system error' which might be reported to api calls from IP offices, 
  # the other errors might be used internally by the WIPO DAS system for technical reporting purposes:
  # code=-100, message="Unknown system error"
  # code=-101, message="DAS system unavailable"
  # code=-102, message="Office system unavailable"
  # code=-103, message="Maintenance clean up by WIPO DAS Support"
  # code=-104, message="Unexpected system internal error"
  #
    exampleOfError500:
      value:
        code: "DAS_SYSTEM_ERROR"
        message: 'WIPO DAS system error'
        details:
          - code: -104
            message: Unexpected internal error

  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # The client must send this token in the Authorization header (i.e. Authorization: Bearer <token>)
    OAuth2:
      type: oauth2
      flows: 
        clientCredentials: 
          tokenUrl: https://login.wipo.int/am/v1/oauth2/access_token
          scopes: {} # Getty Images does not use scopes
