nakadi-event-bus-api.yaml

swagger: '2.0'
info:
  title: Nakadi Event Bus API Definition
  description: |
    -----------
    Definitions
    -----------
    Nakadi at its core aims at being a generic and content-agnostic event broker with a convenient API.
    In doing this, Nakadi abstracts away, as much as possible, details of the backing messaging
    infrastructure. The single currently supported messaging infrastructure is Kafka (Kinesis is planned
    for the future).

    In Nakadi every Event has an EventType, and a **stream** of Events is exposed for each registered
    EventType.

    An EventType defines properties relevant for the operation of its associated stream, namely:

    * The **schema** of the Event of this EventType. The schema defines the accepted format of Events of an
    EventType and will be, if so desired, enforced by Nakadi. Usually Nakadi will respect the schema for
    the EventTypes in accordance to how an owning Application defines them.
    **Note:** *Currently the specification of the schema must be pushed into Nakadi on EventType creation;
    in the future, assuming that Applications will expose the schema for its owned resources, Nakadi might
    support fetching the schema directly from them.*

    * The expected **validation** and **enrichment** procedures upon reception of an Event.
    Validation define conditions for the acceptance of the incoming Event and are strictly enforced by
    Nakadi. Usually the validation will enforce compliance of the payload (or part of it) with the defined
    schema of its EventType. Enrichment specify properties that are added to the payload (body) of the Event
    before persisting it. Usually enrichment affects the metadata of an Event but is not limited to.

    * The **ordering** expectations of Events in this stream. Each EventType will have its Events stored in
    an underlying logical stream (the Topic) that is phisically organized in disjoint collections of
    strictly ordered Events (the Partition). The EventType defines the field that acts as evaluator of the
    ordering (that is, its partitioning key); this ordering is guaranteed by making Events whose partition
    key resolves to the same Partition (usually a hash function on its value) be persisted strictly ordered
    in a Partition.
    In practice this means that all Events within a Partition have their relative order guaranteed: Events
    (of a same EventType) that are *about* a same data entity (that is, have the same value on its Partition
    key) reach always the same Partition, the relative ordering of them is secured. This mechanism implies
    that no statements can be made about the relative ordering of Events that are in different partitions.

    Except for defined enrichment rules, Nakadi will never manipulate the content of any Event.

    Clients of Nakadi can be grouped in 2 categories: **EventType owners** and **Clients** (clients in turn
    are both **Producers** and **Consumers** of Events). Event Type owners interact with Nakadi via the
    **Schema Registry API** for the definition of EventTypes, while Clients via the streaming API for
    submission and reception of Events.

    A low level **Unmanaged API** is available, providing full control and responsibility of position
    tracking and partitioning (and therefore ordering) to the Clients.

    In the high level **Subscription API** the consumption of Events proceeds via the establishment of a
    named **Subscription** to an EventType. Subscriptions are persistent relationships from an Application
    (which might have several instances) and the stream of one or more EventType's, whose consumption
    tracking is managed by Nakadi, freeing Consumers from any responsibility in tracking of the current
    position on a Stream.

    **Note** *Currently the high level API is out of scope in this specification.
    It is in the short term plan to be included.*


    Scope and status of this document
    ---------------------------------

    The present API specification is in **draft** state and is subject to change.

    In this document, ready for review are included:
    * The Schema Registry API, including configuration possibilities for the Schema, Validation, Enrichment
    and Partitioning of Events, and their effects on reception of Events.

    *  The stantardised event format (see definition of Event, BusinessEvent and DataChangeEvent) (Note: at a
    later moment this will be configurable and not be inherent part of this API).

    * Unmanaged API (low level).

    Other aspects of the Event Bus are at this moment to be defined and otherwise specificied, not included
    in this version of this specification.

    Notable omissions here are:

    * Submission of events in batched manner.

    * The contract between Nakadi and clients in the context of the high-level API (i.e. the process for
    clients to establish subscriptions).

    * Validation and enrichment procedures.

    * Security scopes (OAuth) for the different operations

    * Validation and Enrichment Strategies available in Nakadi are out of this document an can be consulted
    in an external document (TBD link to document).

    * Explicit control of (in case of Kafka as underlying messaging broker) topic's creation
    parameters (number of partitions, retention times, etc), as well as their modification.


  version: '0.5.1'
  contact:
    name: Team Aruha @ Zalando
    email: team-aruha+nakadi-maintainers@zalando.de
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  oauth2:
    type: oauth2
    flow: implicit
    authorizationUrl: 'https://auth.example.com/oauth2/tokeninfo'
    scopes:
      nakadi.read: |
        Generic read scope for operations that do not require more specific restrictions.
      nakadi.event.type.write: |
        Grants access for applications to define and update EventTypes.
      nakadi.event.stream.write: |
        Grants access for applications to submit Events.
      nakadi.event.stream.read: |
        Grants access for consuming Event streams.

paths:
  /metrics:
    get:
      tags:
        - monitoring
      summary: Get monitoring metrics
      responses:
        '200':
          description: Ok
          schema:
            $ref: '#/definitions/Metrics'
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'
        '503':
          description: Not available
          schema:
            $ref: '#/definitions/Problem'
  /event-types:
    get:
      tags:
        - schema-registry-api
      description: Returns a list of all registered `EventType`s
      parameters:
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id
      responses:
        '200':
          description: Ok
          schema:
            type: array
            items:
              $ref: '#/definitions/EventType'
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'

    post:
      tags:
        - schema-registry-api
      description: |
        Creates a new `EventType`.

        **Implementation note:** The creation of an EventType implicitly creates the structures in the
        backing messaging implementation needed for the reception and persistency of the Events. Considering
        that at this time only Kafka is used, this corresponds to the creation of a Topic. If so desired,
        clients can interact directly with the topic using the low level API (for existing restrictions see
        the corresponding methods on the topic-api).

        The fields validation-strategies, enrichment-strategies and partition-resolution-strategy have all an
        effect on the incoming Event of this EventType. For its impacts on the reception of events please
        consult the Event submission API methods.

        * Validation strategies define an array of `EventValidationStrategy` to be evaluated on reception of
        an `Event` of this `EventType`. Details of usage can be found in an external document (TBD link to
        document).
        **Notes**: Some EventValidationStrategies might support additional parameters. The behaviour is
        specific to each strategy and one is suggested to consult its `doc` field for detailes of operation.
        The default `SchemaValidationStrategy` supports passing fields to be ignored if the qualifier matches
        the input.

        * TDB Enrichment strategy

        * TDB Partition resolution strategy

        * The schema of an `EventType` is defined as an `EventTypeSchema`. Currently only json-schema is
        supported.

        Following conditions are enforced. Not meeting them will fail the request with the indicated status
        (details are provided in the Problem object):

        * EventType name on creation must be unique (or attempting to update an `EventType` with this
          method), otherwise the request is rejected with status 409 Conflict.

        * Using `EventTypeSchema.type` other than json-schema or passing a `EventTypeSchema.schema`
        that is invalid with respect to the schema's type. Rejects with 422 Unprocessable entity.

        * Referring any of Validation, Enrichment or Partitioning strategies that does not exist or whose
        parameterization is deemed invalid. Rejects with 422 Unprocessable entity.

        Nakadi MIGHT impose necessary schema, validation and enrichment minimal configurations that MUST be
        followed by all EventTypes (examples include: validation rules to match the schema; enriching every
        Event with the reception date-type; adhering to a set of schema fields that are mandatory for all
        EventTypes). **The mechanism to set and inspect such rules is not defined at this time and might not
        be exposed in the API.**

      parameters:
        - name: event-type
          in: body
          description: EventType to be created
          schema:
            $ref: '#/definitions/EventType'
          required: true
      responses:
        '200':
          description: Ok
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '409':
          description: Conflict, for example on creation of EventType with already existing name.
          schema:
            $ref: '#/definitions/Problem'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'


  /event-types/{name}:
    get:
      tags:
        - schema-registry-api
      description: |
        Returns the `EventType` identified by its name.
      parameters:
        - name: name
          in: path
          description: Name of the EventType to load.
          type: string
          required: true
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id
      responses:
        '200':
          description: Ok
          schema:
            $ref: '#/definitions/EventType'
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '404':
          description: EventType not found
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'

    put:
      tags:
        - schema-registry-api
      description: |
        Updates the `EventType` identified by its name. Behaviour is the same as creation of `EventType` (See
        POST /event-type) except where noted below.

        The name field cannot be changed. Attempting to do so will result in a 422 failure.

        At this moment changes in the schema are not supported and will produce a 422 failure. (TODO: define
        conditions for backwards compatible extensions in the schema)
      parameters:
        - name: name
          in: path
          description: Name of the EventType to update.
          type: string
          required: true
        - name: event-type
          in: body
          description: EventType to be updated.
          schema:
            $ref: '#/definitions/EventType'
          required: true
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id
      responses:
        '200':
          description: Ok
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '404':
          description: EventType not found.
          schema:
              $ref: '#/definitions/Problem'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'

  /event-types/{name}/events:
    post:
      tags:
        - stream-api
      description: |
        Publishes one `Event` of this `EventType`. (**Note** *Format and response semantics of publishing of
        batches of Events will be added in the short term.*)

        Reception of Events will always respect the configuration of its `EventType` w.r.t. validation,
        enrichment and partitioning. The steps performed on reception of incoming message are:

        1. Every validation rule specified in the `EventType` will be checked in order against the incoming
        Events. Validation rules are evaluated in the order they are defined and the Event is **rejected**
        in the first case of failure with a status of 400 Bad request. If the offending validation rule
        provides information about the violation it will be included in the Problem response.
        If the `EventType` defines schema validation it will be performed at this moment.

        1. Once the validation succeeded, the content of the Event is updated according to the enrichment
        rules in the order the rules are defined in the `EventType`.
        No preexisting value might be changed (even if added by an enrichment rule). Violations on this will
        force the immediate **rejection** of the Event with a 409 Conflict status. The invalid overwrite
        attempt will be included in the respose's Problem object.

        1. The incoming Event's relative ordering is evaluated according to the rule on the
        `EventType`. Failure to evaluate the rule will **reject** the Event.
        **Restriction**: POSTing Events based on its `EventType` requires it to have a
        `PartitioningStrategy` defined. Violating this condition will produce a 405 Not allowed.

      parameters:
        - name: name
          in: path
          type: string
          description: Name of the EventType
          required: true
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id
        - name: event
          in: body
          description: The Event being published
          schema:
            $ref: '#/definitions/Event'
          required: true
      responses:
        '200':
          description: Ok
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Problem'
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '404':
          description: EventType not found.
          schema:
              $ref: '#/definitions/Problem'
        '405':
          description: Not allowed.
          schema:
              $ref: '#/definitions/Problem'
        '409':
          description: Conflict.
          schema:
              $ref: '#/definitions/Problem'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'
    get:
      tags:
        - stream-api
        - unmanaged-api
        - draft
      description: |
        Starts a stream delivery for the specified partitions of the given EventType.

        The event stream is formated as a sequence of `EventStreamBatch`es separated by `\n`. Each
        `EventStreamBatch` constains a chunk of Events and a `Cursor` pointing to the **end** of the
        chunk (i.e. last delivered Event). The cursor might specify the offset with the symbolic value
        `OLDEST`, which will open the stream starting from the oldest available offset in the partition.
        Currently this format is the only one supported by the system, but in the future other MIME types
        will be suported (like `application/event-stream`).

        If streaming for several distinct partitions, each one is an independent `EventStreamBatch`.

        The initialization of a stream can be parameterized in terms of size of each chunk, timeout for
        flushing each chunk, total amount of delivered Events and total time for the duration of the stream.

        Nakadi will keep a streaming connection open even if there are no events to be delivered. In this
        case the timeout for the flushing of each chunk will still apply and the `EventStreamBatch` will
        contain only the Cursor pointing to the same offset. This can be treated as a keep-alive control for
        some load balancers.

        The tracking of the current offset in the partitions and of which partitions is being read is in
        the responsibility of the client. No commits are needed.
      produces:
        - application/x-json-stream
      parameters:
        - name: name
          in: path
          description: EventType name to get events about
          type: string
          required: true
        - name: X-nakadi-cursors
          in: header
          description: |
            Array of cursors indicating the partitions to read from and the starting offset on each such a
            partition.

            Assumes the offset on each cursor is not inclusive (i.e., first delivered Event is the
            **first one after** the one pointed to in the cursor).

            If the header is not present, the stream for all partitions defined for the EventType will start
            from the newest event available in the system at the moment of making this call.

            **Note:** we are not using query parameters for passing the cursors only because of the length
            limitations on the HTTP query. Another way to initiate this call would be the POST method with
            cursors passed in the method body. This aproach can implemented in the future versions of this
            API.

          required: false
          type: array
          items:
            type: string
            format: '#/definitions/Cursor'
        - name: batch_limit
          in: query
          description: |
            Maximum number of `Event`s in each chunk (and therefore per partition) of the stream.

            * If 0 or unspecified will buffer Events indefinitely and flush on reaching of
            `batch_flush_timeout`.
          type: integer
          format: int32
          required: false
          default: 1
        - name: stream_limit
          in: query
          description: |
            Maximum number of `Event`s in this stream (over all partitions being streamed in this
            connection).

            * If 0 or undefined, will stream batches indefinately.

            * Stream initialization will fail if `stream_limit` is lower than `batch_limit`.
          type: integer
          format: int32
          required: false
          default: 0
        - name: batch_flush_timeout
          in: query
          description: |
            Maximum time in seconds to wait for the flushing of each chunk (per partition).

            * If the amount of buffered Events reaches `batch_limit` before this `batch_flush_timeout`
            is reached, the messages are immediately flushed to the client and batch flush timer is reset.

            * If 0 or undefined, will assume 30 seconds.
          type: number
          format: int32
          required: false
          default: 30
        - name: stream_timeout
          in: query
          description: |
            Maximum time in seconds a stream will live before being interrupted.
            If 0 or unspecified will stream indefinately.

            If this timeout is reached, any pending messages (in the sense of `stream_limit`) will be flushed
            to the client.

            Stream initialization will fail if `stream_timeout` is lower than `batch_flush_timeout`.
          type: number
          format: int32
          required: false
          default: 0
        - name: stream_keep_alive_limit
          in: query
          description: |
            Maximum number of keep-alive messages to get in a row before closing the connection.

            If 0 or undefined will send keep alive messages indefinitely.
          type: integer
          format: int32
          required: false
          default: 0
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id

      responses:
        '200':
          description: |
            Starts streaming to the client.
            Stream format is a continuous series of `EventStreamBatch`s separated by `\n`
          schema:
            $ref: '#/definitions/EventStreamBatch'
        '400':
          description: Bad syntax
          schema:
            $ref: '#/definitions/Problem'
        '401':
          description: Not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '404':
          description: EventType not found
          schema:
            $ref: '#/definitions/Problem'
        '422':
          description: Unprocessable entity
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Internal Server Error. Details are provided on the returned `Problem`.
          schema:
            $ref: '#/definitions/Problem'

  /event-types/{name}/partitions':
    get:
      tags:
        - unmanaged-api
        - monitoring
        - management-api
      description: |
        Lists the `Partition`s for the given event-type.

        This endpoint is mostly interesting for monitoring purposes or in cases when consumer wants to start
        consuming older messages.


      parameters:
        - name: name
          in: path
          description: EventType name
          type: string
          required: true
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id
      responses:
        '200':
          description: OK
          schema:
            type: array
            description: An array of `Partition`s
            items:
              $ref: '#/definitions/Partition'
        '404':
          description: EventType not found
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'

  /event-types/{name}/partitions/{partition}:
    get:
      tags:
        - unmanaged-api
        - management-api
      description: Returns the given `Partition` of this EventType
      parameters:
        - name: name
          in: path
          description: EventType name
          type: string
          required: true
        - name: partition
          in: path
          description: Partition id
          type: string
          required: true
        - name: X-Flow-Id
          in: header
          description: |
            The flow id of the request, which is written into the logs and passed to called services. Helpful
            for operational troubleshooting and log analysis.
          type: string
          format: flow-id
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Partition'
        '401':
          description: Client is not authenticated
          schema:
            $ref: '#/definitions/Problem'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/Problem'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/Problem'

  '/registry/validation-strategies':
    get:
      tags:
        - schema-registry-api
      description: |
        Lists all of the validation strategies supported by this installation of Nakadi.

        If the EventType creation is to have special validations (besides the default), one can consult over
        this method the available possibilities.
      responses:
        '200':
          description: Returns a list of all `EventValidationStrategy` known to Nakadi
          schema:
            type: array
            items:
              $ref: '#/definitions/EventValidationStrategy'

  '/registry/enrichment-strategies':
    get:
      tags:
        - schema-registry-api
      description: |
        Lists all of the enrichment strategies supported by this installation of Nakadi.

        If the EventType creation is to have special enrichments (besides the default), one can consult over
        this method the available possibilities.
      responses:
        '200':
          description: Returns a list of all `EventEnrichmentStrategy` known to Nakadi
          schema:
            type: array
            items:
              $ref: '#/definitions/EventEnrichmentStrategy'


  '/registry/partitioning-strategies':
    get:
      tags:
        - schema-registry-api
      description: |
        Lists all of the partitioning strategies supported by this installation of Nakadi.

        If the EventType creation is to have a specific partitioning (besides the default), one can
        consult over this method the available possibilities.
      responses:
        '200':
          description: Returns a list of all `EventPartitioningStrategy` known to Nakadi
          schema:
            type: array
            items:
              $ref: '#/definitions/PartitionResolutionStrategy'


# ################################### #
#                                     #
#             Definitions             #
#                                     #
# ################################### #

definitions:
  Event:
    type: object
    description: |
      **Note** The Event definition will be externalized in future versions of this document.

      A basic payload of an Event. The actual schema is dependent on the information configured for the
      EventType, as is its enforcement (see POST /event-types). Setting of metadata properties are
      dependent on the configured enrichment as well.

      For explanation on default configurations of validation and enrichment, see documentatin of
      `EventType.type`.

      For concrete examples of what will be enforced by Nakadi see the objects BusinessEvent and
      DataChangeEvent below.
    additionalProperties: true

  EventMetadata:
    type: object
    description: |
      Metadata for this Event.

      Contains commons fields for both Business and DataChange Events. Most are enriched by Nakadi upon
      reception, but they in general MIGHT be set by the client.
    properties:
      metadata:
        type: object
        properties:
          eid:
            description: |
              Identifier of this Event.

              Clients are allowed to generate this and this SHOULD be guaranteed to be unique from the
              perspective of the producer. Consumers MIGHT use this value to assert uniqueness of reception
              of the Event.

              If not present upon reception, Nakadi will generate and fill this with a unique value.
              (TBD: enforce UUID formatif set by the client?)
            type: string
            example: '105a76d8-db49-4144-ace7-e683e8f4ba46'
          event_type:
            description: |
              The EventType of this Event. This is enriched by Nakadi on reception of the Event based on the
              endpoint where the Producer sent the Event to.

              If provided MUST match the endpoint. Failure to do so will cause rejection of the Event.
            type: string
            example: 'pennybags:payment-business-event'
          occurred_at:
            description: |
              Timestamp of creation of the Event generated by the producer. Presence is optional but strongly
              recommended for producers.
            type: string
            format: date-time
          received_at:
            type: string
            description: |
              Timestamp of the reception of the Event by Nakadi. This is enriched upon reception of the
              Event.
              If set by the producer Event will be rejected.
            format: date-time
          parent_eid:
            type: string
            format: uuid
            description: |
              Event identifier of the Event that caused the generation of this Event.
              Set by the procuder.
            example: '105a76d8-db49-4144-ace7-e683e8f4ba46'
          root_eid:
            type: string
            format: uuid
            description: |
              Event identifier of the root of the tree of Events (from the relation constructed from
              parent-eid)
            example: '105a76d8-db49-4144-ace7-e683e8f4ba46'
          flow_id:
            description: |
              The flow-id of the producer of this Event. As this is usually a HTTP header, this is enriched
              from the header into the metadata by Nakadi to avoid clients having to explicitly copy this.
            type: string
            example: 'JAh6xH4OQhCJ9PutIV_RYw'

        additionalProperties: false

    required:
      - metadata

  BusinessEvent:
    type: object
    description: |
      A Business Event.

      Usually represents a status transition in a Business process.
    allOf:
      - $ref: '#/definitions/EventMetadata'
    additionalProperties: true

  DataChangeEventQualifier:
    type: object
    description: |
      Indicators of a `DataChangeEvent`'s referred data type and the type of operations done on them.

    properties:
      data_type:
        type: string
        example: 'pennybags:order'
      data_op:
        type: string
        enum: ['C', 'U', 'D', 'S']
        description: |
          The type of operation executed on the entity.
          * C: Creation
          * U: Update
          * D: Deletion
          * S: Snapshot
    required:
      - data_type
      - data_op

  DataChangeEvent:
    type: object
    description: |
      A Data change Event.

      Represents a change on a resource.
    allOf:
      - $ref: '#/definitions/DataChangeEventQualifier'
      - $ref: '#/definitions/EventMetadata'
    properties:
      data:
        type: object
        description: |
            The payload of the type
    required:
        - data
    additionalProperties: false

  Problem:
    type: object
    properties:
      type:
        type: string
        format: uri
        description: |
          An absolute URI that identifies the problem type.  When dereferenced, it SHOULD provide
          human-readable API documentation for the problem type (e.g., using HTML).
          This Problem object is the same as provided by https://github.com/zalando/problem
        example: http://httpstatus.es/503
      title:
        type: string
        description: |
          A short, summary of the problem type. Written in english and readable for engineers (usually not
          suited for non technical stakeholders and not localized)
        example: Service Unavailable
      status:
        type: integer
        format: int32
        description: |
          The HTTP status code generated by the origin server for this occurrence of the problem.
        example: 503
      detail:
        type: string
        description: |
          A human readable explanation specific to this occurrence of the problem.
        example: Connection to database timed out
      instance:
        type: string
        format: uri
        description: |
          An absolute URI that identifies the specific occurrence of the problem.
          It may or may not yield further information if dereferenced.
    required:
      - type
      - title
      - status

  Metrics:
    type: object

  Partition:
    description: |
      Partition information. Can be helpful when trying to start a stream using an unmanaged API.

      This information is not related to the state of the consumer clients.
    required:
      - partition
      - oldest_available_offset
      - newest_available_offset
    properties:
      partition:
        type: string
      oldest_available_offset:
        description: |
          An offset of the oldest available Event in that partition. This value will be changing upon
          removal of Events from the partition by the background archiving/cleanup mechanism.
        type: string
      newest_available_offset:
        description: |
          An offset of the newest available Event in that partition. This value will be changing upon
          reception of new events for this partition by Nakadi.

          This value can be used to construct a cursor when opening streams (see
          `GET /event-type/{name}/events` for details).

          Might assume the special name OLDEST, meaning a pointer to the offset of the oldest available
          event in the partition.
        type: string

  Cursor:
    required:
      - partition
      - offset
    properties:
      partition:
        type: string
        description: |
          Id of the partition pointed to by this cursor.
      offset:
        type: string
        description: |
          Offset of the event being poninted to.

  EventStreamBatch:
    description: |
      One chunk of events in a stream. A batch consists of an array of `Event`s plus a `Cursor` pointing to
      the offset of the last Event in the stream.

      The size of the array of Event is limited by the parameters used to initialize a Stream.

      If acting as a keep alive message (see `GET /event-type/{name}/events`) the events array will be
      omitted.

      Sequential batches might repeat the cursor if no new events arrive.
    required:
      - cursor
    properties:
      cursor:
        $ref: '#/definitions/Cursor'
      events:
        type: array
        items:
          $ref: '#/definitions/Event'

  EventType:
    description: An event type defines the schema and its runtime properties.
    properties:
      name:
        type: string
        description: |
          Name of this EventType. Encodes the owner/responsible for this EventType.

          The name for the EventType SHOULD follow the pattern, but is not enforced
          'stups_owning_application.event-type', for example
          'gizig.price-change'.

          The components of the name are:
          * Organization: the organizational unit where the team is located; can be omitted.
          * Team name: name of the team responsible for owning application; can be omitted.
          * Owning application: SHOULD match the field owning_application; indicates
          * EventType name: name of this EventType; SHOULD end in ChangeEvent for DataChangeEvents; MUST be
          in the past tense for BusinessEvents.

          (TBD: how to deal with organizational changes? Should be reflected on the name of the EventType?
          Isn t it better to omit [organization:team] completely?)
      owning_application:
        type: string
        description: |
          Indicator of the (Stups) Application owning this `EventType`.
        example: price-service
      category:
        type: string
        enum:
          - undefined
          - data
          - business
        description: |
          Defines the category of this EventType.

          The value set will influence, if not set otherwise, the default set of validation-strategies,
          enrichment-strategies, and the effective_schema in the following way:

          - `undefined`: No predefined changes apply. `effective_schema` is exactly the same as the
            `EventTypeSchema`.
            Default validation_strategy for this `EventType` is `[{name: 'schema-validation'}]`.

          - `data`: Events of this category will be DataChangeEvents. `effective_schema` contains `metadata`,
            and adds fields `data_op` and `data_type`. The passed EventTypeSchema defines the schema of
            `data`.
            Default validation_strategy for this `EventType` is `[{name: 'datachange-schema-validation'}]`.

          - `business`: Events of this category will be BusinessEvents. `effective_schema` contains
            `metadata` and any additionally defined properties passed in the `EventTypeSchema` directly on
            top level of the Event. If name conflicts arise, creation of this EventType will be rejected.
            Default validation_strategy for this `EventType` is `[{name: 'schema-validation'}]`.
      effective_schema:
        type: string
        #read-only: true
        description: |
          The effective schema of this `EventType`. The predefined schema validator will use the value of
          this field as base for the validation.

          The creation of EventTypes of different categories implies a distinct general structure for the
          payload of events of each type. This ultimate format the payload must adhere to is reflected in
          the `effective_schema`. See description of field `category` for more details of its generation.

          This field is informative and its contents cannot be manipulated directly.

      validation_strategies:
        description: |
          Determines the validation that has to be executed upon reception of Events of this type. Events are
          rejected if any of the rules fail (see details of Problem response on the Event publishing
          methods).

          Rule evaluation order is the same as in this array.

          If not explicitly set, default value will respect the definition of the `EventType.category`.
        type: array
        items:
          $ref: '#/definitions/EventValidationStrategy'

      enrichment_strategies:
        description: |
          Determines the enrichment to be performed on an Event upon reception. Enrichment is performed once
          upon reception (and after validation) of an Event and is only possible on fields that are not
          defined on the incoming Event.

          See documentation for the write operation for details on behaviour in case of unsuccessful
          enrichment.
        type: array
        items:
          $ref: '#/definitions/EventEnrichmentStrategy'
        default: [{name: 'metadata-enrichment'}]

      partition_resolution_strategy:
        description: |
          Determines how the assignment of the event to a Partition should be handled.

        type: object
        $ref: '#/definitions/PartitionResolutionStrategy'

      schema:
        type: object
        $ref: '#/definitions/EventTypeSchema'
        description: |
          The schema for this EventType. This is expected to be a json schema in yaml format (other formats
          might be added in the future).

      data_key_fields:
        type: array
        items:
          type: string
        description: |
          Indicators of the path of the properties that constitute the primary key (identifier) of the data
          within this Event.
          If set MUST be a valid required field as defined in the schema.
          (TBD should be required? Is applicable only to both Business and DataChange Events?)

      ordering_key_field:
        type: string
        description: |
          Indicator of the field used for guaranteeing the ordering of Events of this type (used by the
          PartitionResolutionStrategy).
          If set MUST be a valid required field as defined in the schema.

    required:
      - name
      - category

  EventTypeSchema:
    properties:
      type:
        type: string
        example: 'json-schema'
        description: The type of schema definition (avro, json-schema, etc).
      schema:
        type: string
        description: |
          The schema as string in the syntax defined in the field type. Failure to respect the syntax will
          fail any operation on an EventType.
    required:
      - type
      - schema

  EventValidationStrategy:
    description: |
      Defines a rule for validation of an incoming Event.

      Rules might require additional parameters; see the `doc` field of the existing rules for details. See
      GET /registry/validation-strategies for a list of available rules.
    properties:
      name:
        type: string
        description: Name of the strategy.
      doc:
        type: string
        description: Documentation for the validation.
    required:
      - name


  PartitionResolutionStrategy:
    description: |
      Defines a rule for the resolution of incoming Events into partitions.

      Rules might require additional parameters; see the `doc` field of the existing rules for details. See
      `GET /registry/partition-strategies` for a list of available rules.
    properties:
      name:
        type: string
        description: Name of the strategy.
      doc:
        type: string
        description: Documentation for the partition resolution.
    required:
      - name

  EventEnrichmentStrategy:
    description: |
      Defines a rule for transformation of an incoming Event. No existing fields might be modified. In
      practice this is used to set automatically values in the Event upon reception (i.e. set a reception
      timestamp on the Event).

      Rules might require additional parameters; see the `doc` field of the existing rules for details. See
      GET /registry/enrichment-strategies for a list of available rules.
    properties:
      name:
        type: string
        description: Name of the strategy.
      doc:
        type: string
        description: Documentation for the enrichment.
    required:
      - name