swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Layout API
schemes:
- https
tags:
- name: Layout
paths:
  /layout/analyze:
    post:
      summary: Microsoft Azure Analyze Layout
      description: Extract text and layout information from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Alternatively, use 'application/json' type to specify the location (Uri or local path) of the document to be analyzed.
      operationId: microsoftAzureAnalyzelayoutasync
      consumes:
      - application/pdf
      - application/json
      - image/jpeg
      - image/png
      - image/tiff
      - image/bmp
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/FileStream'
      - $ref: '#/parameters/Pages'
      - $ref: '#/parameters/Language'
      - $ref: '#/parameters/ReadingOrder'
      responses:
        '202':
          description: Request is queued successfully.
          headers:
            Operation-Location:
              type: string
              description: URL containing the resultId used to track the progress and obtain the result of the analyze operation.
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Analyze layout:
          $ref: ./examples/LayoutBatch.json
      x-ms-long-running-operation: true
      tags:
      - Layout
  /layout/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Layout Result
      description: Track the progress and obtain the result of the analyze layout operation
      operationId: microsoftAzureGetanalyzelayoutresult
      consumes: []
      produces:
      - application/json
      parameters:
      - name: resultId
        in: path
        description: Analyze operation result identifier.
        required: true
        type: string
        format: uuid
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/AnalyzeOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Get analyze layout result:
          $ref: ./examples/LayoutBatchResult.json
      tags:
      - Layout
definitions:
  KeyValueElement:
    description: Information about the extracted key or value in a key-value pair.
    type: object
    required:
    - text
    properties:
      type:
        $ref: '#/definitions/KeyValueType'
      text:
        description: The text content of the key or value.
        type: string
      boundingBox:
        description: Bounding box of the key or value.
        $ref: '#/definitions/BoundingBox'
      elements:
        description: When includeTextDetails is set to true, a list of references to the text elements constituting this key or value.
        type: array
        items:
          $ref: '#/definitions/ElementReference'
  AnalyzeOperationResult:
    description: Status and result of the queued analyze operation.
    type: object
    required:
    - status
    - createdDateTime
    - lastUpdatedDateTime
    properties:
      status:
        description: Operation status.
        $ref: '#/definitions/OperationStatus'
      createdDateTime:
        format: date-time
        description: Date and time (UTC) when the analyze operation was submitted.
        type: string
        x-nullable: false
      lastUpdatedDateTime:
        format: date-time
        description: Date and time (UTC) when the status was last updated.
        type: string
        x-nullable: false
      analyzeResult:
        description: Results of the analyze operation.
        $ref: '#/definitions/AnalyzeResult'
  DataTableCell:
    description: Information about the extracted cell in a table.
    type: object
    required:
    - rowIndex
    - columnIndex
    - text
    - boundingBox
    - confidence
    properties:
      rowIndex:
        description: Row index of the cell.
        type: integer
        minimum: 0
        x-nullable: false
      columnIndex:
        description: Column index of the cell.
        type: integer
        minimum: 0
        x-nullable: false
      rowSpan:
        description: Number of rows spanned by this cell.
        type: integer
        minimum: 1
        default: 1
        x-nullable: false
      columnSpan:
        description: Number of columns spanned by this cell.
        type: integer
        minimum: 1
        default: 1
        x-nullable: false
      text:
        description: Text content of the cell.
        type: string
      boundingBox:
        description: Bounding box of the cell.
        $ref: '#/definitions/BoundingBox'
      confidence:
        description: Confidence value.
        $ref: '#/definitions/Confidence'
      elements:
        description: When includeTextDetails is set to true, a list of references to the text elements constituting this table cell.
        type: array
        items:
          $ref: '#/definitions/ElementReference'
      isHeader:
        description: Is the current cell a header cell?
        type: boolean
        default: false
        x-nullable: false
      isFooter:
        description: Is the current cell a footer cell?
        type: boolean
        default: false
        x-nullable: false
  SelectionMark:
    description: Information about the extracted selection mark.
    type: object
    required:
    - boundingBox
    - confidence
    - state
    properties:
      boundingBox:
        description: Bounding box of the selection mark.
        $ref: '#/definitions/BoundingBox'
      confidence:
        description: Confidence value.
        $ref: '#/definitions/Confidence'
      state:
        description: State of the selection mark.
        type: string
        enum:
        - selected
        - unselected
  TextLine:
    description: An object representing an extracted text line.
    type: object
    required:
    - text
    - boundingBox
    - words
    properties:
      text:
        description: The text content of the line.
        type: string
      boundingBox:
        description: Bounding box of an extracted line.
        $ref: '#/definitions/BoundingBox'
      words:
        description: List of words in the text line.
        type: array
        items:
          $ref: '#/definitions/TextWord'
      appearance:
        description: Text appearance properties.
        $ref: '#/definitions/Appearance'
  BoundingBox:
    description: Quadrangle bounding box, with coordinates specified relative to the top-left of the original image. The eight numbers represent the four points, clockwise from the top-left corner relative to the text orientation. For image, the (x, y) coordinates are measured in pixels. For PDF, the (x, y) coordinates are measured in inches.
    type: array
    minItems: 8
    maxItems: 8
    items:
      type: number
      x-nullable: false
  KeyValueType:
    type: string
    description: Semantic data type of the key value element.
    enum:
    - string
    - selectionMark
    x-ms-enum:
      name: KeyValueType
      modelAsString: true
    x-nullable: false
  OperationStatus:
    type: string
    description: Status of the queued operation.
    enum:
    - notStarted
    - running
    - succeeded
    - failed
    x-ms-enum:
      name: OperationStatus
      modelAsString: false
    x-nullable: false
  Style:
    description: An object representing the style of the text line.
    type: object
    required:
    - name
    - confidence
    properties:
      name:
        description: The text line style name, including handwriting and other.
        type: string
        x-ms-enum:
          name: TextStyle
          modelAsString: true
        enum:
        - other
        - handwriting
      confidence:
        description: The confidence of text line style.
        type: number
        format: float
  ReadResult:
    description: Text extracted from a page in the input document.
    type: object
    required:
    - page
    - angle
    - width
    - height
    - unit
    properties:
      page:
        description: The 1-based page number in the input document.
        type: integer
        minimum: 1
        x-nullable: false
      angle:
        description: The general orientation of the text in clockwise direction, measured in degrees between (-180, 180].
        type: number
        minimum: -180
        maximum: 180
        exclusiveMinimum: true
        x-nullable: false
      width:
        description: The width of the image/PDF in pixels/inches, respectively.
        type: number
        minimum: 0
        x-nullable: false
      height:
        description: The height of the image/PDF in pixels/inches, respectively.
        type: number
        minimum: 0
        x-nullable: false
      unit:
        description: The unit used by the width, height and boundingBox properties. For images, the unit is "pixel". For PDF, the unit is "inch".
        type: string
        enum:
        - pixel
        - inch
        x-ms-enum:
          name: LengthUnit
          modelAsString: false
        x-nullable: false
      lines:
        description: When includeTextDetails is set to true, a list of recognized text lines. The maximum number of lines returned is 300 per page. The lines are sorted top to bottom, left to right, although in certain cases proximity is treated with higher priority. As the sorting order depends on the detected text, it may change across images and OCR version updates. Thus, business logic should be built upon the actual line location instead of order.
        type: array
        items:
          $ref: '#/definitions/TextLine'
      selectionMarks:
        description: List of selection marks extracted from the page.
        type: array
        items:
          $ref: '#/definitions/SelectionMark'
  ElementReference:
    description: Reference to a line, word or selection mark.
    type: string
  KeyValuePair:
    description: Information about the extracted key-value pair.
    type: object
    required:
    - key
    - value
    - confidence
    properties:
      label:
        description: A user defined label for the key/value pair entry.
        type: string
      key:
        description: Information about the extracted key in a key-value pair.
        $ref: '#/definitions/KeyValueElement'
      value:
        description: Information about the extracted value in a key-value pair.
        $ref: '#/definitions/KeyValueElement'
      confidence:
        description: Confidence value.
        $ref: '#/definitions/Confidence'
  Appearance:
    description: An object representing the appearance of the text line.
    type: object
    required:
    - style
    properties:
      style:
        description: An object representing the style of the text line.
        type: object
        $ref: '#/definitions/Style'
  FieldValueType:
    type: string
    description: Semantic data type of the field value.
    enum:
    - string
    - date
    - time
    - phoneNumber
    - number
    - integer
    - array
    - object
    - selectionMark
    - gender
    - country
    x-ms-enum:
      name: FieldValueType
      modelAsString: false
    x-nullable: false
  TextWord:
    description: An object representing a word.
    type: object
    required:
    - boundingBox
    - text
    properties:
      text:
        description: The text content of the word.
        type: string
      boundingBox:
        description: Bounding box of an extracted word.
        $ref: '#/definitions/BoundingBox'
      confidence:
        description: Confidence value.
        $ref: '#/definitions/Confidence'
  ErrorInformation:
    type: object
    required:
    - code
    - message
    properties:
      code:
        type: string
      message:
        type: string
  DataTable:
    description: Information about the extracted table contained in a page.
    type: object
    required:
    - rows
    - columns
    - cells
    - boundingBox
    properties:
      rows:
        description: Number of rows.
        type: integer
        minimum: 1
        x-nullable: false
      columns:
        description: Number of columns.
        type: integer
        minimum: 1
        x-nullable: false
      cells:
        description: List of cells contained in the table.
        type: array
        items:
          $ref: '#/definitions/DataTableCell'
      boundingBox:
        description: Bounding box of the table.
        $ref: '#/definitions/BoundingBox'
  SourcePath:
    description: Uri or local path to source data.
    type: object
    properties:
      source:
        description: File source path.
        maxLength: 2048
        minLength: 0
        type: string
  ErrorResponse:
    type: object
    required:
    - error
    properties:
      error:
        $ref: '#/definitions/ErrorInformation'
  FieldValue:
    description: Recognized field value.
    type: object
    required:
    - type
    properties:
      type:
        description: Type of field value.
        $ref: '#/definitions/FieldValueType'
      valueString:
        description: String value.
        type: string
      valueDate:
        description: Date value.
        format: date
        type: string
        x-nullable: false
      valueTime:
        description: Time value.
        format: time
        type: string
        x-nullable: false
      valuePhoneNumber:
        description: Phone number value.
        type: string
      valueNumber:
        description: Floating point value.
        type: number
        x-nullable: false
      valueInteger:
        description: Integer value.
        type: integer
        x-nullable: false
      valueArray:
        description: Array of field values.
        type: array
        items:
          $ref: '#/definitions/FieldValue'
      valueObject:
        description: Dictionary of named field values.
        type: object
        additionalProperties:
          $ref: '#/definitions/FieldValue'
      valueSelectionMark:
        description: Selection mark value.
        type: string
        enum:
        - selected
        - unselected
        x-nullable: false
      valueGender:
        description: 'Gender value: M, F, or X.'
        type: string
        enum:
        - M
        - F
        - X
        x-nullable: false
      valueCountry:
        description: 3-letter country code (ISO 3166-1 alpha-3).
        type: string
        x-nullable: false
      text:
        description: Text content of the extracted field.
        type: string
      boundingBox:
        description: Bounding box of the field value, if appropriate.
        $ref: '#/definitions/BoundingBox'
      confidence:
        description: Confidence score.
        $ref: '#/definitions/Confidence'
      elements:
        description: When includeTextDetails is set to true, a list of references to the text elements constituting this field.
        type: array
        items:
          $ref: '#/definitions/ElementReference'
      page:
        description: The 1-based page number in the input document.
        type: integer
        minimum: 1
        x-nullable: false
  DocumentResult:
    description: A set of extracted fields corresponding to the input document.
    type: object
    required:
    - docType
    - pageRange
    - fields
    properties:
      docType:
        description: Document type.
        type: string
      modelId:
        description: Model identifier.
        type: string
        format: uuid
        x-nullable: false
      pageRange:
        description: First and last page number where the document is found.
        type: array
        minItems: 2
        maxItems: 2
        items:
          type: integer
          minimum: 1
          x-nullable: false
      docTypeConfidence:
        description: Predicted document type confidence.
        $ref: '#/definitions/Confidence'
      fields:
        description: Dictionary of named field values.
        type: object
        additionalProperties:
          $ref: '#/definitions/FieldValue'
  AnalyzeResult:
    description: Analyze operation result.
    type: object
    required:
    - version
    - readResults
    properties:
      version:
        description: Version of schema used for this result.
        type: string
      readResults:
        description: Text extracted from the input.
        type: array
        items:
          $ref: '#/definitions/ReadResult'
      pageResults:
        description: Page-level information extracted from the input.
        type: array
        items:
          $ref: '#/definitions/PageResult'
      documentResults:
        description: Document-level information extracted from the input.
        type: array
        items:
          $ref: '#/definitions/DocumentResult'
      errors:
        description: List of errors reported during the analyze operation.
        type: array
        items:
          $ref: '#/definitions/ErrorInformation'
  PageResult:
    description: Extracted information from a single page.
    type: object
    required:
    - page
    properties:
      page:
        description: Page number.
        type: integer
        format: int32
        minimum: 1
        x-nullable: false
      clusterId:
        description: Cluster identifier.
        type: integer
        format: int32
        minimum: 0
        x-nullable: false
      keyValuePairs:
        description: List of key-value pairs extracted from the page.
        type: array
        items:
          $ref: '#/definitions/KeyValuePair'
      tables:
        description: List of data tables extracted from the page.
        type: array
        items:
          $ref: '#/definitions/DataTable'
  Confidence:
    description: Confidence value.
    type: number
    minimum: 0
    maximum: 1
    x-nullable: false
parameters:
  Language:
    name: language
    in: query
    description: Currently, only Afrikaans (‘af’), Albanian (‘sq’), Asturian (‘ast’), Basque (‘eu’), Bislama (‘bi’), Breton (‘br’), Catalan (‘ca’), Cebuano (‘ceb’), Chamorro (‘ch’), Cornish (‘kw’), Corsican (‘co’), Crimean Tatar - Latin script(‘crh’), Czech (‘cs’), Danish (‘da’), Dutch (‘nl’), English ('en'), Estonian (‘et’), Fijian (‘fj’), Filipino (‘fil’), Finnish (‘fi’), French (‘fr’), Friulian (‘fur’), Galician (‘gl’), German (‘de’), Gilbertese (‘gil’), Greenlandic (‘kl’), Haitian Creole (‘ht’), Hani (‘hni’), Hmong Daw (‘mww’), Hungarian (‘hu’), Indonesian (‘id’), Interlingua (‘ia’), Inuktitut (‘iu’), Irish (‘ga’), Italian (‘it’), Japanese (‘ja’), Javanese (‘jv’), Kabuverdianu (‘kea’), Kachin (‘kac’), Kara-Kalpak (‘kaa’), Kashubian (‘csb’), Khasi (‘kha’), Korean (‘ko’), Kurdish - Latin script (‘ku’), K’iche’ (‘quc’), Luxembourgish (‘lb’), Malay (‘ms’), Manx (‘gv’), Neapolitan (‘nap’), Norwegian (‘no’), Occitan (‘oc’), Polish (‘pl’), Portuguese (‘pt’), Romansh (‘rm’), Scots (‘sco’), Scottish Gaelic (‘gd’), simplified Chinese (‘zh-Hans’), Slovenian (‘sl’), Spanish (‘es’), Swahili (‘sw’), Swedish (‘sv’), Tatar - Latin script (‘tt’), Tetum (‘tet’), traditional Chinese (‘zh-Hant’), Turkish (‘tr’), Upper Sorbian (‘hsb’), Uzbek (‘uz’), Volapük (‘vo’), Walser (‘wae’), Western Frisian (‘fy’), Yucatec Maya (‘yua’), Zhuang (‘za’) and Zulu (‘zu’) are supported (print – seventy-three languages and handwritten – English only). Layout supports auto language identification and multi language documents, so only provide a language code if you would like to force the documented to be processed as that specific language.
    required: false
    x-ms-parameter-location: method
    type: string
    enum:
    - af
    - ast
    - bi
    - br
    - ca
    - ceb
    - ch
    - co
    - crh
    - cs
    - csb
    - da
    - de
    - en
    - es
    - et
    - eu
    - fi
    - fil
    - fj
    - fr
    - fur
    - fy
    - ga
    - gd
    - gil
    - gl
    - gv
    - hni
    - hsb
    - ht
    - hu
    - ia
    - id
    - it
    - iu
    - ja
    - jv
    - kaa
    - kac
    - kea
    - kha
    - kl
    - ko
    - ku
    - kw
    - lb
    - ms
    - mww
    - nap
    - nl
    - 'no'
    - oc
    - pl
    - pt
    - quc
    - rm
    - sco
    - sl
    - sq
    - sv
    - sw
    - tet
    - tr
    - tt
    - uz
    - vo
    - wae
    - yua
    - za
    - zh-Hans
    - zh-Hant
    - zu
    x-ms-enum:
      name: Language
      modelAsString: true
  Pages:
    name: pages
    in: query
    description: Custom page numbers for multi-page documents(PDF/TIFF), input the number of the pages you want to get OCR result. For a range of pages, use a hyphen. Separate each page or range with a comma.
    required: false
    x-ms-parameter-location: method
    type: array
    items:
      type: string
      pattern: (^[0-9]+-[0-9]+$)|(^[0-9]+$)
  FileStream:
    name: fileStream
    description: .json, .pdf, .jpg, .png, .tiff or .bmp type file stream.
    x-ms-parameter-location: method
    in: body
    schema:
      $ref: '#/definitions/SourcePath'
  ReadingOrder:
    name: readingOrder
    in: query
    description: 'Reading order algorithm to sort the text lines returned. Supported reading orders include: basic(default), natural.'
    required: false
    x-ms-parameter-location: method
    default: basic
    type: string
    enum:
    - basic
    - natural
    x-ms-enum:
      name: ReadingOrder
      modelAsString: false
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'