# Shared types, errors, paging and security that every Moonitoring API refers to. Initialized from the data model
# (docs/06-data); from here on edited by hand: it is the contract, not a copy of the model. Within v1 it only gains fields.
openapi: 3.1.0
info:
  title: Shared Types
  version: 1.0.0
  description: 'Schemas, parameters and responses that every Moonitoring API refers to. Sequence numbers remain
    JSON integers: clients must preserve their full int64 precision. The final wire encoding decision is deferred;
    these contracts do not change sequence numbers to strings.'
servers:
- url: https://access.moonitoring.com
  description: Shared types have no endpoints of their own; the server is the host of the API that refers to them.
paths: {}
components:
  schemas:
    WriteSequence:
      description: The positive write number that identifies a WriteCommit, not a UUID.
      type: integer
      format: int64
      minimum: 1
      maximum: 9223372036854775807
    ReadSequence:
      description: 'A read cutoff at or below the watermark, not an identifier of a particular WriteCommit.
        Zero represents the initial empty state before any writes.'
      type: integer
      format: int64
      minimum: 0
      maximum: 9223372036854775807
    Telephone:
      description: A telephone number, together with the nation whose prefix applies.
      type: object
      properties:
        telephone_nation:
          type: string
          format: uuid
          description: ID of the Nation.
        telephone_number:
          type: string
          format: regex
      required:
      - telephone_nation
      - telephone_number
    NationalIdentifierType:
      description: A national identifier of an Organization, such as its fiscal code, with the nation whose format
        applies.
      type: object
      properties:
        nation:
          type: string
          format: uuid
          description: ID of the Nation.
        identifier:
          type: string
      required:
      - nation
      - identifier
    OrganizationRoleCapabilityEnum:
      description: The catalog of permissions that organization roles grant. Values are defined in code; each one
        allows an action of a system inside an Organization.
      type: string
      enum:
      - moochat.moochat.access
      - farm.animals.read
      - farm.animals.update
      - farm.animal_groups.read
      - farm.animal_groups.manage_members
      - access.organization_delegations.manage
      - access.organization.update
      - access.members.read
      - access.members.manage
      - farm.ownerships.transfer
      - farm.animal_records.read
      - farm.animal_events.record
      - farm.animal_diagnoses.record
      - farm.official_submissions.submit
      - farm.animal_groups.manage
      - farm.sources.manage
      - farm.ingestion.read
      - access.cooperative_constraints.read
      - access.cooperative_constraints.manage
      - farm.animal_records.edit_own
      - farm.data_issues.read
      - farm.sync_clients.read
      - farm.sync_clients.manage
      - farm.models.use
      - farm.sync_runs.write
      - access.webhooks.manage
      - farm.farm_configurations.manage
      - grant.checks.run
      - grant.documents.manage
      - moochat.connectors.manage
      - access.groups.read
      - access.groups.manage
      - access.organization.close
      - access.cooperative_links.manage
      - farm.erasure_requests.request
      - grant.call_actions.manage
      - access.cooperative_members.read
    IdentifiersValues:
      description: The external identifiers held by an animal or group, grouped by kind.
      type: object
      properties:
        national_identifiers:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the ExternalIdentifier that is a NationalIdentifier. At most one per nation valid at
            the same time. More than one nation is normal for an animal imported from outside the EU that keeps
            its origin tag and receives a local one.
        farm_identifier:
          type: string
          format: uuid
          description: ID of the ExternalIdentifier that is a FarmIdentifier.
        integration_identifiers:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the ExternalIdentifier that is a IntegrationIdentifier.
        unknown_identifiers:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the ExternalIdentifier that is a UnknownIdentifier.
        alias_identifiers:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the ExternalIdentifier that is a AliasIdentifier.
        electronic_identifiers:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the ExternalIdentifier that is a ElectronicIdentifier.
    Period:
      description: A validity interval for registry facts such as ownership and memberships. Each end carries an
        explicit state, so an open end, an unknown end and an unknown start are different things that the database
        can check.
      type: object
      properties:
        valid_from:
          type: string
          format: date-time
        start_state:
          type: string
          enum:
          - known
          - unknown
          default: known
          description: Known requires `valid_from`; unknown has none. An unknown start is never replaced by an import
            date.
        valid_until:
          type: string
          format: date-time
        end_state:
          type: string
          enum:
          - known
          - open
          - unknown
          default: open
          description: Known requires `valid_until`; open and unknown have none. open = explicitly no end; unknown
            = not established, never treated as open. When both ends are known, `valid_until` ≥ `valid_from`.
      required:
      - start_state
      - end_state
    AnimalSexEnum:
      description: The biological sex of an animal.
      type: string
      enum:
      - female
      - male
    MoonitoringCapabilityEnum:
      description: The catalog of permissions that Moonitoring roles grant to platform users.
      type: string
      enum:
      - access.moonitoring_access.read
      - access.moonitoring_access.manage
      - access.moonitoring_roles.manage
      - access.organization_roles.manage
      - releases.releases.read
      - releases.installations.read
      - releases.release_catalog.manage
      - releases.channels.manage
      - releases.builds.upload
      - releases.builds.revoke
      - releases.releases.stage
      - releases.releases.approve
      - releases.releases.pause
      - releases.releases.rollback
      - releases.release_keys.manage
      - releases.release_storage.purge
      - farm.reference_data.manage
      - farm.source_origins.manage
      - access.organizations.read
      - farm.ingestion.read_all
      - farm.sync_clients.manage_all
      - farm.data_issues.read_all
      - farm.canonical_data.read_all
      - farm.entitlements.manage
      - ai-model-platform.models.manage
      - moochat.agents.manage
      - moochat.agent_models.manage
      - access.audit.read
      - ai-model-platform.datasets.manage
      - ai-model-platform.datasets.read
      - ai-gateway.usage.read
      - farm.parse_jobs.manage
      - farm.reconciliation_rules.manage
      - farm.erasure_requests.manage
      - grant.calls.manage
      - grant.sources.manage
      - access.organizations.approve
      - access.nations.manage
      - farm.integration_gaps.read
      - farm.integration_gaps.manage
      - farm.source_adapters.manage
      - farm.adapter_mappings.manage
      - news.articles.write
      - news.articles.publish
      - access.organizations.close
      - status.incidents.read
      - status.incidents.manage
      - status.components.manage
      - farm.sync_clients.read_all
      - ai-model-platform.models.read
      - grant.documents.read_all
    OrganizationPredefinedRoleEnum:
      description: The stable key of a predefined Organization role (req 1028). Owner and Sync Client are system roles
        that no operation changes; systems find a role by its key, never by its name.
      type: string
      enum:
      - owner
      - manager
      - technician
      - veterinarian
      - advisor
      - sync_client
      - analyst
    MoonitoringPredefinedRoleEnum:
      description: The stable key of a predefined staff role (req 1029). Administrators is named only by the job
        access-bootstrap-admin, never through an operation.
      type: string
      enum:
      - administrators
      - support
      - data_operations
      - releases
      - account
      - privacy
      - incident
      - news_editor
      - news_publisher
      - grant_curator
      - ml
      - agents
    ChunkingParams:
      description: How the files of a depot are cut into chunks.
      type: object
      properties:
        algorithm:
          type: string
          enum:
          - fastcdc
        min_size:
          type: integer
        avg_size:
          type: integer
        max_size:
          type: integer
          description: Sizes in bytes.
        hash:
          type: string
          enum:
          - blake3
          - sha256
      required:
      - algorithm
      - min_size
      - avg_size
      - max_size
      - hash
    ObservationValue:
      description: 'The result of an observation: a quantity, a category, a flag or numeric bounds, with its result
        form.'
      type: object
      properties:
        quantity:
          type: number
        category:
          type: string
        flag:
          type: boolean
        result_form:
          type: string
          enum:
          - point
          - interval
          - lower_bound
          - upper_bound
          - category
          - flag
        bounds:
          $ref: '#/components/schemas/NumericBounds'
        censoring_reason:
          type: string
          enum:
          - detection_limit
          - quantification_limit
          - instrument_limit
          - reporting_limit
          - unknown
      required:
      - result_form
      oneOf:
      - properties:
          result_form:
            const: point
        required:
        - quantity
        not:
          anyOf:
          - required: [category]
          - required: [flag]
          - required: [bounds]
      - properties:
          result_form:
            const: interval
          bounds:
            required: [lower, upper]
        required:
        - bounds
        not:
          anyOf:
          - required: [quantity]
          - required: [category]
          - required: [flag]
      - properties:
          result_form:
            const: lower_bound
          bounds:
            required: [lower]
            not:
              required: [upper]
        required:
        - bounds
        not:
          anyOf:
          - required: [quantity]
          - required: [category]
          - required: [flag]
      - properties:
          result_form:
            const: upper_bound
          bounds:
            required: [upper]
            not:
              required: [lower]
        required:
        - bounds
        not:
          anyOf:
          - required: [quantity]
          - required: [category]
          - required: [flag]
      - properties:
          result_form:
            const: category
        required:
        - category
        not:
          anyOf:
          - required: [quantity]
          - required: [flag]
          - required: [bounds]
      - properties:
          result_form:
            const: flag
        required:
        - flag
        not:
          anyOf:
          - required: [quantity]
          - required: [category]
          - required: [bounds]
    ObservationTime:
      description: 'When an observation applies, with the precision the source gave: an instant, a date, a month,
        an interval or unknown.'
      type: object
      properties:
        kind:
          type: string
          enum:
          - instant
          - date
          - month
          - interval
          - unknown
        instant:
          type: string
          format: date-time
        date:
          type: string
          format: date
        month:
          type: string
          pattern: ^\d{4}-(0[1-9]|1[0-2])$
        interval:
          $ref: '#/components/schemas/ObservedPeriod'
        precision:
          allOf:
          - $ref: '#/components/schemas/TimePrecisionEnum'
          description: A local time in the repeated hour of the autumn clock change is resolved by the source's
            own order (increasing record id or end time) when it has one; without an order it takes the later (standard-time)
            reading and the adapter raises a DataIssue of kind `ambiguous_local_time`, never a silent guess.
      required:
      - kind
      - precision
    EventTime:
      description: When an event occurred, with the same precision model as ObservationTime, but without intervals.
      type: object
      properties:
        kind:
          type: string
          enum:
          - instant
          - date
          - month
          - unknown
        instant:
          $ref: '#/components/schemas/ObservationTime/properties/instant'
        date:
          $ref: '#/components/schemas/ObservationTime/properties/date'
        month:
          $ref: '#/components/schemas/ObservationTime/properties/month'
        precision:
          $ref: '#/components/schemas/ObservationTime/properties/precision'
      required:
      - kind
      - precision
      not:
        required: [interval]
      oneOf:
      - properties:
          kind:
            const: instant
        required: [instant]
        not:
          anyOf:
          - required: [date]
          - required: [month]
      - properties:
          kind:
            const: date
        required: [date]
        not:
          anyOf:
          - required: [instant]
          - required: [month]
      - properties:
          kind:
            const: month
        required: [month]
        not:
          anyOf:
          - required: [instant]
          - required: [date]
      - properties:
          kind:
            const: unknown
        not:
          anyOf:
          - required: [instant]
          - required: [date]
          - required: [month]
    TimePrecisionEnum:
      description: The precision of a time value.
      type: string
      enum:
      - second
      - minute
      - hour
      - day
      - month
      - unknown
    AggregationEnum:
      description: How several values were combined into one.
      type: string
      enum:
      - none
      - sum
      - arithmetic_mean
      - mass_weighted_mean
      - volume_weighted_mean
      - geometric_mean
      - min
      - max
      - last
      - count
      - provider_defined
      - unknown
    CodedValue:
      description: A code from a named code system, with optional display text and version.
      type: object
      properties:
        code:
          type: string
        code_system:
          type: string
        display:
          type: string
        version:
          type: string
      required:
      - code
      - code_system
    ParentReference:
      description: A sire, dam or embryo donor, which may be outside our animal registry until an identifier matches.
      type: object
      properties:
        animal:
          type: string
          format: uuid
          description: ID of the Animal.
        external_identifier:
          type: string
        name:
          type: string
        identifier_scheme:
          $ref: '#/components/schemas/CodedValue'
        breed:
          type: string
          format: uuid
          description: ID of the AnimalBreedType. For purchased semen known only by breed (e.g. beef semen, no bull
            indicated). Only for a sire of a service.
    WithdrawalSpec:
      description: A withdrawal period for one tissue after a treatment.
      type: object
      properties:
        tissue:
          type: string
          enum:
          - milk
          - meat
          - organs
          - eggs
          - honey
        duration_hours:
          type: integer
        status:
          type: string
          enum:
          - defined
          - not_permitted
          - not_available
      required:
      - tissue
      - status
    PropertyDefinition:
      description: The fixed constants of an observation type, such as the material sampled (matrix) and the substance
        measured (analyte), selected by its profile family.
      type: object
      properties:
        matrix:
          $ref: '#/components/schemas/CodedValue'
        parameters:
          description: A value typed by constants of the family.
      required:
      - parameters
    PropertyQualifiers:
      description: The typed per-result fields that an observation type's qualifier schema allows.
      type: object
      properties:
        values:
          description: A value typed by fields; empty object allowed.
      required:
      - values
    CoverageDetails:
      description: How much of its intended window or material an observation covers.
      type: object
      properties:
        status:
          type: string
          enum:
          - complete
          - partial
          - unknown
        basis:
          type: string
          enum:
          - time
          - expected_readings
          - represented_milk
          - other_documented
          - unknown
        fraction:
          type: number
        definition:
          $ref: '#/components/schemas/CodedValue'
      required:
      - status
      - basis
    RecordRevision:
      description: 'Revision metadata carried by evidence, resolutions, periods and identity decisions: the chain
        a record belongs to, its revision number, and the writes that made it available and replaced it.'
      type: object
      properties:
        logical_record_id:
          type: string
          format: uuid
        revision_number:
          type: integer
        available_in:
          $ref: '#/components/schemas/WriteSequence'
          description: ID of the WriteCommit. The write that made this revision available. Its `committed_at` is
            the readable clock; cutoffs use the write number, because two concurrent writes can become visible in
            a different order than their timestamps.
        replaced_in:
          $ref: '#/components/schemas/WriteSequence'
          description: 'ID of the WriteCommit. Written once, by the write that appends the next revision of the
            same logical record: an index for as-of range queries, not payload. Empty on the current revision.'
      required:
      - logical_record_id
      - revision_number
      - available_in
    NumericBounds:
      description: 'Lower and upper value bounds with their inclusivity, for interval and censored results.
        The service also checks lower <= upper and requires both ends inclusive when they are equal.'
      type: object
      properties:
        lower:
          type: number
        upper:
          type: number
        lower_inclusive:
          type: boolean
        upper_inclusive:
          type: boolean
      anyOf:
      - required: [lower]
      - required: [upper]
      dependentRequired:
        lower: [lower_inclusive]
        lower_inclusive: [lower]
        upper: [upper_inclusive]
        upper_inclusive: [upper]
    AggregationDetails:
      description: The per-row part of an aggregate value, such as how many readings it combined.
      type: object
      properties:
        input_count:
          type: integer
    RecordReference:
      description: A reference to an exact revision of a record of a declared kind, used as a derivation input.
      type: object
      properties:
        entity_kind:
          type: string
          enum:
          - observation
          - event
          - session
          - resolved_event
          - period
          - animal_link
          - sample
          - product_material
          - observation_selection
          - profile_evidence
          - feed_coverage
        revision_id:
          type: string
          format: uuid
      required:
      - entity_kind
      - revision_id
    ObservedPeriod:
      description: A time interval whose start and end keep their precision, with an explicit open or unknown end.
      type: object
      properties:
        start:
          $ref: '#/components/schemas/EventTime'
        end:
          $ref: '#/components/schemas/EventTime'
        end_state:
          type: string
          enum:
          - known
          - open
          - unknown
      required:
      - start
      - end_state
    SystemVersion:
      description: 'Transaction-time metadata of a registry row: the writes that created and retired each of its
        images.'
      type: object
      properties:
        created_seq:
          $ref: '#/components/schemas/WriteSequence'
          description: ID of the WriteCommit.
        retired_seq:
          $ref: '#/components/schemas/WriteSequence'
          description: ID of the WriteCommit. Empty on the current image. On every change the previous image is
            kept in a history store with its interval.
      required:
      - created_seq
    BreedShare:
      description: A breed and its fraction, as one source states it in profile evidence.
      type: object
      properties:
        breed_type:
          type: string
          format: uuid
          description: ID of the AnimalBreedType.
        breed_value:
          oneOf:
          - type: number
          - type: string
            const: unknown
          description: Same meaning as BreedMembership.`BreedMembership.breed_value`.
      required:
      - breed_type
      - breed_value
    MlDatasetSelection:
      description: 'The filters of a dataset build: which tables, which time ranges, and optionally which animal
        types, breeds, observation types, origins, nations, regions and Organizations. Values within one axis are
        ORed, axes are ANDed, and an empty list means no filter on that axis. The selection is copied into every
        version, so a later edit of the dataset never changes what an existing version meant.'
      type: object
      properties:
        tables:
          type: array
          items:
            type: string
            enum:
            - animals
            - observations
            - events
            - resolved_events
            - periods
            - animal_links
          minItems: 1
        periods:
          type: array
          items:
            $ref: '#/components/schemas/Period'
          minItems: 1
          description: One or more time ranges, by the record's own time; the union of them.
        animal_types:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the AnimalType.
        breeds:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the AnimalBreedType. Through BreedMembership at the build's write number.
        observation_types:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the ObservationType.
        origins:
          type: array
          items:
            type: string
          description: Admitted subtypes of SourceOrigin and assurance values (`SourceOrigin.assurance`), e.g. "SensorSourceOrigin",
            "`accredited_lab`".
        nations:
          type: array
          items:
            type: string
            format: uuid
          description: ID of the Nation.
        regions:
          type: array
          items:
            type: string
          description: Administrative regions as coded on the farm's address, within the nations above.
        organizations:
          type: array
          items:
            type: string
            format: uuid
          description: 'ID of the Organization. Only these Organizations'' data; empty: every Organization the build
            may use (`farm.canonical_data.read_all`).'
      required:
      - tables
      - periods
    Problem:
      description: An error, as defined by RFC 9457 (Problem Details for HTTP APIs).
      type: object
      properties:
        type:
          type: string
          format: uri
          description: Identifies the kind of error, `urn:moonitoring:problem:<slug>`, one of the
            ProblemType catalog; an app words its message by it, never by `detail`.
        title:
          type: string
          description: Short summary of the kind of error.
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: What went wrong in this request.
        instance:
          type: string
          description: Identifies this occurrence, for support.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ProblemFieldError'
          description: The invalid fields, when the problem is about the request body or parameters.
      required:
      - type
      - title
      - status
    SignedUrl:
      description: A short-lived signed URL to upload or download one object directly from Cloud Storage, so that
        no API sits in the path of the bytes.
      type: object
      properties:
        url:
          type: string
          format: uri
        method:
          type: string
          enum:
          - PUT
          - GET
          - POST
          description: The HTTP method the URL accepts; POST starts a resumable upload.
        headers:
          type: object
          additionalProperties:
            type: string
          description: Headers the caller must send as they are.
        expires_at:
          type: string
          format: date-time
      required:
      - url
      - method
      - expires_at
    ProblemType:
      description: 'The catalog of problem types every system answers with, `urn:moonitoring:problem:<slug>`, stable
        across releases, so an app words each refusal for the person. invalid-request (400); unauthenticated (401);
        forbidden (403), the caller lacks the capability; reauthentication-required (403), the sign-in is older than
        five minutes for a write under an admin capability, never for a read; registration-required (403), a new
        person must register first;
        self-action (403), nobody gives, changes or revokes their own memberships or a role they hold;
        role-outranks-you (403), the role given, changed or revoked has a priority not below the caller''s own;
        role-capabilities-not-held (403), the role holds a capability the caller does not hold; administrators-only-by-job
        (403), the staff role Administrators is given and taken only by the job access-bootstrap-admin, never through
        the API; not-found (404); conflict (409); precondition-failed (412); unprocessable-entity (422), `errors` lists
        the fields; too-many-requests (429), with `Retry-After`; internal (500); unavailable (503). The four refusals
        of who may grant what were added on 2026-11-11; they stay 403, and a new type is only ever added.'
      type: string
      enum:
      - urn:moonitoring:problem:invalid-request
      - urn:moonitoring:problem:unauthenticated
      - urn:moonitoring:problem:forbidden
      - urn:moonitoring:problem:reauthentication-required
      - urn:moonitoring:problem:registration-required
      - urn:moonitoring:problem:self-action
      - urn:moonitoring:problem:role-outranks-you
      - urn:moonitoring:problem:role-capabilities-not-held
      - urn:moonitoring:problem:administrators-only-by-job
      - urn:moonitoring:problem:not-found
      - urn:moonitoring:problem:conflict
      - urn:moonitoring:problem:precondition-failed
      - urn:moonitoring:problem:unprocessable-entity
      - urn:moonitoring:problem:too-many-requests
      - urn:moonitoring:problem:internal
      - urn:moonitoring:problem:unavailable
    ProblemFieldError:
      description: One invalid field of a request, listed in `errors` of a Problem with status 400 or 422.
      type: object
      properties:
        field:
          type: string
          description: JSON pointer of the field, e.g. /period/valid_from.
        code:
          type: string
          description: A stable machine-readable code, e.g. required, out_of_range, unknown_reference.
        detail:
          type: string
      required:
      - field
      - code
  parameters:
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: 'Where the page starts: the next_cursor of the previous page.'
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
      description: How many items the page holds at most.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: Chosen by the client for each new request that creates something; a retry repeats it.
    AsOfSeq:
      name: as_of_seq
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/ReadSequence'
      description: 'Read the data as it was at this write number (at or below the watermark). Absent: the current
        watermark. The write number used is returned in the `Moonitoring-As-Of-Seq` response header.'
    IfMatch:
      name: If-Match
      in: header
      required: false
      schema:
        type: string
      description: The ETag of the resource as last read; the change is refused with 412 when the resource changed
        since.
  responses:
    BadRequest:
      description: The request is not valid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: The caller is not signed in.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: 'The caller may not do this. The problem type says why (ProblemType): forbidden,
        reauthentication-required, registration-required, self-action, role-outranks-you, role-capabilities-not-held
        or administrators-only-by-job.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: The resource does not exist.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: The request conflicts with the current state of the resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    UnprocessableEntity:
      description: The request is well formed but breaks a rule of the data model; `errors` lists the fields.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    TooManyRequests:
      description: The caller sent too many requests, or an Organization's metered feature reached its limit; `Retry-After`
        says when to try again.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PreconditionFailed:
      description: The resource changed since it was read (`If-Match` did not match).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Accepted:
      description: The request was accepted and will be processed; the body says where to follow it.
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                format: uuid
              status:
                type: string
            required:
            - id
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The short-lived token signed by `access`.