%UIMA.REST.v1

swagger: '2.0'
info:
  version: "1.0.0"
  title: InterSystems UIMA REST APIs
  description: |
    This is the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) 
    of the UIMA REST APIs, giving you RESTful access to Annotation Store contents in your system.
    Use [swagger-ui](https://github.com/swagger-api/swagger-ui/blob/master/README.md)
    or a similar tool to conveniently browse and test these APIs.
    For more information on UIMA, visit [intersystems.com](http://www.intersystems.com) or
    [Apache UIMA](http://uima.apache.org).
  contact:
    name: InterSystems
    url: http://wrc.intersystems.com
    email: support@intersystems.com
consumes:
  - application/json
produces:
  - application/json
parameters:
  ASNameParam:
    name: annotationStore
    type: string
    in: path
    description: the (package) name of the annotation store to query
    required: true
  DocIDParam:
    name: docID
    type: string
    in: path
    description: the ID of the document to query for
    required: true
definitions:
  AnnotationStoreInfo:
    type: object
    description: metadata and statistics about a given Annotation Store
    required: ["name","annotationTables"]
    properties:
      name:
        description: annotation store name
        type: string
      identifier:
        description: identifier of the object managing this annotation store
        type: string
      annotationTables:
        description: list of annotation tables for this store
        type: array
        items:
          type: object
          required: ["name", "columns"]
          properties:
            name:
              description: annotation table name
              type: string
            topLevel:
              description: whether or not this table stores TOP-level annotations
              type: boolean
              format: integer
            columns:
              type: array
              items:
                type: object
                required: ["name","type"]
                properties:
                  name:
                    type: string
                  type:
                    type: string
                  paths:
                    type: array
                    items:
                      type: object
            filters:
              type: array
              items:
                type: object
            indices:
              type: array
              items:
                type: object
            stats:
              type: object
              title: runtime statistics
              description: runtime statistics for this annotation table
              properties:
                rowCount:
                  description: number of records in this table
                  type: integer
                types:
                  description: list of annotation types in this table
                  type: array
                  items:
                    type: string
  ASRequestObject:
    type: object
    description: request object specifying which annotations to retrieve
    properties:
      maxRows:
        type: integer
        description: maximum number of annotations to retrieve
        default: 500
      columns:
        type: array
        description: list of columns to retrieve, use "*" to retrieve all
        default: ["*"]
        items:
          type: string
      tables:
        type: array
        description: list of tables to retrieve annotations from. leave empty for all 
        default: []
        items:
          type: string
      docIDs:
        type: array
        description: list of documents (idenfied by ID) for which to retrieve annotations
        default: [ 123 ]
        items:
          type: string
      types:
        type: array
        description: list of types of annotations to retrieve. leave empty for all
        default: []
        items:
          type: string
  CASRaw:
    type: object
    description: CAS representation formatted as JsonCasSerializer output
    required: ["_context","_views","_referenced_fss"]
    properties:
      _context:
        type: object
        description: general information on the CAS being serialized
        required: ["_types"]
        properties:
          _types:
            type: object
            description: map of detailed type information, indexed by shortname
            properties:
              ShortName:
                type: object
                description: type information for type with shortname 'SomeType'
                required: ["_id"]
                properties:
                  _id: 
                    type: string
                    description: full type name
                  _feature_types:
                    type: object
                    description: map of nondefault feature types
                    properties:
                      someFeature:
                        type: string
                        description: type of feature
                        enum: ["_ref", "_array", "_binary"]
                  _subtypes:
                    type: array
                    description: list of subtypes (identified by their shortname)
                    items:
                      type: string
      _views:
        type: object
        description: map of the views for this CAS, indexed by view name
        properties:
          _InitialView:
            type: object
            description: map of all types in the view, indexed by type shortname
            properties:
              someType:
                description: array of all annotations in the view of this type
                type: array
                items: 
                  type: object
      _referenced_fss:
        type: object
        description: map of the referenced feature structures from the _views object, indexed by reference
        properties:
          someReference:
            type: object
            description: a feature structure
            required: ["_type"]
            properties:
              _type:
                type: string
                description: the shortname for this FS' type
  Markup:
    type: object
    description: specification for how to mark up text contents
    properties:
      method:
        type: string
        description: how actual markup is specified (such as CSS classes)
        default: "CSS"
        enum: ["CSS"]
      feature:
        type: string
        description: annotation property by which to define distinct styles
        default: "type"
      styleMap:
        type: object
        description: if supplied, this will take precedence over the top-level per-type generated ones
        example: { "com.intersystems.*": "my-css-class", "org.uima.alchemyapi.*": "my-other-css-class" }
        default: {}
  FullDocument:
    type: object
    description: representation of the entire document
    required: ["sofas", "CAS"]
    properties:
      sofas:
        type: array
        items:
          type: object
          description: SofA
          required: ["_id", "sofaID", "mimeType", "sofaString"]
          properties:
            _id:
              type: integer
              description: Internal ID of this SofA in the Annotation Store's Sofa table
            _ref:
              type: integer
              description: Reference of this SofA in the CAS
            sofaID:
              type: string
              description: SofA name in the CAS
              example: "_InitialView"
            sofaString:
              type: string
              description: sofaText
            mimeType:
              type: string
              example: "text"
      CAS:
        $ref: '#/definitions/CASRaw'