openapi: 3.0.3
info:
  title: Delta Sharing API
  description: An Open Protocol for Secure Data Sharing
  license:
    name: AGPL v3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: 0.0.0
tags:
  - name: CatalogService
  - name: DeltaSharingService
    description: Service exposing the official APIs for Delta Sharing.
  - name: official
    description: APIs which are part of published official document
  - name: schemas
    description: Schema discovery APIs
  - name: shares
    description: Share discovery APIs
  - name: tables
    description: Table query and inspection APIs
  - name: unofficial
    description: APIs which are custom to delta-sharing-rs
paths:
  /shares:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: List shares accessible to a recipient.
      operationId: ListShares
      parameters:
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSharesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    post:
      tags:
        - CatalogService
        - shares
        - unofficial
      description: Create a new Share in the Delta Sharing service.
      operationId: CreateShare
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareInfo'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareInfo'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{name}:
    delete:
      tags:
        - CatalogService
        - shares
        - unofficial
      description: Delete a Share in the Delta Sharing service.
      operationId: DeleteShare
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareInfo'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: Get the metadata for a specific share.
      operationId: GetShare
      parameters:
        - name: share
          in: path
          description: The share id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/all-tables:
    get:
      tags:
        - DeltaSharingService
        - tables
        - official
      description: List all the tables under all schemas in a share.
      operationId: ListShareTables
      parameters:
        - name: share
          in: path
          description: The share id.
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListShareTablesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas:
    get:
      tags:
        - DeltaSharingService
        - schemas
        - official
      description: List the schemas in a share.
      operationId: ListSchemas
      parameters:
        - name: share
          in: path
          description: The share id.
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchemasResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    post:
      tags:
        - CatalogService
        - schemas
        - unofficial
      description: Create a new Schema in the Delta Sharing service.
      operationId: CreateSchema
      parameters:
        - name: share
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaInfo'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaInfo'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{name}:
    delete:
      tags:
        - CatalogService
        - schemas
        - unofficial
      description: Delete a Schema in the Delta Sharing service.
      operationId: DeleteSchema
      parameters:
        - name: share
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaInfo'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{name}/tables:
    get:
      tags:
        - DeltaSharingService
        - tables
        - official
      description: List the tables in a given share's schema.
      operationId: ListSchemaTables
      parameters:
        - name: share
          in: path
          description: The share name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: The schema name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchemaTablesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{schema}/tables/{name}/metadata:
    get:
      tags:
        - DeltaSharingService
        - tables
        - official
      operationId: GetTableMetadata
      parameters:
        - name: share
          in: path
          description: The share name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: schema
          in: path
          description: The schema name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: The table name to query. It's case-insensitive.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{schema}/tables/{name}/version:
    get:
      tags:
        - DeltaSharingService
        - tables
        - official
      description: Get the current version for a table within a schema.
      operationId: GetTableVersion
      parameters:
        - name: share
          in: path
          description: The share name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: schema
          in: path
          description: The schema name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: The table name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: startingTimestamp
          in: query
          description: |-
            The startingTimestamp of the query, a string in the  ISO8601 format, in the UTC timezone,
             such as 2022-01-01T00:00:00Z. the server needs to return the earliest table version at
             or after the provided timestamp, can be earlier than the timestamp of table version 0.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTableVersionResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    AdditionalPropertiesItem:
      type: object
      properties:
        schemaOrReference:
          $ref: '#/components/schemas/SchemaOrReference'
        boolean:
          type: boolean
    Any:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/GoogleProtobufAny'
        yaml:
          type: string
    DefaultType:
      type: object
      properties:
        number:
          type: number
          format: double
        boolean:
          type: boolean
        string:
          type: string
    DeltaLogMessage:
      type: object
      properties:
        protocol:
          $ref: '#/components/schemas/ProtocolDelta'
        metadata:
          $ref: '#/components/schemas/MetadatDelta'
    DeltaResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/DeltaLogMessage'
    Discriminator:
      type: object
      properties:
        propertyName:
          type: string
        mapping:
          $ref: '#/components/schemas/Strings'
        specificationExtension:
          type: array
          items:
            $ref: '#/components/schemas/NamedAny'
      description: When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.  When using the discriminator, _inline_ schemas will not be considered.
    ExternalDocs:
      type: object
      properties:
        description:
          type: string
        url:
          type: string
        specificationExtension:
          type: array
          items:
            $ref: '#/components/schemas/NamedAny'
      description: Allows referencing an external resource for extended documentation.
    Format:
      type: object
      properties:
        provider:
          type: string
          description: Name of the encoding for files in this table
        options:
          type: object
          additionalProperties:
            type: string
          description: A map containing configuration options for the format
    GetTableVersionResponse:
      type: object
      properties:
        version:
          type: string
          description: The table version that was requested.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
    ItemsItem:
      type: object
      properties:
        schemaOrReference:
          type: array
          items:
            $ref: '#/components/schemas/SchemaOrReference'
    ListSchemaTablesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Table'
          description: The tables that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of tables.
             An empty or missing token means that no more tables are available for retrieval.
    ListSchemasResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
          description: The schemas that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of schemas.
             An empty or missing token means that no more schemas are available for retrieval.
    ListShareTablesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Table'
          description: The tables that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of tables.
             An empty or missing token means that no more tables are available for retrieval.
    ListSharesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Share'
          description: The shares that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of shares.
             An empty or missing token means that no more shares are available for retrieval.
    MetadatDelta:
      type: object
      properties:
        deltaMetadata:
          allOf:
            - $ref: '#/components/schemas/Metadata'
          description: Metadata from Delta protocol
        version:
          type: string
          description: |-
            The table version the metadata corresponds to, returned when querying
             table data with a version or timestamp parameter, or cdf query
             with includeHistoricalMetadata set to true.
        size:
          type: string
          description: The size of the table in bytes, will be returned if available in the delta log.
        numFiles:
          type: string
          description: The number of files in the table, will be returned if available in the delta log.
    Metadata:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this table
             Validate GUID
        name:
          type: string
          description: User-provided identifier for this table
        description:
          type: string
          description: User-provided description for this table
        format:
          allOf:
            - $ref: '#/components/schemas/Format'
          description: Specification of the encoding for the files stored in the table
        schemaString:
          type: string
          description: Schema of the table
        partitionColumns:
          type: array
          items:
            type: string
          description: An array containing the names of columns by which the data should be partitioned
        createdTime:
          type: string
          description: The time when this metadata action is created, in milliseconds since the Unix epoch
        options:
          type: object
          additionalProperties:
            type: string
          description: A map containing configuration options for the metadata action
    MetadataParquet:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this table
        name:
          type: string
          description: User-provided identifier for this table
        description:
          type: string
          description: User-provided description for this table
        format:
          allOf:
            - $ref: '#/components/schemas/Format'
          description: Specification of the encoding for the files stored in the table
        schemaString:
          type: string
          description: Schema of the table
        partitionColumns:
          type: array
          items:
            type: string
          description: An array containing the names of columns by which the data should be partitioned
    NamedAny:
      type: object
      properties:
        name:
          type: string
          description: Map key
        value:
          allOf:
            - $ref: '#/components/schemas/Any'
          description: Mapped value
      description: Automatically-generated message used to represent maps of Any as ordered (name,value) pairs.
    NamedSchemaOrReference:
      type: object
      properties:
        name:
          type: string
          description: Map key
        value:
          allOf:
            - $ref: '#/components/schemas/SchemaOrReference'
          description: Mapped value
      description: Automatically-generated message used to represent maps of SchemaOrReference as ordered (name,value) pairs.
    NamedString:
      type: object
      properties:
        name:
          type: string
          description: Map key
        value:
          type: string
          description: Mapped value
      description: Automatically-generated message used to represent maps of string as ordered (name,value) pairs.
    ParquetLogMessage:
      type: object
      properties:
        protocol:
          $ref: '#/components/schemas/ProtocolParquet'
        metadata:
          $ref: '#/components/schemas/MetadataParquet'
    ParquetResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/ParquetLogMessage'
    Properties:
      type: object
      properties:
        additionalProperties:
          type: array
          items:
            $ref: '#/components/schemas/NamedSchemaOrReference'
    ProtocolDelta:
      type: object
      properties:
        minReaderVersion:
          type: integer
          description: |-
            The minimum version of the protocol that a client must implement
             in order to correctly read a Delta Lake table.
          format: int32
        minWriterVersion:
          type: integer
          format: int32
    ProtocolParquet:
      type: object
      properties:
        minReaderVersion:
          type: integer
          description: |-
            The minimum version of the protocol that a client must implement
             in order to correctly read a Delta Lake table.
          format: int32
    QueryResponse:
      type: object
      properties:
        parquet:
          allOf:
            - $ref: '#/components/schemas/ParquetResponse'
          description: Parquet response format
        delta:
          allOf:
            - $ref: '#/components/schemas/DeltaResponse'
          description: Delta response format
    Reference:
      type: object
      properties:
        Ref:
          type: string
        summary:
          type: string
        description:
          type: string
      description: A simple object to allow referencing other components in the specification, internally and externally.  The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.   For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.
    Schema:
      type: object
      properties:
        nullable:
          type: boolean
        discriminator:
          $ref: '#/components/schemas/Discriminator'
        readOnly:
          type: boolean
        writeOnly:
          type: boolean
        xml:
          $ref: '#/components/schemas/Xml'
        externalDocs:
          $ref: '#/components/schemas/ExternalDocs'
        example:
          $ref: '#/components/schemas/Any'
        deprecated:
          type: boolean
        title:
          type: string
        multipleOf:
          type: number
          format: double
        maximum:
          type: number
          format: double
        exclusiveMaximum:
          type: boolean
        minimum:
          type: number
          format: double
        exclusiveMinimum:
          type: boolean
        maxLength:
          type: string
        minLength:
          type: string
        pattern:
          type: string
        maxItems:
          type: string
        minItems:
          type: string
        uniqueItems:
          type: boolean
        maxProperties:
          type: string
        minProperties:
          type: string
        required:
          type: array
          items:
            type: string
        enum:
          type: array
          items:
            $ref: '#/components/schemas/Any'
        type:
          type: string
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/SchemaOrReference'
        oneOf:
          type: array
          items:
            $ref: '#/components/schemas/SchemaOrReference'
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/SchemaOrReference'
        not:
          $ref: '#/components/schemas/Schema'
        items:
          $ref: '#/components/schemas/ItemsItem'
        properties:
          $ref: '#/components/schemas/Properties'
        additionalProperties:
          $ref: '#/components/schemas/AdditionalPropertiesItem'
        default:
          $ref: '#/components/schemas/DefaultType'
        description:
          type: string
        format:
          type: string
        specificationExtension:
          type: array
          items:
            $ref: '#/components/schemas/NamedAny'
      description: The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.  For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.
    SchemaInfo:
      type: object
      properties:
        id:
          readOnly: true
          type: string
        name:
          type: string
        share:
          readOnly: true
          type: string
        shareId:
          readOnly: true
          type: string
        description:
          type: string
        properties:
          type: object
    SchemaOrReference:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/Schema'
        reference:
          $ref: '#/components/schemas/Reference'
    Share:
      type: object
      properties:
        name:
          type: string
          description: Name of the share.
        id:
          readOnly: true
          type: string
          description: Unique identifier for the share.
      description: |-
        A share is a logical grouping to share with recipients. A share can be shared with one or multiple recipients.
         A recipient can access all resources in a share. A share may contain multiple schemas.
    ShareInfo:
      type: object
      properties:
        id:
          readOnly: true
          type: string
        name:
          type: string
        description:
          type: string
        properties:
          type: object
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    Strings:
      type: object
      properties:
        additionalProperties:
          type: array
          items:
            $ref: '#/components/schemas/NamedString'
    Table:
      type: object
      properties:
        name:
          type: string
          description: The name of the table.
        schema:
          type: string
          description: The schema name that the table belongs to.
        share:
          type: string
          description: The share name that the table belongs to.
        id:
          readOnly: true
          type: string
          description: Unique identifier for the table.
        shareId:
          readOnly: true
          type: string
          description: A unique identifier for the share this table belongs to.
      description: A table is a Delta Lake table or a view on top of a Delta Lake table.
    Xml:
      type: object
      properties:
        name:
          type: string
        namespace:
          type: string
        prefix:
          type: string
        attribute:
          type: boolean
        wrapped:
          type: boolean
        specificationExtension:
          type: array
          items:
            $ref: '#/components/schemas/NamedAny'
      description: A metadata object that allows for more fine-tuned XML model definitions.  When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior.