# ==============================================================================
# AQDx METADATA FORM VERSION 3
# ==============================================================================
# Instructions:
# - Fill in values to the right of each colon.
# - Do not rename field keys.
# - Use quotes for text with special characters.
# - Use null for "unknown / not applicable".
# - Dates must be YYYYMMDD (8 digits).
# ==============================================================================

# ==============================================================================
# DATASET HEADER
# ==============================================================================
dataset_id: ""               # REQUIRED | Primary Key | Format: string | Matches tabular data
aqdx_metadata_version: "3.0" # REQUIRED | Version of this YAML schema
aqdx_data_version: "3.0"     # REQUIRED | Version of the attached tabular data

# ==============================================================================
# SECTION 1: OVERVIEW & DATA STEWARD
# ==============================================================================
data_steward:
  data_steward_name: ""      # REQUIRED | Format: string (max 64) | Matches tabular data
  contact_name: ""           # REQUIRED | Format: string (max 64)
  contact_email: ""          # REQUIRED | Format: string (max 64)
  contact_phone: null        # OPTIONAL | Format: string
  organization_type: null    # REQUIRED | Format: integer (1-Gov, 2-NGO, 3-Community)
  organization_name_full: "" # REQUIRED | Format: string (max 128)
  address: null              # OPTIONAL | Format: string (max 128)
  last_update_date: ""       # REQUIRED | Format: YYYYMMDD
  is_regulatory_data: 0      # REQUIRED | Format: integer (1=Yes, 0=No)
  data_abstract: null        # OPTIONAL | Format: string (max 500)

# ==============================================================================
# SECTION 2: DATASET-LEVEL QUALITY
# ==============================================================================
dataset_quality:
  automated_qc_applied: null        # REQUIRED | Format: boolean
  automated_qc_methods: null        # OPTIONAL | Format: string (Comma-separated options)
  automated_qc_description: null    # OPTIONAL | Format: string (Free text summary)
  data_review_undergone: null       # REQUIRED | Format: boolean
  data_review_methods: null         # OPTIONAL | Format: string
  data_review_description: null     # OPTIONAL | Format: string (Free text summary)
  official_monitoring_programs: null # OPTIONAL | Format: string
  other_processing_description: null # OPTIONAL | Format: string
  useful_links: null                # OPTIONAL | Format: string (Comma-separated URLs)

# ==============================================================================
# SECTION 3: SITES
# ==============================================================================
sites:
  - site_name: ""            # REQUIRED | Primary Key | Format: string | Matches tabular
    latitude: null           # REQUIRED | Format: decimal
    longitude: null          # REQUIRED | Format: decimal
    original_gis_datum: "WGS84" # REQUIRED | Format: string (max 10)
    address: null            # OPTIONAL | Format: string (max 128)
    state_code: null         # REQUIRED | Format: integer
    county_code: null        # REQUIRED | Format: integer
    site_owner: ""           # REQUIRED | Format: string (max 128)
    site_photos_url: null    # OPTIONAL | Format: string (max 200)
    surroundings_type: null  # REQUIRED | Format: integer (1-Urban, 2-Rural, etc.)
    nearby_sources: null     # OPTIONAL | Format: string (max 200)
    reg_aqs_id: null           # REQUIRED for reg | Format: integer (9-digit)
    reg_monitoring_scale: null # REQUIRED for reg | Format: integer
    reg_site_type: null        # REQUIRED for reg | Format: integer
    reg_groundcover: null      # REQUIRED for reg | Format: integer

# ==============================================================================
# SECTION 4: INSTRUMENTS & PARAMETERS
# ==============================================================================
instruments:
  - device_id: ""            # REQUIRED | Primary Key | Matches tabular data
    site_name: ""            # REQUIRED | Foreign Key | Must match a site_name above
    manufacturer_name: ""    # REQUIRED | Format: string (max 64)
    device_model: ""         # REQUIRED | Format: string (max 64)
    firmware_version: null   # OPTIONAL | Format: string (max 32)
    instrument_classification: null # REQUIRED | Format: integer (1-FRM/FEM, 2-Research, 3-Consumer)
    monitor_start_date: ""   # REQUIRED | Format: YYYYMMDD
    probe_height_m: null     # REQUIRED | Format: decimal (meters)
    monitoring_approach: null # REQUIRED | Format: integer (1-Stationary Cont, etc.)
    monitoring_objective: null # REQUIRED | Format: integer (1-Ambient, etc.)
    expanded_objective: ""   # REQUIRED | Format: string (max 128)
    airflow_arc_degrees: null # REQUIRED | Format: integer (0-360)
    instrument_photos_url: null # OPTIONAL | Format: string (max 200)
    dist_obstructions_m: null   # REQUIRED | Format: decimal
    dist_roof_obstructions_m: null # OPTIONAL | Format: decimal
    reg_network_affiliation: null # OPTIONAL | Format: string (max 64)
    reg_collecting_agency: null # OPTIONAL | Format: string (max 64)
    reg_agency_code: null       # OPTIONAL | Format: integer

    # --------------------------------------------------------------------------
    # PARAMETERS MEASURED BY THIS DEVICE
    # --------------------------------------------------------------------------
    parameters:
      - parameter_code: ""     # REQUIRED | Format: string | Matches tabular data
        measurement_technology_code: "" # REQUIRED | Format: string (XX-XX-XX)
        method_code: null        # OPTIONAL | Format: string | Matches tabular data
        sampling_frequency_sec: null # REQUIRED | Format: decimal (seconds)
        residence_time_sec: null # OPTIONAL | Format: decimal (seconds)
        corrections_applied: null        # REQUIRED | Format: boolean
        corrections_methods: null        # OPTIONAL | Format: string (Comma-separated)
        corrections_description: null    # OPTIONAL | Format: string (Free text)
        detection_limit_methods: null    # OPTIONAL | Format: string
        detection_limit_description: null       # OPTIONAL | Format: string
        precision_quantified: null       # OPTIONAL | Format: boolean
        precision_description: null             # OPTIONAL | Format: string
        bias_linearity_quantified: null  # OPTIONAL | Format: boolean
        bias_linearity_description: null        # OPTIONAL | Format: string
        accuracy_error_quantified: null  # OPTIONAL | Format: boolean
        accuracy_error_description: null        # OPTIONAL | Format: string
        maintenance_procedures_description: null # OPTIONAL | Format: string
        reg_monitor_type: null      # OPTIONAL | Format: string/integer
        reg_method_type: null       # OPTIONAL | Format: string/integer
        reg_analysis_method: null   # OPTIONAL | Format: string (max 64)
        reg_analytical_lab: null    # OPTIONAL | Format: string (max 64)
        reg_probe_material: null    # OPTIONAL | Format: string (max 64)