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 Expand source

  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.

 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.
   
   
   eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6IkRhbmllbCBDSEVORyIsIm91dHB1dFR5cGUiOiJibG9jayIsImxhc3RNb2RpZmllck5hbWUiOiJEYW5pZWwgQ0hFTkciLCJsYW5ndWFnZSI6ImVuIiwidWlDb25maWciOiJ7fSIsImRpYWdyYW1EaXNwbGF5TmFtZSI6IiIsInNGaWxlSWQiOiIiLCJhdHRJZCI6IjEwMjU2MDYwMjUiLCJkaWFncmFtTmFtZSI6IldJUE8gYXV0aG9yaXphdGlvbiBzZXJ2ZXIiLCJhc3BlY3QiOiIiLCJsaW5rcyI6ImF1dG8iLCJjZW9OYW1lIjoiTmV3IERBUyBleGNoYW5nZSBBUEkiLCJ0YnN0eWxlIjoidG9wIiwiY2FuQ29tbWVudCI6ZmFsc2UsImRpYWdyYW1VcmwiOiIiLCJjc3ZGaWxlVXJsIjoiIiwiYm9yZGVyIjp0cnVlLCJtYXhTY2FsZSI6IjEiLCJvd25pbmdQYWdlSWQiOjEwMjU2MDU5OTMsImVkaXRhYmxlIjpmYWxzZSwiY2VvSWQiOjE1NDIxNjQ4NzEsInBhZ2VJZCI6IiIsImxib3giOnRydWUsInNlcnZlckNvbmZpZyI6eyJlbWFpbHByZXZpZXciOiIxIn0sIm9kcml2ZUlkIjoiIiwicmV2aXNpb24iOjEsIm1hY3JvSWQiOiI4YzFiYWU0Mi0wZTRiLTRlMmMtOGEzOC1mYTNjNDUwODczN2UiLCJwcmV2aWV3TmFtZSI6IldJUE8gYXV0aG9yaXphdGlvbiBzZXJ2ZXIucG5nIiwibGljZW5zZVN0YXR1cyI6Ik9LIiwic2VydmljZSI6IiIsImlzVGVtcGxhdGUiOiIiLCJ3aWR0aCI6IjYwMCIsInNpbXBsZVZpZXdlciI6ZmFsc2UsImxhc3RNb2RpZmllZCI6MTYyNDY1NzAyMzk2NywiZXhjZWVkUGFnZVdpZHRoIjpmYWxzZSwib0NsaWVudElkIjoiIn0=
   
   

   
   

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.
   
   
   eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6IkRhbmllbCBDSEVORyIsIm91dHB1dFR5cGUiOiJibG9jayIsImxhc3RNb2RpZmllck5hbWUiOiJEYW5pZWwgQ0hFTkciLCJsYW5ndWFnZSI6ImVuIiwidWlDb25maWciOiJ7fSIsImRpYWdyYW1EaXNwbGF5TmFtZSI6IiIsInNGaWxlSWQiOiIiLCJhdHRJZCI6IjEwMjU2MDYwMjciLCJkaWFncmFtTmFtZSI6Ik11dHVhbCBhdXRob3JpemF0aW9uIHNlcnZlcnMiLCJhc3BlY3QiOiIiLCJsaW5rcyI6ImF1dG8iLCJjZW9OYW1lIjoiTmV3IERBUyBleGNoYW5nZSBBUEkiLCJ0YnN0eWxlIjoidG9wIiwiY2FuQ29tbWVudCI6ZmFsc2UsImRpYWdyYW1VcmwiOiIiLCJjc3ZGaWxlVXJsIjoiIiwiYm9yZGVyIjp0cnVlLCJtYXhTY2FsZSI6IjEiLCJvd25pbmdQYWdlSWQiOjEwMjU2MDU5OTMsImVkaXRhYmxlIjpmYWxzZSwiY2VvSWQiOjE1NDIxNjQ4NzEsInBhZ2VJZCI6IiIsImxib3giOnRydWUsInNlcnZlckNvbmZpZyI6eyJlbWFpbHByZXZpZXciOiIxIn0sIm9kcml2ZUlkIjoiIiwicmV2aXNpb24iOjEsIm1hY3JvSWQiOiIwMmViZWJmMy00ZmI3LTQ0MTItODUzNy0yZGY5MTg0ZmUzNzIiLCJwcmV2aWV3TmFtZSI6Ik11dHVhbCBhdXRob3JpemF0aW9uIHNlcnZlcnMucG5nIiwibGljZW5zZVN0YXR1cyI6Ik9LIiwic2VydmljZSI6IiIsImlzVGVtcGxhdGUiOiIiLCJ3aWR0aCI6IjYwMCIsInNpbXBsZVZpZXdlciI6ZmFsc2UsImxhc3RNb2RpZmllZCI6MTYyNDY1NzA4MjMwNiwiZXhjZWVkUGFnZVdpZHRoIjpmYWxzZSwib0NsaWVudElkIjoiIn0=