openapi: '3.0.3'
info:
  title: VegBankAPI
  version: '2.1.1'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: './assets/vegbank-logo.png'
    altText: VegBank logo
  description: |
    Welcome to the official documentation for the VegBank REST API. You
    can find out more about VegBank at https://github.com/NCEAS/vegbank2.

    ### Introduction
    The [VegBank](http://vegbank.org) data system provides a community
    managed data portal for vegetation data, particularly plots, plant
    taxonomy, and communities. Developed, maintained, and operated by
    the National Center for Ecological Analysis and Synthesis (NCEAS),
    VegBank is a product of the Ecological Society of America (ESA)
    Vegetation Panel, and is affiliated with the National Vegetation
    Classification (USNVC).

    VegBank provides a common storage system and web portal for accessing:
    - Plot data
    - Plant taxonomy data
    - Community data

    VegBank is an open source, community project. We [welcome
    contributions](https://github.com/NCEAS/vegbank2/blob/develop/CONTRIBUTING.md)
    in many forms, including code, graphics, documentation, bug reports,
    testing, etc.

    Use the [VegBank
    discussions](https://github.com/NCEAS/vegbank2/discussions) to
    ask questions, raise issues, or discuss contributions with us.

servers:
  - url: https://api.vegbank.org
    description: VegBank Production API
  - url: https://api-dev.vegbank.org
    description: VegBank Development API (unstable)
security: []

tags:
- name: Plot observations
  description: |
    Operations related to plot observations. A plot observation is a recording
    of the physical, biological, and other environmental attributes (and more)
    of a defined plot at some time and in some place, along with other
    supporting contextual information. In VegBank, each plot observation is
    typically linked to details about the plants (taxon observations) that were
    observed in the plot and interpreted to some plant concept, and it is
    typically classified to a specific community concept.
- name: Community concepts
  description: |
    Operations related to community concepts. A community concept is the
    assertion of a specific community type through the combination of a name and
    an associated reference, augmented by status details, any alternative names,
    and optional relationships (correlations) with other community concepts.
- name: Community classifications
  description: |
    Operations related to community classifications. A community classification
    is an activity wherein one or more contributors make one or more community
    interpretations, each of which corresponds to the assignment of a community
    concept to a plot observation.
- name: Community interpretations
  description: |
    Operations related to community interpretations. A community interpretation
    is the specific act of assigning a community concept to a plot observation,
    perhaps with some asserted fit and confidence level, along with other
    information. Each community interpretation is done in the context of a
    specific community classification, and technically a classification activity
    can yield multiple interpretations (although this is rare in practice).
- name: Plant concepts
  description: |
    Operations related to plant concepts. A plant concept is the assertion of a
    specific plant taxon through the combination of a name and an associated
    reference, augmented by status details, any alternative names, and optional
    relationships (correlations) with other plant concepts.
- name: Taxon observations
  description: |
    Operations related to taxon observations. A taxon observation is a record of
    a particular plant taxon in the context of a particular plot observation.
    Each taxon observation may have additional quantitative details (see Taxon
    importances) and/or may be interpreted to one or more plant concepts (see
    Taxon interpretations).
- name: Strata
  description: |
    Operations related to strata. A stratum is well-defined partition of a
    plot in the context of a specific plot observation, following a
    particular protocol (see Stratum methods). Each taxon importance
    record may be attached to a specific stratum.
- name: Stem counts
  description: |
    Operations related to stem counts. A stem count record stores information
    about the abundance of individual plants (typically tree stems) of a
    specific size, linked to a Taxon importance record for a given Taxon
    observation.
- name: Taxon importances
  description: |
    Operations related to taxon importances. A taxon importance record
    quantifies a taxon observation by recording plant cover, basal area,
    and/or biomass, either within a specific stratum (see Strata) or for
    the plot observation as a whole.
- name: Taxon interpretations
  description: |
    Operations related to taxon interpretations. A taxon interpretation
    is the specific act of assigning a plant concept to a taxon observation
    belonging to a plot observation, perhaps with some asserted fit and
    confidence level, along with other information such as the party who made
    the interpretation.
- name: Cover methods
  description: |
    Operations related to cover methods. A cover method is a particular protocol
    for recording the percent cover occupied by a plant taxon observed in a
    plot, often by specifying and defining one or more ordered categorical cover
    classes (i.e., cover indexes).
- name: Stratum methods
  description: |
    Operations related to stratum methods. A stratum method forms a sampling
    protocol by defining one or more strata, each of which is a logical
    subspace of a plot, often (but not always) associated with a vertical
    partitioning of space aligned with a plant growth forms.
- name: Parties
  description: |
    Operations related to parties. A party is a person or organization connected
    in some way to resources stored in VegBank, such as contributing to data
    collection or the interpretation of a plot.
- name: Projects
  description: |
    Operations related to projects. A project is a named activity established to
    collect vegetation plot data. Every plot observation belongs to exactly one
    project.
- name: References
  description: |
    Operations related to references. A reference is a specific information
    source (e.g., publication, book, website, etc) cited with respect to some resource
    or activity in VegBank.
- name: Named Places
  description: |
    Operations related to named places. A named place is a specific geographic
    location or feature stored in VegBank. Although not currently used for new
    data, older plots in VegBank can be associated with one or more named places.
- name: User Datasets
  description: |
    Operations related to VegBank datasets. A dataset is an arbitrary
    user-defined collection of plot observations, typically defined for
    some specific analysis or similar activity, and registered in
    VegBank with a stable identifier that can be used for citing and
    sharing this defined collection.
- name: Overview
  description: |
    Operations related to the retrieval of basic VegBank summary statistics.

paths:
  /plot-observations/{ob_code}:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-id
      summary: Get plot observation
      description: >
        Retrieve a single plot observation using its `ob_code`.
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /projects/{pj_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-pj
      summary: Get plot observations by project
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations associated with the
        specified project (using its `pj_code`), or a subset thereof
        based on a specified `search` query.
      parameters:
        - name: pj_code
          in: path
          required: true
          schema:
            type: string
          example: "pj.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /parties/{py_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-py
      summary: Get plot observations by party
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations associated with the
        specified party (using its `py_code`), or a subset thereof
        based on a specified `search` query.
      parameters:
        - name: py_code
          in: path
          required: true
          schema:
            type: string
          example: "py.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /named-places/{np_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-np
      summary: Get plot observations by named place
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations associated with the specified named
        place (using its `np_code`), or a subset thereof based on a specified
        `search` query.
      parameters:
        - name: np_code
          in: path
          required: true
          schema:
            type: string
          example: "np.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plant-concepts/{pc_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-pc
      summary: Get plot observations by plant concept
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations with taxon observations
        interpreted to the specified plant concept (using its
        `pc_code`), or a subset thereof based on a specified `search`
        query.
      parameters:
        - name: pc_code
          in: path
          required: true
          schema:
            type: string
          example: "pc.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-concepts/{cc_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-cc
      summary: Get plot observations by community concept
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations with taxon observations
        interpreted to the specified community concept (using its
        `cc_code`), or a subset thereof based on a specified `search`
        query.
      parameters:
        - name: cc_code
          in: path
          required: true
          schema:
            type: string
          example: "cc.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /cover-methods/{cm_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-cm
      summary: Get plot observations by cover method
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations using the specified cover
        method (using its `cm_code`), or a subset thereof based on a
        specified `search` query.
      parameters:
        - name: cm_code
          in: path
          required: true
          schema:
            type: string
          example: "cm.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /stratum-methods/{sm_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-sm
      summary: Get plot observations by stratum method
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations using the specified stratum
        method (using its `sm_code`), or a subset thereof based on a
        specified `search` query.
      parameters:
        - name: sm_code
          in: path
          required: true
          schema:
            type: string
          example: "sm.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /user-datasets/{ds_code}/plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob-by-ds
      summary: Get all plot observations included in a user dataset
      description: >
        Retrieve a paginated and sorted collection of all plot
        observations associated with the specified user dataset (using
        its `ds_code`), or a subset thereof based on a specified
        `search` query.
      parameters:
        - name: ds_code
          in: path
          required: true
          schema:
            type: string
          example: "ds.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations:
    get:
      tags:
        - Plot observations
      operationId: get-ob
      summary: Get all plot observations
      description: >
        Retrieve a paginated and sorted collection of plot observations
        representing all plot observations in VegBank, or a subset
        thereof based on a specified `search` query.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_ob'
        - $ref: '#/components/parameters/detail_ob'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_ob'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/num_taxa_ob'
        - $ref: '#/components/parameters/num_comms_ob'
      responses:
        '200':
          $ref: "#/components/responses/PlotObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Plot observations
      operationId: upload-ob
      security:
        - oauth2:
            - vegbank:contributor
      summary: Upload plot observations
      parameters:
        - $ref: '#/components/parameters/dry_run'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - plot_observations
              properties:
                plot_observations:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new plot observations (required).
                projects:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new projects (optional).
                parties:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new parties (optional).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
                soils:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing details about observed soils (optional).
                disturbances:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing details about observed disturbances
                    (optional).
                community_classifications:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing community classifications of
                    observed plots (optional).
                strata:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing details about strata defined for
                    plot observations (optional).
                strata_cover_data:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing details about plant cover as
                    observed in different strata of a plot (optional).
                stem_data:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing details about counts and/or other
                    details about stems observed on a plot (optional).
                taxon_interpretations:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing taxon interpretations of plants
                    observed on a plot (optional).
                contributors:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing party contributions to the plot
                    observations, projects, and/or community classifications
                    (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /community-concepts/{cc_code}:
    get:
      tags:
        - Community concepts
      operationId: get-cc-by-id
      summary: Get community concept
      description: >
        Retrieve a single community concept using its `cc_code`.
      parameters:
        - name: cc_code
          in: path
          required: true
          schema:
            type: string
          example: "cc.1"
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-classifications/{cl_code}/community-concepts:
    get:
      tags:
        - Community concepts
      operationId: get-cc-by-cl
      summary: Get community concepts by cl
      description: >
        Retrieve a paginated and sorted collection of community concepts
        representing all concepts interpreted under the specified
        community classification (using its `cl_code`), or a subset
        thereof based on a specified `search` query.
      parameters:
        - name: cl_code
          in: path
          required: true
          schema:
            type: string
          example: "cl.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/community-concepts:
    get:
      tags:
        - Community concepts
      operationId: get-cc-by-ob
      summary: Get community concepts by ob
      description: >
        Retrieve a paginated and sorted collection of community concepts
        representing all concepts associated with the specified plot
        observation (using its `ob_code`), or a subset thereof based on
        a specified `search` query.
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /parties/{py_code}/community-concepts:
    get:
      tags:
        - Community concepts
      operationId: get-cc-by-py
      summary: Get community concepts by py
      description: >
        Retrieve a paginated and sorted collection of the community concepts
        with a party perspective (i.e. status record) provided by the specified
        party (using its `py_code`), or a subset thereof based on a specified
        `search` query.
      parameters:
        - name: py_code
          in: path
          required: true
          schema:
            type: string
          example: "py.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /references/{rf_code}/community-concepts:
    get:
      tags:
        - Community concepts
      operationId: get-cc-by-rf
      summary: Get community concepts by rf
      description: >
        Retrieve a paginated and sorted collection of the community concepts
        associated with a given reference (using its `rf_code`), or a subset
        thereof based on a specified `search` query.
      parameters:
        - name: rf_code
          in: path
          required: true
          schema:
            type: string
          example: "rf.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-concepts:
    get:
      tags:
        - Community concepts
      operationId: get-cc
      summary: Get all community concepts
      description: >
        Retrieve a paginated and sorted collection of community concepts
        representing all concepts stored in VegBank, or a subset thereof
        based on a specified `search` query.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Community concepts
      operationId: upload-cc
      security:
        - oauth2:
            - vegbank:contributor
      summary: Upload community concepts
      parameters:
        - $ref: '#/components/parameters/dry_run'
        - name: deactivation
          in: query
          required: false
          schema:
            type: string
            enum: [none, by_party]
            default: none
          description: |
            Which existing concepts to deactivate in VegBank by setting their status stop date to now:
            - `none`: Don't dactivate any concepts
            - `by_party`: Deactivate all concepts associated with any party
              linked to concepts in the uploaded data
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - community_concepts
              properties:
                community_concepts:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing community concepts as community
                    names associated with references, along with with status
                    details and taxonomic parents (required).
                community_names:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing community name usages associated
                    with specific classification systems for new community
                    concepts (optional).
                community_correlations:
                  type: string
                  format: binary
                  description: >
                    Parquet file defining correlations between community
                    concepts (optional).
                parties:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new parties (optional).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /community-classifications/{cl_code}:
    get:
      tags:
        - Community classifications
      operationId: get-cl-by-id
      summary: Get community classification
      description: >
        Retrieve a single community classification using its `cl_code`.
      parameters:
        - name: cl_code
          in: path
          required: true
          schema:
            type: string
          example: "cl.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityClassifications"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-concepts/{cc_code}/community-classifications:
    get:
      tags:
        - Community classifications
      operationId: get-cl-by-cc
      summary: Get community classifications by cc
      description: >
        Retrieve a paginated collection of community classifications
        using the specified community concept (using its `cc_code`).
      parameters:
        - name: cc_code
          in: path
          required: true
          schema:
            type: string
          example: "cc.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityClassifications"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/community-classifications:
    get:
      tags:
        - Community classifications
      operationId: get-cl-by-ob
      summary: Get community classifications by ob
      description: >
        Retrieve a paginated collection of community classifications
        associated with the specified plot observation (using its
        `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_cc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityClassifications"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-classifications:
    get:
      tags:
        - Community classifications
      operationId: get-cl
      summary: Get all community classifications
      description: >
        Retrieve a paginated collection of all community classifications
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityClassifications"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Community classifications
      operationId: upload-cl
      security:
        - oauth2:
            - vegbank:contributor
      summary: Upload community classifications
      parameters:
        - $ref: '#/components/parameters/dry_run'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - community_classifications
              properties:
                community_classifications:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing community classifications of
                    existing observed plots (required).
                parties:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new parties (optional).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
                contributors:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing party contributions to the
                    community classifications (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /community-interpretations/{ci_code}:
    get:
      tags:
        - Community interpretations
      operationId: get-ci-by-id
      summary: Get community interpretation
      description: >
        Retrieve a single community interpretation using its `ci_code`.
      parameters:
        - name: ci_code
          in: path
          required: true
          schema:
            type: string
          example: "ci.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-classifications/{cl_code}/community-interpretations:
    get:
      tags:
        - Community interpretations
      operationId: get-ci-by-cl
      summary: Get community interpretations by cl
      description: >
        Retrieve a paginated collection of community interpretations
        associated with the specified community classification (using
        its `cl_code`).
      parameters:
        - name: cl_code
          in: path
          required: true
          schema:
            type: string
          example: "cl.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/community-interpretations:
    get:
      tags:
        - Community interpretations
      operationId: get-ci-by-ob
      summary: Get community interpretations by ob
      description: >
        Retrieve a paginated collection of community interpretations
        associated with the specified plot observation (using its
        `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-concepts/{cc_code}/community-interpretations:
    get:
      tags:
        - Community interpretations
      operationId: get-ci-by-cc
      summary: Get community interpretations by cc
      description: >
        Retrieve a paginated collection of community interpretations
        using the specified community concept (using its `cc_code`).
      parameters:
        - name: cc_code
          in: path
          required: true
          schema:
            type: string
          example: "cc.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-interpretations:
    get:
      tags:
        - Community interpretations
      operationId: get-ci
      summary: Get all community interpretations
      description: >
        Retrieve a paginated collection of all community interpretations
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CommunityInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /plant-concepts/{pc_code}:
    get:
      tags:
        - Plant concepts
      operationId: get-pc-by-id
      summary: Get plant concept
      description: >
        Retrieve a single plant concept using its `pc_code`.
      parameters:
        - name: pc_code
          in: path
          required: true
          schema:
            type: string
          example: "pc.1"
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/PlantConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /parties/{py_code}/plant-concepts:
    get:
      tags:
        - Plant concepts
      operationId: get-pc-by-py
      summary: Get plant concepts by py
      description: >
        Retrieve a paginated and sorted collection of the plant concepts with a
        party perspective (i.e. status record) provided by the specified party
        (using its `py_code`), or a subset thereof based on a specified `search`
        query.
      parameters:
        - name: py_code
          in: path
          required: true
          schema:
            type: string
          example: "py.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_pc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/PlantConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /references/{rf_code}/plant-concepts:
    get:
      tags:
        - Plant concepts
      operationId: get-pc-by-rf
      summary: Get plant concepts by rf
      description: >
        Retrieve a paginated and sorted collection of the plant concepts
        associated with a given reference (using its `rf_code`), or a subset
        thereof based on a specified `search` query.
      parameters:
        - name: rf_code
          in: path
          required: true
          schema:
            type: string
          example: "rf.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_pc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/PlantConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-observations/{to_code}/plant-concepts:
    get:
      tags:
        - Plant concepts
      operationId: get-pc-by-to
      summary: Get plant concepts by to
      description: >
        Retrieve a paginated and sorted collection of the plant concepts
        applied via interpretation to the specified taxon observation
        (using its `to_code`), or a subset thereof based on a specified
        `search` query.
      parameters:
        - name: to_code
          in: path
          required: true
          schema:
            type: string
          example: "to.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_pc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/PlantConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/plant-concepts:
    get:
      tags:
        - Plant concepts
      operationId: get-pc-by-ob
      summary: Get plant concepts by ob
      description: >
        Retrieve a paginated and sorted collection of all plant concepts
        associated with the specified plot observation (using its
        `ob_code`), or a subset thereof based on a specified `search`
        query.
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_pc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/PlantConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plant-concepts:
    get:
      tags:
        - Plant concepts
      operationId: get-pc
      summary: Get all plant concepts
      description: >
        Retrieve a paginated and sorted collection of plant concepts
        representing all concepts stored in VegBank, or a subset thereof
        based on a specified `search` query.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/status_concept'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/sort_pc'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/PlantConcepts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Plant concepts
      operationId: upload-pc
      security:
        - oauth2:
            - vegbank:contributor
      summary: Upload plant concepts
      parameters:
        - $ref: '#/components/parameters/dry_run'
        - name: deactivation
          in: query
          required: false
          schema:
            type: string
            enum: [none, by_party]
            default: none
          description: |
            Which existing concepts to deactivate in VegBank by setting their status stop date to now:
            - `none`: Don't dactivate any concepts
            - `by_party`: Deactivate all concepts associated with any party linked to concepts in the uploaded data
            - `by_party_below_order`: Like `by_party`, but only for concepts at Family level and below
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - plant_concepts
              properties:
                plant_concepts:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing plant concepts as plant names
                    associated with references, along with with status details
                    and taxonomic parents (required).
                plant_names:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing plant name usages associated with
                    specific classification systems for new plant concepts
                    (optional).
                plant_correlations:
                  type: string
                  format: binary
                  description: >
                    Parquet file defining correlations between plant concepts
                    (optional).
                parties:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new parties (optional).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /taxon-observations/{to_code}:
    get:
      tags:
        - Taxon observations
      operationId: get-to-by-id
      summary: Get taxon observation
      description: >
        Retrieve a single taxon observation using its `to_code`.
      parameters:
        - name: to_code
          in: path
          required: true
          schema:
            type: string
          example: "to.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/taxon-observations:
    get:
      tags:
        - Taxon observations
      operationId: get-to-by-ob
      summary: Get taxon observations by ob
      description: >
        Retrieve a paginated collection of taxon observations
        associated with the specified plot observation (using its
        `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plant-concepts/{pc_code}/taxon-observations:
    get:
      tags:
        - Taxon observations
      operationId: get-to-by-pc
      summary: Get taxon observations by pc
      description: >
        Retrieve a paginated collection of taxon observations
        interpreted to the specified plant concept (using its
        `pc_code`).
      parameters:
        - name: pc_code
          in: path
          required: true
          schema:
            type: string
          example: "pc.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-observations:
    get:
      tags:
        - Taxon observations
      operationId: get-to
      summary: Get all taxon observations
      description: >
        Retrieve a paginated collection of all taxon observations
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonObservations"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /taxon-importances/{tm_code}:
    get:
      tags:
        - Taxon importances
      operationId: get-tm-by-id
      summary: Get taxon importance
      description: >
        Retrieve a single taxon importance using its `tm_code`.
      parameters:
        - name: tm_code
          in: path
          required: true
          schema:
            type: string
          example: "tm.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonImportances"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/taxon-importances:
    get:
      tags:
        - Taxon importances
      operationId: get-tm-by-ob
      summary: Get taxon importances by ob
      description: >
        Retrieve a paginated collection of taxon importances
        associated with the specified plot observation (using its
        `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonImportances"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plant-concepts/{pc_code}/taxon-importances:
    get:
      tags:
        - Taxon importances
      operationId: get-tm-by-pc
      summary: Get taxon importances by pc
      description: >
        Retrieve a paginated collection of taxon importances
        interpreted to the specified plant concept (using its
        `pc_code`).
      parameters:
        - name: pc_code
          in: path
          required: true
          schema:
            type: string
          example: "pc.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonImportances"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-observations/{to_code}/taxon-importances:
    get:
      tags:
        - Taxon importances
      operationId: get-tm-by-to
      summary: Get taxon importances by to
      description: >
        Retrieve a paginated collection of taxon importances
        associated with the specified taxon observation (using its
        `to_code`).
      parameters:
        - name: to_code
          in: path
          required: true
          schema:
            type: string
          example: "to.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonImportances"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-importances:
    get:
      tags:
        - Taxon importances
      operationId: get-tm
      summary: Get all taxon importances
      description: >
        Retrieve a paginated collection of all taxon importances
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonImportances"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /stem-counts/{sc_code}:
    get:
      tags:
        - Stem counts
      operationId: get-sc-by-id
      summary: Get stem count
      description: >
        Retrieve a single stem count using its `sc_code`.
      parameters:
        - name: sc_code
          in: path
          required: true
          schema:
            type: string
          example: "sc.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StemCounts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/stem-counts:
    get:
      tags:
        - Stem counts
      operationId: get-sc-by-ob
      summary: Get stem counts by ob
      description: >
        Retrieve a paginated collection of stem counts associated with the
        specified plot observation (using its `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StemCounts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-observations/{to_code}/stem-counts:
    get:
      tags:
        - Stem counts
      operationId: get-sc-by-to
      summary: Get stem counts by to
      description: >
        Retrieve a paginated collection of stem counts associated with the
        specified taxon observation (using its `to_code`).
      parameters:
        - name: to_code
          in: path
          required: true
          schema:
            type: string
          example: "to.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StemCounts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-importances/{tm_code}/stem-counts:
    get:
      tags:
        - Stem counts
      operationId: get-sc-by-tm
      summary: Get stem counts by tm
      description: >
        Retrieve a paginated collection of stem counts associated with the
        specified taxon importance (using its `tm_code`).
      parameters:
        - name: tm_code
          in: path
          required: true
          schema:
            type: string
          example: "tm.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StemCounts"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /stem-counts:
    get:
      tags:
        - Stem counts
      operationId: get-sc
      summary: Get all stem counts
      description: >
        Retrieve a paginated collection of all stem counts
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StemCounts"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /strata/{sr_code}:
    get:
      tags:
        - Strata
      operationId: get-sr-by-id
      summary: Get stratum
      description: >
        Retrieve a single stratum using its `sr_code`.
      parameters:
        - name: sr_code
          in: path
          required: true
          schema:
            type: string
          example: "sr.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Strata"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/strata:
    get:
      tags:
        - Strata
      operationId: get-sr-by-ob
      summary: Get strata by ob
      description: >
        Retrieve a paginated collection of strata associated with the
        specified plot observation (using its `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Strata"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-observations/{to_code}/strata:
    get:
      tags:
        - Strata
      operationId: get-sr-by-to
      summary: Get strata by to
      description: >
        Retrieve a paginated collection of strata associated with the
        specified taxon observation (using its `to_code`).
      parameters:
        - name: to_code
          in: path
          required: true
          schema:
            type: string
          example: "to.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Strata"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-importances/{tm_code}/strata:
    get:
      tags:
        - Strata
      operationId: get-sr-by-tm
      summary: Get strata by tm
      description: >
        Retrieve a paginated collection of strata associated with the
        specified taxon importance (using its `tm_code`).
      parameters:
        - name: tm_code
          in: path
          required: true
          schema:
            type: string
          example: "tm.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Strata"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /strata:
    get:
      tags:
        - Strata
      operationId: get-sr
      summary: Get all strata
      description: >
        Retrieve a paginated collection of all strata recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Strata"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /taxon-interpretations/{ti_code}:
    get:
      tags:
        - Taxon interpretations
      operationId: get-ti-by-id
      summary: Get taxon interpretation
      description: >
        Retrieve a single taxon interpretation using its `ti_code`.
      parameters:
        - name: ti_code
          in: path
          required: true
          schema:
            type: string
          example: "ti.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plant-concepts/{pc_code}/taxon-interpretations:
    get:
      tags:
        - Taxon interpretations
      operationId: get-ti-by-pc
      summary: Get taxon interpretations by pc
      description: >
        Retrieve a paginated collection of taxon interpretations
        using the specified plant concept (using its `pc_code`).
      parameters:
        - name: pc_code
          in: path
          required: true
          schema:
            type: string
          example: "pc.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/taxon-interpretations:
    get:
      tags:
        - Taxon interpretations
      operationId: get-ti-by-ob
      summary: Get taxon interpretations by ob
      description: >
        Retrieve a paginated collection of taxon interpretations
        applied to taxa observed in the specified plot observation
        (using its `ob_code`).
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-observations/{to_code}/taxon-interpretations:
    get:
      tags:
        - Taxon interpretations
      operationId: get-ti-by-to
      summary: Get taxon interpretations by to
      description: >
        Retrieve a paginated collection of taxon interpretations
        for the specified taxon observation (using its `to_code`).
      parameters:
        - name: to_code
          in: path
          required: true
          schema:
            type: string
          example: "to.1"
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /taxon-interpretations:
    get:
      tags:
        - Taxon interpretations
      operationId: get-ti
      summary: Get all taxon interpretations
      description: >
        Retrieve a paginated collection of all taxon interpretations
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/detail'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/TaxonInterpretations"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Taxon interpretations
      operationId: upload-ti
      security:
        - oauth2:
            - vegbank:contributor
      summary: Upload taxon interpretations
      parameters:
        - $ref: '#/components/parameters/dry_run'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - taxon_interpretations
              properties:
                taxon_interpretations:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing taxon interpretations of plants
                    observed within existing plot observations (required).
                parties:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new parties (optional).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /cover-methods/{cm_code}:
    get:
      tags:
        - Cover methods
      operationId: get-cm-by-id
      summary: Get cover method
      description: >
        Retrieve a single cover method using its `cm_code`.
      parameters:
        - name: cm_code
          in: path
          required: true
          schema:
            type: string
          example: "cm.1"
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CoverMethods"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /cover-methods:
    get:
      tags:
        - Cover methods
      operationId: get-cm
      summary: Get all cover methods
      description: >
        Retrieve a paginated collection of all cover methods
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/CoverMethods"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Cover methods
      operationId: upload-cm
      security:
        - oauth2:
            - vegbank:admin
      summary: Upload cover methods
      parameters:
        - $ref: '#/components/parameters/dry_run'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - cover_methods
              properties:
                cover_methods:
                  type: string
                  format: binary
                  description: >
                   Parquet file containing cover methods and their associated
                   component cover indexes (required).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /stratum-methods/{sm_code}:
    get:
      tags:
        - Stratum methods
      operationId: get-sm-by-id
      summary: Get stratum method
      description: >
        Retrieve a single stratum method using its `sm_code`.
      parameters:
        - name: sm_code
          in: path
          required: true
          schema:
            type: string
          example: "sm.1"
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StratumMethods"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /stratum-methods:
    get:
      tags:
        - Stratum methods
      operationId: get-sm
      summary: Get all stratum methods
      description: >
        Retrieve a paginated collection of all stratum methods
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/StratumMethods"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - Stratum methods
      operationId: upload-sm
      security:
        - oauth2:
            - vegbank:admin
      summary: Upload stratum methods
      parameters:
        - $ref: '#/components/parameters/dry_run'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - stratum_methods
              properties:
                stratum_methods:
                  type: string
                  format: binary
                  description: >
                   Parquet file containing stratum methods and their associated
                   component stratum types (required).
                references:
                  type: string
                  format: binary
                  description: >
                    Parquet file containing new references (optional).
      responses:
        '200':
          description: >
            Upload accepted. When `dry_run=false` (default), returns an upload summary.
            When `dry_run=true`, the same summary is nested under `dry_run_data` and
            the data is not actually inserted into VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /parties/{py_code}:
    get:
      tags:
        - Parties
      operationId: get-py-by-id
      summary: Get party
      description: >
        Retrieve a single party using its `py_code`.
      parameters:
        - name: py_code
          in: path
          required: true
          schema:
            type: string
          example: "py.1"
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Parties"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /plot-observations/{ob_code}/parties:
    get:
      tags:
        - Parties
      operationId: get-py-by-ob
      summary: Get parties by ob
      description: >
        Retrieve a paginated and sorted collection of parties associated
        with the specified plot observation (using its `ob_code`), or a
        subset thereof based on a specified `search` query.
      parameters:
        - name: ob_code
          in: path
          required: true
          schema:
            type: string
          example: "ob.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/sort_py'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Parties"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /community-classifications/{cl_code}/parties:
    get:
      tags:
        - Parties
      operationId: get-py-by-cl
      summary: Get parties by cl
      description: >
        Retrieve a paginated and sorted collection of parties associated
        with the specified community classification (using its
        `cl_code`), or a subset thereof based on a specified `search`
        query.
      parameters:
        - name: cl_code
          in: path
          required: true
          schema:
            type: string
          example: "cl.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/sort_py'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Parties"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /projects/{pj_code}/parties:
    get:
      tags:
        - Parties
      operationId: get-py-by-pj
      summary: Get parties by pj
      description: >
        Retrieve a paginated and sorted collection of parties associated
        with the specified project (using its `pj_code`), or a subset
        thereof based on a specified `search` query.
      parameters:
        - name: pj_code
          in: path
          required: true
          schema:
            type: string
          example: "pj.1"
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/sort_py'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Parties"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /parties:
    get:
      tags:
        - Parties
      operationId: get-py
      summary: Get all parties
      description: >
        Retrieve a paginated collection of all parties
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/sort_py'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Parties"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /roles/{ar_code}:
    get:
      tags:
        - Parties
      operationId: get-ar-by-id
      summary: Get role
      description: >
        Retrieve a single role using its `ar_code`.
      parameters:
        - name: ar_code
          in: path
          required: true
          schema:
            type: string
          example: "ar.1"
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Roles"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /roles:
    get:
      tags:
        - Parties
      operationId: get-ar
      summary: Get all roles
      description: >
        Retrieve a paginated collection of all roles
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Roles"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /projects/{pj_code}:
    get:
      tags:
        - Projects
      operationId: get-pj-by-id
      summary: Get project
      description: >
        Retrieve a single project using its `pj_code`.
      parameters:
        - name: pj_code
          in: path
          required: true
          schema:
            type: string
          example: "pj.1"
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Projects"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /projects:
    get:
      tags:
        - Projects
      operationId: get-pj
      summary: Get all projects
      description: >
        Retrieve a paginated collection of all projects
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/sort_pj'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/Projects"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /references/{rf_code}:
    get:
      tags:
        - References
      operationId: get-rf-by-id
      summary: Get reference
      description: >
        Retrieve a single reference using its `rf_code`.
      parameters:
        - name: rf_code
          in: path
          required: true
          schema:
            type: string
          example: "rf.1"
        - $ref: '#/components/parameters/with_nested'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/References"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /references:
    get:
      tags:
        - References
      operationId: get-rf
      summary: Get all references
      description: >
        Retrieve a paginated collection of all references
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/References"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /named-places/{np_code}:
    get:
      tags:
        - Named Places
      operationId: get-np-by-id
      summary: Get named place
      description: >
        Retrieve a single named place using its `np_code`.
      parameters:
        - name: np_code
          in: path
          required: true
          schema:
            type: string
          example: "np.1"
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/NamedPlaces"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /named-places:
    get:
      tags:
        - Named Places
      operationId: get-np
      summary: Get all named places
      description: >
        Retrieve a paginated collection of all named places
        recorded in VegBank.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/NamedPlaces"
        '400':
          $ref: "#/components/responses/InvalidParameters"

  /user-datasets/{ds_code}:
    get:
      tags:
        - User Datasets
      operationId: get-ds-by-id
      summary: Get a user-defined dataset entry
      description: >
        Retrieve the catalog entry for a single public user-defined dataset
        using its `ds_code`.
      parameters:
        - name: ds_code
          in: path
          required: true
          schema:
            type: string
          example: "ds.1"
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/UserDatasets"
        '400':
          $ref: "#/components/responses/InvalidParameters"
  /user-datasets:
    get:
      tags:
        - User Datasets
      operationId: get-ds
      summary: Get all user-defined datasets entries
      description: >
        Retrieve a paginated catalog of all public user-defined datasets
        registered in VegBank.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/create_parquet'
      responses:
        '200':
          $ref: "#/components/responses/UserDatasets"
        '400':
          $ref: "#/components/responses/InvalidParameters"
    post:
      tags:
        - User Datasets
      operationId: upload-ds
      security:
        - oauth2:
            - vegbank:admin
      summary: Create a user dataset
      parameters:
        - $ref: '#/components/parameters/dry_run'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - data
              properties:
                name:
                  type: string
                  description: Display name for the dataset.
                  example: "Test Dataset 001"
                description:
                  type: string
                  description: Optional human-readable description of the dataset.
                  example: "A test dataset containing 3 observations."
                data:
                  type: object
                  required:
                    - observation
                  properties:
                    observation:
                      type: array
                      items:
                        type: string
                      description: VegBank observation codes to include in the dataset.
                      example:
                        - "ob.2948"
                        - "ob.2949"
                        - "ob.2950"
      responses:
        '200':
          description: >
            Successful dataset creation. When `dry_run=false` (default), returns
            a summary of what was inserted. When `dry_run=true`, the same
            summary is nested under `dry_run_data` and the dataset is not actually
            created in VegBank.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        '403':
          $ref: "#/components/responses/UploadsNotAllowed"
        '500':
          $ref: "#/components/responses/InvalidDataUpload"

  /overview:
    get:
      tags:
        - Overview
      operationId: get-overview
      summary: Get basic VegBank database stats
      description: >
        Retrieve an assortment of count statistics indicating what's in
        VegBank.
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 0
            default: 5
          description: Maximum number of records to return in Top N counts
      responses:
        '200':
          description: Overview statistics successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  core_counts:
                    type: array
                    description: Database-wide count metrics
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Name of the metric being counted"
                          example: "observations"
                        count:
                          type: integer
                          description: "Total count for this metric"
                          example: 115246
                  latest_n_projects:
                    type: array
                    description: Most recent N projects by plot upload date
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Name of the project"
                          example: "California Vegetation Survey"
                        pj_code:
                          type: string
                          description: "VegBank project identifier"
                          example: "pj.1"
                        last_date_added:
                          type: string
                          format: date
                          description: "Most recent plot observation upload date"
                          example: "2026-03-30"
                        count:
                          type: integer
                          description: "Count of observations in this project"
                          example: 3400
                  top_n_community_concepts:
                    type: array
                    description: Top N community concepts by observation count
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Name of the community concept"
                          example: "California Annual Grassland"
                        cc_code:
                          type: string
                          description: "VegBank community concept identifier"
                          example: "cc.1"
                        count:
                          type: integer
                          description: "Count of observations of this community"
                          example: 670
                  top_n_plant_concepts:
                    type: array
                    description: Top N plant concepts by observation count
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Plant concept name"
                          example: "Quercus agrifolia"
                        pc_code:
                          type: string
                          description: "VegBank plant concept identifier"
                          example: "pc.1"
                        count:
                          type: integer
                          description: "Count of observations containing this plant"
                          example: 890
                  top_n_projects:
                    type: array
                    description: Top N projects by observation count
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Name of the project"
                          example: "California Vegetation Survey"
                        pj_code:
                          type: string
                          description: "VegBank project identifier"
                          example: "pj.1"
                        count:
                          type: integer
                          description: "Count of observations in this project"
                          example: 3400
                  top_n_contributors:
                    type: array
                    description: Top N contributors by observation count
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Name of the contributing party"
                          example: "John Smith"
                        py_code:
                          type: string
                          description: "VegBank party identifier"
                          example: "py.1"
                        count:
                          type: integer
                          description: "Count of observations by this contributor"
                          example: 1250
                  top_n_named_places:
                    type: array
                    description: Top N named places by observation count
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Name of the geographic place"
                          example: "California"
                        np_code:
                          type: string
                          description: "VegBank named place identifier"
                          example: "np.1"
                        count:
                          type: integer
                          description: "Count of observations in this place"
                          example: 5432
        '400':
          $ref: "#/components/responses/InvalidParameters"

components:
  parameters:
    search:
      name: search
      in: query
      required: false
      schema:
        type: string
      description: Search term used for full-text record retrieval
    detail:
      name: detail
      in: query
      required: false
      schema:
        type: string
        enum: [minimal, full]
        default: full
      description: |
        Level of detail for the response:
        - `minimal`: Returns basic fields only
        - `full`: Returns more fields
    detail_ob:
      name: detail
      in: query
      required: false
      schema:
        type: string
        enum: [geo, minimal, full]
        default: full
      description: |
        Level of detail for the response:
        - `geo`: Returns core location fields only
        - `minimal`: Returns basic fields only
        - `full`: Returns more fields
    with_nested:
      name: with_nested
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to include nested fields in the response
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Number of records to skip before starting to return records
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 1000
      description: Maximum number of records to return
    create_parquet:
      name: create_parquet
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: If true, return data payload in binary Parquet format
    bundle:
      name: bundle
      in: query
      required: false
      schema:
        type: string
      description: |
        If 'csv', return a zip archive of CSVs. When set, the `limit` parameter
        will default to 20000 (and higher values will be ignored), the `detail`
        parameter will be set to 'full', and the `with_nested` parameter will be
        set to `false`.
    sort_ob:
      name: sort
      in: query
      required: false
      description: |
        Sort order for results. Prefix with `-` for descending order or `+` for
        ascending order. Ascending order is the default if no prefix is provided.

        Available sort fields:
        - `default` - Default sort order
        - `author_obs_code` - Sort by the author-provided plot observation code

        Examples:
        - `sort=author_obs_code` - Sort by observation code ascending
        - `sort=-author_obs_code` - Sort by observation code descending
      schema:
        type: string
        enum:
          - default
          - +default
          - -default
          - author_obs_code
          - +author_obs_code
          - -author_obs_code
        default: default
      example: -author_obs_code
    sort_cc:
      name: sort
      in: query
      required: false
      description: |
        Sort order for results. Prefix with `-` for descending order or `+` for ascending order.
        Ascending order is the default if no prefix is provided.

        Available sort fields:
        - `default` - Default sort order
        - `comm_name` - Sort by community name
        - `obs_count` - Sort by observation count

        Examples:
        - `sort=comm_name` - Sort by community name ascending
        - `sort=-obs_count` - Sort by observation count descending
        - `sort=+comm_name` - Sort by community name ascending (explicit)
      schema:
        type: string
        enum:
          - default
          - +default
          - -default
          - comm_name
          - +comm_name
          - -comm_name
          - obs_count
          - +obs_count
          - -obs_count
        default: default
      example: -obs_count
    sort_pc:
      name: sort
      in: query
      required: false
      description: |
        Sort order for results. Prefix with `-` for descending order or `+` for ascending order.
        Ascending order is the default if no prefix is provided.

        Available sort fields:
        - `default` - Default sort order
        - `plant_name` - Sort by plant name
        - `obs_count` - Sort by observation count

        Examples:
        - `sort=plant_name` - Sort by plant name ascending
        - `sort=-obs_count` - Sort by observation count descending
        - `sort=+plant_name` - Sort by plant name ascending (explicit)
      schema:
        type: string
        enum:
          - default
          - +default
          - -default
          - plant_name
          - +plant_name
          - -plant_name
          - obs_count
          - +obs_count
          - -obs_count
        default: default
      example: -obs_count
    sort_py:
      name: sort
      in: query
      required: false
      description: |
        Sort order for results. Prefix with `-` for descending order or `+` for ascending order.
        Ascending order is the default if no prefix is provided.

        Available sort fields:
        - `default` - Default sort order
        - `surname` - Sort by surname
        - `organization_name` - Sort by organization name
        - `obs_count` - Sort by observation count

        Examples:
        - `sort=surname` - Sort by surname ascending
        - `sort=-obs_count` - Sort by observation count descending
        - `sort=+organization_name` - Sort by organization name ascending (explicit)
      schema:
        type: string
        enum:
          - default
          - +default
          - -default
          - surname
          - +surname
          - -surname
          - organization_name
          - +organization_name
          - -organization_name
          - obs_count
          - +obs_count
          - -obs_count
        default: default
      example: -obs_count
    sort_pj:
      name: sort
      in: query
      required: false
      description: |
        Sort order for results. Prefix with `-` for descending order or `+` for ascending order.
        Ascending order is the default if no prefix is provided.

        Available sort fields:
        - `default` - Default sort order
        - `project_name` - Sort by project name
        - `obs_count` - Sort by observation count

        Examples:
        - `sort=project_name` - Sort by project name ascending
        - `sort=-obs_count` - Sort by observation count descending
        - `sort=+project_name` - Sort by project name ascending (explicit)
      schema:
        type: string
        enum:
          - default
          - +default
          - -default
          - project_name
          - +project_name
          - -project_name
          - obs_count
          - +obs_count
          - -obs_count
        default: default
      example: -obs_count
    num_taxa_ob:
      name: num_taxa
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 5
      description: |
        Number of taxa to return per plot observation. Sort order depends on detail level:
        - With `detail=minimal`: Descending order by max cover
        - With `detail=full`: Alphabetical order by plant name
    num_comms_ob:
      name: num_comms
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 5
      description: Number of communities to return per plot observation, ordered by commclass_id
    status_ob:
      name: status
      in: query
      required: false
      schema:
        type: string
        enum: [any, current]
        default: any
      description: |
        Status criterion for returned plot observations:
        - `any`: Returns matching plot observations regardless of status
        - `current`: Only returns observations that haven't been replaced by a newer observation
    status_concept:
      name: status
      in: query
      required: false
      schema:
        type: string
        enum: [any, current, accepted, current_accepted]
        default: any
      description: |
        Status criterion for returned plant concepts and their children:
        - `any`: Returns matching concepts regardless of status
        - `current`: Only returns concepts that don't have (past) status stop dates
        - `accepted`: Only returns concepts that have an accepted status
        - `current_accepted`: Only returns concepts that are both current and accepted
    dry_run:
      name: dry_run
      in: query
      required: false
      schema:
       type: boolean
       default: false
      description: >
       If true, validates and previews the upload without persisting any data.
       The response will be wrapped in a `dry_run_data` envelope.

  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.vegbank.org/login
          tokenUrl: https://api.vegbank.org/login
          scopes:
            vegbank:admin: Administrator access with full permissions
            vegbank:contributor: Contributor access to create and update plot observations
            vegbank:user: User access for uploading user-defined datasets

  responses:

    InvalidParameters:
      description: Invalid Parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InvalidParameters"

    UploadsNotAllowed:
      description: Uploads not allowed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UploadsNotAllowed"

    InvalidDataUpload:
      description: Invalid data upload
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InvalidDataUpload"

    PlotObservations:
      description: |
        Matching plot observation(s), with fields based on parameters:
        - `detail=geo`: Name, identifier, and lat/lon fields only
        - `detail=minimal&with_nested=false`: Basic fields only
        - `detail=minimal&with_nested=true`: Basic fields + nested array fields
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
        - `bundle=csv`: ZIP archive containing related CSV files
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/plot_obs_geo'
              - $ref: '#/components/schemas/plot_obs_minimal'
              - $ref: '#/components/schemas/plot_obs_minimal_nested'
              - $ref: '#/components/schemas/plot_obs_full'
              - $ref: '#/components/schemas/plot_obs_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.
        application/zip:
          schema:
            type: string
            format: binary
            description: |
              ZIP archive containing multiple related CSV files plus README.txt.
              Returned when `bundle=csv` parameter is specified.

              CSV files conform to the schemas of their respective API endpoints with
              `detail=full&with_nested=false` applied. The archive typically includes:
              - plot_observations.csv: Plot observations matching the request
              - taxon_observations.csv: Plants observed on the plots
              - strata.csv: Strata defined for the plot observations
              - taxon_importances.csv: Importance data for observed plants, by strata
              - stem_counts.csv: Stem counts of observed plants, by size group and strata
              - taxon_intepretations.csv: Taxonomic interpretations of observed plants
              - plant_concepts.csv: Plant concepts associated with the observations
              - community_classifications.csv: Community classifications of the observed plots
              - community_concepts.csv: Community types associated with the observed plots
              - projects.csv: Projects associated with the plot observations
              - parties.csv: Contributing parties (people and organizations)
              - README.txt: Metadata, file descriptions, and citation

              Files are linked via `ob_code` and other identifier code columns.

    CommunityConcepts:
      description: |
        Matching community concept(s), with fields based on parameters:
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/comm_concept_full'
              - $ref: '#/components/schemas/comm_concept_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    CommunityClassifications:
      description: |
        Matching community classification(s), with fields based on parameters:
        - `detail=minimal&with_nested=false`: Basic fields only
        - `detail=minimal&with_nested=true`: Basic fields + nested array fields
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/comm_class_minimal'
              - $ref: '#/components/schemas/comm_class_minimal_nested'
              - $ref: '#/components/schemas/comm_class_full'
              - $ref: '#/components/schemas/comm_class_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    CommunityInterpretations:
      description: |
        Matching community interpretation(s), with fields based on parameters:
        - `detail=minimal&with_nested=false`: Basic fields only
        - `detail=minimal&with_nested=true`: Basic fields + nested array fields
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/comm_interp_minimal'
              - $ref: '#/components/schemas/comm_interp_minimal_nested'
              - $ref: '#/components/schemas/comm_interp_full'
              - $ref: '#/components/schemas/comm_interp_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    PlantConcepts:
      description: |
        Matching plant concept(s), with fields based on parameters:
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/plant_concept_full'
              - $ref: '#/components/schemas/plant_concept_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    TaxonObservations:
      description: |
        Matching taxon observation(s), with fields based on parameters:
        - `detail=minimal&with_nested=false`: Basic fields only
        - `detail=minimal&with_nested=true`: Basic fields + nested array fields
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/taxon_obs_minimal'
              - $ref: '#/components/schemas/taxon_obs_minimal_nested'
              - $ref: '#/components/schemas/taxon_obs_full'
              - $ref: '#/components/schemas/taxon_obs_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    TaxonImportances:
      description: |
        Matching taxon importances(s), with fields based on parameters:
        - `detail=minimal&with_nested=false`: Basic fields only
        - `detail=minimal&with_nested=true`: Basic fields + nested array fields
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/taxon_imp_minimal'
              - $ref: '#/components/schemas/taxon_imp_minimal_nested'
              - $ref: '#/components/schemas/taxon_imp_full'
              - $ref: '#/components/schemas/taxon_imp_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    StemCounts:
      description: |
        Matching stem count(s), with fields based on parameters:
        - `detail=minimal`: Basic fields only
        - `detail=full`: Extended fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/stem_count_minimal'
              - $ref: '#/components/schemas/stem_count_full'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    Strata:
      description: |
        Matching stratum or strata, with fields based on parameters:
        - `detail=minimal`: Basic fields only
        - `detail=full`: Extended fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/stem_count_minimal'
              - $ref: '#/components/schemas/stem_count_full'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    TaxonInterpretations:
      description: |
        Matching taxon interpretation(s), with fields based on parameters:
        - `detail=minimal`: Basic fields only
        - `detail=full`: Extended fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/taxon_interp_minimal'
              - $ref: '#/components/schemas/taxon_interp_full'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    CoverMethods:
      description: |
        Matching cover method(s), with fields based on parameters:
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/cover_method_full'
              - $ref: '#/components/schemas/cover_method_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    StratumMethods:
      description: |
        Matching stratum method(s), with fields based on parameters:
        - `detail=full&with_nested=false`: Extended fields, no nested array fields
        - `detail=full&with_nested=true`: Extended fields + nested array fields
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/stratum_method_full'
              - $ref: '#/components/schemas/stratum_method_full_nested'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    Parties:
      description: Matching party or parties
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/party'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    Roles:
      description: Matching role or roles
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/role'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    Projects:
      description: Matching project(s)
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/project'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    References:
      description: Matching reference(s)
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/reference'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    NamedPlaces:
      description: Matching named place(s)
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/named_place'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

    UserDatasets:
      description: Matching user-defined dataset(s)
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/user_dataset'
        application/vnd.apache.parquet:
          schema:
            type: string
            format: binary
            description: Parquet file with same data as the JSON response.

  schemas:

    InvalidParameters:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: "Invalid vb code 'xx.1'."

    UploadsNotAllowed:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: "Uploads not allowed."

    InvalidDataUpload:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: "An error occurred during upload: The following columns are not supported for stem data: foo."

    PlotObservationBase:
      type: object
      properties:
        ob_code:
          type: string
          description: "VegBank observation identifier"
          example: "ob.1"
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the plot observation. When a plot has only one observation, this will often equal author_plot_code."
          example: "YOSE.001"
        latitude:
          type: number
          format: float
          description: "Latitude of the plot origin in degrees and decimals (datum WGS84), fuzzing applied"
          example: 42.19
        longitude:
          type: number
          format: float
          description: "Longitude of the plot origin in degrees and decimals (datum WGS84), fuzzing applied"
          example: -104.54

    PlotObservationMinimal:
      type: object
      properties:
        area:
          type: number
          format: float
          description: "Total area of the plot in m2. If many subplots, this area includes the subplots and the interstitial space. RESERVED VALUE: -1 is used to indicate that the plot had no boundaries."
          example: 100
        author_plot_code:
          type: string
          description: "Author's plot number/code, or the original plot number if taken from literature."
          example: "YOSE.001"
        country:
          type: string
          description: "The name of a country in which a plot is located"
          example: "United States"
        elevation:
          type: number
          format: float
          description: "The elevation of the plot origin in meters above sea level."
          example: 380
        pl_code:
          type: string
          description: "VegBank plot identifier"
          example: "pl.1"
        state_province:
          type: string
          description: "The name of a state or province in which a plot is located"
          example: "California"
        year:
          type: integer
          description: "The year of the observation, or of the first day of the observation if it spanned more than one day."
          example: 1997

    PlotObservationMinimalNested:
      type: object
      properties:
        taxon_count:
          type: integer
          description: "Count of taxon observations associated with this plot observation"
          example: 32
        taxon_count_returned:
          type: integer
          description: "Count of taxon observations returned in the top_taxon_observations field"
          example: 5
        top_taxon_observations:
          type: array
          items:
            type: object
            properties:
              to_code:
                type: string
                description: "VegBank taxon observation identifier"
                example: "to.1"
              pc_code:
                type: string
                description: "VegBank plant concept identifier"
                example: "pc.1"
              name:
                type: string
                description: "Name of the observed plant, using the scientific name (without authors) associated with the current taxon interpretation if available, otherwise the author-provided plant name"
                example: "Acer rubrum"
              max_cover:
                type: number
                format: float
                description: "Maximum observed cover for this taxon over all recorded strata"
                example: 0.7
          description: "Taxon observations"
        top_classifications:
          type: array
          items:
            type: object
            properties:
              cl_code:
                type: string
                description: "VegBank community classification identifier"
                example: "cl.1"
              ci_code:
                type: string
                description: "VegBank community interpretation identifier"
                example: "ci.1"
              cc_code:
                type: string
                description: "VegBank community concept identifier"
                example: "cc.1"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Fagus grandifolia - Quercus spp. / Kalmia latifolia - Hamamelis virginiana / Galax urceolata Forest"
              comm_code:
                type: string
                description: "Code for the community concept, derived from a comm usage record of class system 'Code'"
                example: "CEGL004549"
          description: "Community classifications"

    PlotObservationFull:
      type: object
      properties:
        rf_code:
          type: string
          description: "VegBank reference identifier"
          example: "rf.1"
        rf_label:
          type: string
          description: "Label for the observation reference"
          example: "Peet Dissertation (1975)"
        parent_pl_code:
          type: string
          description: "VegBack identifier of the parent plot when a plot is nested within another plot."
          example: "pl.1"
        location_accuracy:
          type: number
          format: float
          description: "Estimated accuracy of the location of the plot. Plot origin has a 95% or greater probability of being within this many meters of the reported location."
          example: 50.0
        confidentiality_status:
          type: integer
          description: "Are the data to be considered confidential? 0=no, 1= 1km radius, 2=10km radius, 3=100km radius, 4=location embargo, 5=public embargo on all plot data, 6=full embargo on all plot data. This applies also to region."
          example: 0
        author_e:
          type: string
          description: "Original E-W coordinate as recorded by the author"
          example: "778426"
        author_n:
          type: string
          description: "Original N-S coordinate as recorded by the author"
          example: "447670"
        author_zone:
          type: string
          description: "Original UTM zone reported by the author"
          example: "11"
        author_datum:
          type: string
          description: "Original datum reported by the author"
          example: "NAD83"
        author_location:
          type: string
          description: "Original location as described by author (e.g. Town-Range-Section)"
          example: "Island Creek"
        location_narrative:
          type: string
          description: "Text description that provides information useful for plot relocation."
          example: "1.5 mi w of Payne Lake"
        azimuth:
          type: number
          format: float
          description: "This element stores the azimuth of the x-axis used to describe the relative coordinate system for plot shape (dsgpoly) and other spatial information about the plot. Typically the azimuth is parallel to the long axis of the plot (in the case of a rectangle)."
          example: 354
        dsgpoly:
          type: string
          description: "This field is a text string containing the points circumscribing a plot area. These points are anticipated to have been collected using tapes, GPS, or calculated from the plot shape and area. Points are X-Y coordinates in m relative to plot origin."
          example: "(0,0)(50,0)(50,1)(0,1)(0,0)"
        shape:
          type: string
          description: "Shape of the plot area."
          example: "Rectangular"
        stand_size:
          type: string
          description: "The extent of this community occurrence in relation to the plot size: very extensive (>1000x plot), extensive (>100x plot), large (10-100x plot), small (3-10x plot), very small (1-3x plot)."
          example: "large"
        placement_method:
          type: string
          description: "Brief description of strategy for determining plot placement within the stand."
          example: "Representative"
        permanence:
          type: boolean
          description: "Is the plot monumented so as to assure permanence? If so, this should be described in the layoutNarrative"
          example: false
        layout_narrative:
          type: string
          description: "Text description of and the rationale for the layout of the plot."
          example: "10 m x 10 m"
        elevation_accuracy:
          type: number
          format: float
          description: "The accuracy of the elevation in meters."
          example: 10
        elevation_range:
          type: number
          format: float
          description: "Meters of difference in elevations of the high and low points in the plot."
          example: 0.61
        slope_aspect:
          type: number
          format: float
          description: "Representative azimuth of slope gradient (0-360 degrees); if too flat to determine = -1; if too irregular to determine = -2."
          example: 270
        min_slope_aspect:
          type: number
          format: float
          description: "Minimum azimuth of slope gradient (0-360 degrees), counterclockwise from representative azimuth."
          example: 0
        max_slope_aspect:
          type: number
          format: float
          description: "Maximum azimuth of slope gradient (0-360 degrees), clockwise from representative azimuth"
          example: 359
        slope_gradient:
          type: number
          format: float
          description: "Representative inclination of slope in degrees; if too irregular to determine, = -1."
          example: 0
        min_slope_gradient:
          type: number
          format: float
          description: "Minimum inclination of slope in degrees."
          example: 25
        max_slope_gradient:
          type: number
          format: float
          description: "Maximum inclination of slope in degrees."
          example: 89
        topo_position:
          type: string
          description: "Position of the plot on land surface (e.g., Summit, shoulder, upper slope, middle slope, lower slope, toeslope, no slope, channel bed, dune swale, pond)."
          example: "Midslope"
        landform:
          type: string
          description: "A recognizable physical feature on the surface of the earth, often including consideration of the natural cause of its formation."
          example: "valley floor"
        surficial_deposits:
          type: string
          description: "Surficial deposits represent the parent material that are the geologic or organic precursors to the soil. They may either have been deposited by geologic (wind, ice, gravity or water) or biologic (organic) activity, or formed in place more-or-less directly from rocks and minerals below."
          example: "alluvium"
        rock_type:
          type: string
          description: "RockType values conform to the lithic types in the FGDC Soil Geographic Data Standards, September 1997. http://www.fgdc.gov/standards/documents/standards/soils/soil997.PDF (pages 56-59)."
          example: "sandstone"
        previous_obs_id:
          type: string
          description: "VegBank observation identifier corresponding to the previous observation of this plot."
          example: "ob.1"
        pj_code:
          type: string
          description: "VegBank project identifier"
          example: "pj.1"
        project_name:
          type: string
          description: "Project name"
          example: "Southwest GAP, Nevada"
        obs_start_date:
          type: string
          format: date
          description: "The date of the observation, or the first day if the observation spanned more than one day."
          example: "2006-05-30"
        obs_end_date:
          type: string
          format: date
          description: "If the observation event spanned more than a single day, this is the last day on which observations were made."
          example: "2006-05-30"
        date_accuracy:
          type: string
          description: "Estimated accuracy of the observation date."
          example: "exact"
        date_entered:
          type: string
          format: date
          description: "Date that the observation was added to VegBank"
          example: "2006-05-30"
        cm_code:
          type: string
          description: "VegBank cover method code referring to the scale used to estimate taxon cover. The database stores estimated cover to the nearest percent, but the conversion details are recovered by reference to the specific scale employed."
          example: "cm.1"
        cover_method_name:
          type: string
          description: "Cover method name"
          example: "Percentage (%)"
        cover_dispersion:
          type: string
          description: "Were cover values for the total taxon list collected from one contiguous area or dispersed subplots?"
          example: "subplot-contiguous"
        auto_taxon_cover:
          type: boolean
          description: "True indicates that cover value of taxon observations was automatically calculated from the values of stratum_cover in linked strata records"
          example: False
        method_narrative:
          type: string
          description: "Additional metadata helpful for understanding how the data were collected during the observation event."
          example: "Selected to be representative of area vegetation."
        taxon_observation_area:
          type: number
          format: float
          description: "the total surface area (in m^2) used for cover estimates and for which a complete species list is provided. If subplots were used, this would be the total area of the subplots without interstitial space. RESERVED VALUE: -1 is used to indicate the complete list of species had no known boundaries."
          example: 400
        stem_size_limit:
          type: number
          format: float
          description: "Lower diameter limit in centimeters for inclusion of a tree in the stem count"
          example: 10
        stem_observation_area:
          type: number
          format: float
          description: "the total surface area (in m^2) observed for recording woody stem data. RESERVED VALUE: -1 means no known area."
          example: 400
        stem_sample_method:
          type: string
          description: "The method used to obtain basal area or tree stem data (e.g., full census, point quarter, random pairs, Bitterlich, other)."
          example: "Full census"
        original_data:
          type: string
          description: "Location where the hard data reside and any access instructions."
          example: "California Dept of Fish and Wildlife"
        effort_level:
          type: string
          description: "This is the effort spent making the observations as estimated by the party that submitted the data (e.g., Very thorough, Average, Hurried description)."
          example: "Thorough"
        plot_validation_level:
          type: integer
          description: "Quality of plot as determined by an automated filter system, including values such as (1) sufficient for determining type occurrence, (2) sufficient for inclusion in a classification revision, and (3) fully compliant with recommendations."
          example: 1
        floristic_quality:
          type: string
          description: "Subjective assessment of floristic quality by the party that submitted the plot (e.g., Highest, High, High but incomplete, Moderate, Moderate and incomplete, Low)."
          example: "High"
        bryophyte_quality:
          type: string
          description: "Subjective assessment of the taxonomic quality of the bryophyte data by the party that submitted the plot (e.g., Highest, High, High but incomplete, Moderate, Moderate and incomplete, Low, Very incomplete, absent)."
          example: "Very incomplete"
        lichen_quality:
          type: string
          description: "Subjective assessment of the taxonomic quality of the lichen data by the party that submitted the plot (e.g., Highest, High, High but incomplete, Moderate, Moderate and incomplete, Low, Very incomplete, absent)."
          example: "Not examined"
        observation_narrative:
          type: string
          description: "Additional unstructured observations useful for understanding the ecological attributes and significance of the plot observations."
          example: "stand size: 5X5 ha"
        landscape_narrative:
          type: string
          description: "Unstructured observations on the landscape context of the observed plot."
          example: "Wetland"
        homogeneity:
          type: string
          description: "How homogeneous was the community (e.g., homogeneous, compositional trend across plot, conspicuous inclusions, irregular mosaic or pattern)."
          example: "irregular or pattern mosaic"
        phenologic_aspect:
          type: string
          description: "Season expression of the community (e.g., typical growing season, vernal, aestival, wet, autumnal, winter, dry, irregular ephemerals present)."
          example: "typical growing season"
        representativeness:
          type: string
          description: "How representative was the plot of the stand?"
          example: "Very good."
        stand_maturity:
          type: string
          description: "How mature is the stand. Could be young, mature but even-aged, old-growth, etc."
          example: "Mature, even-age"
        successional_status:
          type: string
          description: "Description of the assumed successional status of the plot. This description is of necessity highly subjective."
          example: "mature"
        basal_area:
          type: number
          format: float
          description: "Total basal area of woody stems (in m²/ha). 0 should be used to indicate that plots have no stems."
          example: 4.54009
        hydrologic_regime:
          type: string
          description: "What is the hydrologic regime, which is a reflection of frequency and duration of flooding? List is taken from Cowardin et al. 1979, 1985."
          example: "temporarily flooded"
        soil_moisture_regime:
          type: string
          description: "How moist was the soil at the sampling event?"
          example: "mesic"
        soil_drainage:
          type: string
          description: "Identifies the natural drainage conditions of the soil and refers to the frequency and duration of wet periods. The soil drainage classes are defined in terms of (1) actual moisture content (in excess of field moisture capacity) and (2) the extent of the period during which excess water is present in the plant-root zone. Soil drainage class categories conform to the FGDC Soil Geographic Data Standards, September 1997. (http://www.fgdc.gov/standards/documents/standards/soils/soil997.PDF.) Definitions are derived from Grossman et al. (1998) and Sims et al. (1997)."
          example: "moderately well drained"
        water_salinity:
          type: string
          description: "How saline is the water, if a flooded community?"
          example: "Freshwater"
        water_depth:
          type: number
          format: float
          description: "For aquatic or marine vegetation, what was the water depth in m."
          example: 0.3
        shore_distance:
          type: number
          format: float
          description: "For aquatic or marine vegetation, what was the closest distance to shore in m."
          example: 10
        soil_depth:
          type: number
          format: float
          description: "Median depth to bedrock or permafrost in m (usually from averaging multiple probe readings)."
          example: 0.1
        organic_depth:
          type: number
          format: float
          description: "Depth of the surficial organic layer, where present, in centimeters."
          example: 6
        st_code:
          type: string
          description: "VegBank soil taxon identifier referencing a table of soil taxa within the USDA classification hierarchy, including Order, Suborder, Greatgroup, Subgroup, Family and Series."
          example: "st.1"
        soil_taxon_src:
          type: string
          description: "How was the soil taxon determined (e.g., field observation, map, other sources)?"
          example: "USDA county soil survey"
        percent_bed_rock:
          type: number
          format: float
          description: "Percent of surface that is exposed bedrock."
          example: 5
        percent_rock_gravel:
          type: number
          format: float
          description: "Percent of surface that is exposed rock and gravel."
          example: 5
        percent_wood:
          type: number
          format: float
          description: "Percent of surface that is wood."
          example: 5
        percent_litter:
          type: number
          format: float
          description: "Percent of surface that is litter."
          example: 5
        percent_bare_soil:
          type: number
          format: float
          description: "Percent of surface that is bare soil."
          example: 5
        percent_water:
          type: number
          format: float
          description: "Percent of surface that is water."
          example: 5
        percent_other:
          type: number
          format: float
          description: "Percent of surface that belong to an additional itemized category"
          example: 5
        name_other:
          type: string
          description: "Name of additional itemized ground cover category (e.g., beer cans)."
          example: "bryophytes and lichens"
        tree_ht:
          type: number
          format: float
          description: "Height of the tree layer in m."
          example: 30
        shrub_ht:
          type: number
          format: float
          description: "Height of the shrub layer in m."
          example: 1.5
        field_ht:
          type: number
          format: float
          description: "Height of the field layer in m."
          example: 0.25
        nonvascular_ht:
          type: number
          format: float
          description: "Height of the nonvascular layer in m."
          example: 1
        submerged_ht:
          type: number
          format: float
          description: "Height of the submerged layer in m."
          example: 0
        tree_cover:
          type: number
          format: float
          description: "Total cover of the tree layer in percent. Includes tall trees (single-stemmed woody plants, generally more than 5 m in height or greater at maturity under optimal growing conditions). Very tall shrubs with tree-like form may also be included here, as may other life forms, such as lianas and epiphytes."
          example: 50
        shrub_cover:
          type: number
          format: float
          description: "Total cover of the shrub layer in percent. Includes shrubs (multiple-stemmed woody plants, generally less than 5 m in height at maturity under optimal growing conditions) and shorter trees (saplings). As with the tree stratum, other life forms present in this stratum may also be included (however, herbaceous life forms should be excluded, as their stems often die back annually and do not have as consistent a height as woody life forms). Where dwarf-shrubs (i.e. shrubs shorter than 0.5 m) form a distinct stratum (either as part of a series of strata, as in a forest, or as the top stratum of more open vegetation, such as tundra or xeric shrublands), they should be treated as a low version of the shrub stratum (or short shrub substratum). In many vegetation types, dwarf-shrubs may simply occur as one life form component of the herb stratum."
          example: 30
        field_cover:
          type: number
          format: float
          description: "Total cover of the field layer in percent. Also referred to as Herb stratum. Includes herbs (plants without woody stems and often dying back annually), often in association with low creeping semi-shrubs, dwarf-shrubs, vines, and non-woody brambles (such as raspberries), as well as tree or shrub seedlings."
          example: 10
        nonvascular_cover:
          type: number
          format: float
          description: "Total cover of the nonvascular layer in percent. Also referred to as moss, bryoid, or ground stratum. Defined entirely by mosses, lichens, liverworts, and alga. Ground-creeping vines, prostrate shrubs and herbs should be treated in the herb stratum. Where herbs are entirely absent, it is still possible to recognize this stratum if other very low woody or semi-woody life forms are present."
          example: 5
        floating_cover:
          type: number
          format: float
          description: "Total cover of the floating layer in percent. Includes rooted or drifting plants that float on the water surface (e.g., duckweed, water-lily)."
          example: 1
        submerged_cover:
          type: number
          format: float
          description: "Total cover of the submerged layer in percent. Includes rooted or drifting plants that by-and-large remain submerged in the water column or on the aquatic bottom (e.g., pondweed). The focus is on the overall strata arrangement of these aquatic plants. Note that emergent plants life forms in a wetland should be placed in above water strata (e.g., cattail or sedges would be placed in the herb stratum, whereas the duckweed would be in the floating aquatic stratum)."
          example: 0
        dominant_stratum:
          type: string
          description: "Which of the six standard strata is dominant?"
          example: "Tree"
        growthform_1_type:
          type: string
          description: "The predominant growth form?"
          example: "Herbs"
        growthform_2_type:
          type: string
          description: "The second-most predominant growthform?"
          example: "Shrubs"
        growthform_3_type:
          type: string
          description: "The third-most predominant growthform"
          example: "Moss"
        growthform_1_cover:
          type: number
          format: float
          description: "Total cover of the predominant growthform?"
          example: 90
        growthform_2_cover:
          type: number
          format: float
          description: "Total cover of the second-most predominant growthform?"
          example: 30
        growthform_3_cover:
          type: number
          format: float
          description: "Total cover of the third-most predominant growthform?"
          example: 10
        total_cover:
          type: number
          format: float
          description: "The total cover, in percent, of all vegetation on the plot."
          example: 40
        has_observation_synonym:
          type: boolean
          description: "Does this observation have an observation synonym record?"
          example: true
        replaced_by_ob_code:
          type: string
          description: "VegBank identifier of the current plot observation superseding this plot observation, if this observation has been replaced by a newer record"
          example: "ob.2"

    PlotObservationFullNested:
      type: object
      properties:
        disturbances:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: "Type of disturbance being reported"
                example: "Wind event"
              comment:
                type: string
                description: "Description of details of the disturbance and its impact on the vegetation"
                example: "Hurricane blowdown"
              intensity:
                type: string
                description: "Intensity or degree of the disturbance"
                example: "Low"
              age:
                type: number
                format: float
                description: "Estimated time in years since the disturbance event"
                example: 10
              extent:
                type: number
                format: float
                description: "Percent of the plot that experienced the event"
                example: 5
          description: "Observer estimation of the disturbance history of the plot"
        soils:
          type: array
          items:
            type: object
            properties:
              horizon:
                type: string
                description: "The horizon to which this soil observation applies"
                example: "B"
              depth_top:
                type: number
                format: float
                description: "The depth at which the horizon observation starts"
                example: 84
              depth_bottom:
                type: number
                format: float
                description: "The depth at which the horizon observation ends"
                example: 86
              color:
                type: string
                description: "Soil color (USDA guidelines recommended)"
                example: "10yr 6/6 brown yellow"
              organic:
                type: number
                format: float
                description: "Percent organic content of the soil; for methods, see the plot observation methods_narrative"
                example: 13.37
              texture:
                type: string
                description: "Soil texture class. The texture classes sands, loamy sands, and sandy loams (plural terms) correspond to sand, loamy sand, and sandy loam (singular terms) in the textural triangle."
                example: "Clay Loam"
              sand:
                type: number
                format: float
                description: "Percent sand in the soil horizon"
                example: 15.85
              silt:
                type: number
                format: float
                description: "Percent silt in the soil horizon"
                example: 3.47
              clay:
                type: number
                format: float
                description: "Percent clay in the soil horizon"
                example: 0.68
              coarse:
                type: number
                format: float
                description: "Percent coarse fragments in the soil, prior to removal for textural analysis"
                example: 0.13
              ph:
                type: number
                format: float
                description: "pH of the soil; for methods, see the plot observation methods_narrative"
                example: 4.3
              exchange_capacity:
                type: number
                format: float
                description: "Cation exchange capacity; for methods, see the plot observation methods_narrative"
                example: 3.68
              base_saturation:
                type: number
                format: float
                description: "Percent base saturation; for methods, see the plot observation          methods_narrative"
                example: 32.2
              description:
                type: string
                description: "Text description of the soil"
                example: "Beige sticky clay with gray clay below"
          description: "Observations on soil horizons made during the plot observation event"
        named_places:
          type: array
          items:
            type: object
            properties:
              np_code:
                type: string
                description: "VegBank named place identifier"
                example: "np.1"
              system:
                type: string
                description: "Name of the system of names. The system 'Geographic Name' is an open list, whereas the other systems are generally closed lists defined by a known system with an external authority (e.g., USGSQuad, Continent, Country, State, County, HUC, and Ecoregion)"
                example: "county"
              name:
                type: string
                description: "The name of a place in or at which a plot is located."
                example: "Marin"
              description:
                type: string
                description: "Description of a named place. For US county names, this field identifies the containing state."
                example: "California"
              code:
                type: string
                description: "Optional code for location identification"
                example: "6041"
          description: "Named places that a plot may have been located in"
        taxon_count:
          type: integer
          description: "Count of taxon observations associated with this plot observation"
          example: 32
        taxon_importance_count:
          type: integer
          description: "Count of taxon importance records associated with this plot observation"
          example: 54
        taxon_importance_count_returned:
          type: integer
          description: "Count of taxon importance records returned in the top_taxon_observations field"
          example: 5
        top_taxon_observations:
          type: array
          items:
            type: object
            properties:
              to_code:
                type: string
                description: "VegBank taxon observation identifier"
                example: "to.1"
              tm_code:
                type: string
                description: "VegBank taxon importance identifier"
                example: "tm.1"
              pc_code:
                type: string
                description: "VegBank plant concept identifier"
                example: "pc.1"
              plant_name:
                type: string
                description: "Name of the observed plant, using the scientific name (without authors) associated with the current taxon interpretation if available, otherwise the author-provided plant name"
                example: "Acer rubrum"
              sr_code:
                type: string
                description: "VegBank stratum identifier"
                example: "sr.1"
              stratum_name:
                type: string
                description: "Stratum name, or '<All>' if sr_code is null"
                example: "herb"
              cover:
                type: number
                format: float
                description: "Observed cover for this taxon in the referenced stratum (or overall, if no stratum provided)"
                example: 0.7
          description: "Taxon observations"
        top_classifications:
          type: array
          items:
            type: object
            properties:
              cl_code:
                type: string
                description: "VegBank community classification identifier"
                example: "cl.1"
              ci_code:
                type: string
                description: "VegBank community interpretation identifier"
                example: "ci.1"
              cc_code:
                type: string
                description: "VegBank community concept identifier"
                example: "cc.1"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Fagus grandifolia - Quercus spp. / Kalmia latifolia - Hamamelis virginiana / Galax urceolata Forest"
              comm_code:
                type: string
                description: "Code for the community concept, derived from a comm usage record of class system 'Code'"
                example: "CEGL004549"
          description: "Community classifications"

    record_count:
      type: object
      properties:
        count:
          type: integer
          description: Total matching record count
          example: 115000

    plot_obs_geo:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlotObservationBase'

    plot_obs_minimal:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlotObservationBase'
                  - $ref: '#/components/schemas/PlotObservationMinimal'

    plot_obs_minimal_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlotObservationBase'
                  - $ref: '#/components/schemas/PlotObservationMinimal'
                  - $ref: '#/components/schemas/PlotObservationMinimalNested'

    plot_obs_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlotObservationBase'
                  - $ref: '#/components/schemas/PlotObservationMinimal'
                  - $ref: '#/components/schemas/PlotObservationFull'
                  - $ref: '#/components/schemas/StratumMethodBase'

    plot_obs_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlotObservationBase'
                  - $ref: '#/components/schemas/PlotObservationMinimal'
                  - $ref: '#/components/schemas/PlotObservationFull'
                  - $ref: '#/components/schemas/StratumMethodBase'
                  - $ref: '#/components/schemas/PlotObservationFullNested'

    CommConceptFull:
      type: object
      properties:
        cc_code:
          type: string
          description: "VegBank community concept identifier"
          example: "cc.1"
        comm_name:
          type: string
          description: "Community name, as recorded on the community concept"
          example: "Muhlenbergia rigens Wet Meadow"
        comm_code:
          type: string
          description: "Code for the community concept, derived from a community usage record of class system 'Code'"
          example: "CEGL005306"
        comm_description:
          type: string
          description: "Description of the community concept by the party contributing the concept"
          example: "This herbaceous bunchgrass association has been documented in..."
        concept_rf_code:
          type: string
          description: "VegBank identifier for the reference in which the community was identified by a name."
          example: "rf.1"
        concept_rf_label:
          type: string
          description: "Name/label for the reference in which the community was identified by a name."
          example: "NatureServe Biotics 2019"
        status_rf_code:
          type: string
          description: "VegBank identifier for the reference in which the status was reported"
          example: "rf.1"
        status_rf_label:
          type: string
          description: "Name/label for the reference in which the status was reported"
          example: "NatureServe Biotics 2019"
        obs_count:
          type: integer
          description: "Number of plot observations associated with this entity"
          example: 17
        comm_level:
          type: string
          description: "Level in the taxonomic hierarchy to which a class belongs. This is an open list with the possible values defined by the classification system employed. If the party responsible for the record is using the U.S. National Vegetation Classification, the acceptable levels are defined in the Vegetation Classification Standard of the Federal Geographic Data Committee as adopted June 1997. The standard is available at http://biology.usgs.gov/fgdc.veg/standards/vegstd.htm and the allowable entries for each of the physiognomic levels are listed in the appendix (see http://www.fgdc.gov/standards/documents/standards/vegetation/tables19-41.pdf). If the Braun-Blanquet classification system is employed, the acceptable values are defined in the International Code of Phytosociological Nomenclature (Weber, H.E., Moravec, J. Theurillat, J.-P. 2000. Journal of Vegetation Science. 11: 739-769)"
          example: "Association"
        status:
          type: string
          description: "Status of the concept by the party (accepted, not accepted, undetermined)"
          example: "accepted"
        start_date:
          type: string
          format: date
          description: "Date for which the status assignment by the party started."
          example: "2006-05-30"
        stop_date:
          type: string
          format: date
          description: "Date for which the status assignment by the party ended."
          example: "2006-05-30"
        current_accepted:
          type: boolean
          description: "Is this concept currently accepted by at least one party?"
          example: True
        py_code:
          type: string
          description: "VegBank identifier for the party that made the status assignment"
          example: "py.1"
        party_label:
          type: string
          description: "Name/label for the party that made the status assignment"
          example: "NatureServe (organization)"
        comm_party_comments:
          type: string
          description: "Comments by party providing rationale for status assignment"
          example: "This association is the result of..."
        parent_cc_code:
          type: string
          description: "VegBank identifier of the parent concept in the classification hierarchy. For example, if this concept were at the association level, the parent would be a concept that is the parent alliance type."
          example: "cc.1"
        parent_name:
          type: string
          description: "Name of the parent concept in the classification hierarchy"
          example: "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"

    CommConceptFullNested:
      type: object
      properties:
        usages:
          type: array
          items:
            type: object
            properties:
              class_system:
                type: string
                description: "The name of the classification system wherein the name is applied (e.g., Scientific, Spanish common)"
                example: "Scientific"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Acer rubrum Swamp Woodland Alliance"
              status:
                type: string
                description: "Status of the concept by the party (accepted, not accepted, undetermined)"
                example: "accepted"
          description: "Name usages for this community concept"
        children:
          type: array
          items:
            type: object
            properties:
              cc_code:
                type: string
                description: "VegBank community concept identifier"
                example: "cc.1"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Acer rubrum"
          description: "Hierarchical children of this community concept"
        correlations:
          type: array
          items:
            type: object
            properties:
              cc_code:
                type: string
                description: "VegBank community concept identifier"
                example: "cc.1"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Acer rubrum"
              convergence:
                type: string
                description: "Descriptive attribute used to relate the congruence between this concept and each correlated concepts, generally expressed as either greater than, less than, or equal to. For example, if the current concept has been split, the convergence would be 'greater than' (i.e., the old concept is 'greater than' the new concept)."
                example: "undetermined"
          description: "Other (newer, valid) concepts correlated to this (older, no longer valid) community concept"

    comm_concept_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommConceptFull'

    comm_concept_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommConceptFull'
                  - $ref: '#/components/schemas/CommConceptFullNested'

    CommClassMinimal:
      type: object
      properties:
        cl_code:
          type: string
          description: "VegBank community classification identifier"
          example: "cl.1"
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        class_start_date:
          type: string
          format: date
          description: "Start date for the application of a vegetation class to a plot observation by one or more parties."
          example: "2006-05-30"
        class_stop_date:
          type: string
          format: date
          description: "Stop date for the application of a vegetation class to a plot observation by one or more parties."
          example: "2006-05-30"
        inspection:
          type: boolean
          description: "Was the classification informed by simple inspection of data?"
          example: false
        table_analysis:
          type: boolean
          description: "Was the classification informed by inspection of floristic composition tables?"
          example: false
        multivariate_analysis:
          type: boolean
          description: "Was the classification informed by use of multivariate numerical tools?"
          example: false
        expert_system:
          type: string
          description: "Description of any automated expert system used in classification"
          example: "DCA, UPGMA"
        class_publication_rf_code:
          type: string
          description: "VegBank reference identifier for the publication wherein the observation was classified"
          example: "rf.1"
        class_publication_rf_label:
          type: string
          description: "Reference label for the publication wherein the observation was classified"
          example: "NVC 2004"
        class_notes:
          type: string
          description: "Notes about the classification event by the parties participating in the event. This might include the purpose or rationale for the classification."
          example: "Abies Grandis Alliance"

    CommClassMinimalNested:
      type: object
      properties:
        interpretations:
          type: array
          items:
            type: object
            properties:
              ci_code:
                type: string
                description: "VegBank community interpretation identifier"
                example: "ci.1"
              cc_code:
                type: string
                description: "VegBank community concept identifier"
                example: "cc.1"
              comm_code:
                type: string
                description: "Code for the community concept, derived from a comm usage record of class system 'Code'"
                example: "CEGL004549"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Fagus grandifolia - Quercus spp. / Kalmia latifolia - Hamamelis virginiana / Galax urceolata Forest"
          description: "Basic details about the community interpretations made as part of this classification"
        contributors:
          type: array
          items:
            type: object
            properties:
              py_code:
                type: string
                description: "VegBank party identifier for the classification contributor"
                example: "py.1"
              party_label:
                type: string
                description: "Party label for the classification contributor"
                example: "Doe, John"
              role:
                type: string
                description: "Role descriptor for the classification contributor"
                example: "Classifier"
          description: "Contributors to this community classification"

    CommClassFull:
      type: object
      properties:
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation."
          example: "YOSE.001"

    CommClassFullNested:
      type: object
      properties:
        interpretations:
          type: array
          items:
            type: object
            properties:
              ci_code:
                type: string
                description: "VegBank community interpretation identifier"
                example: "ci.1"
              cc_code:
                type: string
                description: "VegBank community concept identifier"
                example: "cc.1"
              comm_code:
                type: string
                description: "Code for the community concept, derived from a comm usage record of class system 'Code'"
                example: "CEGL004549"
              comm_name:
                type: string
                description: "Community name, as recorded on the community concept"
                example: "Fagus grandifolia - Quercus spp. / Kalmia latifolia - Hamamelis virginiana / Galax urceolata Forest"
              comm_label:
                type: string
                description: "Community label, derived from the community concept name and reference"
                example: "Fagus grandifolia - Quercus spp. / Kalmia latifolia - Hamamelis virginiana / Galax urceolata Forest"
              class_fit:
                type: string
                description: "Degree of fit with the community concept being assigned. Values derive from Gopal, S., and Woodcock, C. (1994), Theory and methods for accuracy assessment of thematic maps using fuzzy sets. Photogrammetric Engineering and Remote Sensing 60(2):181-188"
                example: "Reasonable or acceptable answer"
              class_confidence:
                type: string
                description: "Degree of confidence of the interpreter(s) in the interpretation made. This can reflect the level of familiarity with the classification or the sufficiency of information about the plot (e.g., High, Moderate, Low)"
                example: "High"
              comm_authority_rf_code:
                type: string
                description: "VegBank reference identifier for the reference from which information on the community concept was obtained during the classification event"
                example: "rf.1"
              comm_authority_name:
                type: string
                description: "Reference label for the publication wherein the observation was classified"
                example: "Keeler-Wolf and Evens 2006"
              notes:
                type: string
                description: "Notes pertaining to the classification analysis and decision"
                example: "no confidence associated with this classification"
              type:
                type: boolean
                description: "Is this assignment the type description for the community concept, as indicated in the publication referenced in community classification class_publication?"
                example: false
              nomenclatural_type:
                type: boolean
                description: "Is this a typal plot for the Braun-Blanquet community name?"
                example: false
          description: "Extended details about the community interpretations made as part of this classification"
        contributors:
          type: array
          items:
            type: object
            properties:
              py_code:
                type: string
                description: "VegBank party identifier for the classification contributor"
                example: "py.1"
              party_label:
                type: string
                description: "Party label for the classification contributor"
                example: "Doe, John"
              role:
                type: string
                description: "Role descriptor for the classification contributor"
                example: "Classifier"
          description: "Contributors to this community classification"

    comm_class_minimal:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommClassMinimal'
    comm_class_minimal_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommClassMinimal'
                  - $ref: '#/components/schemas/CommClassMinimalNested'
    comm_class_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommClassMinimal'
                  - $ref: '#/components/schemas/CommClassFull'
    comm_class_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommClassMinimal'
                  - $ref: '#/components/schemas/CommClassFull'
                  - $ref: '#/components/schemas/CommClassFullNested'

    CommInterpMinimal:
      type: object
      properties:
        ci_code:
          type: string
          description: "VegBank community interpretation identifier"
          example: "ci.1"
        cl_code:
          type: string
          description: "VegBank community classification identifier"
          example: "cl.1"
        cc_code:
          type: string
          description: "VegBank community concept identifier"
          example: "cc.1"
        class_fit:
          type: string
          description: "Indicates the degree of fit with the community concept being assigned. Values derive from Gopal, S., and Woodcock, C. (1994), Theory and methods for accuracy assessment of thematic maps using fuzzy sets. Photogrammetric Engineering and Remote Sensing 60(2):181-188"
          example: "Reasonable or acceptable answer"
        class_confidence:
          type: string
          description: "Indicates the degree of confidence of the interpreter(s) in the interpretation made. This can reflect the level of familiarity with the classification or the sufficiency of information about the plot (e.g., High, Moderate, Low)"
          example: "High"
        comm_authority_rf_code:
          type: string
          description: "VegBank reference identifier for the reference from which information on the interpreted community concept was obtained during the classification event"
          example: "rf.1"
        notes:
          type: string
          description: "Notes pertaining to the classification analysis and decision"
          example: "no confidence associated with this classification"
        type:
          type: boolean
          description: "Is this assignment the type description for the community concept, as indicated in the publication referenced in community classification class_publication?"
          example: false
        nomenclatural_type:
          type: boolean
          description: "Is this a typal plot for the Braun-Blanquet community name?"
          example: false

    CommInterpFull:
      type: object
      properties:
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation."
          example: "YOSE.001"
        comm_code:
          type: string
          description: "Code for the interpreted community concept, derived from a comm usage record of class system 'Code'"
          example: "CEGL004549"
        comm_name:
          type: string
          description: "Community name, as recorded on the interpreted community concept"
          example: "Fagus grandifolia - Quercus spp. / Kalmia latifolia - Hamamelis virginiana / Galax urceolata Forest"
        comm_label:
          type: string
          description: "Label for the interpreted community concept"
          example: "Muhlenbergia rigens Wet Meadow [NatureServe Biotics 2019]"
        comm_authority_rf_label:
          type: string
          description: "Reference label for the publication wherein the observation was classified"
          example: "Keeler-Wolf and Evens 2006"
        class_start_date:
          type: string
          format: date
          description: "Start date for the application of a vegetation class to a plot observation by one or more parties."
          example: "2006-05-30"
        class_stop_date:
          type: string
          format: date
          description: "Stop date for the application of a vegetation class to a plot observation by one or more parties."
          example: "2006-05-30"
        inspection:
          type: boolean
          description: "Was the classification informed by simple inspection of data?"
          example: false
        table_analysis:
          type: boolean
          description: "Was the classification informed by inspection of floristic composition tables?"
          example: false
        multivariate_analysis:
          type: boolean
          description: "Was the classification informed by use of multivariate numerical tools?"
          example: false
        expert_system:
          type: string
          description: "Description of any automated expert system used in classification"
          example: "DCA, UPGMA"
        class_notes:
          type: string
          description: "Notes about the classification event by the parties participating in the event. This might include the purpose or rationale for the classification."
          example: "Abies Grandis Alliance"
        comm_framework:
          type: string
          description: "Community framework"
        comm_level:
          type: string
          description: "Community level"

    CommInterpFullNested:
      type: object
      properties:
        class_contributors:
          type: array
          items:
            type: object
            properties:
              py_code:
                type: string
                description: "VegBank party identifier for the classification contributor"
                example: "py.1"
              party_label:
                type: string
                description: "Party label for the classification contributor"
                example: "Doe, John"
              role:
                type: string
                description: "Role descriptor for the classification contributor"
                example: "Classifier"
          description: "Contributors to this community classification"

    comm_interp_minimal:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommInterpMinimal'
    comm_interp_minimal_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommInterpMinimal'
    comm_interp_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommInterpMinimal'
                  - $ref: '#/components/schemas/CommInterpFull'
    comm_interp_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CommInterpMinimal'
                  - $ref: '#/components/schemas/CommInterpFull'
                  - $ref: '#/components/schemas/CommInterpFullNested'

    PlantConceptFull:
      type: object
      properties:
        pc_code:
          type: string
          description: "VegBank plant concept identifier"
          example: "pc.1"
        plant_name:
          type: string
          description: "Plant name, as recorded on the plant concept"
          example: "Acer rubrum"
        plant_code:
          type: string
          description: "Code for the plant concept, derived from a plant usage record of class system 'Code'"
          example: "ACRU"
        plant_description:
          type: string
          description: "Description of the plant concept by the party contributing the concept"
          example: "Named for the Cahaba River"
        concept_rf_code:
          type: string
          description: "VegBank identifier for the reference in which the plant was identified by a name."
          example: "rf.1"
        concept_rf_label:
          type: string
          description: "Name/label for the reference in which the plant was identified by a name."
          example: "USDA Plants 2002"
        status_rf_code:
          type: string
          description: "VegBank identifier for the reference in which the status was reported"
          example: "rf.1"
        status_rf_label:
          type: string
          description: "Name/label for the reference in which the status was reported"
          example: "USDA Plants 2002"
        obs_count:
          type: integer
          description: "Number of plot observations associated with this entity"
          example: 17
        plant_level:
          type: string
          description: "Level in the taxonomic hierarchy to which the plant concept belongs."
          example: "Genus"
        status:
          type: string
          description: "Status of the concept by the party (accepted, not accepted, undetermined)"
          example: "accepted"
        start_date:
          type: string
          format: date
          description: "Date for which the status assignment by the party started."
          example: "2006-05-30"
        stop_date:
          type: string
          format: date
          description: "Date for which the status assignment by the party ended."
          example: "2006-05-30"
        current_accepted:
          type: boolean
          description: "Is this concept currently accepted by at least one party?"
          example: True
        py_code:
          type: string
          description: "VegBank identifier for the party that made the status assignment"
          example: "py.1"
        party_label:
          type: string
          description: "Name/label for the party that made the status assignment"
          example: "USDA-NRCS-PLANTS (organization)"
        plant_party_comments:
          type: string
          description: "Comments by party providing rationale for status assignment"
          example: "present at plants.usda.gov as a higher level taxon"
        parent_pc_code:
          type: string
          description: "VegBank identifier of the parent concept in the taxonomic hierarchy. For example, if this concept were at the species level, the parent would be a concept that is the parent genus level."
          example: "pc.1"
        parent_name:
          type: string
          description: "Name of the parent concept in the taxonomic hierarchy."
          example: "Acer"

    PlantConceptFullNested:
      type: object
      properties:
        usages:
          type: array
          items:
            type: object
            properties:
              class_system:
                type: string
                description: "The name of the classification system wherein the name is applied (e.g., Scientific, Spanish common)"
                example: "Scientific"
              plant_name:
                type: string
                description: "Plant name, as recorded on the plant concept"
                example: "Acer rubrum"
              status:
                type: string
                description: "Status of the concept by the party (accepted, not accepted, undetermined)"
                example: "accepted"
          description: "Name usages for this plant concept"
        children:
          type: array
          items:
            type: object
            properties:
              pc_code:
                type: string
                description: "VegBank plant concept identifier"
                example: "pc.1"
              plant_name:
                type: string
                description: "Plant name, as recorded on the plant concept"
                example: "Acer rubrum"
          description: "Hierarchical children of this plant concept"
        correlations:
          type: array
          items:
            type: object
            properties:
              pc_code:
                type: string
                description: "VegBank plant concept identifier"
                example: "pc.1"
              plant_name:
                type: string
                description: "Plant name, as recorded on the plant concept"
                example: "Acer rubrum"
              convergence:
                type: string
                description: "Descriptive attribute used to relate the congruence between this concept and each correlated concepts, generally expressed as either greater than, less than, or equal to. For example, if the current concept has been split, the convergence would be 'greater than' (i.e., the old concept is 'greater than' the new concept)."
                example: "undetermined"
          description: "Other (newer, valid) concepts correlated to this (older, no longer valid) plant concept"

    plant_concept_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlantConceptFull'

    plant_concept_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/PlantConceptFull'
                  - $ref: '#/components/schemas/PlantConceptFullNested'

    TaxonObsMinimal:
      type: object
      properties:
        to_code:
          type: string
          description: "VegBank taxon observation identifier"
          example: "to.1"
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        int_curr_pc_code:
          type: string
          description: "VegBank identifier for the current interpreted plant concept"
          example: "pc.1"
        int_orig_pc_code:
          type: string
          description: "VegBank identifier for the original interpreted plant concept"
          example: "pc.1"
        taxon_inference_area:
          type: number
          format: float
          description: "Area in m2 used to infer the presence of a given taxon. Generally this should be equal to the plot-observation taxon_inference_area, but at times this area may be larger or smaller for a specific taxon. RESERVED VALUE: -1 is used to indicate that no known plot boundaries were used when recording this species on the plot. That is, this species may occur outside the plot area as indicated in the plot and observation tables."
          example: 405
        rf_code:
          type: string
          description: "VegBank identifier for the reference serving as the authority for the taxon used by the plot author; if the authority is unknown, the author of the plot is the authority"
          example: "rf.1"

    TaxonObsFull:
      type: object
      properties:
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation"
          example: "YOSE.001"
        author_plant_name:
          type: string
          description: "Name provided by the plot author to refer to a taxon observed within the plot"
          example: "Lichen"
        int_curr_plant_code:
          type: string
          description: "Plant code for the current interpreted plant concept"
          example: "QUTU2"
        int_curr_plant_common:
          type: string
          description: "Common name for the current interpreted plant concept"
          example: "Sonoran scrub oak"
        int_curr_plant_sci_full:
          type: string
          description: "Scientific name (with authors) for the current interpreted plant concept"
          example: "Quercus turbinella Greene"
        int_curr_plant_sci_name_no_auth:
          type: string
          description: "Scientific name (without authors) for the current interpreted plant concept"
          example: "Quercus turbinella"
        int_orig_plant_code:
          type: string
          description: "Plant code for the original interpreted plant concept"
          example: "QUTU2"
        int_orig_plant_common:
          type: string
          description: "Common name for the original interpreted plant concept"
          example: "Sonoran scrub oak"
        int_orig_plant_sci_full:
          type: string
          description: "Scientific name (with authors) for the original interpreted plant concept"
          example: "Quercus turbinella Greene"
        int_orig_plant_sci_name_no_auth:
          type: string
          description: "Scientific name (without authors) for the original interpreted plant concept"
          example: "Quercus turbinella"
        rf_label:
          type: string
          description: "Name/label of the reference serving as the authority for the taxon used by the plot author; if the authority is unknown, the author of the plot is the authority"
          example: "USDA Plants 2002"

    TaxonObsNested:
      type: object
      properties:
        taxon_importance:
          type: array
          items:
            type: object
            properties:
              tm_code:
                type: string
                description: "VegBank taxon importance identifier"
                example: "tm.1"
              sr_code:
                type: string
                description: "VegBank identifier for the specific stratum to which this taxon importance record applies; if null, this record speaks to the importance of the taxon across all strata"
                example: "sr.1"
              stratum_name:
                type: string
                description: "Name of the specific stratum to which this taxon importance record applies; if '<All>', this record speaks to the importance of the taxon across all strata"
                example: "trees"
              cover:
                type: number
                format: float
                description: "Cover, in percent, of the taxon (potentially limited to one stratum if sr_cide has a value)"
                example: 5
              cover_code:
                type: string
                description: "The original cover code used by the author in the Cover Method for the plot"
                example: "1-9"
              basal_area:
                type: number
                format: float
                description: "Total basal area of the species in m2/ha (potentially limited to one stratum if sr_code has a value)"
                example: 2.18
              biomass:
                type: number
                format: float
                description: "biomass of the taxon in g/m2 (potentially limited to one stratum if sr_cide has a value)"
                example: 810
              inference_area:
                type: number
                format: float
                description: "Area in m2 used to infer the importance values (i.e. cover, biomass, basal area) in this record; RESERVED VALUE: -1 is used to indicate no plot boundaries were used when estimating importance values"
                example: 1000
              stratum_base:
                type: number
                format: float
                description: "Base of the stratum in meters."
                example: 35
              stratum_height:
                type: number
                format: float
                description: "Tallest part of the Stratum in meters."
                example: 50
          description: "Extended details about taxon importance"

    taxon_obs_minimal:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonObsMinimal'
    taxon_obs_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonObsMinimal'
                  - $ref: '#/components/schemas/TaxonObsFull'
    taxon_obs_minimal_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonObsMinimal'
                  - $ref: '#/components/schemas/TaxonObsNested'
    taxon_obs_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonObsMinimal'
                  - $ref: '#/components/schemas/TaxonObsFull'
                  - $ref: '#/components/schemas/TaxonObsNested'

    TaxonImpMinimal:
      type: object
      properties:
        tm_code:
          type: string
          description: "VegBank taxon importance identifier"
          example: "tm.1"
        to_code:
          type: string
          description: "VegBank taxon observation identifier"
          example: "to.1"
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        sr_code:
          type: string
          description: "VegBank stratum identifier"
          example: "sr.1"
        cover:
          type: number
          format: float
          description: "Cover, in percent, of the taxon (limited to one stratum if sr_code has a value)"
          example: 17.5
        cover_code:
          type: string
          description: "Original cover code used by the author in the Cover Method for the plot"
          example: "6"
        basal_area:
          type: number
          format: float
          description: "Total basal area of the species in m2/ha (limited to one stratum if sr_code has a value)"
          example: 13.141
        biomass:
          type: number
          format: float
          description: "Biomass of the species in g/m2 (limited to one stratum if sr_code has a value)"
          example: 813
        inference_area:
          type: number
          format: float
          description: "Area used to infer the importance values of the taxon, if not the
            same as plot-observation taxon_inference_area"
          example: 1000
        stratum_base:
          type: number
          format: float
          description: "Base of the stratum, in meters"
          example: 3
        stratum_height:
          type: number
          format: float
          description: "Tallest part of the stratum, in meters"
          example: 25

    TaxonImpFull:
      type: object
      properties:
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation"
          example: "YOSE.001"
        author_plant_name:
          type: string
          description: "Name provided by the plot author to refer to a taxon observed within the plot"
          example: "Lichen"
        stratum_name:
          type: string
          description: "Name associated with stratum by the stratum method"
          example: "trees"

    TaxonImpNested:
      type: object
      properties:
        stems:
          type: array
          items:
            type: object
            properties:
              sc_code:
                type: string
                description: "VegBank stem count record identifier"
                example: "sc.1"
              diameter:
                type: number
                format: float
                description: "Diameter of the stem in centimeters. When diameter classes are used, the diameter is the midpoint between the low end and high end for the diameter class; the offset between this and the endpoints is stored in stem_diameter_accuracy."
                example: 3.75
              diameter_accuracy:
                type: number
                format: float
                description: "Accuracy of the stem diameter measurements in centimeters, representing the distance between the diameter class midpoint and endpoint"
                example: 1.25
              height:
                type: number
                format: float
                description: "Measured height of the stem in meters. When height classes are used, the height is the midpoint between the low end and high end for the height class; the offset between this and the endpoint is stored in stem_height_accuracy."
                example: 1.185
              height_accuracy:
                type: number
                format: float
                description: "Accuracy of the measured height of a stem, representing the offset between the midpoint of the class and the endpoint, in meters."
                example: 0.185
              count:
                type: integer
                description: "Number of stems of a single species that have these specific stem diameter and height data in common"
                example: 1
              taxon_area:
                type: number
                format: float
                description: "Area in m2 used to infer the presence of the stem(s) referenced in this record. Overrides similar area field in taxon observation, taxon importance, and/or plot observation. RESERVED VALUE: -1 is used to indicate no known boundaries were used while collecting this stem size."
                example: 600
          description: "Stem count records"

    taxon_imp_minimal:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonImpMinimal'
    taxon_imp_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonImpMinimal'
                  - $ref: '#/components/schemas/TaxonImpFull'
    taxon_imp_minimal_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonImpMinimal'
                  - $ref: '#/components/schemas/TaxonImpNested'
    taxon_imp_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/TaxonImpMinimal'
                  - $ref: '#/components/schemas/TaxonImpFull'
                  - $ref: '#/components/schemas/TaxonImpNested'

    StemCountMinimal:
      type: object
      properties:
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        to_code:
          type: string
          description: "VegBank taxon observation identifier"
          example: "to.1"
        tm_code:
          type: string
          description: "VegBank taxon importance identifier"
          example: "tm.1"
        sr_code:
          type: string
          description: "VegBank stratum identifier"
          example: "sr.1"
        sc_code:
          type: string
          description: "VegBank stem count record identifier"
          example: "sc.1"
        diameter:
          type: number
          format: float
          description: "Diameter of the stem in centimeters. When diameter classes are used, the diameter is the midpoint between the low end and high end for the diameter class; the offset between this and the endpoints is stored in stem_diameter_accuracy."
          example: 3.75
        diameter_accuracy:
          type: number
          format: float
          description: "Accuracy of the stem diameter measurements in centimeters, representing the distance between the diameter class midpoint and endpoint"
          example: 1.25
        height:
          type: number
          format: float
          description: "Measured height of the stem in meters. When height classes are used, the height is the midpoint between the low end and high end for the height class; the offset between this and the endpoint is stored in stem_height_accuracy."
          example: 1.185
        height_accuracy:
          type: number
          format: float
          description: "Accuracy of the measured height of a stem, representing the offset between the midpoint of the class and the endpoint, in meters."
          example: 0.185
        count:
          type: integer
          description: "Number of stems of a single species that have these specific stem diameter and height data in common"
          example: 1
        taxon_area:
          type: number
          format: float
          description: "Area in m2 used to infer the presence of the stem(s) referenced in this record. Overrides similar area field in taxon observation, taxon importance, and/or plot observation. RESERVED VALUE: -1 is used to indicate no known boundaries were used while collecting this stem size."
          example: 600

    StemCountFull:
      type: object
      properties:
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation"
          example: "YOSE.001"
        author_plant_name:
          type: string
          description: "Name provided by the plot author to refer to a taxon observed within the plot"
          example: "Lichen"
        stratum_name:
          type: string
          description: "Stratum name, or '<All>' if sr_code is null"
          example: "Canopy"

    stem_count_minimal:
      allOf:
      - $ref: '#/components/schemas/record_count'
      - type: object
        properties:
          data:
            description: Data records
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/StemCountMinimal'
    stem_count_full:
      allOf:
      - $ref: '#/components/schemas/record_count'
      - type: object
        properties:
          data:
            description: Data records
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/StemCountMinimal'
                - $ref: '#/components/schemas/StemCountFull'

    StratumMinimal:
      type: object
      properties:
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        sr_code:
          type: string
          description: "VegBank stratum identifier"
          example: "sr.1"
        name:
          type: string
          description: "Stratum name"
          example: "Dwarf shrub"
        height:
          type: number
          format: float
          description: "#TODO"
          example: 5
        base:
          type: number
          format: float
          description: "#TODO"
          example: 2
        cover:
          type: number
          format: float
          description: "#TODO"
          example: 45
        description:
          type: string
          description: "Stratum description"
          example: "Dwarf shrub"
        sm_code:
          type: string
          description: "VegBank stratum method identifier"
          example: "sm.1"
        sy_code:
          type: string
          description: "VegBank stratum type identifier"
          example: "sy.1"

    StratumFull:
      type: object
      properties:
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation"
          example: "YOSE.001"
        stratum_method_name:
          type: string
          description: "Name of the stratum method (e.g., Braun-Blanquet, TNC-ABI, NC Vegetation Survey #1, NC Vegetation Survey #2, etc.)"
          example: "TurboVeg"
        stratum_type_name:
          type: string
          description: "Name associated with this stratum by the stratum method"
          example: "Dwarf shrub"

    stratum_minimal:
      allOf:
      - $ref: '#/components/schemas/record_count'
      - type: object
        properties:
          data:
            description: Data records
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/StratumMinimal'
    stratum_full:
      allOf:
      - $ref: '#/components/schemas/record_count'
      - type: object
        properties:
          data:
            description: Data records
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/StratumMinimal'
                - $ref: '#/components/schemas/StratumFull'


    TaxonInterpMinimal:
      type: object
      properties:
        ti_code:
          type: string
          description: "VegBank taxon interpretation identifier"
          example: "ti.1"
        to_code:
          type: string
          description: "VegBank taxon observation identifier"
          example: "to.1"
        pc_code:
          type: string
          description: "VegBank plant concept identifier"
          example: "pc.1"
        interpretation_date:
          type: string
          format: date
          description: "Date when the interpretation was made."
          example: "2006-05-30"
        interpretation_type:
          type: string
          description: "Categories for the interpretation (e.g.,  uthor, computer generated, simplified for comparative analysis, correction, finer resolution)"
          example: "Author"
        py_code:
          type: string
          description: "VegBank identifier for the party making the interpretation"
          example: "py.1"
        rf_code:
          type: string
          description: "VegBank Reference identifier for the publication in which the interpretation was formally made, or in which the plot was used in a formal analysis"
          example: "rf.1"
        taxon_fit:
          type: string
          description: "Degree of fit with the plant concept being assigned. Values derive from Gopal, S., and Woodcock, C. (1994), Theory and methods for accuracy assessment of thematic maps using fuzzy sets. Photogrammetric Engineering and Remote Sensing 60(2):181-188."
          example: "Reasonable or acceptable answer"
        taxon_confidence:
          type: string
          description: "Degree of confidence of the interpreter(s) in the interpretation made. This can reflect the level of familiarity with the taxon or the sufficiency of information about the plant (e.g., High, Moderate, Low)"
          example: "High"
        collection_number:
          type: string
          description: "The collector's identification code for the voucher"
          example: "091907F"
        group_type:
          type: string
          description: "The type of group formed for this taxon interpretation"
          example: "union"
        notes:
          type: string
          description: "Notes that the interpreter has included with the interpretation (generally, the reason for the interpretation)"
          example: "Identified from specimen"
        is_orig:
          type: boolean
          description: "Is this the original interpretation?"
          example: True
        is_curr:
          type: boolean
          description: "Is this the current interpretation?"
          example: True

    TaxonInterpFull:
      type: object
      properties:
        ob_code:
          type: string
          description: "VegBank plot observation identifier"
          example: "ob.1"
        author_obs_code:
          type: string
          description: "Code or name provided by the author to identify the classified plot observation."
          example: "YOSE.001"
        author_plant_name:
          type: string
          description: "Name provided by the plot author to refer to a taxon observed within the plot"
          example: "Lichen"
        plant_code:
          type: string
          description: "Code for the plant concept, derived from a plant usage record of class system 'Code'"
          example: "ACRU"
        plant_name:
          type: string
          description: "Plant name, as recorded on the plant concept"
          example: "Acer rubrum"
        plant_label:
          type: string
          description: "Label for the interpreted plant concept"
          example: "Lichen [USDA Plants 2002]"
        party_label:
          type: string
          description: "Name/label for the party making the interpretation"
          example: "py.1"
        role:
          type: string
          description: "Role of the party making the interpretation"
          example: "Plot author"
        rf_label:
          type: string
          description: "Reference label for the publication in which the interpretation was formally made, or in which the plot was used in a formal analysis"
          example: "Keeler-Wolf and Evens 2006"

    taxon_interp_minimal:
      allOf:
      - $ref: '#/components/schemas/record_count'
      - type: object
        properties:
          data:
            description: Data records
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/TaxonInterpMinimal'
    taxon_interp_full:
      allOf:
      - $ref: '#/components/schemas/record_count'
      - type: object
        properties:
          data:
            description: Data records
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/TaxonInterpMinimal'
                - $ref: '#/components/schemas/TaxonInterpFull'

    CoverMethodFull:
      type: object
      properties:
        cm_code:
          type: string
          description: "VegBank cover method identifier"
          example: "cm.1"
        cover_type:
          type: string
          description: "Name of the coverclass method (e.g., Braun-Blanquet, Barkman, Domin, Daubenmire, Carolina Vegetation Survey, etc.)"
          example: "Braun-Blanquet"
        cover_estimation_method:
          type: string
          description: "How cover is estimated on the observation"
          example: "Canopy cover"
        rf_code:
          type: string
          description: "VegBank identifier for the defining cover method reference"
          example: "rf.1"
        rf_label:
          type: string
          description: "Name/label for the defining cover method reference"
          example: "TurboVeg1.98a"

    CoverMethodFullNested:
      type: object
      properties:
        cover_indexes:
          type: array
          items:
            type: object
            properties:
              cv_code:
                type: string
                description: "VegBank cover index identifier"
                example: "cv.1"
              cover_code:
                type: string
                description: "Name or label used in the cover class scale for this specific cover class."
                example: "2"
              lower_limit:
                type: number
                format: float
                description: "Lower limit, in percent, associated with a specific coverCode. Where a cover scale has a non-quantitative lower or upper value, as in the '+' of the Braun-Blanquet scale, this is an approximation with '0' being the lower limit of the bottom-most class."
                example: 0.1
              upper_limit:
                type: number
                format: float
                description: "Upper limit, in percent, associated with the specific cover code"
                example: 1
              cover_percent:
                type: number
                format: float
                description: "Middle value (usually mean or geometric mean) between the upper_limit and lower_limit for each taxon observation and used for all cover class conversions and interpretations; assigned by the author of the cover class schema"
                example: 0.505
              index_description:
                type: string
                description: "Description of the specific coverclass; this is particularly helpful in the case that there is no numeric value that can be applied."
                example: "0-1 percent"

    cover_method_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CoverMethodFull'
    cover_method_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/CoverMethodFull'
                  - $ref: '#/components/schemas/CoverMethodFullNested'

    StratumMethodBase:
      type: object
      properties:
        sm_code:
          type: string
          description: "VegBank stratum method identifier"
          example: "sm.1"
        stratum_method_name:
          type: string
          description: "Name of the stratum method (e.g., Braun-Blanquet, TNC-ABI, NC Vegetation Survey #1, NC Vegetation Survey #2, etc.)"
          example: "TurboVeg"
        stratum_method_description:
          type: string
          description: "Describes the general methods used for strata. For example, this field should distinguish as to whether strata are defined as including all foliage on plants that predominantly occupy the stratum regardless of the height of that foliage, or only the foliage that actually occurs within a specified vertical slice of the community."
          example: "Standard strata used in the TurboVeg application"
        stratum_assignment:
          type: string
          description: "The way that an individual's cover is assigned to the different stratum. Some methodologies allow an individul to span multiple strata and have stratum cover values in each stratum. Other methodologies require that all cover from an individual be assigned to the upper-most stratum. Further information about the specifics of stratum methodologies that deviate from the standard practice of the stratum method should be described in the plot observation method narrative."
          example: "predominant stratum"

    StratumMethodFull:
      type: object
      properties:
        rf_code:
          type: string
          description: "VegBank reference identifier for the publication that defines the stratum method"
          example: "rf.1"
        rf_label:
          type: string
          description: "Name/label for the publication that defines the stratum method"
          example: "TurboVeg1.98a"

    StratumMethodFullNested:
      type: object
      properties:
        stratum_types:
          type: array
          items:
            type: object
            properties:
              sy_code:
                type: string
                description: "VegBank stratum type identifier"
                example: "sy.1"
              stratum_index:
                type: string
                description: "Short code used to identify the stratum"
                example: "H"
              stratum_name:
                type: string
                description: "Name associated with this stratum by the stratum method"
                example: "Herb"
              stratum_description:
                type: string
                description: "This field describes the specific stratum.  For example, a value of 'F' under stratum_index might have a stratum_name = 'Floating' and a stratum_description = 'foliage floating on or near the surface of water'"
                example: "Foliage generally less than 0.5m high"

    stratum_method_full:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/StratumMethodBase'
                  - $ref: '#/components/schemas/StratumMethodFull'
    stratum_method_full_nested:
      allOf:
        - $ref: '#/components/schemas/record_count'
        - type: object
          properties:
            data:
              description: Data records
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/StratumMethodBase'
                  - $ref: '#/components/schemas/StratumMethodFull'
                  - $ref: '#/components/schemas/StratumMethodFullNested'

    Party:
      type: object
      properties:
        py_code:
          type: string
          description: "VegBank party identifier"
          example: "py.1"
        party_label:
          type: string
          description: "Name/label for the party"
          example: "NatureServe (organization)"
        salutation:
          type: string
          description: "Salutation used in addressing an individual with a particular title"
          example: "Dr."
        given_name:
          type: string
          description: "All names, except the surname, of the individual associated with the resource. Possible usages include: first name and middle name, first name and middle initials, first name, etc."
          example: "Jo R."
        middle_name:
          type: string
          description: "Middle name or initial, if any"
          example: "R."
        surname:
          type: string
          description: "Name shared in common to identify the members of a family, as distinguished the given name"
          example: "Smith"
        organization_name:
          type: string
          description: "Full name of the organization, which may be the party itself if this is an organization-type party record, or else is the organization that the party is associated with if this is a person-type party record"
          example: "NatureServe"
        contact_instructions:
          type: string
          description: "Instructions for contacting a party"
          example: "contact the contributor at specified email"
        obs_count:
          type: integer
          description: "Number of plot observations associated with this entity"
          example: 17

    party:
      $ref: '#/components/schemas/Party'

    Role:
      type: object
      properties:
        ar_code:
          type: string
          description: "VegBank role identifier"
          example: "ar.56"
        name:
          type: string
          description: "Role name/label"
          example: "Data aggregator"
        description:
          type: string
          description: "Role description"
          example: "Person who aggregates and directs data from one place or platform to another"

    role:
      $ref: '#/components/schemas/Role'

    Project:
      type: object
      properties:
        pj_code:
          type: string
          description: "VegBank project identifier"
          example: "pj.1"
        project_name:
          type: string
          description: "Project name as defined by the principal investigator"
          example: "Pawnee Grassland Classification"
        project_description:
          type: string
          description: "Short description of the project including the original purpose for conducting the project"
          example: "Classification of the Pawnee National Grassland"
        start_date:
          type: string
          format: date
          description: "Project start date"
          example: "2006-05-30"
        stop_date:
          type: string
          format: date
          description: "Project stop date"
          example: "2006-05-30"
        obs_count:
          type: integer
          description: "Number of plot observations associated with this entity"
          example: 17
        last_plot_added_date:
          type: string
          format: date
          description: "Date a plot observation was last added to this project"
          example: "2006-05-30"

    project:
      $ref: '#/components/schemas/Project'

    Reference:
      type: object
      properties:
        rf_code:
          type: string
          description: "VegBank reference identifier"
          example: "rf.1"
        rf_label:
          type: string
          description: "Label for the reference"
          example: "Peet Dissertation (1975)"
        short_name:
          type: string
          description: "Concise or abbreviated name that describes the resource being documented"
          example: "Anderson, L. et al. 1990."
        full_citation:
          type: string
          description: "Full text of the reference citation"
          example: "Anderson, L. et al. 1990. Bryologist 93: 448-499."
        reference_type:
          type: string
          description: "Type of reference"
          example: "Report"
        title:
          type: string
          description: "Formal title given to the work by its author or publisher, providing a description of the resource sufficient to differentiate it from other similar resources"
          example: "The Biology of Lichens"
        publication_date:
          type: string
          format: date
          description: "Date that the resource was published"
          example: "2011-08-25"
        total_pages:
          type: integer
          description: "Total number of pages in the resource being described"
          example: 17
        publisher:
          type: string
          description: "Organization that physically put together the report and publishes it"
          example: "NCU Herbarium"
        publication_place:
          type: string
          description: "Location where the work was published"
          example: "Chapel Hill, NC, USA"
        degree:
          type: string
          description: "Name or degree level for which the thesis was completed"
          example: "PhD"
        isbn:
          type: string
          description: "The ISBN, or International Standard Book Number that has been assigned to this literature resource"
          example: "978-1-889878-38-6"
        url:
          type: string
          description: "URL (Uniform Resource Locator) identifying where the resource and/or additional information about it is (or was) available"
          example: "http://www.algaebase.org"
        doi:
          type: string
          description: "DOI (Digital Object Identifier) serving as the persistent identifier for the resource"
          example: "10.1000/182"
        journal:
          type: string
          description: "Name of the journal, magazine, etc. in which the article was published"
          example: "Regnum Vegetabile"

    reference:
      $ref: '#/components/schemas/Reference'

    NamedPlace:
      type: object
      properties:
        np_code:
          type: string
          description: "VegBank named place identifier"
          example: "np.1"
        system:
          type: string
          description: "Name of the system of names. The system 'Geographic Name' is an open list, whereas the other systems are generally closed lists defined by a known system with an external authority (e.g., USGSQuad, Continent, Country, State, County, HUC, and Ecoregion)"
          example: "county"
        name:
          type: string
          description: "The name of a place in or at which a plot is located."
          example: "Zion NP"
        description:
          type: string
          description: "Description of a named place. For US county names, this field identifies the containing state."
          example: "Zion National Park"
        code:
          type: string
          description: "Optional code for location identification"
          example: "ZION"
        owner:
          type: string
          description: "Designated location owner"
          example: "US NPS"
        rf_label:
          type: string
          description: "Label for the observation reference"
          example: "US NPS place names"
        obs_count:
          type: integer
          description: "Number of plot observations associated with this named place"
          example: 8

    named_place:
      $ref: '#/components/schemas/NamedPlace'

    UserDataset:
      type: object
      properties:
        ds_code:
          type: string
          description: "VegBank dataset identifier"
          example: "ds.1"
        accession_code:
          type: string
          description: "Accession code identifying older VegBank datasets"
          example: "VB.ds.196904.27074B058D5FD45"
        start:
          type: string
          format: date
          description: "Dataset creation date"
          example: "2006-05-30"
        stop:
          type: string
          format: date
          description: "User-defined dataset expiration date"
          example: "2006-05-30"
        name:
          type: string
          description: "Dataset name"
          example: "Example dataset 1"
        description:
          type: string
          description: "Dataset description"
          example: "Some plots in North Carolina"
        type:
          type: string
          description: "Dataset type"
          example: "normal"
        owner_label:
          type: string
          description: "Name of the dataset creator/owner"
          example: "Mary Smith"
        owner_email:
          type: string
          description: "Email address of dataset creator/owner"
          example: "msmith@university.edu"
        py_code:
          type: string
          description: "VegBank party identifier for the dataset creator/owner"
          example: "py.1"
        obs_count:
          type: integer
          description: "Number of plot observations associated with this dataset"
          example: 17

    user_dataset:
      $ref: '#/components/schemas/UserDataset'

    UploadSummary:
      type: object
      description: >
        Counts of inserted records per entity type, plus the uploaded and
        VegBank-assigned identifiers for each record. Entity type keys (e.g.
        `pl`, `ob`, `rf`, `ds`) vary depending on what was uploaded. `ds`
        always appears and represents the internal dataset record created to
        log the upload.
      properties:
        counts:
          type: object
          additionalProperties:
            type: object
            properties:
              inserted:
                type: integer
          example:
            xx:
              inserted: 1
            yy:
              inserted: 2
            ds:
              inserted: 1
        resources:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              additionalProperties: true
              properties:
                action:
                  type: string
                user_xx_code:
                  type: string
                vb_xx_code:
                  type: string
          example:
            xx:
              - action: INSERT
                user_xx_code: "my_xx_code"
                vb_xx_code: "xx.123"
            yy:
              - action: INSERT
                user_yy_code: "my_yy_code_1"
                vb_yy_code: "yy.123"
            ds:
              - action: INSERT
                user_ds_code: "upload_dataset_20260325110254"
                vb_ds_code: "ds.123"

    UploadResult:
      oneOf:
        - $ref: "#/components/schemas/UploadSummary"
        - type: object
          title: DryRunSummary
          description: Returned when `dry_run=true`. Transaction is rolled back.
          properties:
            dry_run_data:
              $ref: "#/components/schemas/UploadSummary"
            message:
              type: string
              example: "dry run, transaction was rolled back"