Skip to main content

s2_kit/schema/
mod.rs

1//! The shape of S2 JSON, as data.
2//!
3//! [`TYPES`] is generated from the official schema files by
4//! `cargo xtask gen-schema-table`: every object type, its properties in schema order,
5//! which of them are required, and the bounds on every array. Two things use it.
6//!
7//! * **Lenient decoding.** A proxy or analyzer has to forward a message it would refuse
8//!   to send, so [`prune_unknown`] strips properties the schema does not define and
9//!   reports them, instead of failing the whole message.
10//! * **Cardinality rules.** `maxItems` is on more than forty arrays; transcribing those
11//!   numbers into the validator by hand would be forty chances to get one wrong.
12//!
13//! The full schema files are vendored under `schema/s2-json/` and used by the tests,
14//! which check the hand-written Rust types against them in both directions. They are not
15//! embedded in the library: a table of names and bounds is a few kilobytes, and the
16//! schemas are three hundred.
17
18mod table;
19
20use alloc::string::String;
21use alloc::vec::Vec;
22
23pub use table::{BETA_TYPES, TYPES};
24
25use crate::types::WireProfile;
26
27/// The `minItems` and `maxItems` an array property carries.
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub struct ArrayBounds {
30    /// The fewest elements the schema allows.
31    pub min: Option<u64>,
32    /// The most elements the schema allows.
33    pub max: Option<u64>,
34}
35
36impl ArrayBounds {
37    /// Whether `len` satisfies both bounds.
38    #[must_use]
39    pub const fn accepts(self, len: u64) -> bool {
40        let above = match self.min {
41            Some(m) => len >= m,
42            None => true,
43        };
44        let below = match self.max {
45            Some(m) => len <= m,
46            None => true,
47        };
48        above && below
49    }
50}
51
52/// What a property holds.
53#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54pub enum Kind {
55    /// A number, string, boolean or enumeration.
56    Scalar,
57    /// An S2 [`Id`](crate::types::Id).
58    ///
59    /// A scalar as far as the decoder is concerned, and distinguished here because a tool
60    /// that walks a message often wants to *follow* identifiers: to rewrite them, to link
61    /// them, to see which of them a message introduces. Telling them apart by property
62    /// name would be a hand-maintained list of forty-odd spellings, which is the thing
63    /// this table exists to avoid.
64    Id,
65    /// Another object type, named here so a walk can recurse into it.
66    Object(&'static str),
67    /// An array of scalars.
68    ScalarArray(ArrayBounds),
69    /// An array of [`Id`](crate::types::Id)s.
70    IdArray(ArrayBounds),
71    /// An array of another object type.
72    ObjectArray(&'static str, ArrayBounds),
73}
74
75impl Kind {
76    /// The array bounds, if this property is an array.
77    #[must_use]
78    pub const fn bounds(self) -> Option<ArrayBounds> {
79        match self {
80            Kind::ScalarArray(b) | Kind::IdArray(b) | Kind::ObjectArray(_, b) => Some(b),
81            Kind::Scalar | Kind::Id | Kind::Object(_) => None,
82        }
83    }
84
85    /// Whether this property holds one or more S2 identifiers.
86    #[must_use]
87    pub const fn is_id(self) -> bool {
88        matches!(self, Kind::Id | Kind::IdArray(_))
89    }
90}
91
92/// One property of an S2 object type.
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94pub struct Property {
95    /// The name as it appears on the wire, misspellings included.
96    pub name: &'static str,
97    /// Whether the schema lists it in `required`.
98    pub required: bool,
99    /// What it holds.
100    pub kind: Kind,
101}
102
103/// One S2 object type.
104#[derive(Debug, Clone, Copy, PartialEq, Eq)]
105pub struct TypeSpec {
106    /// The schema file's name: `FRBC.Instruction`, `NumberRange`.
107    pub name: &'static str,
108    /// The `message_type` constant, for the 36 types that are messages.
109    pub message_type: Option<&'static str>,
110    /// Its properties, in schema order.
111    pub properties: &'static [Property],
112}
113
114impl TypeSpec {
115    /// The named property, if the type has one.
116    #[must_use]
117    pub fn property(&self, name: &str) -> Option<&'static Property> {
118        self.properties.iter().find(|p| p.name == name)
119    }
120}
121
122/// The specification for a type, by schema name.
123#[must_use]
124pub fn type_spec(name: &str) -> Option<&'static TypeSpec> {
125    TYPES
126        .binary_search_by(|t| t.name.cmp(name))
127        .ok()
128        .and_then(|i| TYPES.get(i))
129}
130
131/// The specification for a type as a given wire profile defines it.
132///
133/// The two tagged versions of S2 JSON differ in exactly one type, so this is an overlay
134/// with a fall-through rather than two tables: [`BETA_TYPES`] first when the profile is
135/// `v0.0.2-beta`, [`TYPES`] otherwise and as the fallback.
136///
137/// Using this rather than [`type_spec`] is what keeps a lenient decoder from pruning
138/// `DDBC.SystemDescription.present_demand_rate` — a **required** property of that
139/// profile, and absent from `v1.0.0` — out of a message and then refusing it for the
140/// field it just removed.
141#[must_use]
142pub fn type_spec_in(profile: WireProfile, name: &str) -> Option<&'static TypeSpec> {
143    match profile {
144        WireProfile::V0_0_2Beta => BETA_TYPES
145            .iter()
146            .find(|t| t.name == name)
147            .or_else(|| type_spec(name)),
148        WireProfile::V1_0_0 => type_spec(name),
149    }
150}
151
152/// The specification for a message, by its `message_type`.
153#[must_use]
154pub fn message_spec(message_type: &str) -> Option<&'static TypeSpec> {
155    TYPES.iter().find(|t| t.message_type == Some(message_type))
156}
157
158/// Every message type the vendored schemas define.
159pub fn message_types() -> impl Iterator<Item = &'static str> {
160    TYPES.iter().filter_map(|t| t.message_type)
161}
162
163/// How deep [`prune_unknown`] will walk.
164///
165/// The schema's own deepest path is
166/// `PPBC.PowerProfileDefinition → container → sequence → element → value`, five levels.
167/// Twice that is room for a schema that grows and a bound that does not depend on a value
168/// a peer chose: the walk is driven by the *schema*, but the value decides how many array
169/// elements each level has, and a recursion whose depth nothing states is a recursion
170/// nobody has checked.
171pub const MAX_PRUNE_DEPTH: usize = 16;
172
173/// Removes properties the schema does not define, recursively, reporting each.
174///
175/// This is what `Strictness::Lenient` does before decoding. It is deliberately *not* a
176/// validator: it removes what the types cannot represent and leaves everything else —
177/// including values that are out of range — for [`crate::validate`] to judge and report.
178///
179/// Returns the number of properties removed. Each is named in `removed` as a JSON
180/// pointer, so a proxy can tell its operator exactly what it dropped. Below
181/// [`MAX_PRUNE_DEPTH`] nothing is pruned and nothing is reported: the typed decode that
182/// follows refuses the message anyway, so the only thing a deeper walk buys is a deeper
183/// stack.
184pub fn prune_unknown(
185    value: &mut serde_json::Value,
186    type_name: &str,
187    profile: WireProfile,
188    removed: &mut Vec<String>,
189) -> usize {
190    prune_at(value, type_name, profile, "", removed, MAX_PRUNE_DEPTH)
191}
192
193fn prune_at(
194    value: &mut serde_json::Value,
195    type_name: &str,
196    profile: WireProfile,
197    path: &str,
198    removed: &mut Vec<String>,
199    depth: usize,
200) -> usize {
201    let Some(depth) = depth.checked_sub(1) else {
202        return 0;
203    };
204    let Some(spec) = type_spec_in(profile, type_name) else {
205        return 0;
206    };
207    let Some(object) = value.as_object_mut() else {
208        return 0;
209    };
210
211    let mut count = 0;
212    let unknown: Vec<String> = object
213        .keys()
214        .filter(|k| k.as_str() != "message_type" && spec.property(k).is_none())
215        .cloned()
216        .collect();
217    for key in unknown {
218        removed.push(alloc::format!("{path}/{key}"));
219        object.remove(&key);
220        count += 1;
221    }
222
223    for property in spec.properties {
224        let Some(child) = object.get_mut(property.name) else {
225            continue;
226        };
227        let child_path = alloc::format!("{path}/{}", property.name);
228        match property.kind {
229            Kind::Object(inner) => {
230                count += prune_at(child, inner, profile, &child_path, removed, depth);
231            }
232            Kind::ObjectArray(inner, _) => {
233                if let Some(items) = child.as_array_mut() {
234                    for (i, item) in items.iter_mut().enumerate() {
235                        let item_path = alloc::format!("{child_path}/{i}");
236                        count += prune_at(item, inner, profile, &item_path, removed, depth);
237                    }
238                }
239            }
240            Kind::Scalar | Kind::Id | Kind::ScalarArray(_) | Kind::IdArray(_) => {}
241        }
242    }
243    count
244}
245
246#[cfg(test)]
247mod tests {
248    use super::*;
249    use crate::message::MessageKind;
250    use alloc::string::ToString;
251
252    #[test]
253    fn the_table_covers_every_message_the_crate_claims() {
254        // The generated table comes from the vendored schema directory; MessageKind is
255        // hand-written. If they disagree, one of them is wrong — which is the whole
256        // point of generating the table rather than trusting the enum.
257        let mut from_schema: Vec<&str> = message_types().collect();
258        from_schema.sort_unstable();
259        let mut from_rust: Vec<&str> = MessageKind::ALL.iter().map(|k| k.as_str()).collect();
260        from_rust.sort_unstable();
261        assert_eq!(from_schema, from_rust);
262    }
263
264    #[test]
265    fn the_beta_overlay_is_the_one_place_the_two_tags_differ() {
266        // Every type the overlay names must also exist in the main table, and must differ
267        // from it — an overlay entry that is identical is dead weight that hides the one
268        // real difference.
269        for spec in BETA_TYPES {
270            let base = type_spec(spec.name).expect("an overlay type the main table lacks");
271            assert_ne!(
272                base.properties, spec.properties,
273                "{} is in the overlay but identical to v1.0.0",
274                spec.name
275            );
276        }
277        // And the difference is a *property*, never an array bound: `check_array` reads
278        // the main table alone, which is only sound while that stays true.
279        for spec in BETA_TYPES {
280            let base = type_spec(spec.name).expect("an overlay type");
281            for property in spec.properties {
282                if let Some(same) = base.property(property.name) {
283                    assert_eq!(
284                        same.kind.bounds(),
285                        property.kind.bounds(),
286                        "{}/{} has different array bounds per profile",
287                        spec.name,
288                        property.name
289                    );
290                }
291            }
292        }
293    }
294
295    #[test]
296    fn a_property_a_profile_requires_is_not_pruned_out_of_it() {
297        // The bug this pins: the property table is v1.0.0's, and
298        // `DDBC.SystemDescription.present_demand_rate` is *required* in `0.0.2-beta` and
299        // absent from v1.0.0. Pruning a beta message against the v1.0.0 table removed the
300        // required field and the typed decode then refused the message for missing it —
301        // so an analyzer could not read a conforming beta transcript at all.
302        let text = r#"{"message_type":"DDBC.SystemDescription","message_id":"m1",
303            "valid_from":"2019-08-24T14:15:22Z","actuators":[],
304            "present_demand_rate":{"start_of_range":0.0,"end_of_range":1.0},
305            "provides_average_demand_rate_forecast":false,"vendor":1}"#;
306
307        let mut value: serde_json::Value = serde_json::from_str(text).unwrap();
308        let mut removed = Vec::new();
309        let n = prune_unknown(
310            &mut value,
311            "DDBC.SystemDescription",
312            WireProfile::V0_0_2Beta,
313            &mut removed,
314        );
315        assert_eq!(n, 1, "only the vendor extension should go");
316        assert_eq!(removed, alloc::vec!["/vendor".to_string()]);
317        assert!(value.get("present_demand_rate").is_some());
318
319        // And against v1.0.0 it *is* unknown, because that tag removed it.
320        let mut value: serde_json::Value = serde_json::from_str(text).unwrap();
321        let mut removed = Vec::new();
322        prune_unknown(
323            &mut value,
324            "DDBC.SystemDescription",
325            WireProfile::V1_0_0,
326            &mut removed,
327        );
328        assert!(removed.contains(&"/present_demand_rate".to_string()));
329    }
330
331    #[test]
332    fn types_are_sorted_so_lookup_can_binary_search() {
333        for pair in TYPES.windows(2) {
334            if let [a, b] = pair {
335                assert!(a.name < b.name, "{} should sort before {}", a.name, b.name);
336            }
337        }
338        assert!(type_spec("FRBC.Instruction").is_some());
339        assert!(type_spec("NumberRange").is_some());
340        assert!(type_spec("Nope").is_none());
341    }
342
343    #[test]
344    fn array_bounds_came_from_the_schema() {
345        let forecast = type_spec("PowerForecast").unwrap();
346        let elements = forecast.property("elements").unwrap();
347        assert_eq!(
348            elements.kind,
349            Kind::ObjectArray(
350                "PowerForecastElement",
351                ArrayBounds {
352                    min: Some(1),
353                    max: Some(288)
354                }
355            )
356        );
357        let details = type_spec("ResourceManagerDetails").unwrap();
358        assert_eq!(
359            details.property("roles").unwrap().kind.bounds(),
360            Some(ArrayBounds {
361                min: Some(1),
362                max: Some(3)
363            })
364        );
365        // And `PEBC.PowerConstraints` really does demand at least two limit ranges.
366        let constraints = type_spec("PEBC.PowerConstraints").unwrap();
367        assert_eq!(
368            constraints
369                .property("allowed_limit_ranges")
370                .unwrap()
371                .kind
372                .bounds()
373                .unwrap()
374                .min,
375            Some(2)
376        );
377    }
378
379    #[test]
380    fn required_flags_came_from_the_schema() {
381        let details = type_spec("ResourceManagerDetails").unwrap();
382        assert!(details.property("resource_id").unwrap().required);
383        assert!(!details.property("name").unwrap().required);
384        assert!(!details.property("currency").unwrap().required);
385    }
386
387    #[test]
388    fn pruning_removes_only_what_the_schema_does_not_define() {
389        let mut value: serde_json::Value = serde_json::from_str(
390            r#"{
391                "message_type": "FRBC.ActuatorStatus",
392                "message_id": "m1",
393                "actuator_id": "a1",
394                "active_operation_mode_id": "om1",
395                "operation_mode_factor": 0.5,
396                "vendor_extension": {"anything": 1}
397            }"#,
398        )
399        .unwrap();
400        let mut removed = Vec::new();
401        let n = prune_unknown(
402            &mut value,
403            "FRBC.ActuatorStatus",
404            WireProfile::V1_0_0,
405            &mut removed,
406        );
407        assert_eq!(n, 1);
408        assert_eq!(removed, alloc::vec!["/vendor_extension".to_string()]);
409        assert!(value.get("vendor_extension").is_none());
410        assert!(value.get("operation_mode_factor").is_some());
411        assert!(value.get("message_type").is_some(), "the tag must survive");
412    }
413
414    #[test]
415    fn pruning_stops_at_a_depth_a_peer_did_not_choose() {
416        // The schema's deepest real path is five levels, so the cap never fires on a
417        // legitimate message — this asserts it exists rather than that it bites.
418        const { assert!(MAX_PRUNE_DEPTH > 8) };
419
420        // A nested value as deep as the schema allows is still pruned all the way down.
421        let mut value: serde_json::Value = serde_json::from_str(
422            r#"{
423                "message_type": "PPBC.PowerProfileDefinition",
424                "message_id": "m1", "id": "p1",
425                "start_time": "2024-01-01T00:00:00Z",
426                "end_time": "2024-01-02T00:00:00Z",
427                "power_sequences_containers": [
428                  {"id": "c1", "power_sequences": [
429                    {"id": "s1", "elements": [
430                      {"duration": 900000, "power_values": [
431                        {"value_expected": 1.0,
432                         "commodity_quantity": "ELECTRIC.POWER.L1",
433                         "surprise": 1}]}],
434                     "is_interruptible": false, "abnormal_condition_only": false}]}]
435            }"#,
436        )
437        .unwrap();
438        let mut removed = Vec::new();
439        assert_eq!(
440            prune_unknown(
441                &mut value,
442                "PPBC.PowerProfileDefinition",
443                WireProfile::V1_0_0,
444                &mut removed
445            ),
446            1
447        );
448        assert_eq!(
449            removed,
450            alloc::vec![
451                "/power_sequences_containers/0/power_sequences/0/elements/0/power_values/0/surprise"
452                    .to_string()
453            ]
454        );
455    }
456
457    #[test]
458    fn pruning_reaches_into_nested_objects_and_arrays() {
459        let mut value: serde_json::Value = serde_json::from_str(
460            r#"{
461                "message_type": "FRBC.SystemDescription",
462                "message_id": "m1",
463                "valid_from": "2019-08-24T14:15:22Z",
464                "actuators": [
465                  {"id": "a1", "supported_commodities": ["ELECTRICITY"],
466                   "operation_modes": [
467                     {"id": "om1", "elements": [], "abnormal_condition_only": false,
468                      "surprise": 1}
469                   ],
470                   "transitions": [], "timers": [], "mystery": true}
471                ],
472                "storage": {"provides_leakage_behaviour": false,
473                            "provides_fill_level_target_profile": false,
474                            "provides_usage_forecast": false,
475                            "fill_level_range": {"start_of_range": 0, "end_of_range": 100,
476                                                 "hidden": 2}}
477            }"#,
478        )
479        .unwrap();
480        let mut removed = Vec::new();
481        let n = prune_unknown(
482            &mut value,
483            "FRBC.SystemDescription",
484            WireProfile::V1_0_0,
485            &mut removed,
486        );
487        assert_eq!(n, 3, "{removed:?}");
488        removed.sort();
489        assert_eq!(
490            removed,
491            alloc::vec![
492                "/actuators/0/mystery".to_string(),
493                "/actuators/0/operation_modes/0/surprise".to_string(),
494                "/storage/fill_level_range/hidden".to_string(),
495            ]
496        );
497    }
498}