swagger: '2.0'

info:
  title: Approvals

  description: >-
    This API manages state-transition based approvals for Financial Institutions.  Approval milestones are useful in confirming that part or all of a process is complete.

      
    Examples of approvals may include Identity Verification Document approval or Account Application approval.
      
      
    Approval States may be one of the following:
      
      * **`open`** Created but pending input subject to approval
      * **`submitted`** Pending review by approver
      * **`approved`** Approval granted
      * **`rejected`** Approval denied
      * **`waived`** Approval forgiven
      * **`returned`** Approver returns approval for modification
      * **`canceled`** Approval request withdrawn

    Allowed state transitions are:

      * `open` -> `submitted`
      * `open` -> `waived`
      * `submitted` -> `approved`
      * `submitted` -> `rejected`
      * `submitted` -> `waived`
      * `submitted` -> `returned`
      * `returned` -> `submitted`
      * `open` -> `canceled`
      * `submitted` -> `canceled`
      * `returned` -> `canceled`
      
    An approval may only be deleted if its `state` is `open` or
    `canceled`. In order to change the state, use `POST` to 
    the `href` in the corresponding 
    links (`apiture:approve`, `apiture:submit`, `apiture:reject`, etc.) 
    in the approval resource as described fully in the _Approval_ schema.


    All approval resources contain an approval type, a resource that
    is also managed in this API. Approval types provide financial
    institutions the ability to track, reconcile and group specific
    approvals. In addition, metadata regarding specific types of
    approvals can be stored on the approval type. Approval types may
    only be deleted if they are not in use by any existing approvals.
    Some examples of approval types may be specific documents releated
    to new account opening that need to be manually approved, account
    applications or transfer requests.


    The _target_ of the approval, which may be any resource, is not
    required but may be provided on the `POST` operation that creates
    the approval. This may be done in the `_links` with the link
    relation `apiture:target`. Alternatively, the content to be approved
    may be embedded within the `attributes` on the
    approval request. It will also be conveyed in the approval representation
    in the `GET` operation on the instance and the summary
    representation in the `/approvals` collection. Some `target`
    examples may include an account application or a document.


    Additional data related to an approval or approval type may be
    stored in the resource's attributes. Attributes can be modified
    through `PATCH` and are _*not*_ copied from the approval type to
    the approval.
      

  version: 0.3.0

  contact:
    name: Apiture
    url: 'https://developer.aptiture.com'
    email: api@apiture.com

  termsOfService: 'TODO: Terms of Service is TBD; need input from Legal team.'

schemes:
  - https

basePath: /approvals

consumes:
  - application/hal+json
  - application/json

produces:
  - application/hal+json
  - application/json

tags:
  - name: API
    description: Endpoints which describe this API.
paths:
  /approvals:
    get:
      summary: Return a collection of approvals
      description: >-
        Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[
        sortable](http://doc.apiture.com/api/concepts/sorting)[
        filterable](http://doc.apiture.com/api/concepts/filtering)[
        searchable](http://doc.apiture.com/api/concepts/searchable) collection
        of approvals. The [links](http://doc.apiture.com/api/concepts/links) in
        the response include pagination links.
      operationId: getApprovals
      x-apiture-implemented: true
      x-apiture-traits:
        link:
          rel: approvals
          title: List Approvals
      tags:
        - Approval
      parameters:
        - name: start
          in: query
          description: >-
            The zero-based index of the first approval item to include in this
            page. The default 0 denotes the beginning of the collection.
          type: integer
          format: int64
          default: 0
        - name: limit
          in: query
          description: >-
            The maximum number of approval representations to return in this
            page.
          type: integer
          format: int32
          default: 100
        - name: sortBy
          in: query
          type: string
          description: >-
            Optional sort criteria. See [sort criteria
            format](http://docs.apiture.com/api/concepts/sorting#criteria), such
            as `?sortBy=field1,-field2`.
        - $ref: '#/parameters/filterQueryParam'
        - $ref: '#/parameters/qQueryParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approvals'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '422':
          $ref: '#/responses/422'
    post:
      summary: Create a new approval
      description: 'Create a new approval in the approvals collection. The link to an Approval Type resource is required in order to create a new Approval resource.  This link should be passed in the _links in the request with an `apiture:approvalType` key.  The optional target of an approval may be passed on Approval create in either the `_links` with the link relation `apiture:target` or in `attributes`.'
      operationId: createApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - name: approval
          in: body
          description: The data necessary to create a new approval.
          required: true
          schema:
            $ref: '#/definitions/createApproval'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/approval'
          headers:
            Location:
              description: >-
                The URI of the new resource. If the URI begins with / it is
                relative to the API root context. Else, it is a full URI
                starting with *`scheme`*`://host`
              type: string
              format: uri
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
  '/approvals/{approvalId}':
    get:
      summary: Fetch a representation of this approval
      description: >-
        Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation
        of this approval resource.
      operationId: getApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalIdPathParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this approval resource.
              type: string
        '304':
          $ref: '#/responses/304'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404Approval'
    put:
      summary: Update this approval
      description: Perform a complete replacement of this approval.
      operationId: updateApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalIdPathParam'
        - name: approval
          in: body
          required: true
          schema:
            $ref: '#/definitions/updateApproval'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this approval resource.
              type: string
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404Approval'
        '412':
          $ref: '#/responses/412'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
    patch:
      summary: Update this approval
      description: >-
        Perform a partial update of this approval. Fields which are omitted are
        not updated. Nested `_embedded` and `_links` are ignored if included.
      operationId: patchApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalIdPathParam'
        - name: approval
          in: body
          required: true
          schema:
            $ref: '#/definitions/updateApproval'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this approval resource.
              type: string
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404Approval'
        '412':
          $ref: '#/responses/412'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
    delete:
      summary: Delete this approval resource
      description: Delete this approval resource and any resources that are owned by it.  an Approval may only be deleted if its state is `open` or `canceled`.
      operationId: deleteApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalIdPathParam'
      responses:
        '204':
          $ref: '#/responses/204Deleted'
        '401':
          $ref: '#/responses/401'
  /approvedApprovals:
    post:
      summary: Approve an approval
      description: Approve an approval.
        <p>
        Only product types which are `submitted` may be `approved`.
        <p>
        This operation is invoked from the `apiture:approve` link on a
        product type when it is eligible to be approved.
        <p>
        This changes the `state` to `approved`.
      operationId: approveApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalQueryParam'
        - name: approvalUri
          description: >-
            The URI of an existing approval which is eligible to be approved.
            Note: This parameter is **deprecated** and will be removed in
            the next version. Use `?approval=` instead.
          type: string
          in: query
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
        '400':
          description: >-
            Bad Request. The `approval` or `approvalUri` parameter was malformed or does not refer to
            an approval.
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalConflict'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
  /rejectedApprovals:
    post:
      summary: Reject an approval
      description: Reject an approval.
        <p>
        Only product types which are `submitted` may be `rejected`.
        <p>
        This operation is invoked from the `apiture:reject` link on a
        product type when it is eligible to be rejected.
        <p>
        This changes the `state` to `rejected`.
      operationId: rejectApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalQueryParam'
        - name: approvalUri
          description: >-
            The URI of an existing approval which is eligible to be rejected.
            Note: This parameter is **deprecated** and will be removed in
            the next version. Use `?approval=` instead.
          type: string
          in: query
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
        '400':
          description: >-
            Bad Request. The `approval` or `approvalUri` was malformed or does not refer to
            an approval.
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalConflict'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
  /waivedApprovals:
    post:
      summary: Waive an approval
      description: Waive an approval.
        <p>
        Only product types which are `open` or `submitted` may be `waived`.
        <p>
        This operation is invoked from the `apiture:waive` link on a
        product type when it is eligible to be waived.
        <p>
        This changes the `state` to `waived`.
      operationId: waiveApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalQueryParam'
        - name: approvalUri
          description: >-
            The URI of an existing approval which is eligible to be waived.
            Note: This parameter is **deprecated** and will be removed in
            the next version. Use `?approval=` instead.
          type: string
          in: query
          required: true
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
        '400':
          description: >-
            Bad Request. The 'approval` or `approvalUri` was malformed or does not refer to
            an approval.
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalConflict'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
  /submittedApprovals:
    post:
      summary: Submit an approval
      description: Submit an approval.
        <p>
        Only product types which are `open` or `returned` may be `submitted`.
        <p>
        This operation is invoked from the `apiture:submit` link on a
        product type when it is eligible to be submitted.
        <p>
        This changes the `state` to `submitted`.
      operationId: submitApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalQueryParam'
        - name: approvalUri
          description: >-
            The URI of an existing approval which is eligible to be submitted.
            Note: This parameter is **deprecated** and will be removed in
            the next version. Use `?approval=` instead.
          type: string
          in: query
          required: true
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
        '400':
          description: >-
            Bad Request. The `approval` or `approvalUri` was malformed or does not refer to
            an approval.
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalConflict'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
  /returnedApprovals:
    post:
      summary: Return an approval
      description: Return an approval.
        <p>
        Only product types which are `submitted` may be `returned`.
        <p>
        This operation is invoked from the `apiture:return` link on a
        product type when it is eligible to be returned.
        <p>
        This changes the `state` to `returned`.
      operationId: returnApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalQueryParam'
        - name: approvalUri
          description: >-
            The URI of an existing approval which is eligible to be returned.
            Note: This parameter is **deprecated** and will be removed in
            the next version. Use `?approval=` instead.
          type: string
          in: query
          required: true
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
        '400':
          description: >-
            Bad Request. The `approval` or `approvalUri` was malformed or does not refer to
            an approval.
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalConflict'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
  /canceledApprovals:
    post:
      summary: Cancel an approval
      description: Cancel an approval.
        <p>
        Only product types which are `open`, `submitted` or `returned` may be `canceled`.
        <p>
        This operation is invoked from the `apiture:cancel` link on a
        product type when it is eligible to be cenceled.
        <p>
        This changes the `state` to `canceled`.
      operationId: cancelApproval
      x-apiture-implemented: true
      tags:
        - Approval
      parameters:
        - $ref: '#/parameters/approvalQueryParam'
        - name: approvalUri
          description: >-
            The URI of an existing approval which is eligible to be canceled.
            Note: This parameter is **deprecated** and will be removed in
            the next version. Use `?approval=` instead.
          type: string
          in: query
          required: true
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approval'
        '400':
          description: >-
            Bad Request. The `approval` or `approvalUri` was malformed or does not refer to
            an approval.
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalConflict'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
  /approvalTypes:
    get:
      summary: Return a collection of approval types
      description: >-
        Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[
        sortable](http://doc.apiture.com/api/concepts/sorting)[
        filterable](http://doc.apiture.com/api/concepts/filtering)[
        searchable](http://doc.apiture.com/api/concepts/searchable) collection
        of approvals. The [links](http://doc.apiture.com/api/concepts/links) in
        the response include pagination links.
      operationId: getApprovalTypes
      x-apiture-implemented: true
      x-apiture-traits:
        link:
          rel: approvalTypes
          title: List Approval Types
      tags:
        - Approval Type
      parameters:
        - name: start
          in: query
          description: >-
            The zero-based index of the first approval type item to include in this
            page. The default 0 denotes the beginning of the collection.
          type: integer
          format: int64
          default: 0
        - name: limit
          in: query
          description: >-
            The maximum number of approval type representations to return in this
            page.
          type: integer
          format: int32
          default: 100
        - name: sortBy
          in: query
          type: string
          description: >-
            Optional sort criteria. See [sort criteria
            format](http://docs.apiture.com/api/concepts/sorting#criteria), such
            as `?sortBy=field1,-field2`.
        - $ref: '#/parameters/filterQueryParam'
        - $ref: '#/parameters/qQueryParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approvalTypes'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '422':
          $ref: '#/responses/422'
    post:
      summary: Create a new approval type
      description: 'Create a new approval type in the approval types collection. '
      operationId: createApprovalType
      x-apiture-implemented: true
      tags:
        - Approval Type
      parameters:
        - name: approvalType
          in: body
          description: The data necessary to create a new approval type.
          required: true
          schema:
            $ref: '#/definitions/createApprovalType'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/approvalType'
          headers:
            Location:
              description: >-
                The URI of the new resource. If the URI begins with / it is
                relative to the API root context. Else, it is a full URI
                starting with *`scheme`*`://host`
              type: string
              format: uri
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update the resource.
              type: string
        '409':
          $ref: '#/responses/409ApprovalTypeConflict'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
  '/approvalTypes/{approvalTypeId}':
    get:
      summary: Fetch a representation of this approval type
      description: >-
        Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation
        of this approval type resource.
      operationId: getApprovalType
      x-apiture-implemented: true
      tags:
        - Approval Type
      parameters:
        - $ref: '#/parameters/approvalTypeIdPathParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approvalType'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this approval type resource.
              type: string
        '304':
          $ref: '#/responses/304'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404ApprovalType'
    put:
      summary: Update this approval type
      description: Perform a complete replacement of this approval type.
      operationId: updateApprovalType
      x-apiture-implemented: true
      tags:
        - Approval Type
      parameters:
        - $ref: '#/parameters/approvalTypeIdPathParam'
        - name: approvalType
          in: body
          required: true
          schema:
            $ref: '#/definitions/updateApprovalType'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approvalType'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this approval type resource.
              type: string
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404ApprovalType'
        '412':
          $ref: '#/responses/412'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
    patch:
      summary: Update this approval type
      description: >-
        Perform a partial update of this approval type. Fields which are omitted are
        not updated. Nested `_embedded` and `_links` are ignored if included.
      operationId: patchApprovalType
      x-apiture-implemented: true
      tags:
        - Approval Type
      parameters:
        - $ref: '#/parameters/approvalTypeIdPathParam'
        - name: approval
          in: body
          required: true
          schema:
            $ref: '#/definitions/patchApprovalType'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/approvalType'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this approval type resource.
              type: string
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404ApprovalType'
        '412':
          $ref: '#/responses/412'
        '422':
          $ref: '#/responses/422'
        '428':
          $ref: '#/responses/428'
    delete:
      summary: Delete this approval type resource
      description: Delete this approval type resource and any resources that are owned by it.  Deleting an Approval Type is only allowed if it is not in use by any existing Approvals.
      operationId: deleteApprovalType
      x-apiture-implemented: true
      tags:
        - Approval Type
      parameters:
        - $ref: '#/parameters/approvalTypeIdPathParam'
      responses:
        '204':
          $ref: '#/responses/204Deleted'
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409ApprovalTypeConflict'

  /:
    get:
      summary: Top-level resources and operations in this API
      description: Return links to the top-level resources and operations in this API.
      operationId: getApi
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/root'
      tags:
        - API
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      x-apiture-implemented: true
      produces:
        - application/json
        - application/openapi+json;version=2.0
        - application/openapi+yaml;version=2.0
      responses:
        '200':
          description: OK
          schema:
            type: object
      tags:
        - API

parameters:
  approvalIdPathParam:
    name: approvalId
    description: The unique identifier of this approval. This is an opaque string.
    in: path
    type: string
    required: true

  approvalQueryParam:
    name: approval
    description: A server-generated key which identifies an existing approval resource.
    type: string
    in: query
    required: true

  approvalTypeIdPathParam:
    name: approvalTypeId
    description: The unique identifier of this approval type. This is an opaque string.
    in: path
    type: string
    required: true

  filterQueryParam:
    name: filter
    in: query
    description: >-
      Optional filter criteria. See
      [filtering](http://docs.apiture.com/api/concepts/filtering#criteria).
    type: string

  qQueryParam:
    name: q
    in: query
    description: >-
      Optional search string. See
      [searching](http://docs.apiture.com/api/concepts/searching).
    type: string

  ifMatchHeaderParam:
    name: If-Match
    description: >-
      The entity tag that was returned in the `ETag` response. This must match
      the current entity tag of the resource.
    in: header
    type: string

  ifNoneMatchHeaderParam:
    name: If-None-Match
    description: >-
      The entity tag that was returned in the `ETag` response. If the resource's
      current entity tag matches, the `GET` will return 304 (Not Modified) and
      no response body, else the resource representation will be returned.
    in: header
    type: string

responses:
  '304':
    description: >-
      Not Modified. The resource has not been modified since it was last
      fetched.
  '400':
    description: >-
      Bad Request. 
      The request body or one or more of the query parameters was not well
      formed.  The `_error` field in the response will contain details about the
      request error.
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - malformedRequestBody
  '401':
    description: >-
      Unauthorized. The request has not been applied because it lacks valid authentication 
      credentials for the target resource.
    schema:
      $ref: '#/definitions/errorResponse'
  '412':
    description: >-
      Precondition Failed. The supplied `if-Match` header value does not match
      the most recent `ETag` response header value. The resource has changed in
      the interim.
    schema:
      $ref: '#/definitions/errorResponse'
  '422':
    description: >-
      Unprocessable Entity. One or more of the query parameters was well formed
      but otherwise invalid. The `_error` field in the response will contain
      details about the request error.
    schema:
      $ref: '#/definitions/errorResponse'
  '428':
    description: >-
      Precondition Required. The request did not include the required `if-Match`
      header. Resubmit with the operation, supplying the value of the `ETag` and
      the most recent state of the resource.
    schema:
      $ref: '#/definitions/errorResponse'

  404Approval:
    description: >-
      Not Found. There is no such approval resource at the specified
      `{approvalId}`. The `_error` field in the response will contain details
      about the request error.
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - invalidApprovalId

  404ApprovalType:
    description: >-
      Not Found. There is no such approval type resource at the specified
      `{approvalTypeId}`. The `_error` field in the response will contain details
      about the request error.
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - invalidApprovalTypeId

  409ApprovalConflict:
    description: >-
      Conflict. There is a conflict between the request and the current state of
      the resource. It may be one of the following:
        * The `state` of an Approval resource may only be changed in accordance with the state transitions described in this specification.
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - approveApprovalInvalidState
      - deleteApprovalInvalidState
      - cancelApprovalInvalidState
      - rejectApprovalInvalidState
      - returnApprovalInvalidState
      - submitApprovalInvalidState
      - waiveApprovalInvalidState

  409ApprovalTypeConflict:
    description: >-
      Conflict. There is a conflict between the request and the current state of
      the resource. It may be one of the following:
        * The `name` and `domain` of the Approval Type must be a unique combination within the FI Approval Type Resources.
        * The Approval Type is in use and cannot be deleted.
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - nameAndDomainMustBeUnique
      - approvalTypeInUse

  204Deleted:
    description: No Content. The resource was deleted successfully.

definitions:
  approvalFields:
    title: Approval Fields
    description: >-
      Common fields of the approval resource used to build other model schemas.
    properties:
      label:
        description: The approval's common name.  If ommitted on create request, this will default to the label of the Approval Type.
        type: string
      description:
        description: The approval's description.  If ommitted on create request, this will default to the description of the Approval Type.
        type: string
      state:
        description: >-
          The approval's state.


            * **`open`** Created but pending input subject to approval
            * **`submitted`** Pending review by approver
            * **`approved`** Approval granted
            * **`rejected`** Approval denied
            * **`waived`** Approval forgiven
            * **`returned`** Approver returns approval for modification
            * **`canceled`** Approval request withdrawn


          This is an immutable and derived property. It's value can only be changed by using the corresponding `POST` operations,
          `submitApproval`, `approveApproval`, `rejectApproval`, `waiveApproval`, `returnApproval`, and `cancelApproval`.

        type: string
        enum:
          - open
          - submitted
          - approved
          - rejected
          - waived
          - returned
          - canceled
        default: open
      done:
        description: Inferred done flag.  If `done` is true, the approval is in a terminal state and may no longer be acted upon.  Done states include `canceled`, `approved`, `waived` or `rejected`.
        type: boolean
      typeName:
        description: The name of the Approval Type.  This field is immutable and derived from the name of the Approval Type.
        type: string
      reviewedBy:
        description: The id of the User that reviewed the approval.
        type: string
      reviewedAt:
        description: The date-time when the approval was reviewed.
        type: string
        format: date-time
    example:
      state: active
      done: true
      label: Government Issued ID
      typeName: governmentId
      description: A document that identifies a user
      reviewedBy: /users/users/0399abed-fd3d-4830-a88b-30f38b8a365c
      reviewedAt: '2018-04-17T10:12:58.375Z'

  createApproval:
    title: Create Approval
    description: >-
      Representation used to create a new approval.  A link to an `apiture:approvalType` is required to perform this operation.  An optional `apiture:target` link may also be specified to represent the target resource for the approval. The target can be any resource, for example, an account application or a document.
    allOf:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/approvalFields'
      - type: object
        properties:
          attributes:
            type: object
            description: >-
              An optional map of name/value pairs which provide additional
              metadata about the approval.
    example:
      _profile: 'http://api.apiture.com/schemas/basePath/approval/v1.0.0/profile.json'

  summaryApproval:
    title: Approval Summary
    description: >-
      Summary representation of an approval resource in approvals collections. This
      representation normally does not contain any `_embedded` objects. If
      needed, call the `GET` operation on the item's `self` link to get
      `_embedded` objects.
    allOf:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/approvalFields'
      - type: object
        properties:
          _id:
            description: >-
              The unique identifier for this approval resource. This is an
              immutable opaque string.
            type: string
    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'http://api.apiture.com/schemas/approvals/approvals/v1.0.0/profile.json'
      _links:
        self:
          href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c

  updateApproval:
    title: Update Approval
    description: >-
      Representation used to update or patch an approval.  The `state` field is immutable and not updated by this operation, but by the `state transition` POST operations such as `approve` or `reject` (ex. `apiture:approve` and `apiture:reject`).
    allOf:
      - $ref: '#/definitions/summaryApproval'
      - type: object
        properties:
          attributes:
            type: object
            description: >-
              An optional map of name/value pairs which provide additional
              metadata about the approval.
    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'http://api.apiture.com/schemas/approvals/approvals/v1.0.0/profile.json'

  approval:
    title: Approval
    description: >-
      An approval represents the _review_ of
      some process, activity or resource, such as a document or an application.
      The state of the approval is recorded in its `state` property. The
      target of the approval is in the link named `apiture:target`;
      see the _Create Approval_ schema and `createApproval` operation.

      Links on an approval convey which state transitions are available.
      These links are:

        * **`apiture:approve`** -- mark the review request as approved
        * **`apiture:reject`** -- to reject the approval request
        * **`apiture:waive`** -- to waive the approval requirements. For example, rather than requiring a specific
        identity verification document to be approved, waiving the requirement means the document does not have to
        be provided.
        * **`apiture:return`** -- to return the request so the client can update the request or resource, then resubmit the request for approval
        * **`apiture:submit`** -- to submit a new request for appoval, or resubmit a request after it has been returned
        * **`apiture:cancel`** -- to cancel the request for review/approval
        
      The client should use `POST` to invoke these operations, using the `href`
      on the named link object. No request body is used on these operations.


      The absence of a link indicates that the particular state
      transition is not available at that time or that the caller
      is not authorized to make the change. For example, a user
      may lack permissions to approve a wire transfer they submitted.
    allOf:
      - $ref: '#/definitions/updateApproval'
      - type: object
        properties:
          createdAt:
            description: The date-time when the approval was created.
            type: string
            format: date-time
          updatedAt:
            description: The date-time when the approval was updated
            type: string
            format: date-time
          _embedded:
            description: The objects which participate in this association
            type: object
            properties:
              approvalType:
                description: The role for this association
                allOf:
                  - $ref: '#/definitions/summaryApprovalType'

    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'http://api.apiture.com/schemas/approvals/approvals/v0.1.0/profile.json'
      createdAt: '2018-04-17T10:04:46.375Z'
      updatedAt: '2018-04-17T10:12:58.375Z'
      _links:
        self:
          href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c
        'apiture:approvalType':
          href: /approvals/approvalTypes/e4f09b4d-eba6-46da-86d3-ba28595067cd
        'apiture:target':
          href: /vault/files/e4f09b4d-eba6-46da-86d3-hjr434fuhe
      _embedded:
        approvalType:
          _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
          _profile: >-
            http://api.apiture.com/schemas/approvals/approvalTypes/v0.1.0/profile.json
          _links:
            self:
              href: /approvals/approvalTypes/0399abed-fd3d-4830-a88b-30f38b8a365c
          name: governmentId
          label: Government Issued ID
          description: A document that identifies a user

  approvals:
    title: Approval Collection
    description: >-
      Collection of approvals. The items in the collection are ordered in the
      `_embedded.items` array; the `name` is `approvals`.
       The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.)
        

    allOf:
      - $ref: '#/definitions/collection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              items:
                description: An array containing a page of approval items.
                type: array
                items:
                  $ref: '#/definitions/summaryApproval'
    example:
      _profile: 'http://api.apiture.com/schemas/basePath/approvals/v0.1.0/profile.json'
      start: 10
      limit: 10
      count: 67
      name: approvals
      _links:
        self:
          href: /basePath/approvals?start=10&limit=10
        first:
          href: /basePath/approvals?start=0&limit=10
        next:
          href: /basePath/approvals?start=20&limit=10
        collection:
          href: /basePath/approvals
      _embedded:
        items:
          - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            _profile: >-
              http://api.apiture.com/schemas/approvals/approvals/v0.1.0/profile.json
            _links:
              self:
                href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c
            state: active
            done: true
            label: Government Issued ID
            description: A document that identifies a user
            reviewedBy: /users/users/0399abed-fd3d-4830-a88b-30f38b8a365c
            reviewedAt: '2018-04-17T10:12:58.375Z'

  approvalTypeFields:
    title: Approval Type Fields
    description: >-
      Common fields of the approval resource used to build other model schemas.
    properties:
      name:
        description: The approval's name.
        type: string
      label:
        description: The approval's common name.
        type: string
      description:
        description: The approval's description.
        type: string
      domain:
        description: A namespace for grouping related resources, to keep them separate from other resources. For example, a department or bank branch may define a domain, and all Approval Type instances they define will use that domain, so that they can avoid conflicting with Approval Type names in other domains. An API or service may define a domain for Approval Types that it defines. The combination of domain and name must be unique within the set of all resources of this type. It is a best practice to define domains with URIs.
        type: string
    example:
      name: governmentId
      label: Government Issued ID
      description: A document that identifies a user
      domain: http://api.apiture.com/domains/approvals/documentRequirement

  approvalTypes:
    title: Approval Types Collection
    description: >-
      Collection of approval types. The items in the collection are ordered in the
      `_embedded.items` array; the `name` is `approvals`.
       The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.)

    allOf:
      - $ref: '#/definitions/collection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              items:
                description: An array containing a page of approval type items.
                type: array
                items:
                  $ref: '#/definitions/summaryApprovalType'
    example:
      _profile: 'http://api.apiture.com/schemas/basePath/approvalTypes/v0.1.0/profile.json'
      start: 10
      limit: 10
      count: 67
      name: approvalTypes
      _links:
        self:
          href: /basePath/approvalTypes?start=10&limit=10
        first:
          href: /basePath/approvalTypes?start=0&limit=10
        next:
          href: /basePath/approvalTypes?start=20&limit=10
        collection:
          href: /basePath/approvalTypes
      _embedded:
        items:
          - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            _profile: >-
              http://api.apiture.com/schemas/approvals/approvalTypes/v0.1.0/profile.json
            _links:
              self:
                href: /approvals/approvalTypes/0399abed-fd3d-4830-a88b-30f38b8a365c
            name: governmentId
            label: Government Issued ID
            description: A document that identifies a user

  createApprovalType:
    title: Create Approval Type
    description: >-
      Representation used to create a new approval type.
    required:
      - name
    allOf:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/approvalTypeFields'
      - type: object
        properties:
          attributes:
            type: object
            description: >-
              An optional map of name/value pairs which provide additional
              metadata about the approval type.
    example:
      _profile: 'http://api.apiture.com/schemas/basePath/approvalTypes/v1.0.0/profile.json'

  approvalType:
    title: Approval Type
    description: >-
      All Approval resources contain an Approval Type, a resource that is also managed in this API.  Approval Types provide Financial Institutions the ability to track, reconcile and group specific Approvals.  In addition, metadata regarding specific types of Approvals can be stored on the Approval Type.  Approval Types may onle be deleted if they are not in use by any existing Approvals.  Some examples of Approval Types may be specific documents releated to New Account Opening that need to be manually approved, Account Applications or Transfer requests.

    allOf:
      - $ref: '#/definitions/updateApprovalType'
      - type: object
        properties:
          createdAt:
            description: The date-time when the approval was created.
            type: string
            format: date-time
          updatedAt:
            description: The date-time when the approval was updated
            type: string
            format: date-time

  updateApprovalType:
    title: Update Approval Type
    required:
      - name
    description: >-
      Representation used to update or patch an approval type.
    allOf:
      - $ref: '#/definitions/summaryApprovalType'
      - type: object
        properties:
          attributes:
            type: object
            description: >-
              An optional map of name/value pairs which provide additional
              metadata about the approval type.
    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'http://api.apiture.com/schemas/approvals/approvalTypes/v1.0.0/profile.json'

  patchApprovalType:
    title: Update Approval Type
    description: >-
      Representation used to update or patch an approval type.
    allOf:
      - $ref: '#/definitions/summaryApprovalType'
      - type: object
        properties:
          attributes:
            type: object
            description: >-
              An optional map of name/value pairs which provide additional
              metadata about the approval type.
    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'http://api.apiture.com/schemas/approvals/approvalTypes/v1.0.0/profile.json'

  summaryApprovalType:
    title: Approval Type Summary
    description: >-
      Summary representation of an approval type resource in approvals collections. This
      representation normally does not contain any `_embedded` objects. If
      needed, call the `GET` operation on the item's `self` link to get
      `_embedded` objects.
    allOf:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/approvalTypeFields'
      - type: object
        properties:
          _id:
            description: >-
              The unique identifier for this approval resource. This is an
              immutable opaque string.
            type: string
    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'http://api.apiture.com/schemas/approvals/approvalTypes/v1.0.0/profile.json'
      _links:
        self:
          href: /approvals/approvalTypes/0399abed-fd3d-4830-a88b-30f38b8a365c

  abstractResource:
    title: Abstract Resource
    description: >-
      An augmented [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08)
      resource representation. This model contains hypermedia `_links`, and
      either optional domain object data with `_profile` and optional
      `_embedded` objects, or an `_error` object. In responses, if the operation
      was successful, this object will not include the `_error`, but if the
      operation was a 4xx or 5xx error, this object will not include `_embedded`
      or any data fields, only `_error` and optionally `_links`.
    example:
      _profile: 'http://api.apiture.com/schemas/example/v1.0.0/profile.json'
      _links:
        self:
          href: '{uri of current resource}'
        apiture:approvalType:
          href: '/approvals/approvalType/0399abed-fd3d-4830-a88b-30f38b8a365c'
        apiture:target:
          href: /vault/files/e4f09b4d-eba6-46da-86d3-hjr434fuhe
    properties:
      _links:
        $ref: '#/definitions/links'
      _embedded:
        description: >-
          An optional map of nested resources, mapping each nested resource name
          to a nested resource representation.
        type: object
      _profile:
        description: >-
          The URI of a [resource
          profile](http://doc.apiture.com/api/concepts/resource-profile) which
          describes the representation.
        type: string
        format: uri
      _error:
        description: >-
          An object which describes an error. This value is omitted if the
          operation succeeded without error.
        type: object
        allOf:
          - $ref: '#/definitions/error'

  root:
    title: API Root
    description: >-
      A HAL response, with hypermedia `_links` for the top-level resources and
      operations in API.
    example:
      id: apiName
      name: API name
      apiVersion: 0.0.1-SNAPSHOT
      _profile: 'https://api.apiture.com/schemas/root/v1.0.0/profile.json'
      _links: {}
    allOf:
      - $ref: '#/definitions/abstractResource'
      - type: object
        properties:
          _id:
            type: string
            description: This API's unique ID.
          name:
            type: string
            description: This API's name.
          apiVersion:
            type: string
            description: This API's version.

  errorResponse:
    title: Error Response
    description: >-
      Describes an error response, typically returned on 4xx or 5xx errors from
      API operations. The `_error` object contains the error details.
    allOf:
      - $ref: '#/definitions/abstractResource'
    example:
      _profile: 'http://api.apiture.com/schemas/error/v1.0.0/profile.json'
      _error:
        _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
        _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json'
        message: The value for deposit must be greater than 0.
        statusCode: 422
        type: positiveNumberRequired
        attributes:
          value: -125.5
        remediation: Provide a value which is greater than 0
        occurredAt: 2018-01-25T05:50:52.375Z
        _links:
          describedby:
            href: 'http://doc.apiture.com/errors/positiveNumberRequired'
        _embedded:
          errors: []

  error:
    title: Error
    description: >-
      An error description. Nested source errors are contained in the
      `_embedded` object with the key `"errors"`; this is an array of nested
      error objects. For example, an API which validates its request body may
      find multiple errors in the request, which may be detailed here. The
      `_links` may contain a `describedby` link which refers to a web page with
      details about the error.
      The `attributes` field An optional map of name/value pairs which provide
      structured data about the error. For example, if the error is a value out
      of range, the attributes may specify the range values `min` and `max`.
      This allows clients to present error messages as they see fit (the API
      does not assume the client/presentation tier).
    required:
      - message
    properties:
      message:
        type: string
        description: A localized message string describing the error condition.
      _id:
        type: string
        description: >-
          A unique identifier for this error instance. This may be used as a
          correlation ID with the root cause error (i.e. this ID may be logged
          at the source of the error). This is is an opaque string.
      statusCode:
        description: The HTTP status code associate with this error.
        type: integer
        minimum: 100
        maximum: 599
        example: 422
      type:
        type: string
        description: >-
          An error identifier which indicates the category of error and
          associate it with API support documentation or which the UI tier can
          use to render an appropriate message or hint. This provides a finer
          level of granularity than the `statusCode`. For example, instead of
          just 400 Bad Request, the `type` may be much more specific. such as
          `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
          `stringValueNotInAllowedSet`.
      occurredAt:
        type: string
        format: date-time
        description: An ISO 8601 UTC time stamp indicating when the error occurred.
        example: '2018-02-02T03:37:15.375Z'
      attributes:
        description: >-
          Data attribute associated with the error, such as values or
          constraints.
        allOf:
          - $ref: '#/definitions/attributes'
      remediation:
        type: string
        description: >-
          An optional localized string which provides hints for how the user or
          client can resolve the error.
      _embedded:
        description: >-
          Optional embedded array of errors. This field may not exist if the
          error does not have nested errors.
        type: object
        properties:
          items:
            description: An array of error objects.
            type: array
            items:
              $ref: '#/definitions/errorResponse'
    example:
      _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
      _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json'
      message: The value for deposit must be greater than 0.
      statusCode: 422
      type: positiveNumberRequired
      attributes:
        value: -125.5
      remediation: Provide a value which is greater than 0
      occurredAt: '2018-01-25T05:50:52.375Z'
      _links:
        describedby:
          href: 'http://doc.apiture.com/errors/positiveNumberRequired'
      _embedded:
        errors: []

  attributes:
    title: Attributes
    description: >-
      An optional map of name/value pairs which contains additional dynamic data
      about the resource.
    type: object

  links:
    title: Links
    description: >-
      An optional map of links, mapping each link relation to a link object.
      This model defines the `_links` object of HAL representations.
    type: object
    additionalProperties:
      $ref: '#/definitions/link'

  link:
    title: Link
    description: >-
      Describes a hypermedia link within a `_links` object in HAL
      representations. In Apiture APIs, links are [HAL
      links](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), but
      Apiture APIs do not use the `name` or `hreflang` properties of HAL.
      Apiture links _may_ include a `method` property.
    required:
      - href
    properties:
      href:
        type: string
        format: uri
        description: >-
          The URI or URI template for the resource/operation this link refers
          to.
      type:
        type: string
        description: The media type for the resource.
      templated:
        type: boolean
        description: >-
          If true, the link's href is a [URI
          template](https://tools.ietf.org/html/rfc6570).
      title:
        type: string
        description: An optional human-readable localized title for the link.
      deprecation:
        type: string
        format: uri
        description: >-
          If present, the containing link is deprecated and the value is a URI
          which provides human-readable text information about the deprecation.
      profile:
        type: string
        format: uri
        description: >-
          The URI of a profile document, a JSON document which describes the
          target resource/operation.

  collection:
    x-apiture-version: '1.0.0'
    title: Collection
    description: >-
      A collection of resources.
      This is an abstract model schema which is extended to define
      specific resource collections.
    allOf:
      - $ref: '#/definitions/abstractResource'
      - type: object
        properties:
          count:
            description: 'The number of items in the full collection.'
            type: integer
          start:
            description: 'The start index of this page of items.'
            type: integer
          limit:
            description: 'The maximum number of items per page.'
            type: integer
          name:
            description: 'The name of the collection.'
            type: string

x-apiture-errors:
  approvalAccessDenied:
    description: The credentials supplied in the request are insufficient to grant access
    remediation: Check the supplied credentials for validity

  approvalTypeAccessDenied:
    description: The credentials supplied in the request are insufficient to grant access
    remediation: Check the supplied credentials for validity

  invalidApprovalId:
    description: No approvals were found for the specified approvalId
    remediation: Check to make sure that the supplied approvalId corresponds to an apiture approval resource

  invalidApprovalTypeId:
    description: No approvalTypes were found for the specified approvalTypeId
    remediation: Check to make sure that the supplied approvalTypeId corresponds to an apiture approvalType resource

  malformedRequestBody:
    description: The supplied request body was malformed
    remediation: Check to make sure that your request body exists and that it does not contain syntax errors

  ifMatchHeaderMissing:
    description: The "If-Match" header was not supplied
    remediation: Verify you are supplying an "If-Match" header in the request
  
  ifMatchHeaderDoesntMatch:
    description: This "If-Match" header does not match the current resource state
    remediation: Try getting the latest version of the resource and re-submitting your request

  deleteApprovalInvalidState:
    description: Approvals may only be deleted if they are in an open or canceled state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requiredStates: ['canceled', 'open']

  approveApprovalInvalidState:
    description: Approvals may only be approved if they are in a submitted state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requestedState: 'approved'
        requiredStates: ['submitted']

  cancelApprovalInvalidState:
    description: Approvals may only be canceled if they are in a submitted, open or returned state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requestedState: 'canceled'
        requiredStates: ['submitted', 'open', 'returned']

  rejectApprovalInvalidState:
    description: Approvals may only be rejected if they are in a submitted state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requestedState: 'rejected'
        requiredStates: ['submitted']

  returnApprovalInvalidState:
    description: Approvals may only be returned if they are in a submitted state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requestedState: 'returned'
        requiredStates: ['submitted']

  submitApprovalInvalidState:
    description: Approvals may only be submitted if they are in an open or returned state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requestedState: 'submitted'
        requiredStates: ['open', 'returned']

  waiveApprovalInvalidState:
    description: Approvals may only be waived if they are in an open or submitted state
    remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation
    attributes:
      properties:
        requestedState: 'waived'
        requiredStates: ['open', 'submitted']

  nameAndDomainMustBeUnique:
    description: The combination of name and domain must be unique across ApprovalTypes
    remediation: Check the existing ApprovalTypes for an existing resource that matches the name and domain on your request

  approvalTypeInUse:
    description: Approval Types may only be deleted if they are not being used by an Approval
    remediation: Check to see if any Approval resources are linked to the supplied Approval Type

x-apiture-traits:
  - api:
      title: Approvals
      basePath: approvals
      links: [getApprovals, createApproval, getApprovalTypes, createApprovalType, getApi, getApiDoc]
  - resource:
      name: approval
      description: >-
        An Approval record represents a blocking action that must be
        acknowledged in order to progress in the current process.
      simpleModelSchema: true

  - resource:
      name: approval type
      description: >-
        An Approval Type record contains information specific to the
        type of Approval being requested.  All Aprovals will have Approval
        Types.
      simpleModelSchema: true
