openapi: '3.0.3'
info:
  version: '1.0'
  title: IPCPUB
  description: This API provides frontend resources from IPCPUB application server
  contact:
    email: its4ics@wipo.int
servers:
  - url: https://ipcpub.wipo.int/api/v1
paths:
  /settings:
    summary: returns current IPCPUB configuration values
    get:
      parameters:
        - name: maintenance
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsResponse'
  /bridge:
    summary: returns the list of links to external IP web site
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeResponse'

  /search/quick:
    summary: search for terms using all available search services
    get:
      parameters:
        - $ref: '#/components/parameters/QueryString'
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - $ref: '#/components/parameters/PageLength'
        - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultResponse'
  /search/advanced/terms:
    summary: search for terms using IPCPUB Solr service
    get:
      parameters:
        - $ref: '#/components/parameters/QueryString'
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - $ref: '#/components/parameters/PageLength'
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/IncludeSymbols'
        - $ref: '#/components/parameters/ExcludeSymbols'
        - $ref: '#/components/parameters/Stemmed'
        - $ref: '#/components/parameters/IpcNotion'
        - name: path
          in: query
          schema:
            type: boolean
            default: true
        - name: schemerefs
          in: query
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultResponse'
  /search/advanced/xrefs:
    summary: search for symbol references using IPCPUB Solr service
    get:
      parameters:
        - $ref: '#/components/parameters/QueryString'
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - $ref: '#/components/parameters/PageLength'
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/IpcNotion'
        - name: subgroup
          in: query
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultResponse'
  /search/advanced/stats:
    summary: search for terms using Patentscope Solr service
    get:
      parameters:
        - $ref: '#/components/parameters/QueryString'
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - $ref: '#/components/parameters/IncludeSymbols'
        - $ref: '#/components/parameters/ExcludeSymbols'
        - $ref: '#/components/parameters/Stemmed'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultResponse'
  /search/advanced/ipccat:
    summary: get categorization symbols for the submitted text using IPCCAT service
    get:
      parameters:
        - $ref: '#/components/parameters/QueryString'
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpccatLanguage'
        - name: level
          in: query
          schema:
            type: string
            enum:
              - class
              - subclass
              - maingroup
              - subgroup
            default: subgroup
        - name: limit
          in: query
          schema:
            type: integer
            enum:
              - 3
              - 5
            default: 3
        - name: startfrom
          in: query
          schema:
            $ref: '#/components/schemas/IpcSymbol'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultResponse'
  /catchwords/roots:
    summary: get root nodes of the IPC Catchwords tree
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatchwordsTreeResponse'
  /catchwords/children:
    summary: get children nodes of an IPC Catchwords root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatchwordsTreeResponse'
  /catchwords/ancestors:
    summary: get ancestors node IDs of an IPC Catchword node by its CW ID
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - name: cwid
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatchwordsAncestorsResponse'
  /compilation/roots:
    summary: get root nodes of the IPC Compilation tree
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompilationTreeResponse'
  /compilation/children:
    summary: get children nodes of an IPC Compilation root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompilationTreeResponse'
  /compilation/ancestors:
    summary: get ancestors node IDs of an IPC Compilation node by its Symbol code
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/IpcLanguage'
        - name: symbol
          in: query
          schema:
            $ref: '#/components/schemas/IpcSymbol'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompilationAncestorsResponse'
  /scheme/roots/l1:
    get:
      description: ''
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/roots/l2:
    get:
      description: ''
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/roots/l3:
    get:
      description: ''
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/children/l1:
    summary: get children nodes of an IPC Scheme root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/children/l2:
    summary: get children nodes of an IPC Scheme root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/children/l3:
    summary: get children nodes of an IPC Scheme root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/children/cf/l1:
    summary: get children nodes of an IPC Scheme root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/children/cf/l2:
    summary: get children nodes of an IPC Scheme root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/children/cf/l3:
    summary: get children nodes of an IPC Scheme root node
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeTreeResponse'
  /scheme/ancestors:
    summary: get ancestors node IDs of an IPC Compilation node by its Symbol code
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - name: symbol
          in: query
          schema:
            $ref: '#/components/schemas/IpcSymbol'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemeAncestorsResponse'
  /scheme/isValidSymbol:
    summary: Check symbol validity in the specified version (default to latest version)
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - name: symbol
          in: query
          schema:
            $ref: '#/components/schemas/IpcSymbol'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleStringResponse'
  /scheme/getSymbolValidity:
    summary: Return details of symbol validity in the specified version (default to latest version)
    get:
      parameters:
        - $ref: '#/components/parameters/IpcVersion'
        - name: symbol
          in: query
          schema:
            $ref: '#/components/schemas/IpcSymbol'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidityResponse'
  /scheme/setCurrentSymbol:
    summary: Store an IPC Symbol (1, 3, 4 or 14 characters) in the browser session cookie
    get:
      parameters:
        - name: symbol
          in: query
          schema:
            $ref: '#/components/schemas/IpcSymbol'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleStringResponse'
  /scheme/getCurrentSymbol:
    summary: Return the IPC Symbol stored in the browser session cookie
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleStringResponse'
  /GlossaryDefinition:
    summary: returns the definition of a glossary term
    get:
      parameters:
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleStringResponse'
components:
  schemas:
    IpcVersion:
      type: string
      enum:
        - 19680901
        - 19740701
        - 19800101
        - 19850101
        - 19900101
        - 19950101
        - 20000101
        - 20060101
        - 20070101
        - 20071001
        - 20080101
        - 20080401
        - 20090101
        - 20100101
        - 20110101
        - 20120101
        - 20130101
        - 20140101
        - 20150101
        - 20160101
        - 20170101
        - 20180101
        - 20190101
        - 20200101
        - 20210101
        - 20220101
        - 20230101
        - 20240101
        - latest
      default: latest
    IpcSymbol:
      type: string
      pattern: '^[A-H]((0[1-9]|[1-9][0-9])([A-HJ-NP-Z]([0-9]{10})?)?)?$'
    IpcSymbols:
      type: string
      pattern: '^[A-H]((0[1-9]|[1-9][0-9])([A-HJ-NP-Z]([0-9]{10})?)?)?(,[A-H]((0[1-9]|[1-9][0-9])([A-HJ-NP-Z]([0-9]{10})?)?)?)*$'
    IpcLanguage:
      type: string
      enum:
        - en
        - fr
      default: en
    IpccatLanguage:
      type: string
      enum:
        - en
        - fr
        - es
        - de
        - ru
        - ar
        - ko
        - ja
        - pt
        - zh
      default: en
    SettingsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        maintenance:
          type: boolean
        ipcpubVersion:
          type: string
        languages:
          type: array
          items:
            $ref: '#/components/schemas/IpcLanguage'
        lastModified:
          type: string
        cpcVersion:
          type: string
        fiVersion:
          type: string
        showCpcFi:
          type: boolean
        showBridge:
          type: boolean
        extendedTermsSearch:
          type: boolean
        statsSearch:
          type: boolean
        ipccatSearch:
          type: boolean
        ipccatLanguages:
          type: array
          items:
            $ref: '#/components/schemas/IpccatLanguage'
        pdfUrlRoot:
          type: string
        supportUrlBase:
          type: string
        googleAnalyticsCode:
          type: string
        ipcVersions:
          type: array
          items:
            type: object
            properties:
              number:
                type: string
              label:
                type: string
              archived:
                type: boolean
              current:
                type: boolean
              previous:
                type: string
              definitions:
                type: boolean
              rcl:
                type: boolean
              compilation:
                type: boolean
              catchwords:
                type: boolean
              pdf:
                type: boolean
              pdfType:
                type: string
              supportLabel:
                type: string
              timestamp:
                type: string
      required:
        - code
        - message
        - maintenance
    BridgeResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              purpose:
                type: string
                enum:
                  - IPC
                  - PatentDB
                  - Other
                default: IPC
              url:
                type: string
              parameter:
                type: string
    SearchResultResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        count:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
        offset:
          type: integer
          minimum: 0
        version:
          type: string
        lang:
          type: string
        path:
          type: boolean
        hilite:
          type: string
          enum:
            - none
            - terms
            - symbols
          default: none
        search:
          description: selected search method
          type: string
          enum:
            - sterms
            - cterms
            - dterms
            - sxrefs
            - cxrefs
            - dxrefs
            - stats
            - ipccat
        return:
          type: string
          enum:
            - none
            - terms
            - symbols
          default: none
        results:
          type: array
          items:
            type: object
            properties:
              score:
                type: integer
              code:
                type: string
              display:
                type: string
              hilites:
                type: array
                items:
                  type: string
              subresults:
                type: array
                items:
                  type: object
                  properties:
                    score:
                      type: integer
                    code:
                      type: string
                    display:
                      type: string
      required:
        - code
        - message
        - count
        - version
        - lang
        - search
        - return
    BaseTreeNode:
      type: object
      properties:
        key:
          type: string
        folder:
          type: boolean
        lazy:
          type: boolean
        expanded:
          type: boolean
        text:
          type: string
        kind:
          type: string
    BaseTreeResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
      required:
        - code
        - message
        - data
    CatchwordsTreeNode:
      allOf:
        - $ref: '#/components/schemas/BaseTreeNode'
        - type: object
          properties:
            cwid:
              type: string
            children:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/CatchwordsTreeNode'
      example:
        key: "1"
        folder: true
        lazy: false
        expanded: true
        text: A
        kind: "1"
        cwid: CW259852291
        children:
          - key: "2"
            folder: true
            lazy: true
            expanded: false
            children: null
            text: ABACUSES - ADHESION
            kind: r
            cwid: CW259852292
    CatchwordsTreeResponse:
      allOf:
        - $ref: '#/components/schemas/BaseTreeResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/CatchwordsTreeNode'
    CatchwordsAncestorsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseTreeResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                properties:
                  key:
                    type: string
    CompilationTreeNode:
      allOf:
        - $ref: '#/components/schemas/BaseTreeNode'
        - type: object
          properties:
            symbol:
              type: string
            symbolcode:
              type: string
            children:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/CompilationTreeNode'
      example:
        key: "1"
        folder: true
        lazy: false
        expanded: true
        text: ""
        kind: s
        symbol: A
        symbolcode: A
        children:
          - key: "2"
            folder: true
            lazy: false
            expanded: true
            text: ""
            kind: c
            symbol: A01
            symbolcode: A01
            children:
              - key: "3"
                folder: true
                lazy: true
                expanded: false
                text: ""
                kind: u
                symbol: A01H
                symbolcode: A01H
                children: null
    CompilationTreeResponse:
      allOf:
        - $ref: '#/components/schemas/BaseTreeResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/CompilationTreeNode'
    CompilationAncestorsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseTreeResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                properties:
                  key:
                    type: string
    SchemeTreeNode:
      allOf:
        - $ref: '#/components/schemas/BaseTreeNode'
        - type: object
          properties:
            symbol:
              type: string
            symbolcode:
              type: string
            entrytype:
              type: string
            amendment:
              type: string
            title1:
              type: string
            title2:
              type: string
            definition:
              type: string
            waerning:
              type: string
            scheme:
              type: string
            cpcfi:
              type: string
            expandable:
              type: string
            structured:
              type: string
            foreign:
              type: string
            kindclass:
              type: string
            length:
              type: integer
            children:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/SchemeTreeNode'
    SchemeTreeResponse:
      allOf:
        - $ref: '#/components/schemas/BaseTreeResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SchemeTreeNode'
    SchemeAncestorsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseTreeResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                properties:
                  key:
                    type: string
    SingleStringResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          type: string
      required:
        - code
        - message
        - data
    ValidityResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          type: object
          properties:
            version:
              type: string
            section:
              type: string
            class:
              type: string
            subclass:
              type: string
            main_group:
              type: string
            subgroup:
              type: string
            ipc_version_indicator:
              type: string
            symbol_category:
              type: string
            classification_validity:
              type: string
              enum:
                - V
                - N
              default: N
  parameters:
    Key:
      name: key
      in: query
      schema:
        type: string
    QueryString:
      name: q
      in: query
      schema:
        type: string
        maxLength: 1500
    IpcVersion:
      name: version
      description: IPC Version number
      in: query
      schema:
        $ref: '#/components/schemas/IpcVersion'
    IpcLanguage:
      name: lang
      in: query
      schema:
        $ref: '#/components/schemas/IpcLanguage'
    IpccatLanguage:
      name: lang
      in: query
      schema:
        $ref: '#/components/schemas/IpccatLanguage'
    PageLength:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        default: 10
    PageOffset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
    IncludeSymbols:
      name: include
      in: query
      schema:
        $ref: '#/components/schemas/IpcSymbols'
    ExcludeSymbols:
      name: include
      in: query
      schema:
        $ref: '#/components/schemas/IpcSymbols'
    Stemmed:
      name: stemmed
      in: query
      schema:
        type: boolean
        default: true
    IpcNotion:
      name: notion
      description: either s (scheme), c (catchwords) or d (definitions)
      in: query
      schema:
        type: string
        enum:
          - s
          - c
          - d
        default: s
