refactor(dataset): replace free-form attributes with typed structs

Introduce DatasetAttributes and PathogenAttributes structs with typed
fields for recognized keys (name, reference name, reference accession,
deprecated, experimental) plus #[serde(flatten)] for extensibility.

Author: ivan-aksamentov

packages/nextclade-cli/src/dataset/dataset_table.rs

@@ -35,13 +35,7 @@ pub fn format_dataset_table(filtered: &[Dataset]) -> String {
 
     let attrs = attributes
       .iter()
-      .map(|(key, val)| {
-        format!(
-          "{}={}",
-          surround_with_quotes(key),
-          surround_with_quotes(val.to_string())
-        )
-      })
+      .map(|(key, val)| format!("{}={}", surround_with_quotes(key), surround_with_quotes(val)))
       .join("\n");
 
     let versions = dataset.versions.iter().map(|ver| &ver.tag).join("\n");

packages/nextclade/src/analyze/virus_properties.rs

@@ -29,15 +29,41 @@ use validator::Validate;
 const PATHOGEN_JSON_SCHEMA_VERSION_FROM: &str = "3.0.0";
 const PATHOGEN_JSON_SCHEMA_VERSION_TO: &str = "3.0.0";
 
+/// Pathogen metadata attributes with recognized keys and extensibility
+#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
+pub struct PathogenAttributes {
+  /// Human-readable dataset name
+  #[serde(default, skip_serializing_if = "Option::is_none")]
+  pub name: Option<String>,
+
+  /// Name of the reference sequence
+  #[serde(rename = "reference name", default, skip_serializing_if = "Option::is_none")]
+  pub reference_name: Option<String>,
+
+  /// Accession number of the reference sequence
+  #[serde(rename = "reference accession", default, skip_serializing_if = "Option::is_none")]
+  pub reference_accession: Option<String>,
+
+  /// Additional custom attributes
+  #[serde(flatten)]
+  pub other: BTreeMap<String, AnyType>,
+}
+
+impl PathogenAttributes {
+  pub fn is_default(&self) -> bool {
+    self == &Self::default()
+  }
+}
+
 /// pathogen.json dataset file. Contains external configuration and data specific for a particular pathogen.
 #[derive(Clone, Default, Debug, Eq, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[schemars(title = "PathogenJson", example = "VirusProperties::example")]
 pub struct VirusProperties {
   pub schema_version: String,
 
-  #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
-  pub attributes: BTreeMap<String, AnyType>,
+  #[serde(default, skip_serializing_if = "PathogenAttributes::is_default")]
+  pub attributes: PathogenAttributes,
 
   #[serde(default, skip_serializing_if = "Vec::is_empty")]
   pub shortcuts: Vec<String>,
@@ -325,11 +351,13 @@ impl VirusProperties {
   pub fn example() -> Self {
     Self {
       schema_version: o!("3.0.0"),
-      attributes: btreemap! {
-        o!("name") => AnyType::String(o!("Influenza A H3N2 HA")),
-        o!("segment") => AnyType::String(o!("ha")),
-        o!("reference accession") => AnyType::String(o!("CY163680")),
-        o!("reference name") => AnyType::String(o!("A/Wisconsin/67/2005-egg")),
+      attributes: PathogenAttributes {
+        name: Some(o!("Influenza A H3N2 HA")),
+        reference_name: Some(o!("A/Wisconsin/67/2005-egg")),
+        reference_accession: Some(o!("CY163680")),
+        other: btreemap! {
+          o!("segment") => AnyType::String(o!("ha")),
+        },
       },
       shortcuts: vec_of_owned!["flu_h3n2_ha_broad", "nextstrain/flu/h3n2/ha/wisconsin-67-2005"],
       meta: DatasetMeta::default(),

packages/nextclade/src/io/dataset.rs

@@ -12,6 +12,61 @@ use std::cmp::Ordering;
 use std::collections::BTreeMap;
 use std::ops::{Deref, DerefMut};
 
+/// Dataset metadata attributes with recognized keys and extensibility
+#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct DatasetAttributes {
+  /// Human-readable dataset name
+  #[serde(default, skip_serializing_if = "Option::is_none")]
+  pub name: Option<String>,
+
+  /// Name of the reference sequence
+  #[serde(rename = "reference name", default, skip_serializing_if = "Option::is_none")]
+  pub reference_name: Option<String>,
+
+  /// Accession number of the reference sequence
+  #[serde(rename = "reference accession", default, skip_serializing_if = "Option::is_none")]
+  pub reference_accession: Option<String>,
+
+  /// If true, dataset is deprecated and excluded from listings by default.
+  /// Authors mark a dataset as deprecated to indicate it will no longer be updated or supported.
+  /// Use `--include-deprecated` CLI flag to show deprecated datasets.
+  #[serde(default, skip_serializing_if = "Option::is_none")]
+  pub deprecated: Option<bool>,
+
+  /// If true, dataset is experimental and excluded with `--no-experimental` CLI flag.
+  /// Authors mark a dataset as experimental when development is still in progress,
+  /// or if the dataset is incomplete or of lower quality than usual. Use at own risk.
+  #[serde(default, skip_serializing_if = "Option::is_none")]
+  pub experimental: Option<bool>,
+
+  /// Additional custom attributes
+  #[serde(flatten)]
+  pub other: BTreeMap<String, AnyType>,
+}
+
+impl DatasetAttributes {
+  pub fn is_default(&self) -> bool {
+    self == &Self::default()
+  }
+
+  /// Iterate over all attributes as (key, value) pairs for display
+  pub fn iter(&self) -> impl Iterator<Item = (&str, String)> {
+    let typed = [
+      self.name.as_ref().map(|v| ("name", v.clone())),
+      self.reference_name.as_ref().map(|v| ("reference name", v.clone())),
+      self.reference_accession.as_ref().map(|v| ("reference accession", v.clone())),
+      self.deprecated.map(|v| ("deprecated", v.to_string())),
+      self.experimental.map(|v| ("experimental", v.to_string())),
+    ]
+    .into_iter()
+    .flatten();
+
+    let other = self.other.iter().map(|(k, v)| (k.as_str(), v.to_string()));
+
+    chain!(typed, other)
+  }
+}
+
 const INDEX_JSON_SCHEMA_VERSION_FROM: &str = "3.0.0";
 const INDEX_JSON_SCHEMA_VERSION_TO: &str = "3.0.0";
 
@@ -114,8 +169,8 @@ pub struct Dataset {
   #[serde(default, skip_serializing_if = "Vec::is_empty")]
   pub shortcuts: Vec<String>,
 
-  #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
-  pub attributes: BTreeMap<String, AnyType>,
+  #[serde(default, skip_serializing_if = "DatasetAttributes::is_default")]
+  pub attributes: DatasetAttributes,
 
   #[serde(default, skip_serializing_if = "DatasetMeta::is_default")]
   pub meta: DatasetMeta,
@@ -148,7 +203,7 @@ impl Dataset {
   }
 
   pub fn name(&self) -> Option<&str> {
-    self.attributes.get("name").and_then(AnyType::as_str_maybe)
+    self.attributes.name.as_deref()
   }
 
   pub fn shortcuts(&self) -> impl Iterator<Item = &str> {
@@ -175,30 +230,19 @@ impl Dataset {
   }
 
   pub fn ref_name(&self) -> Option<&str> {
-    self.attributes.get("reference name").and_then(AnyType::as_str_maybe)
+    self.attributes.reference_name.as_deref()
   }
 
   pub fn ref_accession(&self) -> Option<&str> {
-    self
-      .attributes
-      .get("reference accession")
-      .and_then(AnyType::as_str_maybe)
+    self.attributes.reference_accession.as_deref()
   }
 
   pub fn deprecated(&self) -> bool {
-    self
-      .attributes
-      .get("deprecated")
-      .and_then(AnyType::as_bool_maybe)
-      .unwrap_or(false)
+    self.attributes.deprecated.unwrap_or(false)
   }
 
   pub fn experimental(&self) -> bool {
-    self
-      .attributes
-      .get("experimental")
-      .and_then(AnyType::as_bool_maybe)
-      .unwrap_or(false)
+    self.attributes.experimental.unwrap_or(false)
   }
 
   pub fn is_community(&self) -> bool {

packages/nextclade/src/run/nextclade_wasm.rs

@@ -21,7 +21,6 @@ use crate::tree::tree::{AuspiceGraph, AuspiceRefNodesDesc, AuspiceTree, CladeNod
 use crate::tree::tree_builder::graph_attach_new_nodes_in_place;
 use crate::tree::tree_preprocess::graph_preprocess_in_place;
 use crate::types::outputs::NextcladeOutputs;
-use crate::utils::any::AnyType;
 use crate::utils::option::{OptionMapRefFallible, find_some};
 use eyre::{Report, WrapErr, eyre};
 use itertools::Itertools;
@@ -67,14 +66,9 @@ impl NextcladeParams {
       } else {
         let ref_name = virus_properties
           .attributes
-          .get("reference name")
-          .cloned()
-          .unwrap_or_else(|| AnyType::String("reference".to_owned()))
-          .as_str()
-          .wrap_err(
-            "When reading Auspice JSON v2 `.meta.extensions.nextclade.pathogen.attributes[\"reference name\"]`",
-          )?
-          .to_owned();
+          .reference_name
+          .clone()
+          .unwrap_or_else(|| "reference".to_owned());
 
         let ref_seq = auspice_json.root_sequence.as_ref().and_then(|root_sequence| root_sequence.get("nuc"))
           .ok_or_else(|| eyre!("Auspice JSON v2 is used as input dataset, but does not contain required reference sequence field (.root_sequence.nuc) and a reference sequence is not provided any other way."))?.to_owned();