openapi: 3.0.3
info:
  title: Doc2Data API
  description: |-
    Welcome to the Doc2Data API. Use our API to extract data from _Structured
    Machine-Readable Documents_ (SMRDs) into JSON.

    Do this as an atomic operation with a single request to the _Process
    Document_ API. Alternatively, you can go with a two-step approach involving
    subsequent requests to the _Transform_ and _Process XML Document_ API for a
    full control over the document processing workflow.

    _Generate Mapping_ API can be especially helpful when you just start
    working with Doc2Data, as it will create a dummy mapping metadata based on
    the provided document, so you don't need to do it from scratch.

    Useful links:
    - if you are new to Doc2Data, jump to our [Getting Started](https://docs.d2d.work/index.html#getting-started) guide;
    - for more info about Doc2Data, read the official [documentation](https://docs.d2d.work/index.html);
    - create new or edit existing mapping file in the [Document Mapping Editor](https://app.d2d.work).
  contact:
    email: support@d2d.work
  version: 1.0.0
servers:
  - url: https://api.d2d.work/
    description: "Production server"
paths:
  /document/process:
    post:
      summary: Extract data from the document using the mapping metadata
      description: |-
        Extract required data from the document into JSON structure using the
        mapping metadata.
      tags:
        - Process Document
      requestBody:
        description: Document and metadata files to generate mapping result
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  type: string
                  format: binary
                metadata:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                {"result":{"company":{"name":"ACME Corporation","type":"LLC","contacts":["+1 555-555-1212","+1 555-555-1212","https://acmemax.com/"]},"items":[{"itemNo":"23423423","description":"Product XYZ","quantity":"15","price":"150.00","total":"2,250.00"},{"itemNo":"45645645","description":"Product ABC","quantity":"1","price":"75.00","total":"75.00"}]},"errors":[],"warnings":[]}
        '400':
          description: |-
            Bad request. This can indicate either a problem while parsing
            malformed or corrupted document or metadata files or an error while
            applying the mapping to the internal representation of the document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                {"result":null,"errors":[{"message":"Unable to parse document mapping metadata","causeMessage":"Could not resolve subtype of [simple type, class work.d2d.doc2data.mapping.DocumentSegmentMapping]: missing type id property 'type' (for POJO property 'mapping')\n at [Source: (FileInputStream); line: 33, column: 7] (through reference chain: work.d2d.doc2data.mapping.DocumentMappingMetadata[\"mapping\"]->work.d2d.doc2data.mapping.ObjectSegmentMapping[\"mapping\"]->java.util.LinkedHashMap[\"company\"])","nestedErrors":[]}],"warnings":[]}

  /document/transform:
    post:
      summary: Transform the document to its internal representation in XHTML format
      description: |-
        Transform the document to its internal representation in XHTML format.
        This is the first step of the document processing flow provided by
        the Process Document API.
        The Transform Document API allows splitting the document processing flow
        into independent phases to provide better scalability.
      tags:
        - Transform Document
      requestBody:
        description: Document file to generate internal representation
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                {"result":"<html xmlns=\"http://www.w3.org/1999/xhtml\">\n  <head>\n    <meta name=\"protected\" content=\"false\"/>\n    <meta name=\"extended-properties:Application\" content=\"Apache POI\"/>\n    <meta name=\"extended-properties:DocSecurityString\" content=\"None\"/>\n    <meta name=\"dc:creator\" content=\"Apache POI\"/>\n    <meta name=\"dcterms:created\" content=\"2022-06-16T16:26:09Z\"/>\n    <meta name=\"Content-Type\" content=\"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\"/>\n    <title/>\n  </head>\n  <body>\n    <div>\n      <h1>Table Name</h1>\n      <table>\n        <tbody>\n          <tr>\n            <td>Column 1</td>\n            <td>Column 2</td>\n            <td>Column 3</td>\n            <td>Column 4</td>\n            <td>Column 5</td>\n            <td>Column 6</td>\n          </tr>\n        </tbody>\n      </table>\n    </div>\n  </body>\n</html>\n","errors":[]}
        '400':
          description: |-
            Bad request. This can indicate a problem while parsing malformed or
            corrupted document file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                {"errors":[{"message":"Field 'document': must not be empty","causeMessage":null,"nestedErrors":[]}],"result":null}

  /xml/process:
    post:
      summary: Process XML document using the mapping metadata file
      description: |-
        Process the document’s internal representation (XHTML) or arbitrary XML
        with mapping metadata to extract the required data into JSON structure.
        This is the second step of the document processing flow provided by
        the Process Document API.
        The Process XML Document API can be used in combination with the
        Transform Document API to provide better scalability.
      tags:
        - Process XML Document
      requestBody:
        description: XHTML/XML document and metadata files to generate mapping result
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  type: string
                  format: binary
                metadata:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                {"result":{"company":{"name":"ACME Corporation","type":"LLC","contacts":["+1 555-555-1212","+1 555-555-1212","https://acmemax.com/"]},"items":[{"itemNo":"23423423","description":"Product XYZ","quantity":"15","price":"150.00","total":"2,250.00"},{"itemNo":"45645645","description":"Product ABC","quantity":"1","price":"75.00","total":"75.00"}]},"errors":[],"warnings":[]}
        '400':
          description: |-
            Bad request. This can indicate either a problem while parsing
            malformed or corrupted XML document or metadata files or an error
            while applying the mapping to the XML document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                {"errors":[{"message":"Field 'document': must not be empty","causeMessage":null,"nestedErrors":[]}],"result":null}

  /document/generate-mapping-metadata:
    post:
      summary: Generate the mapping metadata
      description: |-
        Generate the mapping metadata based on the provided document.
        It is a good starting point for document processing.
      tags:
        - Generate Mapping Metadata
      requestBody:
        description: Document file for which the mapping metadata should be generated
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                { "result": { "name": "Document Template","version": "0.1","documentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document","mapping": { "type": "object","query": "/html","mapping": { "title": { "type": "value","query": "./head/title/text()","postprocessing": null } } } },"errors": [] }
        '400':
          description: |-
            Bad request. This can indicate a problem while parsing malformed or
            corrupted document file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                { "errors": [{ "message": "Field 'document': must not be empty","causeMessage": null,"nestedErrors": [] }],"result": null }

  /version:
    get:
      summary: Get application version
      description: |-
        Get the information about current version of running application as well
        as Git revision from which it is built.
      tags:
        - Application Version
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
              example:
                {"doc2data":{"version":"1.0.0-m6","revision":"2a752dc3150053dc018b003412c2899c1eee3e76"}}

components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          nullable: true
        causeMessage:
          type: string
          nullable: true
        nestedErrors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Warning:
      type: object
      properties:
        message:
          type: string
          nullable: false
    Result:
      required:
        - result
        - errors
        - warnings
      type: object
      properties:
        result:
          type: object
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          nullable: false
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          nullable: false
    Version:
      required:
        - doc2data
      type: object
      properties:
        doc2data:
          type: object
          nullable: false
          required:
            - version
            - revision
          properties:
            version:
              type: string
              nullable: false
            revision:
              type: string
              nullable: false
