# Proposed contract, version 1: endpoints, errors, paging, idempotency, security and the capability of every
# operation. Resource schemas were initialized from the data model (docs/06-data) and are kept aligned with it; input
# schemas (*Input, *Request) and views are specific to this contract. Status: proposal for review, not confirmed design.
# Conventions: docs/05-interfaces/choosing-an-interface.md. Vendor extensions: x-moonitoring-audience (who calls),
# x-moonitoring-capability (the capability checked), x-moonitoring-entitlement (the entitlement feature checked),
# x-moonitoring-requirements (the requirements of 1.requisiti-raffinati.txt the operation serves).
openapi: 3.1.0
info:
  title: Grant Documents API
  version: 1.0.0
  description: The documents a farmer uploads from a call's check (fascicolo aziendale, visura camerale, registro
    BDN, report ClassyFarm), private to the research and read by a worker into typed facts with their citations;
    the farmer sees every fact, can dispute one, and the requirements of a call are evaluated against the facts
    (req 215 to 218). Uploads go straight to the private bucket through a resumable session; nothing starts a model
    call from the web app.
servers:
- url: https://grant.moonitoring.com/documents/v1
  description: Prod
- url: https://stage-grant.moonitoring.com/documents/v1
  description: Stage, through IAP
security:
- bearer: []
tags:
- name: Documents
  description: Farmer documents
- name: Facts
  description: What was read
- name: Checks
  description: Requirements against facts
paths:
  /documents:
    get:
      summary: List my documents
      operationId: listFarmerDocuments
      description: Of the research behind the token or the guest cookie. The capability applies through the research's
        Farm Organization (req 212.8, D21); a guest passes without one.
      tags:
      - Documents
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: state
        in: query
        required: false
        schema:
          type: string
          enum:
          - uploading
          - stored
          - queued
          - processing
          - ready
          - partial
          - failed
          - deleting
          - deleted
        description: Only this state.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/FarmerDocument'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215'
      - '1002.29'
    post:
      summary: Announce an upload
      operationId: createFarmerDocument
      description: Refused above ten active documents. Returns the resumable session.
      tags:
      - Documents
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUploadRequest'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadTarget'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215'
      - '215.6'
      - '217.4'
      - '1209'
      - '1002.29'
  /documents/{document_id}/finalize:
    post:
      summary: Finalize an upload
      operationId: finalizeFarmerDocument
      description: Checks name, size, type and generation, pins the generation, then dispatches a worker execution
        if a slot is free. Publishes `farmer_document.uploaded.v1`.
      tags:
      - Documents
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmerDocument'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215.8'
      - '215.13'
      - '1002.29'
  /documents/{document_id}/retry:
    post:
      summary: Retry a reading
      operationId: retryFarmerDocument
      description: Frees stale slots and dispatches again; at most five attempts, five minutes apart.
      tags:
      - Documents
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmerDocument'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215.13'
      - '1002.29'
  /documents/{document_id}:
    get:
      summary: Read a document
      operationId: getFarmerDocument
      tags:
      - Documents
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmerDocument'
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215'
      - '215.10'
      - '1210'
    delete:
      summary: Delete a document
      operationId: deleteFarmerDocument
      description: Hidden and unused at once; storage purged by the daily run; its facts leave the checks.
      tags:
      - Documents
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Done.
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215.9'
      - '1002.29'
  /documents/{document_id}/download-url:
    post:
      summary: Download my document
      operationId: getFarmerDocumentUrl
      tags:
      - Documents
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: ../../../../common/v1/schemas.yaml#/components/schemas/SignedUrl
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '215'
  /documents/{document_id}/facts:
    get:
      summary: List the facts read from a document
      operationId: listFarmFacts
      tags:
      - Facts
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/FarmFact'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '216'
      - '1200'
  /facts/{fact_id}/dispute:
    post:
      summary: Dispute a fact
      operationId: disputeFarmFact
      description: A disputed candidate makes its requirement unknown.
      tags:
      - Facts
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: fact_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeRequest'
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmFact'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '216.10'
  /profile:
    get:
      summary: Read my document profile
      operationId: getFarmerDocumentProfile
      tags:
      - Facts
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmerDocumentProfile'
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.documents.manage
      x-moonitoring-requirements:
      - '217'
  /checks/{call_id}:
    get:
      summary: Read the check of a call
      operationId: getGrantCheck
      description: 'Evaluated against the current facts; two gates for a research bound to an Organization: `grant.checks.run`
        and the feature `grant.checks`.'
      tags:
      - Checks
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - name: call_id
        in: path
        required: true
        schema:
          type: string
        description: The call's public id.
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantCheck'
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.checks.run
      x-moonitoring-entitlement: grant.checks
      x-moonitoring-requirements:
      - '218'
      - '1203'
      - '1204'
      - '1201'
      - '1002.28'
      - '68'
  /checks:
    get:
      summary: List my checks
      operationId: listGrantChecks
      tags:
      - Checks
      parameters:
      - name: farm-research
        in: cookie
        required: false
        schema:
          type: string
        description: 'The guest credential of a research without an account: 32 random bytes, HttpOnly, renewed
          on every visit for 90 days. A signed-in farmer presents the bearer token instead (req 212).'
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/GrantCheck'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      security:
      - {}
      - bearer: []
      x-moonitoring-audience: any
      x-moonitoring-capability: grant.checks.run
      x-moonitoring-entitlement: grant.checks
      x-moonitoring-requirements:
      - '218'
  /operator/documents:
    get:
      summary: List every farmer document
      operationId: listAllFarmerDocuments
      description: 'For the operator: inspect, then recover, pause or resume through the actions below.'
      tags:
      - Documents
      parameters:
      - name: state
        in: query
        required: false
        schema:
          type: string
          enum:
          - uploading
          - stored
          - queued
          - processing
          - ready
          - partial
          - failed
          - deleting
          - deleted
        description: Only this state.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/FarmerDocument'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: staff
      x-moonitoring-capability: grant.documents.read_all
      x-moonitoring-requirements:
      - '215'
      - '1006.36'
  /operator/documents/{document_id}/recover:
    post:
      summary: Recover a failed reading
      operationId: recoverFarmerDocument
      tags:
      - Documents
      parameters:
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmerDocument'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
      x-moonitoring-audience: staff
      x-moonitoring-capability: grant.sources.manage
      x-moonitoring-requirements:
      - '215.9'
      - '1006.36'
      - '70'
  /operator/processing:
    post:
      summary: Pause or resume document processing
      operationId: setDocumentProcessing
      description: The global pause switch; resume also runs the reconciliation.
      tags:
      - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paused:
                  type: boolean
              required:
              - paused
      responses:
        '204':
          description: Done.
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability: grant.sources.manage
      x-moonitoring-requirements:
      - '215.13'
      - '1006.36'
      - '70'
components:
  schemas:
    FarmerDocument:
      type: object
      description: One PDF a farmer uploaded, with its reading state (req 215).
      properties:
        id:
          type: string
          format: uuid
        research:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - fascicolo
          - visura
          - bdn
          - classyfarm
        filename:
          type: string
        byte_size:
          type: integer
        expected_hash:
          type: string
        state:
          type: string
          enum:
          - uploading
          - stored
          - queued
          - processing
          - ready
          - partial
          - failed
          - deleting
          - deleted
        failure_reason:
          type: string
          enum:
          - pdf_encrypted
          - pdf_page_limit
          - pdf_malformed
          - pdf_limits
          - document_integrity
          - document_mismatch
          - insufficient_evidence
          - company_mismatch
          - multiple_companies
          - model_unavailable
          - processing_failed
        page_count:
          type: integer
        unreadable_pages:
          type: array
          items:
            type: integer
        extraction_version:
          type: string
        finalized_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - research
      - kind
      - filename
      - byte_size
      - expected_hash
      - state
      - created_at
      - updated_at
    FarmFact:
      type: object
      description: One value read from a farmer document, kept only when its quote is found and its company matches
        (req 216).
      properties:
        id:
          type: string
          format: uuid
        document:
          type: string
          format: uuid
        key:
          type: string
          description: A FactKey (req 1200).
        subject_kind:
          type: string
          enum:
          - company
          - person
          - holding
          - parcel
        subject:
          type: string
        value:
          description: Typed by the key's unit.
        unit:
          type: string
          enum:
          - text
          - boolean
          - date
          - count
          - ha
          - EUR
          - percent
        observed_at:
          type: string
          format: date
        period:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/Period
        citation:
          type: object
          properties:
            page:
              type: integer
            quote:
              type: string
          required:
          - page
          - quote
        disputed:
          type: boolean
        created_at:
          type: string
          format: date-time
      required:
      - id
      - document
      - key
      - subject_kind
      - unit
      - citation
      - disputed
      - created_at
    FarmerDocumentProfile:
      type: object
      description: The company identity of a research's documents and its counters (req 217).
      properties:
        research:
          type: string
          format: uuid
        company_id:
          type: string
        revision:
          type: integer
        active_documents:
          type: integer
        reserved_pages:
          type: integer
        updated_at:
          type: string
          format: date-time
      required:
      - research
      - revision
      - active_documents
      - updated_at
    GrantCheck:
      type: object
      description: The requirements of a call evaluated against a farm's facts; only a definitely failed group excludes
        (req 218).
      properties:
        id:
          type: string
          format: uuid
        research:
          type: string
          format: uuid
        call:
          type: string
        profile_revision:
          type: integer
        rule_version:
          type: string
        verdict:
          type: string
          enum:
          - excluded
          - candidate
        groups:
          type: array
          items:
            type: object
            properties:
              clause:
                type: object
                additionalProperties: true
              status:
                type: string
                enum:
                - satisfied
                - not_satisfied
                - unknown
              why:
                type: string
              facts:
                type: array
                items:
                  type: string
                  format: uuid
            required:
            - clause
            - status
        not_verified_by_documents:
          type: array
          items:
            type: string
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - research
      - call
      - profile_revision
      - rule_version
      - verdict
      - groups
      - updated_at
    DocumentUploadRequest:
      type: object
      description: Announces a document; the response carries the resumable upload session. A second upload of the
        same bytes returns the existing document.
      properties:
        kind:
          type: string
          enum:
          - fascicolo
          - visura
          - bdn
          - classyfarm
        filename:
          type: string
        byte_size:
          type: integer
          minimum: 1
          maximum: 26214400
        expected_hash:
          type: string
          description: SHA-256 of the content.
      required:
      - kind
      - filename
      - byte_size
      - expected_hash
    DocumentUploadTarget:
      type: object
      description: The document record and the resumable session to put the bytes in, straight to the bucket; keep
        the session URL out of logs.
      properties:
        document:
          $ref: '#/components/schemas/FarmerDocument'
        upload:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/SignedUrl
      required:
      - document
      - upload
    DisputeRequest:
      type: object
      description: Contests or restores a fact.
      properties:
        disputed:
          type: boolean
      required:
      - disputed
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The short-lived token signed by `access`: an Organization user token, a staff token or a client
        token, as the operation''s audience says.'