basalt_schema.yaml

---
id: https://emsl-computing.github.io/BASALT-Schema
name: basalt-schema
title: BASALT Schema
version: 0.1.0
description: |-
  LinkML schema for MONet/EMSL scientific data across biogeochemical, biological,
  and environmental domains. Defines samples, provenance, laboratory activities,
  and analytical products as the canonical source of truth for BASALT consumers
  (Analysis API, database models, and related tooling).
license: CC0-1.0
see_also:
  - https://emsl-computing.github.io/BASALT-Schema
  - https://github.com/EMSL-Computing/BASALT-Schema

prefixes:
  basalt_schema: https://emsl-computing.github.io/BASALT-Schema/elements/
  linkml: https://w3id.org/linkml/
  xsd: http://www.w3.org/2001/XMLSchema#
  # schema: http://schema.org/
  # qudt: http://qudt.org/schema/qudt/
  # unit: http://qudt.org/vocab/unit/
  # uuid: https://w3id.org/uuid/

# Prefixes declared in enums.yaml and used only in permissible-value "meaning:".
# pythongen emits CurieNamespace variables for root-schema prefixes, class/slot/type
# URIs and mappings, but it never scans enum meanings - so without listing them here
# the generated dataclasses reference undefined names (e.g. CHEBI["38472"]).
emit_prefixes:
  - CHEBI
  - OBI
  - PO
  - BTO
  - MS
  - EC
  - ror

default_prefix: basalt_schema
default_range: string

imports:
  - linkml:types
  - administration
  - enums
  - mass_spec
  - media_strain_culture_plate
  - metagenomics
  - methods
  - organism
  - products
  - sample_classes
  # - sample_processing
  - slots
  - study
  - value_tables
  - zip_download
  # - linkage_cache   # uncomment when linkage_cache.yaml is added

types:
  uuid:
    typeof: string
    uri: xsd:string
    pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
  timestamp_tz:
    typeof: datetime
    uri: xsd:dateTime

classes:

  Activity: 
    description: Something that happens over time and can use equipment.
    abstract: true
    attributes:
      id:
        identifier: true
        range: uuid
      ended_at_time:
        range: datetime
      processing_institution:
        range: InstitutionEnum
        description: The institution where the activity took place.
      protocol_link:
        range: string 
        description: A link to a protocol that describes the steps and parameters of the activity.
      started_at_time:
        range: datetime
    slots:
    - name
    - description

  Entity:
    description: Base identifiable thing.
    abstract: true
    attributes:
      id:
        identifier: true
        range: uuid
    slots:
    - name
    - description

  DataProduct:
    abstract: true
    description: |-
      Abstract base class for raw or processed data accessible in S3 storage.
      Carries S3-pointer and sample-linkage slots shared across product types.
      processedData and future sitePhoto extend this via is_a.
      No direct database table, subclasses map to tables.
    slots:
      - name
      - description
      - project
      - sampling_set
      - core_section
      - sample_name
      - s3_base_url
      - s3_bucket
      - s3_key
      - filesize
      - md5checksum
    attributes:
      id:
        identifier: true
        range: uuid
        required: true

  ProcessedData:
    is_a: DataProduct
    abstract: true
    description: A data product generated by a workflow execution.
    slots:
      - summary_metrics  # [ADDED] key-value product summary, per-type schema TBD
      - lims_barcode     # [PROMOTED] from inline attribute
      - sample_id        # [ADDED] link back to originating sample
    todos:
      - all subclasses need a more specific upstream slot to replace was_generated_by


  InstrumentData:
    is_a: DataProduct
    abstract: true
    description: >-
      An abstract parent class for raw data files generated by different kinds 
      of instruments. All subclasses must have a slot pointing upstream that 
      specifies the analysisActivity subclass which created them.
    slots:
      - file_curie
    slot_usage:
      description:
        required: true
    attributes:
      alternative_identifiers:
        range: string
      compression_type:
        range: string
      file_type:
        range: FileTypeEnum
      software_version:
        range: string
    todos:
      - all subclasses need a more specific upstream slot to replace was_generated_by
      - add subclasses for non-mass spec data
      - revisit alternative identifiers range - array?
      - revisit filetype enum - restrict on subclasses

  SitePhoto:
    is_a: DataProduct
    description: |-
      A data product representing a photo of a site, typically taken during sampling.
      One row per photo with metadata about the photo type and when it was taken.
    attributes:
      site_photo_type:
        range: SitePhotoCategoryEnum
      photo_taken_during:
        range: SamplingActivity

  DataGenerationActivity:
    abstract: true
    description: |-
      Abstract base for any data generation activity (physical to digital). Input data should 
      be specified on workflow subclasses.
    slots:
      - sequence_order   
      - name
      - description
      - protocol_url
      - protocol_version
    attributes:
      id:
        identifier: true
        range: uuid
      analyte_id:
        range: ProcessedSample
      acquisition_start_time:
        range: datetime
        required: true
      acquisition_end_time:
        range: datetime
        required: true
      instrument_used:
        range: Instrument
      instrument_operator_id:
        range: PersonValue


  RespirationDataGenerationActivity:
    is_a: DataGenerationActivity
    description: |-
      Data generation activity for soil respiration analysis.
      Captures CO2-C efflux measured per gram of soil.
    attributes:
      method_id:
        range: RespirationMethod
        description: Reference to the RespirationMethod used for this run

  DataProcessingActivity:
    abstract: true
    description: |-
      Abstract base for any data processing activity (digital to digital). Input data should 
      be specified on workflow subclasses.
    slots:
      - parent_workflow_id  # [ADDED] self-referential chain link
      - workflow_steps      # [CHANGED] key-value direction; schema TBD (was # TODO JSONB)
      - description
    slot_usage:
      description: 
        description: >-
          A human-readable description of the data analysis workflow. May 
          include details such as the purpose, output, and/or main steps of 
          the workflow.
    attributes:
      id:
        identifier: true
        range: uuid
      started_at_time:
        range: datetime
        required: true
      ended_at_time:
        range: datetime
      software_url:
        range: string
      software_version:
        range: string
      software_poc:
        range: string
      execution_resource:
        range: ExecutionResourceEnum

  AlternativeIdentifier:
    attributes:
      id:
        identifier: true
        range: uuid
      alternate_id:
        range: string
        required: true
      alternate_identifier_type:
        range: AlternateIdentifierType
        required: true

  FunctionalAnnotationIdentifier:
    attributes:
      id:
        identifier: true
        range: uuid
      functional_identifier:
        range: string
        required: true
      database:
        range: AnnotationDatabaseEnum
        required: true

  Instrument:
    description: |-
      A material entity that is designed to perform a function in a scientific 
      investigation, but is not a reagent. This class models a specific
      instance of an instrument IF identifying information is filled out, 
      otherwise, it is a generic standin for an instrument model.
    attributes:
      id:
        identifier: true
        range: uuid
      name:
        range: string
        required: true
      vendor:
        range: VendorEnum
      model:
        range: ModelEnum
      serial_number:
        range: string
        description: instrument instance specifier
      lims_resource_id:   #ADDED for optional L7 traceability
        range: integer
        description: L7 resource_id for the instrument, if known.
      location:
        range: string
      maintenance:
        range: string
        description: Maintenance notes or directions to a maintenance log.
      alternative_names:
        range: string # TODO ARRAY
      instrument_parameters:
        range: string # TODO JSON
      mass_analyzer_type:
        range: MassAnalyzerEnum
        description: The type of mass analyzer present in the instrument, if applicable (e.g., Orbitrap, Time-of-Flight, Quadrupole).
      other_properties:
        range: string
        description: Other important properties of the instrument that are not captured in other fields.

  OntologyClass: # table has no data
    attributes:
      id:
        identifier: true
        range: uuid
      description:
        range: string
      alternative_identifiers:
        range: string
      name:
        range: string

  ContainerType:
    attributes:
      id:
        identifier: true
        range: uuid
      description:
        range: string
      container_type:
        range: ContainerTypeEnum
      container_size_id:
        range: QuantityValue
      axes:
        multivalued: true
        range: ContainerAxis
      contains:
        multivalued: true
        range: uriorcurie   
      label_format:
        range: string      
      renderer:
        range: string       
        description: UI renderer to use for this container type (e.g., defaultcontainer.js).
      slot_capacity:
        range: string
    todos:
    - reconcile with enums and in media_strain_culture_plate.yaml
    - potentially delete along with ContainerAxis? What are these for?

  ContainerAxis: #container_axis.yml - L7
    attributes:
      name:
        range: string     
      values:
        multivalued: true
        range: string
    todos:
    - I'm only including this in case we need it to sync up with L7 in some way

  Custodian:
    attributes:
      id:
        identifier: true
        range: uuid
      person_id:
        range: PersonValue

  InstrumentAlternativeIdentifier:
    attributes:
      id:
        identifier: true
        range: uuid
      alt_id:
        range: AlternativeIdentifier
      instrument_alt_id_provider:
        range: InstrumentAltIdProviderEnum
      instrument_id:
        range: Instrument
        required: true

  LabDevice:
    description: |-
      A lab device is a physical instrument or equipment used in a laboratory setting for conducting experiments, measurements, or analyses. It can include various types of instruments such as microscopes, spectrometers, centrifuges, and other specialized equipment. Lab devices are essential for performing scientific research and obtaining accurate data.
    attributes:
      id:
        identifier: true
        range: uuid
      description:
        range: string
      device_type:
        range: DeviceTypeEnum
      activity_time_id:
        range: QuantityValue
      activity_speed_id:
        range: QuantityValue

  SampleProcessing:
    abstract: true
    description: |-
      Abstract base for any sample processing activity (physical to physical). Input data should 
      be specified on workflow subclasses.
    slots:
      - protocol_url
      - protocol_version
    attributes:
      id:
        identifier: true
        range: uuid
      analysis_type:
        range: RouteMethodEnum
      method_name:
        range: MethodNameEnum
      processing_steps:
        range: string # TODO JSONB   key-value direction deferred; schema TBD
        required: true
      uses_sample:
        range: Sample
    todos:
      - why does this have both analysis type and method name, as enums, just set the range to the class

  ProcessingSampleLink:
    description: |-
      A link between a processed sample and the sample processing activity that produced it.
      This class captures the relationship between a processed sample and the sample processing
      activity that generated it, including the step number and role of the sample in the process.
    attributes:
      id:
        identifier: true
        range: uuid
      sample_base_id:
        range: Sample
        required: true
      processing_id:
        range: SampleProcessing
        required: true
      step_number:
        range: integer
        required: true
      role:
        range: SampleRole
        required: true
    unique_keys:
      unique_sample_process_step:
        unique_key_slots:
          - sample_base_id
          - processing_id
          - step_number
          - role

  InstrumentCustodian:
    description: |-
      A link between an instrument and a custodian (person) responsible for it.
      This class captures the relationship between an instrument and the person
      who is responsible for its maintenance, calibration, and proper use.
    attributes:
      instrument_id:
        range: Instrument
        required: true
      custodian_id:
        range: Custodian
        required: true


  WorkflowExecutionFunctionalAnnotation:
    description: |-
      A link between a workflow execution and a functional annotation identifier.
      This class captures the relationship between a workflow execution and the
      functional annotation identifier that was used in the analysis.
    attributes:
      workflow_id:
        range: DataProcessingActivity
        required: true
      functional_annotation_id:
        range: FunctionalAnnotationIdentifier
        required: true
      count:
        range: double

  XRayDataGenerationActivity:
      is_a: DataGenerationActivity
      abstract: true
      description: |-
        Abstract base class for X-ray analytical methods including XRF (elemental)
        and XRD (mineralogical) analysis. Inherits acquisition_time, instrument_id,
        protocol_url, analyte_id, and other core metadata from DataGenerationActivity.
        
        Concrete subclasses define method-specific measurement parameters.
        Future X-ray methods (e.g., XCT) can extend this class.
        
        Shared patterns:
          - Direct instrument output (no computational workflow) is typical for XRF
          - XRD may optionally link to DataProcessingActivity for Rietveld refinement
          - protocol_url should link to vendor SOP or EMSL internal protocol documentation

  XRFDataGenerationActivity:
    is_a: XRayDataGenerationActivity
    description: |-
      X-ray Fluorescence (XRF) elemental analysis activity.
      
      XRF measures elemental composition by detecting characteristic X-ray emissions
      from a sample bombarded with high-energy X-rays. Typical output: concentrations
      of 10-30 elements per sample (Ni, Pb, As, Cr, Fe, Ca, K, etc.).
      
      Data product: XRFElementalProduct (one row per element per sample)
      
      Workflow pattern: Direct instrument output (no computational processing step)
        processedSample -> XRFDataGenerationActivity -> XRFElementalProduct (workflow_id = NULL)
      
      Protocol information: Stored externally; link via protocol_url attribute.
      Example protocol parameters (stored in external SOP or DataProcessingActivity
      if computational correction is needed):
        - Beam voltage (kV), beam current (mA)
        - Measurement duration (seconds)
        - Matrix correction method (fundamental parameters, empirical)
        - Calibration date
        - Operator ID
      
      Required enum additions to enums.yaml:
        routemethod:
          xrf_analysis:  # Add to routemethod permissible_values

  XRDDataGenerationActivity:
    is_a: XRayDataGenerationActivity
    description: |-
      X-ray Diffraction (XRD) mineralogical analysis activity.
      
      XRD identifies crystalline mineral phases by measuring diffraction patterns.
      Output: mineral phase names and quantitative abundances (weight %).
      
      Data product: XRDPhaseProduct (one row per mineral phase per sample)
      
      Workflow patterns:
        1. Direct/semi-quantitative: 
             processedSample -> XRDDataGenerationActivity -> XRDPhaseProduct (workflow_id = NULL)
        2. With Rietveld refinement (computational):
             processedSample -> XRDDataGenerationActivity -> 
             DataProcessingActivity(type='xrd_rietveld_refinement') -> 
             XRDPhaseProduct (workflow_id = refinement WEA)
      
      Protocol information: Stored externally; link via protocol_url attribute.
      Example protocol parameters (stored in external SOP or DataProcessingActivity):
        - Diffractometer geometry (Bragg-Brentano, Debye-Scherrer)
        - X-ray tube type (Cu, Co, Mo)
        - Scan range (2-theta degrees), step size
        - Refinement software (HighScore Plus, GSAS-II, FullProf)
        - R-factor, GOF (goodness of fit)
      
      Required enum additions to enums.yaml:
        routemethod:
          xrd_analysis:  # Add to routemethod permissible_values