powerio_tx/format/

routing.rs

//! Shared format alias and JSON shape routing for the `powerio` crate.
//!
//! It maps format name aliases with no parsing at all, and classifies JSON
//! content by deserializing a typed header instead of materializing the
//! whole document into a generic value tree.

use serde::Deserialize;

// The top-level facade owns PowerIO IR. This private routing marker lets the
// lower-level JSON classifier recognize the stable identity without making
// `powerio-core` own the stored representation.
const POWERIO_IR_SCHEMA: &str = "pio-ir";

/// A classification result that can be known, absent, or unsafe to choose.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Detection<T> {
    Known(T),
    Unknown,
    Ambiguous,
}

impl<T> Detection<T> {
    pub fn known(self) -> Option<T> {
        match self {
            Self::Known(value) => Some(value),
            Self::Unknown | Self::Ambiguous => None,
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Domain {
    Transmission,
    Distribution,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum TransmissionFormat {
    Matpower,
    PowerModelsJson,
    EgretJson,
    Psse,
    Psse34,
    Psse35,
    PsseRawx,
    PowerWorld,
    PandapowerJson,
    PypsaCsv,
    Pslf,
    Pwb,
    Gridfm,
    Goc3Json,
    SurgeJson,
    DeepMindOpfDataJson,
    Xiidm,
    Jiidm,
    Cgmes,
    Ucte,
    /// The IEEE Common Data Format, a read only fixed column text case.
    IeeeCdf,
    /// Explicit positive-sequence profile of the two-family SINCAL container.
    SincalBalanced,
    /// MG-RAVENS JSON, the LANL CIM-derived interchange schema, balanced profile.
    RavensJson,
}

impl TransmissionFormat {
    pub fn name(self) -> &'static str {
        match self {
            Self::SincalBalanced => "sincal-balanced",
            Self::Matpower => "matpower",
            Self::PowerModelsJson => "powermodels-json",
            Self::EgretJson => "egret-json",
            Self::Psse => "psse",
            Self::Psse34 => "psse34",
            Self::Psse35 => "psse35",
            Self::PsseRawx => "psse-rawx",
            Self::PowerWorld => "powerworld",
            Self::PandapowerJson => "pandapower-json",
            Self::PypsaCsv => "pypsa-csv",
            Self::Pslf => "pslf",
            Self::Pwb => "pwb",
            Self::Gridfm => "gridfm",
            Self::Goc3Json => "goc3-json",
            Self::SurgeJson => "surge-json",
            Self::RavensJson => "ravens-json",
            Self::DeepMindOpfDataJson => "opfdata-json",
            Self::Xiidm => "xiidm",
            Self::Jiidm => "jiidm",
            Self::Cgmes => "cgmes",
            Self::Ucte => "ucte",
            Self::IeeeCdf => "ieee-cdf",
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum DistributionFormat {
    Dss,
    PmdJson,
    BmopfJson,
    /// Distribution CIM (CIM100 RDF/XML).
    CimDist,
    SincalMulticonductor,
    Gridlabd,
    GridlabdArras,
    /// MG-RAVENS JSON, the multiconductor (distribution) profile.
    RavensJson,
    /// PowerModelsDistribution MATHEMATICAL model JSON.
    PmdMathJson,
}

impl DistributionFormat {
    pub fn name(self) -> &'static str {
        match self {
            Self::SincalMulticonductor => "sincal-multiconductor",
            Self::Dss => "dss",
            Self::Gridlabd => "gridlabd",
            Self::GridlabdArras => "gridlabd-arras",
            Self::PmdJson => "pmd-json",
            Self::BmopfJson => "bmopf-json",
            Self::CimDist => "cim-dist",
            Self::RavensJson => "ravens-json",
            Self::PmdMathJson => "pmd-math-json",
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum SourceFormat {
    Transmission(TransmissionFormat),
    Distribution(DistributionFormat),
}

impl SourceFormat {
    pub fn domain(self) -> Domain {
        match self {
            Self::Transmission(_) => Domain::Transmission,
            Self::Distribution(_) => Domain::Distribution,
        }
    }

    pub fn name(self) -> &'static str {
        match self {
            Self::Transmission(format) => format.name(),
            Self::Distribution(format) => format.name(),
        }
    }
}

pub type JsonFormat = SourceFormat;

/// Resolve a source format name or common alias.
pub fn classify_format_name(name: &str) -> Detection<SourceFormat> {
    if canonical_key(name) == "sincal" {
        return Detection::Ambiguous;
    }
    if let Some(format) = parse_transmission_format(name) {
        return Detection::Known(SourceFormat::Transmission(format));
    }
    if let Some(format) = parse_distribution_format(name) {
        return Detection::Known(SourceFormat::Distribution(format));
    }
    Detection::Unknown
}

pub fn parse_transmission_format(name: &str) -> Option<TransmissionFormat> {
    let key = canonical_key(name);
    match key.as_str() {
        "sincalbalanced" => Some(TransmissionFormat::SincalBalanced),
        "matpower" | "m" => Some(TransmissionFormat::Matpower),
        "powermodelsjson" | "powermodels" | "pm" => Some(TransmissionFormat::PowerModelsJson),
        "egretjson" | "egret" => Some(TransmissionFormat::EgretJson),
        "psse" | "psse33" | "raw" | "raw33" => Some(TransmissionFormat::Psse),
        "psse34" | "raw34" => Some(TransmissionFormat::Psse34),
        "psse35" | "raw35" => Some(TransmissionFormat::Psse35),
        "psserawx" | "rawx" => Some(TransmissionFormat::PsseRawx),
        "powerworld" | "aux" => Some(TransmissionFormat::PowerWorld),
        "pandapowerjson" | "pandapower" | "pp" => Some(TransmissionFormat::PandapowerJson),
        "pypsacsv" | "pypsa" => Some(TransmissionFormat::PypsaCsv),
        "pslf" | "epc" | "pslfepc" => Some(TransmissionFormat::Pslf),
        "pwb" => Some(TransmissionFormat::Pwb),
        "gridfm" => Some(TransmissionFormat::Gridfm),
        "goc3" | "goc3json" | "go3" | "gochallenge3" | "c3" => Some(TransmissionFormat::Goc3Json),
        "surge" | "surgejson" => Some(TransmissionFormat::SurgeJson),
        "ravens" | "ravensjson" | "mgravens" | "mgravensjson" => {
            Some(TransmissionFormat::RavensJson)
        }
        "xiidm" | "iidm" => Some(TransmissionFormat::Xiidm),
        "jiidm" => Some(TransmissionFormat::Jiidm),
        "cgmes" => Some(TransmissionFormat::Cgmes),
        "ucte" | "uct" | "uctedef" => Some(TransmissionFormat::Ucte),
        "ieeecdf" | "cdf" => Some(TransmissionFormat::IeeeCdf),
        "opfdata"
        | "opfdatajson"
        | "deepmindopfdata"
        | "deepmindopfdatajson"
        | "gridopt"
        | "gridoptjson" => Some(TransmissionFormat::DeepMindOpfDataJson),
        _ => None,
    }
}

pub fn parse_distribution_format(name: &str) -> Option<DistributionFormat> {
    let key = canonical_key(name);
    match key.as_str() {
        "sincalmulticonductor" => Some(DistributionFormat::SincalMulticonductor),
        "dss" | "opendss" => Some(DistributionFormat::Dss),
        "glm" | "gridlabd" | "gridlabdpnnl" => Some(DistributionFormat::Gridlabd),
        "gridlabdarras" => Some(DistributionFormat::GridlabdArras),
        "pmd" | "pmdjson" | "engineering" => Some(DistributionFormat::PmdJson),
        "pmdmath" | "pmdmathjson" | "mathematical" => Some(DistributionFormat::PmdMathJson),
        "bmopf" | "bmopfjson" => Some(DistributionFormat::BmopfJson),
        "cimdist" => Some(DistributionFormat::CimDist),
        "ravens" | "ravensjson" | "mgravens" | "mgravensjson" => {
            Some(DistributionFormat::RavensJson)
        }
        _ => None,
    }
}

/// Top level classification of bare JSON text: a PowerIO IR document or a case
/// document with its format detection. One header read answers every question
/// instead of requiring a full document parse per question.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum JsonClass {
    /// A `.pio.json` stored module document. The stored document is not a
    /// converter boundary format, so it stays out of [`SourceFormat`];
    /// callers route it to the stored module reader instead of a case parser.
    Module,
    /// A case document and its format detection.
    Case(Detection<JsonFormat>),
}

/// The closed set of classification families, in the one spelling every
/// surface uses: the Rust [`JsonClass`], the C `pio_classify_str` label before
/// its optional `:<format>` tail, the Python `classify_json_text` status, and
/// the Julia family symbol.
///
/// A consumer may cache this set. A spelling never changes, a new family is
/// appended within a release line, and a family leaves only in a breaking
/// release that records the removal in the changelog and the migration guide,
/// as 0.11 recorded `model-json`.
pub const JSON_CLASSES: [&str; 5] = [
    "transmission",
    "distribution",
    "module",
    "ambiguous",
    "unknown",
];

impl JsonClass {
    /// This classification's family token, one of [`JSON_CLASSES`]. The
    /// detected format, where there is one, is [`SourceFormat::name`].
    #[must_use]
    pub fn family(self) -> &'static str {
        match self {
            Self::Module => "module",
            Self::Case(Detection::Known(format)) => match format.domain() {
                Domain::Transmission => "transmission",
                Domain::Distribution => "distribution",
            },
            Self::Case(Detection::Ambiguous) => "ambiguous",
            Self::Case(Detection::Unknown) => "unknown",
        }
    }
}

/// Classify a JSON document: a PowerIO IR module or a case document across the
/// transmission and distribution domains.
///
/// PowerIO IR is recognized by its `schema: "pio-ir"` header.
/// For a case, Unknown means there is no recognized top level marker, and
/// Ambiguous means the document contains strong markers from both domains, so
/// the caller must ask the user for an explicit format.
pub fn classify_json_text(text: &str) -> JsonClass {
    // PowSybl JIIDM opens with its `version` key, the same test PowSybl's
    // importer applies; no other JSON case format starts that way.
    if super::xiidm::looks_like_jiidm(text) {
        return JsonClass::Case(Detection::Known(SourceFormat::Transmission(
            TransmissionFormat::Jiidm,
        )));
    }
    // Windows tooling saves JSON with a UTF-8 byte order mark, which
    // serde_json rejects; strip it so a BOM never hides the format.
    let Ok(header) = serde_json::from_str::<JsonHeader>(text.trim_start_matches('\u{feff}')) else {
        return JsonClass::Case(Detection::Unknown);
    };
    // PowerIO IR names itself in its header.
    if header.schema.as_deref() == Some(POWERIO_IR_SCHEMA) {
        return JsonClass::Module;
    }
    header.classify()
}

/// Classify JSON bytes without performing lossy text replacement.
///
/// Invalid UTF-8 has no trustworthy JSON markers and returns the same
/// [`Detection::Unknown`] classification as malformed JSON. A leading UTF-8
/// byte order mark is accepted through [`classify_json_text`].
#[must_use]
pub fn classify_json_bytes(bytes: &[u8]) -> JsonClass {
    let Ok(text) = std::str::from_utf8(bytes) else {
        return JsonClass::Case(Detection::Unknown);
    };
    classify_json_text(text)
}

fn canonical_key(name: &str) -> String {
    name.to_ascii_lowercase()
        .chars()
        .filter(|c| *c != '-' && *c != '_')
        .collect()
}

/// Reads `true` when a key is present, for whatever value it holds — a JSON
/// `null` included, unlike a plain `Option<T>` field, which would treat a
/// `null` value the same as a missing key. [`serde::de::IgnoredAny`] walks
/// and discards the value without materializing it, so a marker key whose
/// value is a large array or object (an unrelated top level table in the
/// same document) costs one scan, not an allocation per element.
fn present<'de, D>(deserializer: D) -> Result<bool, D::Error>
where
    D: serde::Deserializer<'de>,
{
    serde::de::IgnoredAny::deserialize(deserializer)?;
    Ok(true)
}

/// The key's string value, or `None` for a missing key, a `null`, or any
/// other non-string value — matching `serde_json::Value::as_str`'s
/// permissive read, so a marker key of the wrong type carries no marker
/// instead of failing the whole header.
fn maybe_str<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Ok(serde_json::Value::deserialize(deserializer)?
        .as_str()
        .map(str::to_owned))
}

/// The key's string value, or an empty string for a present key of any
/// other type, so presence survives a `null` marker: `Some("")` is present
/// with no usable value and `None` is absent.
fn present_str<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Ok(Some(
        serde_json::Value::deserialize(deserializer)?
            .as_str()
            .unwrap_or_default()
            .to_owned(),
    ))
}

/// `Some(header)` when the key's value is a JSON object, `None` for a
/// missing key or any non-object value — matching the object guard the
/// nested markers (`grid`, `solution`, `metadata`) read before checking a
/// key within them.
fn maybe_object<'de, D, T>(deserializer: D) -> Result<Option<T>, D::Error>
where
    D: serde::Deserializer<'de>,
    T: Deserialize<'de>,
{
    let value = serde_json::Value::deserialize(deserializer)?;
    if value.is_object() {
        T::deserialize(value)
            .map(Some)
            .map_err(serde::de::Error::custom)
    } else {
        Ok(None)
    }
}

/// The `network` key's presence, independent of its shape (the surge marker
/// only needs presence), paired with its nested markers when it does turn
/// out to be an object (the GO Challenge 3 markers). One key answers both,
/// since a `maybe_object` field alone would lose the presence signal for a
/// non-object value.
#[derive(Default)]
struct NetworkField {
    present: bool,
    header: NetworkHeader,
}

impl<'de> Deserialize<'de> for NetworkField {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let value = serde_json::Value::deserialize(deserializer)?;
        let header = if value.is_object() {
            NetworkHeader::deserialize(value).map_err(serde::de::Error::custom)?
        } else {
            NetworkHeader::default()
        };
        Ok(Self {
            present: true,
            header,
        })
    }
}

#[derive(Default, Deserialize)]
#[expect(clippy::struct_excessive_bools)]
struct NetworkHeader {
    #[serde(default, deserialize_with = "present")]
    caseid: bool,
    #[serde(default, deserialize_with = "present")]
    simple_dispatchable_device: bool,
    #[serde(default, deserialize_with = "present")]
    ac_line: bool,
    #[serde(default, deserialize_with = "present")]
    two_winding_transformer: bool,
}

#[derive(Deserialize)]
struct GridHeader {
    #[serde(default, deserialize_with = "present")]
    nodes: bool,
    #[serde(default, deserialize_with = "present")]
    edges: bool,
    #[serde(default, deserialize_with = "present")]
    context: bool,
}

#[derive(Deserialize)]
struct SolutionHeader {
    #[serde(default, deserialize_with = "present")]
    nodes: bool,
    #[serde(default, deserialize_with = "present")]
    edges: bool,
}

#[derive(Deserialize)]
struct MetadataHeader {
    #[serde(default, deserialize_with = "present")]
    objective: bool,
}

/// The top level markers [`JsonClass`] needs, read in one pass over the
/// document: unlisted keys (every case format's actual data rows) are
/// skipped by serde's derived `Deserialize` without being materialized, and
/// the listed keys cost at most a presence check or one short string.
// Every bool here is an independent named field a derived `Deserialize`
// fills from its own JSON key, never a positional constructor argument, so
// the excessive-bools lint's mix-up concern does not apply.
#[allow(clippy::struct_excessive_bools)]
#[derive(Default, Deserialize)]
struct JsonHeader {
    #[serde(default, deserialize_with = "maybe_str")]
    schema: Option<String>,
    #[serde(default, deserialize_with = "maybe_str", rename = "_class")]
    pandapower_class: Option<String>,
    #[serde(default, deserialize_with = "present")]
    elements: bool,
    #[serde(default, deserialize_with = "present")]
    system: bool,
    #[serde(default)]
    network: NetworkField,
    #[serde(default, deserialize_with = "present")]
    time_series_input: bool,
    #[serde(default, deserialize_with = "present")]
    time_series_output: bool,
    #[serde(default, deserialize_with = "present")]
    reliability: bool,
    #[serde(default, deserialize_with = "maybe_str")]
    format: Option<String>,
    #[serde(default, deserialize_with = "present")]
    schema_version: bool,
    #[serde(default, deserialize_with = "maybe_object")]
    grid: Option<GridHeader>,
    #[serde(default, deserialize_with = "maybe_object")]
    solution: Option<SolutionHeader>,
    #[serde(default, deserialize_with = "maybe_object")]
    metadata: Option<MetadataHeader>,
    #[serde(default, deserialize_with = "present", rename = "baseMVA")]
    base_mva_camel: bool,
    #[serde(default, deserialize_with = "present")]
    branch: bool,
    #[serde(default, deserialize_with = "present")]
    r#gen: bool,
    #[serde(default, deserialize_with = "present")]
    gencost: bool,
    #[serde(default, deserialize_with = "present_str")]
    data_model: Option<String>,
    #[serde(default, deserialize_with = "present")]
    line: bool,
    #[serde(default, deserialize_with = "present")]
    linecode: bool,
    #[serde(default, deserialize_with = "present")]
    transformer: bool,
    #[serde(default, deserialize_with = "present")]
    voltage_source: bool,
    #[serde(default, deserialize_with = "present")]
    bus: bool,
    #[serde(default, deserialize_with = "present")]
    load: bool,
    #[serde(default, deserialize_with = "present")]
    generator: bool,
    #[serde(default, deserialize_with = "present")]
    shunt: bool,
    #[serde(default, deserialize_with = "present")]
    switch: bool,
    // MG-RAVENS documents nest everything under CIM hash tables; the
    // top-level `ConnectivityNode` / `PowerSystemResource` pair appears in
    // no other supported dialect.
    #[serde(default, deserialize_with = "present", rename = "ConnectivityNode")]
    connectivity_node: bool,
    #[serde(default, deserialize_with = "present", rename = "PowerSystemResource")]
    power_system_resource: bool,
    // The multiconductor MG-RAVENS profile states line impedances in a
    // `PerLengthLineParameter` table and catalog data under `AssetInfo`;
    // the balanced profile has neither.
    #[serde(
        default,
        deserialize_with = "present",
        rename = "PerLengthLineParameter"
    )]
    per_length_line_parameter: bool,
    #[serde(default, deserialize_with = "present", rename = "AssetInfo")]
    asset_info: bool,
}

impl JsonHeader {
    fn classify(&self) -> JsonClass {
        let is_pandapower = self.pandapower_class.as_deref() == Some("pandapowerNet");
        let is_egret = self.elements && self.system;
        let is_goc3 = self.time_series_output
            || ((self.time_series_input || self.reliability)
                && (self.network.header.simple_dispatchable_device
                    || self.network.header.ac_line
                    || self.network.header.two_winding_transformer));
        let is_rawx = self.network.header.caseid;
        let is_surge = self.format.as_deref() == Some("surge-json")
            && self.schema_version
            && self.network.present;
        let is_opfdata = self
            .grid
            .as_ref()
            .is_some_and(|grid| grid.nodes && grid.edges && grid.context)
            && self
                .solution
                .as_ref()
                .is_some_and(|solution| solution.nodes && solution.edges)
            && self
                .metadata
                .as_ref()
                .is_some_and(|metadata| metadata.objective);
        let is_ravens = self.connectivity_node || self.power_system_resource;
        // A multiconductor table at the top level selects the distribution
        // profile here; a per-phase class nested deeper is caught by the
        // facade's content check before the balanced reader sees it.
        let is_ravens_multiconductor =
            is_ravens && (self.per_length_line_parameter || self.asset_info);
        // PMD's `data_model` marker is its own: a MATHEMATICAL document
        // carries `branch` and `gen` tables shaped like PowerModels', and the
        // marker says which reader they belong to.
        let is_pmd = self.data_model.is_some();
        let is_power_models =
            (self.base_mva_camel || self.branch || self.r#gen || self.gencost) && !is_pmd;
        let transmission = is_pandapower
            || is_egret
            || is_goc3
            || is_rawx
            || is_surge
            || (is_ravens && !is_ravens_multiconductor)
            || is_opfdata
            || is_power_models;

        let is_pmd_math = self
            .data_model
            .as_deref()
            .is_some_and(|m| m.eq_ignore_ascii_case("MATHEMATICAL"));
        let strong_bmopf = self.line || self.linecode || self.transformer || self.voltage_source;
        let weak_bmopf = self.bus || self.load || self.generator || self.shunt || self.switch;
        let distribution =
            is_ravens_multiconductor || is_pmd || strong_bmopf || (weak_bmopf && !transmission);

        match (transmission, distribution) {
            (true, true) => JsonClass::Case(Detection::Ambiguous),
            (true, false) => JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                if is_pandapower {
                    TransmissionFormat::PandapowerJson
                } else if is_egret {
                    TransmissionFormat::EgretJson
                } else if is_rawx {
                    TransmissionFormat::PsseRawx
                } else if is_goc3 {
                    TransmissionFormat::Goc3Json
                } else if is_surge {
                    TransmissionFormat::SurgeJson
                } else if is_ravens {
                    TransmissionFormat::RavensJson
                } else if is_opfdata {
                    TransmissionFormat::DeepMindOpfDataJson
                } else {
                    TransmissionFormat::PowerModelsJson
                },
            ))),
            (false, true) => JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                if is_ravens_multiconductor {
                    DistributionFormat::RavensJson
                } else if is_pmd_math {
                    DistributionFormat::PmdMathJson
                } else if is_pmd {
                    DistributionFormat::PmdJson
                } else {
                    DistributionFormat::BmopfJson
                },
            ))),
            (false, false) => JsonClass::Case(Detection::Unknown),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{
        Detection, DistributionFormat, JsonClass, SourceFormat, TransmissionFormat,
        classify_json_bytes, classify_json_text,
    };

    #[test]
    fn classifies_powerio_ir() {
        assert_eq!(
            classify_json_text(r#"{"schema":"pio-ir","version":2}"#),
            JsonClass::Module
        );
        // Routing is the schema name's job alone. Every PowerIO IR generation
        // reaches the deserializer, which owns the version rule and can then
        // name the version it refuses.
        for version in ["1", "3", r#""0.11.0""#, "null"] {
            assert_eq!(
                classify_json_text(&format!(r#"{{"schema":"pio-ir","version":{version}}}"#)),
                JsonClass::Module,
                "version {version}"
            );
        }
        assert_eq!(
            classify_json_text(r#"{"buses":[],"linecodes":[]}"#),
            JsonClass::Case(Detection::Unknown)
        );
        assert_eq!(
            classify_json_text(r#"{"baseMVA":100.0,"bus":{},"model":"ACP","model_kind":"opf"}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PowerModelsJson
            )))
        );
        assert_eq!(
            classify_json_text("not json"),
            JsonClass::Case(Detection::Unknown)
        );
    }

    #[test]
    fn classifies_ravens_profiles_by_their_top_level_tables() {
        // The CIM hash tables alone read as the balanced profile.
        assert_eq!(
            classify_json_text(r#"{"Versions":{},"ConnectivityNode":{},"PowerSystemResource":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::RavensJson
            )))
        );
        // A per-length impedance or asset catalog table marks the
        // multiconductor profile.
        for table in ["PerLengthLineParameter", "AssetInfo"] {
            assert_eq!(
                classify_json_text(&format!(
                    r#"{{"ConnectivityNode":{{}},"PowerSystemResource":{{}},"{table}":{{}}}}"#
                )),
                JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                    DistributionFormat::RavensJson
                ))),
                "{table}"
            );
        }
        for alias in ["ravens", "ravens-json", "mg-ravens", "MG_RAVENS_JSON"] {
            assert_eq!(
                super::parse_transmission_format(alias),
                Some(TransmissionFormat::RavensJson),
                "{alias}"
            );
            assert_eq!(
                super::parse_distribution_format(alias),
                Some(DistributionFormat::RavensJson),
                "{alias}"
            );
        }
    }

    #[test]
    fn classifies_pmd_json() {
        assert_eq!(
            classify_json_text(r#"{"data_model":"ENGINEERING","bus":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                DistributionFormat::PmdJson
            )))
        );
        // The marker's value picks the PMD model.
        assert_eq!(
            classify_json_text(r#"{"data_model":"MATHEMATICAL","bus":{},"per_unit":true}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                DistributionFormat::PmdMathJson
            )))
        );
        // A marker with a non-string value still names PMD, as before.
        assert_eq!(
            classify_json_text(r#"{"data_model":null,"bus":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                DistributionFormat::PmdJson
            )))
        );
    }

    #[test]
    fn classifies_full_bmopf_json() {
        assert_eq!(
            classify_json_text(r#"{"bus":{},"linecode":{},"voltage_source":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                DistributionFormat::BmopfJson
            )))
        );
    }

    #[test]
    fn classifies_minimal_bmopf_json() {
        assert_eq!(
            classify_json_text(r#"{"bus":{"a":{"terminal_names":["1"]}}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                DistributionFormat::BmopfJson
            )))
        );
    }

    #[test]
    fn classifies_power_models_with_bus_and_base_mva_as_transmission() {
        assert_eq!(
            classify_json_text(
                r#"{"baseMVA":100.0,"bus":{},"branch":{},"gen":{},"load":{},"switch":{}}"#
            ),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PowerModelsJson
            )))
        );
    }

    #[test]
    fn a_bare_network_object_is_not_a_case_or_powerio_ir() {
        assert_eq!(
            classify_json_text(r#"{"base_mva":100.0,"buses":[],"branches":[]}"#),
            JsonClass::Case(Detection::Unknown)
        );
    }

    #[test]
    fn every_family_is_in_the_closed_set() {
        for class in [
            JsonClass::Module,
            JsonClass::Case(Detection::Ambiguous),
            JsonClass::Case(Detection::Unknown),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::Matpower,
            ))),
            JsonClass::Case(Detection::Known(SourceFormat::Distribution(
                DistributionFormat::Dss,
            ))),
        ] {
            assert!(
                super::JSON_CLASSES.contains(&class.family()),
                "{class:?} answers with a family outside the closed set"
            );
        }
    }

    #[test]
    fn classifies_pandapower_json() {
        assert_eq!(
            classify_json_text(r#"{"_class":"pandapowerNet","_object":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PandapowerJson
            )))
        );
    }

    #[test]
    fn classifies_egret_json() {
        assert_eq!(
            classify_json_text(r#"{"elements":{},"system":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::EgretJson
            )))
        );
    }

    #[test]
    fn classifies_goc3_json() {
        assert_eq!(
            classify_json_text(
                r#"{"network":{"bus":[],"simple_dispatchable_device":[]},"time_series_input":{}}"#
            ),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::Goc3Json
            )))
        );
        assert_eq!(
            classify_json_text(r#"{"time_series_output":{"bus":[]}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::Goc3Json
            )))
        );
    }

    #[test]
    fn classifies_rawx_and_normalizes_its_alias() {
        assert_eq!(
            classify_json_text(
                r#"{"network":{"caseid":{"fields":["rev"],"data":[35]},"bus":{"fields":[],"data":[]}}}"#
            ),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PsseRawx
            )))
        );
        for alias in ["psse-rawx", "rawx", "PSSERAWX"] {
            assert_eq!(
                super::parse_transmission_format(alias),
                Some(TransmissionFormat::PsseRawx)
            );
        }
        assert_eq!(TransmissionFormat::PsseRawx.name(), "psse-rawx");
    }

    #[test]
    fn resolves_goc3_aliases() {
        for alias in ["goc3-json", "goc3", "go3", "go-challenge-3", "c3"] {
            assert_eq!(
                super::parse_transmission_format(alias),
                Some(TransmissionFormat::Goc3Json),
                "{alias}"
            );
        }
    }

    #[test]
    fn classifies_surge_json() {
        assert_eq!(
            classify_json_text(
                r#"{"format":"surge-json","schema_version":"0.1.0","network":{"buses":[]}}"#
            ),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::SurgeJson
            )))
        );
    }

    #[test]
    fn resolves_ieee_cdf_aliases() {
        for alias in ["ieee-cdf", "ieee_cdf", "IEEECDF", "cdf"] {
            assert_eq!(
                super::parse_transmission_format(alias),
                Some(TransmissionFormat::IeeeCdf),
                "{alias}"
            );
        }
        assert_eq!(TransmissionFormat::IeeeCdf.name(), "ieee-cdf");
    }

    #[test]
    fn resolves_surge_aliases() {
        for alias in ["surge-json", "surge", "surgejson"] {
            assert_eq!(
                super::parse_transmission_format(alias),
                Some(TransmissionFormat::SurgeJson),
                "{alias}"
            );
        }
    }

    #[test]
    fn classifies_opfdata_json() {
        assert_eq!(
            classify_json_text(
                r#"{
                    "grid":{"nodes":{},"edges":{},"context":[]},
                    "solution":{"nodes":{},"edges":{}},
                    "metadata":{"objective":0.0}
                }"#
            ),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::DeepMindOpfDataJson
            )))
        );
        assert_eq!(
            classify_json_text(r#"{"grid":{},"solution":{},"metadata":{}}"#),
            JsonClass::Case(Detection::Unknown)
        );
    }

    #[test]
    fn resolves_opfdata_aliases() {
        for alias in [
            "opfdata-json",
            "opfdata",
            "OPFData",
            "deepmind-opfdata-json",
            "deepmind-opfdata",
            "gridopt-json",
            "gridopt",
        ] {
            assert_eq!(
                super::parse_transmission_format(alias),
                Some(TransmissionFormat::DeepMindOpfDataJson),
                "{alias}"
            );
        }
    }

    #[test]
    fn classifies_json_with_leading_byte_order_mark() {
        assert_eq!(
            classify_json_text("\u{feff}{\"baseMVA\":100.0,\"bus\":{},\"branch\":{}}"),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PowerModelsJson
            )))
        );
    }

    #[test]
    fn classifies_json_bytes_without_lossy_utf8_replacement() {
        assert_eq!(
            classify_json_bytes(b"\xef\xbb\xbf{\"baseMVA\":100.0,\"bus\":{},\"branch\":{}}"),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PowerModelsJson
            )))
        );
        assert_eq!(
            classify_json_bytes(b"{\"base_mva\":100.0,\"buses\":[],\"branches\":[]}"),
            JsonClass::Case(Detection::Unknown)
        );
        assert_eq!(
            classify_json_bytes(b"{\"baseMVA\":100.0,\"bus\":{}\xff}"),
            JsonClass::Case(Detection::Unknown)
        );
    }

    #[test]
    fn unknown_json_has_no_signal() {
        assert_eq!(
            classify_json_text(r#"{"name":"case"}"#),
            JsonClass::Case(Detection::Unknown)
        );
    }

    #[test]
    fn mixed_transmission_and_distribution_markers_are_ambiguous() {
        assert_eq!(
            classify_json_text(r#"{"baseMVA":100.0,"voltage_source":{}}"#),
            JsonClass::Case(Detection::Ambiguous)
        );
    }

    /// A key's presence check is true even when its value is JSON `null`;
    /// only an absent key is absent. A string marker (`schema`, `_class`,
    /// `format`) whose value is not a string carries no marker from that key, matching
    /// `serde_json::Value::as_str`'s permissive read; classification still
    /// proceeds over the document's other markers instead of erroring.
    #[test]
    fn a_non_string_value_at_a_string_marker_key_is_read_as_absent() {
        assert_eq!(
            classify_json_text(r#"{"schema":123,"baseMVA":100.0,"bus":{},"branch":{}}"#),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::PowerModelsJson
            )))
        );
    }

    /// A `network` value that is not a JSON object carries no GO Challenge 3
    /// marker, but does not stop the surge marker (also keyed off `network`,
    /// as a presence check rather than a shape check) from resolving.
    #[test]
    fn a_non_object_network_value_does_not_stop_the_surge_marker() {
        assert_eq!(
            classify_json_text(
                r#"{"format":"surge-json","schema_version":"0.1.0","network":"opaque"}"#
            ),
            JsonClass::Case(Detection::Known(SourceFormat::Transmission(
                TransmissionFormat::SurgeJson
            )))
        );
    }
}