Background

Both of the automated interfaces currently in use (TDA and SFTP) depend on older technologies. The future DAS service should be upgraded to a more modern technology, which will simplify the implementation for offices, improve security and authentication mechanisms, and potentially allow for faster document exchange.

A new REST API is proposed to modernise the automated interfaces between offices and WIPO DAS:

  • REST Web Services.
  • OpenID Connect and asymmetric encryption for unpublished document content to secure the exchange process and content

  •  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 

    Please click here to download the specification in yaml

    Revised on 2024-01-14
    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-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:
            '201':
              description: successful operation
            '400':
              description: Bad request
              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'
                application/xml:
                  schema:
                    type: string
                    format: binary
            '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/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: true
              schema:
                type: string
            - name: documentDate
              in: query
              required: true
              schema:
                type: string
            - name: dasAccessCode
              in: query
              required: true
              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'
                    exampleOfNotRegisteredDocument:
                      $ref: '#/components/examples/exampleOfNotRegisteredDocument'
                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 
    
        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: IB
            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'
    
        exampleOfNotRegisteredDocument:
          value:
            officeCode: IB
            documentKindCategory: 'design'
            documentCodeCategory: 'priority document'
            documentNumber: 'ES U 20235131'
            documentDate: "2020-06-23"
            dasAccessCode: ABCD
            operationDateTime: 
            documentStatusCategory: "document not registered"
            documentAvailabilityDate: 
    
        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
    
    #---------------------- 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 -> expected documentDate=2022-10-01, dasAccessCode=45AB"
    #
    #
    # 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:
            error:
              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:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -13
                  message: 'Missing required field: officeCode'
    
        error400MissingFileChecksum:
          value:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -13
                  message: 'Missing required field: fileChecksum'
    
        error400DocumentDetails:
          value:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
              - code: -4
                message: 'Invalid input value: documentDate=2021-02-30'
    
        error400FileId:
          value:
            error:
              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:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
              - code: -4
                message: 'Invalid email format: email=jjduffy@example'
    
        error400FileCorrupted:
          value:
            error:
              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:
            error:
              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:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -4
                  message: 'Mismatched access code: dasAccessCode=1234 -> expected dasAccessCode=AB46'
    
        error400FilterCriteria:
          value:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -4
                  message: 'Invalid input data: operationCategory=all'
    
        error400NotificationDetails:
          value:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -4
                  message: 'Invalid input data: dateTime=2020-01-23T12:23'
    
        error400InvalidAckId:
          value:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -4
                  message: 'Invalid input data: requestAckId=USIB2022010101'
    
        error400InvalidOfficeCode:
          value:
            error:
              code: "INVALID_INPUT_DATA"
              message: 'Invalid input data or document'
              details:
                - code: -4
                  message: 'Invalid input data: officeCode=xx'
    
        error400DocumentNotAvailable:
          value:
            error:
              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:
            error:
              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:
            error:
              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:
            error:
              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:
            error:
              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:
            error:
              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:
            error:
              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:
            error:
              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="DAS system unavailable"
      #
        exampleOfError500:
          value:
            error:
              code: "DAS_SYSTEM_ERROR"
              message: 'WIPO DAS system error'
              details:
                - code: -100
                  message: Unknown system 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
    
    
    

API Security

For advanced API Security, the FAPI (Financial grade API) – Part 2 standard adds an extra-layer on top of OAuth2.0 and OIDC.

  1. private_key_jwt, if the client sends its credentials as a JWT.
  2. tls_client_auth, if the client uses a CA-signed certificate for mutual TLS authentication.
  3. self_signed_tls_client_auth, if the client uses a self-signed certificate for mutual TLS authentication. 

Access control implementation

To allow safe, secure and trustable authentication, DAS API will have to implement one of the authentication permitted by FAPI part 2. In order not to the implementation of the backend infrastructure too complex, the proposed implementation will only support the private_key_jwt authentication method. The private_key_jwt authentication is based on the asymmetric key signature of the login information, those details – login info + signature - are sent to the authorization server which returns an access token if valid. The access token can then be used to call the DAS API.

Mutual TLS authentication

The other tls_client_auth and self_signed_tls_client_auth authentication methods defined in the FAPI part 2 standard leverages mutual TLS which necessitates tailored backend servers infrastructure. They are not proposed for DAS API authentication due the non-negligible additional costs and complexity that they will generate . 

 The following controls must be enforced to guaranty the same level of security than the TDA VPN connection

Network access-control

Decrease the threat surface and avoid data exfiltration:

  1. Restrict communication between WIPO and IP Offices with white listed IP addresses
  2. Perform egress/ingress filtering on the approved protocols to avoid data exfiltration.
  3. Achieve non-disclosure countermeasure and information protection in transit by enabling TLS1.2 encryption.
API mandatory controls 

Protect access to API

  1. API DDOS protection
  2. API –Threat protection

Possible setups

DAS protocol necessitates bi-directional communication between offices and WIPO, in practical terms it means that offices must also support private_key_jwt authentication. To ease integration and give freedom to office to choose, we propose two possible setups:

  1. WIPO authorization server setup
    Office will use the WIPO authorization server infrastructure for authentication:
    Inbound traffic: whenever a call is received from the WIPO central DAS service the office will have to contact and verify the token against the WIPO authorization server.
    Outbound traffic: office will authenticate using its client id registered in WIPO authorization server and will use the returned access_token to call the WIPO DAS API.



  2. Mutual authorization server setup
    Office wants to take care of the authentication by itself consequently provides the private_key_jwt authentication.
    Inbound traffic: The WIPO central DAS service will authenticate against a client id registered in the office authorization server and will use the returned access_token to call the office DAS API 
    Outbound traffic: office will authenticate using its client id registered in WIPO authorization server and will use the returned access_token to call the WIPO DAS API.



  • No labels