DarkMatterFM schema suite

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://darkmatterfm.org/schemas/bsm_model.schema.yaml"
title: "BSM dark-matter model card"
description: "Top-level schema for one structured BSM dark-matter model entry."
type: object
additionalProperties: false

properties:
  schema_version:
    type: string

  model_id:
    type: string
    pattern: '^[a-z0-9_-]+$'

  identity:
    type: object
    additionalProperties: false
    properties:
      name:
        type: string
      family:
        type: string
        examples:
          - cold_dark_matter
          - warm_dark_matter
          - fuzzy_ultralight_dark_matter
          - axion_like_dark_matter
          - sterile_neutrino_dark_matter
          - self_interacting_dark_matter
          - asymmetric_dark_matter
          - freeze_in_dark_matter
          - hidden_sector_dark_matter
          - primordial_black_holes
          - multi_component_dark_matter
      aliases:
        type: array
        items:
          type: string
      short_description:
        type: string
      historical_origin_or_motivation:
        type: string
      status:
        type: string
        enum:
          - canonical
          - speculative
          - emerging
          - benchmark
          - deprecated
          - excluded
          - unknown
      model_kind:
        type: string
        enum:
          - complete_theory
          - simplified_model
          - effective_field_theory
          - phenomenological_parameterization
          - benchmark_mapping
          - unknown
    required:
      - name
      - family
      - short_description
      - status
      - model_kind

  theory:
    type: object
    additionalProperties: false
    properties:
      theory_level:
        type: string
        enum:
          - uv_complete
          - simplified_model
          - effective_field_theory
          - phenomenological_parameterization
          - benchmark_mapping
          - unknown
      parent_frameworks:
        type: array
        items:
          type: string
      lagrangian_available:
        type: string
        enum: ['yes', 'no', partial, unknown, not_applicable]
      renormalizable:
        type: string
        enum: ['yes', 'no', unknown, not_applicable]
      eft_cutoff:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      embedded_in_larger_framework:
        type: string
        enum: ['yes', 'no', unknown]
      notes:
        type: string
    required:
      - theory_level
      - lagrangian_available
      - renormalizable

  particle_content:
    type: object
    additionalProperties: false
    properties:
      dark_matter_candidate:
        type: object
        additionalProperties: false
        properties:
          name:
            type: string
          spin:
            type: string
          statistics:
            type: string
            enum:
              - boson
              - fermion
              - scalar
              - vector
              - tensor
              - black_hole
              - macroscopic_object
              - unknown
          elementary_or_composite:
            type: string
            enum:
              - elementary
              - composite
              - macroscopic
              - unknown
          number_of_components:
            type: string
            enum:
              - single_component
              - multi_component
              - subcomponent
              - unknown
        required: [name, spin, statistics, elementary_or_composite]
      additional_dark_sector_particles:
        type: array
        items:
          type: string
      mediators:
        type: array
        items:
          type: string
      dark_radiation_species:
        type: array
        items:
          type: string
      excited_or_degenerate_states:
        type: array
        items:
          type: string
      long_lived_particles:
        type: array
        items:
          type: string
      unstable_parent_particles:
        type: array
        items:
          type: string
      standard_model_extension:
        type: string
        enum: [minimal, substantial, none, unknown]
    required:
      - dark_matter_candidate
      - standard_model_extension

  symmetries:
    type: object
    additionalProperties: false
    properties:
      stabilizing_mechanism:
        type: string
      symmetries:
        type: array
        items:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            type:
              type: string
              enum:
                - gauge
                - global
                - approximate
                - discrete
                - shift
                - accidental
                - unknown
            exact_or_approximate:
              type: string
              enum: [exact, approximate, assumed, broken, unknown]
            breaking:
              type: string
            breaking_scale:
              anyOf:
                - $ref: "common.schema.yaml#/$defs/parameter"
                - type: "null"
          required: [name, type, exact_or_approximate]
      topological_defects_possible:
        type: string
        enum: ['yes', 'no', unknown, not_applicable]
    required:
      - stabilizing_mechanism
      - symmetries

  interactions:
    type: object
    additionalProperties: false
    properties:
      portals:
        type: array
        items:
          type: string
          enum:
            - higgs
            - vector
            - neutrino
            - axion
            - gravitational
            - other
            - none
            - unknown
      standard_model_targets:
        type: array
        items:
          type: string
      dark_sector_couplings:
        type: array
        items:
          type: string
      mediator_types:
        type: array
        items:
          type: string
      interaction_operators:
        type: array
        items:
          type: string
      scattering:
        type: object
        additionalProperties: false
        properties:
          elastic:
            type: string
            enum: ['yes', 'no', unknown, not_applicable]
          inelastic:
            type: string
            enum: ['yes', 'no', parameter_dependent, unknown, not_applicable]
          momentum_dependence:
            type: string
            enum: [none, mild, strong, unknown, not_applicable]
          velocity_dependence:
            type: string
            enum: [none, mild, strong, parameter_dependent, unknown, not_applicable]
          spin_dependence:
            type: string
            enum: [none, spin_independent, spin_dependent, both, unknown, not_applicable]
      annihilation_channels:
        type: array
        items:
          type: string
      decay_channels:
        type: array
        items:
          type: string
      self_scattering_channels:
        type: array
        items:
          type: string
      cp_structure:
        type: string
      flavor_structure:
        type: string
      tree_or_loop_level:
        type: string
        enum: [tree, loop, both, unknown, not_applicable]
    required:
      - portals
      - standard_model_targets
      - mediator_types

  operators:
    type: object
    additionalProperties: false
    properties:
      renormalizable_terms:
        type: array
        items:
          type: string
      eft_operators:
        type: array
        items:
          type: string
      contact_or_light_mediator:
        type: string
        enum: [contact, light_mediator, both, unknown, not_applicable]
      coupling_types:
        type: array
        items:
          type: string

  parameters:
    type: object
    additionalProperties: false
    properties:
      core:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/parameter"
      nuisance:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/parameter"
      derived:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/parameter"
    required:
      - core

  mass_scales_and_hierarchies:
    type: object
    additionalProperties: false
    properties:
      scales:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/parameter"
      hierarchy_questions:
        type: array
        items:
          type: object
          additionalProperties: false
          properties:
            question:
              type: string
            answer:
              type: string
            status:
              $ref: "common.schema.yaml#/$defs/status"
          required: [question, answer, status]

  production:
    type: object
    additionalProperties: false
    properties:
      mechanisms:
        type: array
        items:
          type: string
      thermal_equilibrium_with_standard_model:
        type: string
        enum: ['yes', 'no', partial, unknown]
      thermal_equilibrium_with_hidden_sector:
        type: string
        enum: ['yes', 'no', partial, parameter_dependent, unknown, not_applicable]
      abundance_set_by:
        type: array
        items:
          type: string
      depends_on_reheating_temperature:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown]
      can_produce_all_dark_matter:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown]
      nonthermal_momentum_distribution:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown, not_applicable]
      notes:
        type: string
    required:
      - mechanisms
      - thermal_equilibrium_with_standard_model
      - can_produce_all_dark_matter

  relic_density:
    type: object
    additionalProperties: false
    properties:
      full_or_subcomponent:
        type: string
        enum: [full_dark_matter, subcomponent, either, unknown]
      target_fraction:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      calculation_type:
        type: string
        enum: [thermal, nonthermal, mixed, phenomenological, unknown]
      key_dependencies:
        type: array
        items:
          type: string
      requires_entropy_dilution:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown, not_applicable]
      overclosure_risk:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown]
      underproduction_risk:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown, not_applicable]
      tuning_assessment:
        type: string
        enum: [natural, mild_tuning, tuned, severe_tuning, parameter_dependent, unknown]
    required:
      - full_or_subcomponent
      - calculation_type

  cosmological_history:
    type: object
    additionalProperties: false
    properties:
      standard_history_assumed:
        type: boolean
      nonstandard_features:
        type: array
        items:
          type: string
      dark_sector_temperature:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      delta_neff:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      kinetic_decoupling:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      chemical_decoupling:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      phase_transitions:
        type: array
        items:
          type: string
      topological_defects:
        type: array
        items:
          type: string
      isocurvature_perturbations:
        type: string
        enum: ['yes', 'no', parameter_dependent, unknown]
      bbn_relevance:
        $ref: "common.schema.yaml#/$defs/relevance"
      cmb_relevance:
        $ref: "common.schema.yaml#/$defs/relevance"
      notes:
        type: [string, "null"]
    required:
      - standard_history_assumed
      - bbn_relevance
      - cmb_relevance

  phase_space:
    type: object
    additionalProperties: false
    properties:
      distribution_type:
        type: string
        enum:
          - thermal
          - nonthermal
          - resonant
          - decay_produced
          - mixed_cold_warm
          - field_like
          - not_applicable
          - unknown
      distribution_function_available:
        type: string
        enum: ['yes', 'no', approximate, unknown, not_applicable]
      f_of_p_or_q:
        type: [string, "null"]
      average_momentum_relative_to_thermal:
        anyOf:
          - type: number
          - type: string
          - type: "null"
      free_streaming_length:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: "null"
      velocity_dispersion_today:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter"
          - type: string
          - type: "null"
      phase_space_bounds:
        type: array
        items:
          type: string
      notes:
        type: [string, "null"]
    required:
      - distribution_type
      - distribution_function_available

  structure_formation:
    type: object
    additionalProperties: false
    properties:
      linear:
        type: object
        additionalProperties: false
        properties:
          behaves_like_cdm:
            type: string
            enum: ['yes', 'no', approximately, scale_dependent, unknown]
          transfer_function_shape:
            type: string
            enum:
              - cdm_like
              - smooth_cutoff
              - oscillatory
              - step_like
              - mixed_cold_warm
              - enhanced_small_scale_power
              - scale_dependent_growth
              - unknown
          small_scale_power_effect:
            type: string
            enum: [suppression, enhancement, oscillations, none, mixed, unknown]
          half_mode_mass:
            anyOf:
              - $ref: "common.schema.yaml#/$defs/parameter"
              - type: "null"
          thermal_wdm_mapping:
            type: object
            additionalProperties: false
            properties:
              available:
                type: boolean
              validity:
                type: string
                enum: [valid, approximate, misleading, invalid, unknown, not_applicable]
              warning:
                type: string
            required: [available, validity]
          impact_on_sigma8_s8:
            type: string
        required:
          - behaves_like_cdm
          - transfer_function_shape
          - small_scale_power_effect
      nonlinear:
        type: object
        additionalProperties: false
        properties:
          halo_mass_function_effect:
            type: string
          subhalo_mass_function_effect:
            type: string
          infall_subhalo_mass_function_effect:
            type: string
          present_day_bound_subhalo_mass_function_effect:
            type: string
          concentration_mass_relation_effect:
            type: string
          density_profile_effect:
            type: string
          core_or_cusp_effect:
            type: string
          subhalo_survival_effect:
            type: string
          tidal_stripping_effect:
            type: string
          smallest_galaxies_effect:
            type: string
          simulation_calibrated:
            type: string
            enum: ['yes', 'no', partial, unknown]
        required:
          - halo_mass_function_effect
          - subhalo_mass_function_effect
          - simulation_calibrated
      notes:
        type: [string, "null"]
    required:
      - linear
      - nonlinear

  environment_dependence:
    type: object
    additionalProperties: false
    properties:
      depends_on_host_halo_mass:
        type: boolean
      depends_on_redshift:
        type: boolean
      depends_on_velocity_dispersion:
        type: boolean
      depends_on_local_density:
        type: boolean
      relevant_environments:
        type: array
        items:
          type: string
      baryonic_feedback_degeneracy:
        type: string
        enum: [high, medium, low, none, unknown]
      notes:
        type: string

  observables:
    type: array
    items:
      $ref: "observable.schema.yaml#/$defs/observable"

  constraints:
    type: array
    description: >
      Flat list of constraint entries; each entry's `applies` field records
      whether/how it applies (the earlier applicable/not_applicable buckets
      are folded into that field).
    items:
      $ref: "constraint.schema.yaml#/$defs/constraint"

  validity_domain:
    type: array
    items:
      $ref: "common.schema.yaml#/$defs/validity_entry"

  degeneracies_and_confounders:
    type: object
    additionalProperties: false
    properties:
      astrophysical:
        type: array
        items:
          type: string
      cosmological:
        type: array
        items:
          type: string
      experimental:
        type: array
        items:
          type: string
      analysis_level:
        type: array
        items:
          type: string

  computational_representation:
    type: object
    additionalProperties: false
    properties:
      analytic_formula_available:
        type: string
        enum: ['yes', 'no', approximate, unknown]
      boltzmann_solver_required:
        type: string
        enum: [none, class, camb, modified_class, modified_camb, unknown]
      simulations_required:
        type: array
        items:
          type: string
      semi_analytic_model_available:
        type: string
        enum: ['yes', 'no', partial, unknown]
      emulator_available:
        type: string
        enum: ['yes', 'no', partial, unknown]
      likelihoods_available:
        type: array
        items:
          type: string
      public_codes:
        type: array
        items:
          type: string
      recasting_pipeline_available:
        type: string
        enum: ['yes', 'no', partial, unknown]
      custom_requirements:
        type: array
        items:
          type: string
    required:
      - analytic_formula_available
      - boltzmann_solver_required
      - emulator_available


  associated_code:
    $ref: "code.schema.yaml#/$defs/associated_code"

  theory_to_observable_routing:
    type: object
    additionalProperties: false
    properties:
      routes:
        type: array
        items:
          $ref: "route.schema.yaml#/$defs/route"
    required:
      - routes

  assumptions:
    type: object
    additionalProperties: false
    properties:
      global:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/assumption"
      constraint_specific:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/assumption"
      computation_specific:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/assumption"
    required:
      - global

  provenance:
    $ref: "provenance.schema.yaml#/$defs/provenance"

  model_comparison:
    type: object
    additionalProperties: false
    properties:
      theoretical_motivation:
        type: string
        enum: [low, medium, high, unknown]
      naturalness:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      minimality:
        type: string
        enum: [low, medium, high, unknown]
      explanatory_power:
        type: array
        items:
          type: string
      observational_distinctiveness:
        type: string
        enum: [low, medium, high, unknown]
      near_term_testability:
        type: string
        enum: [low, medium, high, unknown]
      compatibility_with_current_data:
        type: string
        enum: [allowed, partially_allowed, excluded, disputed, unknown]
      complementarity_across_probes:
        type: string
        enum: [low, medium, high, unknown]
      public_tool_availability:
        type: string
        enum: [none, partial, good, excellent, unknown]

  robustness:
    $ref: "common.schema.yaml#/$defs/robustness"

  benchmarks:
    type: object
    additionalProperties: false
    properties:
      points:
        type: array
        items:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
            description:
              type: string
            status:
              type: string
              enum:
                - allowed
                - excluded
                - near_future_testable
                - stress_test
                - emulator_training
                - likelihood_validation
                - unknown
            parameter_values:
              type: object
            purpose:
              type: array
              items:
                type: string
          required: [id, description, status]
      regimes:
        type: array
        items:
          type: string

  agent_failure_modes:
    type: object
    additionalProperties: false
    properties:
      warnings:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/agent_warning"
    required:
      - warnings

  relations:
    type: object
    additionalProperties: false
    description: >
      Typed, directed edges from this model to other models in the registry.
      Intended to be populated after deduplication into canonical entries,
      so that targets are canonical model_ids; edges between per-paper
      duplicate cards are not meaningful. Together with the family taxonomy
      (coarse grouping) and dedup clusters (identity), these edges form the
      model-relations graph and upgrade novelty checking from "is this model
      already in the registry?" to "where does this model sit in theory space?".
    properties:
      edges:
        type: array
        items:
          type: object
          additionalProperties: false
          properties:
            relation:
              type: string
              enum:
                - special_case_of
                - generalizes
                - equivalent_in_limit
                - uv_completion_of
                - effective_limit_of
                - shares_portal
                - shares_mediator
                - shares_production_mechanism
                - same_signature_degenerate_with
                - embedded_in_same_framework
                - competes_with
                - other
            target_model_id:
              type: string
              pattern: '^[a-z0-9_-]+$'
            target_model_name:
              type:
                - string
                - "null"
            limit_or_condition:
              type:
                - string
                - "null"
              description: >
                Parameter limit or condition under which the relation holds
                (e.g. "m_mediator -> infinity recovers the EFT", "theta -> 0").
            rationale:
              type: string
            confidence:
              type: string
              enum: [low, medium, high, unknown]
          required: [relation, target_model_id, rationale]
    required:
      - edges

  capability_gaps:
    type: object
    additionalProperties: false
    description: >
      First-class record of what is MISSING to evaluate this model against
      data: theoretical derivations, tools, simulations, emulators,
      likelihoods, or data products. Complements computational_representation
      (which records what exists) and route steps with status missing/partial.
      Aggregated registry-wide, these entries form a community development
      roadmap: which capabilities, if built, unblock the most high-priority
      models.
    properties:
      gaps:
        type: array
        items:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
              pattern: '^[a-z0-9_-]+$'
            gap_type:
              type: string
              enum:
                - theory
                - derivation
                - tool
                - simulation
                - emulator
                - likelihood
                - data
                - calibration
                - other
            description:
              type: string
            blocking_observables:
              type: array
              description: >
                Observable ids or channels that cannot be evaluated until
                this gap is closed.
              items:
                type: string
            blocking_routes:
              type: array
              description: >
                Route or forward-model-chain step ids whose status is
                missing/partial because of this gap.
              items:
                type: string
            proposed_resolution:
              type:
                - string
                - "null"
              description: >
                Concrete suggested approach to close the gap (e.g. "extend the
                ETHOS parameterization in a modified CLASS to cover oscillatory
                kinetic decoupling").
            estimated_effort:
              type: string
              enum: [small, medium, large, major_program, unknown]
            severity:
              type: string
              enum:
                - blocks_all_observables
                - blocks_key_observables
                - degrades_precision
                - minor
                - unknown
          required: [gap_type, description]
    required:
      - gaps

required:
  - schema_version
  - model_id
  - identity
  - theory
  - particle_content
  - symmetries
  - interactions
  - parameters
  - production
  - relic_density
  - cosmological_history
  - phase_space
  - structure_formation
  - validity_domain
  - assumptions
  - associated_code
  - provenance
  - robustness
  - agent_failure_modes

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://darkmatterfm.org/schemas/common.schema.yaml"
title: "Common reusable schema definitions"
description: >
  Shared definitions used across the DarkMatterFM BSM dark-matter theory
  registry schemas.
type: object
additionalProperties: false

$defs:
  confidence_level:
    type: string
    enum: [low, medium, high, unknown]

  relevance:
    type: string
    description: "How relevant a phenomenon, constraint, or observable is for this model."
    enum: [none, low, medium, high, critical, unknown, not_applicable]

  status:
    type: string
    description: "Generic evidence or implementation status."
    enum:
      - established
      - inferred
      - assumed
      - approximate
      - speculative
      - disputed
      - excluded
      - deprecated
      - specified
      - derived
      - benchmark
      - unknown
      - not_applicable

  yes_no_unknown:
    type: string
    enum: ['yes', 'no', partial, unknown, not_applicable]

  scalar_or_string:
    anyOf:
      - type: number
      - type: string
      - type: boolean
      - type: "null"

  numeric_or_symbolic_value:
    anyOf:
      - type: number
      - type: string
      - type: "null"
      - type: array
        items:
          anyOf:
            - type: number
            - type: string
            - type: "null"
      - type: object
        additionalProperties: true

  parameter_range:
    type: object
    additionalProperties: false
    properties:
      min:
        $ref: "#/$defs/numeric_or_symbolic_value"
      max:
        $ref: "#/$defs/numeric_or_symbolic_value"
      inclusive_min:
        type: boolean
      inclusive_max:
        type: boolean
      unit:
        type: [string, "null"]
      notes:
        type: [string, "null"]
    required: [min, max]

  parameter:
    type: object
    additionalProperties: false
    description: >
      A physical, nuisance, derived, computational, or phenomenological parameter.
      Values may be numeric, symbolic, null, or structured when the allowed range is
      model-dependent.
    properties:
      name:
        type: string
      symbol:
        type: [string, "null"]
      description:
        type: [string, "null"]
      value:
        $ref: "#/$defs/numeric_or_symbolic_value"
      fiducial_value:
        $ref: "#/$defs/numeric_or_symbolic_value"
      range:
        anyOf:
          - $ref: "#/$defs/parameter_range"
          - type: array
            minItems: 2
            maxItems: 2
            items:
              $ref: "#/$defs/numeric_or_symbolic_value"
          - type: string
          - type: "null"
      unit:
        type: [string, "null"]
      prior:
        type: [string, "null"]
        examples: [linear_uniform, log_uniform, literature_informed, fixed, derived]
      scale:
        type: [string, "null"]
        enum: [linear, log, log10, natural_log, categorical, derived, null]
      role:
        type: [string, "null"]
        enum: [core, nuisance, derived, benchmark, computational, cosmological, astrophysical, experimental, phenomenological, null]
      status:
        $ref: "#/$defs/status"
      source_reference_ids:
        type: array
        items:
          type: string
      notes:
        type: [string, "null"]
    required: [name]

  assumption:
    type: object
    additionalProperties: false
    properties:
      id:
        type: string
      description:
        type: string
      scope:
        type: string
        description: >
          Free-form scope label; extraction uses a rich vocabulary
          (e.g. "direct detection", "Lyman-alpha recast").
        examples:
          - global
          - theory
          - cosmological_history
          - production
          - structure_formation
          - observable
          - constraint
          - computation
          - emulator
          - likelihood
          - other
      status:
        $ref: "#/$defs/status"
      impact_if_violated:
        type: [string, "null"]
      can_be_relaxed:
        type: string
        enum: ['yes', 'no', partial, unknown, not_applicable]
      source_reference_ids:
        type: array
        items:
          type: string
      notes:
        type: [string, "null"]
    required: [id, description, scope, status]

  validity_entry:
    type: object
    additionalProperties: false
    properties:
      id:
        type: string
      applies_to:
        type: string
        examples: [model, parameter, observable, likelihood, emulator, transfer_function, EFT]
      condition:
        type: string
      valid_range:
        anyOf:
          - $ref: "#/$defs/parameter_range"
          - type: string
          - type: "null"
      status:
        $ref: "#/$defs/status"
      extrapolation_risk:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      caveats:
        type: array
        items:
          type: string
      source_reference_ids:
        type: array
        items:
          type: string
      notes:
        type: [string, "null"]
    required: [id, applies_to, condition, status]

  robustness:
    type: object
    additionalProperties: false
    properties:
      overall:
        type: string
        enum: [low, medium, high, unknown]
      theory_robustness:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      observational_robustness:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      computational_robustness:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      constraint_robustness:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      dominant_uncertainties:
        type: array
        items:
          type: string
      validation_status:
        type: string
        enum:
          - validated
          - partially_validated
          - smoke_test_only
          - unvalidated
          - expert_judgment_only
          - unknown
      notes:
        type: [string, "null"]
    required: [overall]

  agent_warning:
    type: object
    additionalProperties: false
    description: >
      A failure mode or caution that an automated agent should surface before
      using this model entry in reasoning, routing, or inference.
    properties:
      id:
        type: string
      severity:
        type: string
        enum: [low, medium, high, critical, unknown]
      category:
        type: string
        enum:
          - invalid_mapping
          - extrapolation
          - assumption_mismatch
          - missing_likelihood
          - approximate_constraint
          - disputed_claim
          - code_unvalidated
          - degeneracy
          - unit_convention
          - notation_conflict
          - other
      warning:
        type: string
      mitigation:
        type: [string, "null"]
      source_reference_ids:
        type: array
        items:
          type: string
    required: [id, severity, category, warning]

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://darkmatterfm.org/schemas/observable.schema.yaml"
title: "Observable schema"
description: "Reusable observable-channel definition for BSM dark-matter model entries."
type: object
additionalProperties: false

$defs:
  observable:
    type: object
    additionalProperties: false
    properties:
      id:
        type: string
        pattern: "^[a-z0-9_-]+$"
      name:
        type: string
      channel:
        type: string
        enum:
          - cosmology
          - cmb
          - lyman_alpha
          - large_scale_structure
          - small_scale_structure
          - milky_way_satellites
          - stellar_streams
          - strong_lensing
          - dwarf_galaxies
          - clusters
          - direct_detection
          - indirect_detection
          - collider
          - precision_laboratory
          - gravitational_waves
          - black_holes
          - other
          - unknown
      subchannel:
        type: [string, "null"]
      predicted_effect:
        type: string
        description: "Qualitative effect expected in this observable."
      effect_direction:
        type: string
        enum:
          - suppression
          - enhancement
          - oscillatory
          - shape_change
          - rate_change
          - spectral_line
          - morphology_change
          - null_signal
          - model_dependent
          - unknown
          - not_applicable
      key_quantities:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/parameter"
      redshift_range:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter_range"
          - type: string
          - type: "null"
      scale_range:
        anyOf:
          - $ref: "common.schema.yaml#/$defs/parameter_range"
          - type: string
          - type: "null"
      environments:
        type: array
        items:
          type: string
      observability:
        type: string
        enum: [low, medium, high, unknown, not_applicable]
      relevance:
        $ref: "common.schema.yaml#/$defs/relevance"
      linked_constraints:
        type: array
        items:
          type: string
      linked_routes:
        type: array
        items:
          type: string
      caveats:
        type: array
        items:
          type: string
      source_reference_ids:
        type: array
        items:
          type: string
      notes:
        type: [string, "null"]
    required:
      - id
      - name
      - channel
      - predicted_effect
      - effect_direction
      - relevance

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://darkmatterfm.org/schemas/constraint.schema.yaml"
title: "Constraint schema"
description: "Reusable schema for constraints on BSM dark-matter models."
type: object
additionalProperties: false

$defs:
  constraint:
    type: object
    additionalProperties: false
    properties:
      id:
        type: string
        pattern: "^[a-z0-9_-]+$"
      name:
        type: string
      constraint_type:
        type: string
        enum:
          - direct_detection
          - indirect_detection
          - cosmological
          - astrophysical
          - collider
          - laboratory
          - theoretical
          - numerical
          - other
          - unknown
      observable_channel:
        type: string
      applies:
        type: string
        enum: ['yes', 'no', parameter_dependent, recast_required, unknown, not_applicable]
      constrained_parameters:
        type: array
        items:
          type: string
      excluded_regions:
        type: array
        items:
          type: string
      allowed_regions:
        type: array
        items:
          type: string
      benchmark_implications:
        type: array
        items:
          type: string
      likelihood_available:
        type: string
        enum: ['yes', 'no', partial, approximate, unknown]
      likelihood_reference:
        type: [string, "null"]
      data_release:
        type: [string, "null"]
      recasting_needed:
        type: string
        enum: ['yes', 'no', partial, unknown, not_applicable]
      robustness:
        type: string
        enum: [low, medium, high, unknown]
      assumptions:
        type: array
        items:
          $ref: "common.schema.yaml#/$defs/assumption"
      caveats:
        type: array
        items:
          type: string
      source_reference_ids:
        type: array
        items:
          type: string
      notes:
        type: [string, "null"]
    required:
      - id
      - name
      - constraint_type
      - observable_channel
      - applies
      - robustness

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://darkmatterfm.org/schemas/route.schema.yaml"
title: "Theory-to-observable routing schema"
description: >
  Schema for routing a BSM dark-matter model from theory parameters to
  observables, forward models, emulators, and likelihoods.
type: object
additionalProperties: false

$defs:
  route:
    type: object
    additionalProperties: false
    properties:
      id:
        type: string
        pattern: "^[a-z0-9_-]+$"
      description:
        type: string
      source_model_features:
        type: array
        description: "Model features or parameters that trigger this route."
        items:
          type: string
      input_parameters:
        type: array
        items:
          type: string
      derived_quantities:
        type: array
        items:
          type: string
      forward_model_chain:
        type: array
        description: "Ordered sequence of computations from theory to observable."
        items:
          type: object
          additionalProperties: false
          properties:
            step_id:
              type: string
            step_type:
              type: string
              enum:
                - analytic_formula
                - boltzmann_solver
                - transfer_function
                - emulator
                - semi_analytic_model
                - simulation
                - likelihood
                - recasting
                - data_transform
                - validation
                - other
            tool_or_code:
              type: [string, "null"]
            status:
              type: string
              description: >
                Whether the capability this step needs actually exists.
                "missing"/"partial" steps are capability gaps; cross-reference
                them from the card's capability_gaps block via blocking_routes.
              enum: [available, partial, missing, unknown]
            inputs:
              type: array
              items:
                type: string
            outputs:
              type: array
              items:
                type: string
            validity:
              type: [string, "null"]
            notes:
              type: [string, "null"]
          required: [step_id, step_type]
      observable_ids:
        type: array
        items:
          type: string
      constraint_ids:
        type: array
        items:
          type: string
      likelihoods:
        type: array
        items:
          type: string
      required_code_resources:
        type: array
        items:
          type: string
      validation_tests:
        type: array
        items:
          type: string
      route_status:
        type: string
        enum: [implemented, partially_implemented, planned, unavailable, unknown]
      agent_notes:
        type: [string, "null"]
      caveats:
        type: array
        items:
          type: string
    required:
      - id
      - description
      - source_model_features
      - forward_model_chain
      - observable_ids
      - route_status

$schema: https://json-schema.org/draft/2020-12/schema
$id: https://darkmatterfm.org/schemas/provenance.schema.yaml
title: Provenance schema for a BSM dark-matter model entry
description: Reusable provenance definition for a BSM dark-matter theory registry
  entry.
type: object
additionalProperties: false
$defs:
  provenance:
    type: object
    additionalProperties: false
    required:
    - model_id
    - entry_version
    - status
    - created_at
    - last_updated
    - sources
    - extraction
    - evidence
    - review
    properties:
      model_id:
        type: string
        description: Stable registry identifier for the model entry.
        examples:
        - sterile_neutrino_resonant_v1
        - fuzzy_dark_matter_ultralight_scalar_v1
      model_name:
        type:
        - string
        - 'null'
        description: Human-readable model name.
      model_family:
        type:
        - string
        - 'null'
        description: Broad family or class of the dark-matter model.
        examples:
        - warm_dark_matter
        - sterile_neutrino
        - axion_like_particle
        - self_interacting_dark_matter
        - asymmetric_dark_matter
        - freeze_in_dark_matter
      entry_version:
        type: string
        description: Semantic version of this registry entry.
        pattern: ^v?[0-9]+\.[0-9]+\.[0-9]+$
        examples:
        - 0.1.0
        - v1.0.0
      status:
        type: string
        description: Current provenance/review state of the registry entry.
        enum:
        - draft
        - machine_extracted
        - human_reviewed
        - expert_reviewed
        - deprecated
      created_at:
        type: string
        format: date
        description: Date on which this registry entry was created.
      last_updated:
        type: string
        format: date
        description: Date on which this registry entry was last updated.
      sources:
        type: object
        additionalProperties: false
        required:
        - primary_papers
        properties:
          primary_papers:
            type: array
            description: Original or central papers defining the model.
            items:
              $ref: '#/$defs/source_document'
          review_papers:
            type: array
            description: Review papers used to contextualize the model.
            items:
              $ref: '#/$defs/source_document'
          constraint_papers:
            type: array
            description: Papers imposing observational, cosmological, astrophysical,
              collider, or laboratory constraints.
            items:
              allOf:
              - $ref: '#/$defs/source_document'
              - type: object
                properties:
                  observable_channel:
                    type: string
                    description: Observable or data channel to which the constraint
                      applies.
                  constraint_type:
                    type: string
                    enum:
                    - direct_detection
                    - indirect_detection
                    - cosmological
                    - astrophysical
                    - collider
                    - laboratory
                    - theoretical
                    - other
          external_databases:
            type: array
            description: External databases or registries used as sources.
            items:
              type: object
              additionalProperties: false
              required:
              - name
              properties:
                name:
                  type: string
                url:
                  type:
                  - string
                  - 'null'
                  format: uri
                note:
                  type:
                  - string
                  - 'null'
      extraction:
        type: object
        additionalProperties: false
        required:
        - method
        - extracted_by
        - extraction_date
        - confidence
        properties:
          method:
            type: string
            enum:
            - manual
            - llm_assisted
            - automated_parser
            - imported_from_code
            - imported_from_database
            - mixed
          extracted_by:
            type: string
            description: Human, agent, script, or database responsible for extraction.
          extractor_name:
            type:
            - string
            - 'null'
            description: Optional name/version of extractor, agent, parser, or person.
          extraction_date:
            type: string
            format: date
          confidence:
            type: string
            enum:
            - low
            - medium
            - high
          source_chunks_or_sections:
            type: array
            description: Specific document locations used during extraction.
            items:
              type: object
              additionalProperties: false
              required:
              - reference_id
              properties:
                reference_id:
                  type: string
                section:
                  type:
                  - string
                  - 'null'
                page:
                  type:
                  - integer
                  - 'null'
                  minimum: 1
                quote_or_summary:
                  type:
                  - string
                  - 'null'
          unresolved_items:
            type: array
            description: Open questions or fields that could not be extracted reliably.
            items:
              type: string
      evidence:
        type: object
        description: 'Map from registry physics claims to supporting references. Each
          top-level key should correspond to a major physics block in the model entry.

          '
        additionalProperties:
          type: array
          items:
            $ref: '#/$defs/evidence_item'
        properties:
          particle_content:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          symmetries:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          interactions:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          production_mechanism:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          cosmological_history:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          parameter_ranges:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          observable_signatures:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          constraints:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
          validity_domain:
            type: array
            items:
              $ref: '#/$defs/evidence_item'
      review:
        type: object
        additionalProperties: false
        required:
        - human_reviewed
        - expert_reviewed
        - scientific_confidence
        - implementation_confidence
        properties:
          human_reviewed:
            type: boolean
          reviewed_by:
            type:
            - string
            - 'null'
          review_date:
            type:
            - string
            - 'null'
            format: date
          expert_reviewed:
            type: boolean
          expert_reviewer:
            type:
            - string
            - 'null'
          expert_review_date:
            type:
            - string
            - 'null'
            format: date
          reviewer_notes:
            type: array
            items:
              type: string
          scientific_confidence:
            type: string
            enum:
            - low
            - medium
            - high
          implementation_confidence:
            type: string
            enum:
            - low
            - medium
            - high
      versioning:
        type: object
        additionalProperties: false
        properties:
          current_version:
            type: string
          previous_versions:
            type: array
            items:
              type: object
              additionalProperties: false
              required:
              - version
              - date
              - change_summary
              properties:
                version:
                  type: string
                date:
                  type: string
                  format: date
                change_summary:
                  type: string
          change_log:
            type: array
            items:
              type: object
              additionalProperties: false
              required:
              - date
              - change_type
              - description
              properties:
                date:
                  type: string
                  format: date
                changed_by:
                  type:
                  - string
                  - 'null'
                change_type:
                  type: string
                  enum:
                  - added
                  - modified
                  - corrected
                  - deprecated
                  - reviewed
                description:
                  type: string
      caveats:
        type: array
        description: Known caveats, ambiguities, disputed interpretations, or mapping
          limitations.
        items:
          type: string
      related_entries:
        type: array
        description: Links to related model entries in the registry.
        items:
          type: object
          additionalProperties: false
          required:
          - model_id
          - relation
          properties:
            model_id:
              type: string
            relation:
              type: string
              enum:
              - parent_model
              - child_model
              - limiting_case
              - benchmark_variant
              - phenomenological_mapping
              - same_signature_class
              - related_uv_completion
              - other
            note:
              type:
              - string
              - 'null'
      external_links:
        type: object
        additionalProperties: false
        properties:
          public_codes:
            type: array
            items:
              $ref: '#/$defs/external_resource'
          likelihoods:
            type: array
            items:
              allOf:
              - $ref: '#/$defs/external_resource'
              - type: object
                properties:
                  observable_channel:
                    type:
                    - string
                    - 'null'
          datasets:
            type: array
            items:
              allOf:
              - $ref: '#/$defs/external_resource'
              - type: object
                properties:
                  observable_channel:
                    type:
                    - string
                    - 'null'
  source_document:
    type: object
    additionalProperties: false
    required:
    - reference_id
    - title
    - role
    properties:
      reference_id:
        type: string
        description: Local citation key or bibliographic identifier.
      title:
        type: string
      authors:
        type: array
        items:
          type: string
      year:
        type:
        - integer
        - 'null'
      arxiv_id:
        type:
        - string
        - 'null'
      doi:
        type:
        - string
        - 'null'
      url:
        type:
        - string
        - 'null'
        format: uri
      role:
        type: string
        enum:
        - original_model
        - primary_model_source
        - extension
        - benchmark
        - review
        - constraint
        - implementation
        - dataset
        - likelihood
        - other
      notes:
        type:
        - string
        - 'null'
  evidence_item:
    type: object
    additionalProperties: false
    required:
    - reference_id
    - note
    properties:
      reference_id:
        type: string
      note:
        type: string
      confidence:
        type: string
        enum:
        - low
        - medium
        - high
      section:
        type:
        - string
        - 'null'
      page:
        type:
        - integer
        - 'null'
        minimum: 1
  external_resource:
    type: object
    additionalProperties: false
    required:
    - name
    - purpose
    properties:
      name:
        type: string
      url:
        type:
        - string
        - 'null'
        format: uri
      purpose:
        type: string
      notes:
        type:
        - string
        - 'null'

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://darkmatterfm.org/schemas/code.schema.yaml"
title: "Code resources schema for BSM dark-matter model entries"
description: >
  Reusable schema for recording whether a BSM dark-matter model has associated
  software, repositories, notebooks, simulation tools, likelihood code,
  emulators, or analysis pipelines. This is intended to distinguish official
  model implementations from community reimplementations, wrappers, constraint
  pipelines, and unpublished private code.
type: object
additionalProperties: false

$defs:
  associated_code:
    type: object
    additionalProperties: false
    description: >
      Structured description of code associated with the model. This should be
      present even when no code is known, so the registry can distinguish
      "checked and none found" from "not yet checked".
    required:
      - has_associated_code
    properties:
      has_associated_code:
        type: string
        description: "Whether any code is known to be associated with this model entry."
        enum:
          - 'yes'
          - 'no'
          - partial
          - unknown

      code_summary:
        type:
          - string
          - "null"
        description: "Short human-readable summary of known code resources or absence of code."

      primary_code_role:
        type:
          - string
          - "null"
        description: "Main role of the associated code, if there is one."
        enum:
          - model_definition
          - relic_density_calculation
          - boltzmann_solver_patch
          - transfer_function
          - halo_model
          - structure_formation_simulation
          - emulator
          - likelihood
          - recasting_pipeline
          - compute_cross_sections
          - direct_detection_rate
          - indirect_detection_signal
          - collider_simulation
          - notebook_or_example
          - data_processing
          - visualization
          - other
          - unknown
          - null

      repositories:
        type: array
        description: "Public, private, or on-request repositories associated with the model."
        items:
          $ref: "#/$defs/code_resource"

      packages_or_modules:
        type: array
        description: "Installable packages, modules, or code components relevant to the model."
        items:
          $ref: "#/$defs/code_resource"

      notebooks:
        type: array
        description: "Tutorial, validation, or analysis notebooks associated with the model."
        items:
          $ref: "#/$defs/code_resource"

      scripts:
        type: array
        description: "Standalone scripts associated with the model."
        items:
          $ref: "#/$defs/code_resource"

      containers_or_environments:
        type: array
        description: "Docker/Singularity images, conda environments, requirements files, or other execution environments."
        items:
          $ref: "#/$defs/execution_environment"

      expected_inputs:
        type: array
        description: "Typical inputs expected by the associated code."
        items:
          type: string
        examples:
          - model_parameters
          - cosmological_parameters
          - transfer_function
          - halo_catalog
          - likelihood_data_vector

      expected_outputs:
        type: array
        description: "Typical outputs produced by the associated code."
        items:
          type: string
        examples:
          - relic_density
          - transfer_function
          - matter_power_spectrum
          - half_mode_mass
          - direct_detection_rate
          - log_likelihood

      supported_observable_channels:
        type: array
        description: "Observable channels supported by the code."
        items:
          type: string
        examples:
          - cmb
          - lyman_alpha
          - satellite_counts
          - stellar_streams
          - strong_lensing
          - direct_detection
          - indirect_detection
          - collider

      reproducibility:
        type: object
        additionalProperties: false
        description: "How reproducible and usable the code is for this model entry."
        properties:
          reproducibility_level:
            type: string
            enum:
              - exact
              - approximate
              - partial
              - not_reproducible
              - unknown
          has_tests:
            type: string
            enum: ['yes', 'no', partial, unknown]
          has_examples:
            type: string
            enum: ['yes', 'no', partial, unknown]
          has_documentation:
            type: string
            enum: ['yes', 'no', partial, unknown]
          pinned_dependencies:
            type: string
            enum: ['yes', 'no', partial, unknown]
          notes:
            type:
              - string
              - "null"

      validation:
        type: object
        additionalProperties: false
        description: "Validation status of the associated code for this model."
        properties:
          validation_status:
            type: string
            enum:
              - validated_against_paper
              - validated_against_public_benchmark
              - internally_validated
              - smoke_test_only
              - unvalidated
              - unknown
          benchmark_references:
            type: array
            items:
              type: string
          validation_notes:
            type:
              - string
              - "null"

      caveats:
        type: array
        description: "Known caveats, limitations, missing dependencies, licensing issues, or code/model mismatches."
        items:
          type: string

  code_resource:
    type: object
    additionalProperties: false
    required:
      - name
      - resource_type
      - availability
      - relationship_to_model
      - purpose
    properties:
      name:
        type: string
        description: "Name of the code resource, repository, package, notebook, or script."

      resource_type:
        type: string
        enum:
          - repository
          - package
          - module
          - script
          - notebook
          - patch
          - fork
          - container
          - web_service
          - data_release_code
          - unknown

      availability:
        type: string
        enum:
          - public
          - private
          - on_request
          - restricted
          - unavailable
          - unknown

      relationship_to_model:
        type: string
        description: "How directly this code is connected to the model."
        enum:
          - official_author_code
          - official_collaboration_code
          - community_implementation
          - independent_reimplementation
          - wrapper_around_public_tool
          - constraint_analysis_code
          - emulator_training_code
          - benchmark_or_tutorial
          - used_for_analysis
          - related_but_not_model_specific
          - unknown

      purpose:
        type: array
        description: "Tasks this code can perform."
        items:
          type: string
          enum:
            - define_lagrangian
            - compute_relic_density
            - compute_decay_rates
            - compute_cross_sections
            - solve_boltzmann_equations
            - compute_transfer_function
            - compute_matter_power_spectrum
            - compute_hmf_or_shmf
            - run_simulations
            - train_emulator
            - run_emulator
            - compute_likelihood
            - recast_constraints
            - collider_simulation
            - generate_benchmarks
            - reproduce_figures
            - process_data
            - other

      url:
        type:
          - string
          - "null"
        format: uri

      repository_url:
        type:
          - string
          - "null"
        format: uri

      documentation_url:
        type:
          - string
          - "null"
        format: uri

      archive_url:
        type:
          - string
          - "null"
        format: uri
        description: "Permanent archive URL, for example Zenodo or institutional archive."

      doi:
        type:
          - string
          - "null"

      license:
        type:
          - string
          - "null"

      languages:
        type: array
        items:
          type: string
        examples:
          - Python
          - C
          - C++
          - Fortran
          - Julia

      version:
        type:
          - string
          - "null"
        description: "Version, release tag, or semantic version."

      commit:
        type:
          - string
          - "null"
        description: "Pinned commit hash if needed for reproducibility."

      last_checked:
        type:
          - string
          - "null"
        format: date

      maintained:
        type: string
        enum:
          - 'yes'
          - 'no'
          - unknown
          - not_applicable

      dependencies:
        type: array
        items:
          type: string

      supported_parameters:
        type: array
        description: "Model or nuisance parameters explicitly supported by the code."
        items:
          type: string

      supported_model_families:
        type: array
        description: "Model families this code supports."
        items:
          type: string

      supported_observables:
        type: array
        description: "Observables or likelihood channels supported by the code."
        items:
          type: string

      inputs:
        type: array
        items:
          type: string

      outputs:
        type: array
        items:
          type: string

      validity_domain:
        type: array
        description: "Known validity limits for this code resource."
        items:
          type: string

      citation_reference_ids:
        type: array
        description: "Reference IDs from the provenance block that should be cited when using this code."
        items:
          type: string

      notes:
        type:
          - string
          - "null"

  execution_environment:
    type: object
    additionalProperties: false
    required:
      - environment_type
      - name
    properties:
      environment_type:
        type: string
        enum:
          - conda
          - pip_requirements
          - docker
          - singularity
          - spack
          - module_file
          - nix
          - other
          - unknown
      name:
        type: string
      url:
        type:
          - string
          - "null"
        format: uri
      file_path:
        type:
          - string
          - "null"
      version_or_tag:
        type:
          - string
          - "null"
      notes:
        type:
          - string
          - "null"