--- id: "VOLT-HOME-WP-098" title: "Can schema contracts prevent silent breakage in home-energy integrations?" slug: "can-schema-contracts-prevent-silent-breakage-in-home-energy-integrations" description: "Four deterministic breaking-change fixtures show what explicit required-field and interval validation can detect—and what remains untested." published: "2026-08-30" cluster: "Reliable automation and machine-readable energy evidence" status: "measured" evidence: "/research-data/home-papers/can-schema-contracts-prevent-silent-breakage-in-home-energy-integrations.json" figure: "/research-media/home-papers/can-schema-contracts-prevent-silent-breakage-in-home-energy-integrations.webp" figure_alt: "Chart for Can schema contracts prevent silent breakage in home-energy integrations?: schema-contract detection rate in declared breaking-change fixtures, shown as 8 fields, 12 fields, 16 fields, 20 fields." source_ids: - "google-article" - "google-structured-data" - "google-scaled-content" - "entsoe-sdac" - "volt-architecture" peer_reviewed: false --- ## Abstract Home-energy integrations often fail dangerously when a payload still parses but no longer means what the controller assumes. A renamed field, changed unit, absent interval boundary, or altered cardinality can produce a plausible schedule without producing an obvious exception. This paper evaluates four deterministic breaking-change fixtures with 8, 12, 16, and 20 fields. Every fixture removes or changes one required contract. The registered validator detected 100% of the four fixtures, and the artifact reports no uncertainty interval for this estimand. The result demonstrates the value of explicit required-field and interval-contract validation in the declared fixtures. It does not estimate detection of arbitrary future schema changes. The four cases are deterministic fault injections, not production incidents, customer failures, or a claimed run of a repository-wide test suite. A robust integration should validate syntax, types, units, enumerations, interval continuity, target windows, freshness, and cross-field invariants before generating a schedule. Unknown or incompatible schema versions must be quarantined. Additive fields can be accepted only under a declared compatibility policy, while removed or semantically changed required fields should fail closed. Production-origin receipts in the wider research family provide infrastructure context, but the primary 100% here comes solely from fixtures. Schema contracts reduce silent breakage by converting known incompatibilities into explicit rejection; they cannot eliminate unknown semantic errors without layered monitoring and end-to-end receipts. ## Plain-language answer Yes, for the four breakages that were deliberately constructed. The validator rejected every declared fixture in which a required contract was removed or changed. That is a 100% detection rate across four cases. No, this does not prove that a schema catches every future bug. A payload can satisfy field types and still use the wrong timezone, unit, target date, revision, or business meaning. A downstream adapter can also discard information after the API response has passed validation. Use a schema as the first gate, then add semantic checks. Confirm that intervals are ordered and complete, prices use the expected unit, the zone and delivery window match the request, the resolution is supported, and timestamps are fresh. If any required property is missing or incompatible, stop the new automation plan and surface an explicit contract error. Do not fill a missing field with a convenient default unless that default is part of the versioned contract. ## Research question The research question is whether schema contracts can turn breaking API changes into explicit failures before a home-energy integration silently changes behavior. “Silent breakage” means the workflow continues while its output no longer represents the intended market intervals or control decision. The registered outcome is narrow and deterministic: detection of one required-contract mutation in each of four fixture sizes. It does not sample production schema changes. The sample size is four fixtures, and the field counts identify fixture complexity rather than independent systems or customers. The decision criterion is fail-closed compatibility. A payload may proceed only if its declared schema version and all required syntactic and semantic invariants are accepted. An unsupported version, missing required member, changed type, invalid interval, or inconsistent target must block schedule generation. The paper also asks what a schema cannot do, because treating validation as complete safety would itself create silent risk. ## Data and provenance The evidence JSON identifies `VOLT-HOME-WP-098`, status `measured`, schema `volt-home-paper-evidence-v1`, and publication cutoff 2026-08-30T00:00:00Z. Its assumption states: “Four deterministic fixture sizes; every fixture removes or changes one required contract.” The primary metric is “schema-contract detection rate in declared breaking-change fixtures,” with sample size four, value 100%, and no reported interval. The fixture labels are 8 fields, 12 fields, 16 fields, and 20 fields. The analysis supplies a detection outcome of 100 for each case. These are constructed inputs in the frozen analysis code. They are not records extracted from the production snapshot and not observed integration outages. The corpus provenance still binds the artifact to analysis-code SHA-256 `57c57de79cdab2b5b6d6c54c485cb5162598c5ba0b0bfe995da40d75e6c52ba9`, snapshot SHA-256 `7e97489fc8528c8cc8c38830e05b48d949ce1f67b98575dff26f5d7c321e4c67`, protocol SHA-256 `adb36bf6b447af9f96339249b8becaefc20422499cca1977242866347a97bd4b`, paper-registry SHA-256 `7bcb91d7476d0a69fe9fa75a5c7782f8117e0153f82f9112b7e1d307d3943717`, and source-registry SHA-256 `07949550ac443ff673fda5c0209b99f137544f3ffecf6775f109bb9d09663bd6`. The evidence-manifest hashes are `5d0574a931c7b79b19af0ef36332799a57f97074529e349f806422171f2e7070` for the JSON and `ad06ef2a4a3e52a0d85ed0f8982fc66c28fbddfaed3db3d947de86cdf07d2866` for the WebP figure. The snapshot extraction was read-only, but the primary fixture result does not depend on a production receipt count. The family source contract lists auction publications, grid revisions, ingestion runs, public API schemas, and repository integration fixtures. This paper uses the fixture side of that contract. No claim is made that a named repository test command was run. ## Method The registered analysis defines four field-count labels and assigns a detected-breaking-change result to each. Every fixture changes or removes one required contract. The primary value is the mean detection percentage across the four outcomes, which is 100%. The regenerated evidence records `bootstrap_95_interval: null` and `interval_method: "not reported for this estimand"`. This method is best interpreted as a deterministic acceptance demonstration. It proves the frozen validator model recognizes all declared mutations. It does not estimate generalization because there are no undetected fixture classes, randomized mutations, production incidents, or independent adapter implementations in the sample. A production-grade contract should operate in layers. Structural validation checks object shape, required fields, primitive types, nullable rules, and version identifiers. Domain validation checks price units, currency, zone codes, resolution, UTC timestamps, and allowed enumerations. Temporal validation checks ordered non-overlapping intervals, complete target coverage, publication and revision clocks, and freshness. Decision validation confirms the payload supports the requested appliance window. Only then should an integration construct commands. Strict rejection and permissive evolution have a tradeoff. Rejecting every unknown field makes harmless additive changes disruptive. Ignoring all unknowns improves forward compatibility but can hide semantic drift. A practical policy tolerates additive fields, rejects removal or incompatible alteration of required fields, and requires explicit support for new schema versions or changed semantics. The native payload remains archived for diagnosis. ## Results The schema-contract detection rate is 100% across four declared breaking-change fixtures. The figure values are exactly 100%, 100%, 100%, and 100% for the 8-, 12-, 16-, and 20-field fixtures. The evidence reports no interval. The predefined interpretation is that required-field and interval-contract validation turns silent shape drift into an explicit rejected payload. ![Chart for Can schema contracts prevent silent breakage in home-energy integrations?: schema-contract detection rate in declared breaking-change fixtures, shown as 8 fields, 12 fields, 16 fields, 20 fields.](/research-media/home-papers/can-schema-contracts-prevent-silent-breakage-in-home-energy-integrations.webp) The field-count labels show that the demonstration spans four fixture sizes, but the evidence does not enumerate which required member changed in each case. It also does not report additive-change behavior, error messages, validation latency, adapter versions, or device outcomes. The result supports the proposition that declared contracts can prevent the tested classes of silent breakage. It does not justify “schema contracts prevent all silent breakage.” Unknown semantic errors, controller bugs after validation, and device-side incompatibilities remain outside the measured boundary. ## Robustness and placebo checks A good fixture suite should pair each breaking case with a valid control of the same size. The valid control checks that strictness does not reject compatible payloads. Additive-field placebos should also pass under a forward-compatible policy, while required-field removal, incompatible type changes, invalid units, or broken interval boundaries should fail. These are recommended extensions; the evidence reports only four detected breaking fixtures. Mutation coverage should expand beyond field count. Useful deterministic faults include wrong timezone offsets, swapped interval boundaries, unsupported resolution, price represented in the wrong unit, duplicated delivery starts, stale issue times, conflicting revision identities, and a target day that is internally valid but not the one requested. None is claimed as measured unless it is present in the frozen four-case artifact. Production canaries should validate real responses without authorizing device actions. They can compare payload shape and semantic invariants against a known schema version, then alert on drift. Production-origin canaries and deterministic fixtures should have separate metrics so a fixture pass is not confused with real-world compatibility. The outcome is descriptive. The family’s Holm rule would matter for inferential comparisons across validators or mutation classes, but no such inference is made. ## Limitations Four deterministic fixtures are a small, designed set. Their 100% result has no direct denominator of all possible breaking changes. The absence of a reported interval should not be read as population certainty. The analysis does not expose fixture contents, error classes, or validator implementation details in the paper-level JSON. A reader can reproduce the aggregate from the registered code, but the public result alone cannot assess mutation coverage. A schema validates data at one boundary. An adapter can still mis-map a valid field, aggregate native intervals incorrectly, cache stale data, or send a duplicate device command. A customer network or firmware can fail after a perfect API validation. The evidence limitation explicitly excludes those downstream guarantees. No repository test command or production incident sample is reported. The primary result is entirely fixture-based. It makes no claim about savings, forecast accuracy, availability, or trading. ## Practical implication Publish and consume a versioned machine-readable contract. Require stable identifiers for zone, product, delivery start and end, native resolution, price and unit, source, publication or issue time, and revision. Generate typed clients where useful, but keep runtime validation at trust boundaries because generated types do not validate arbitrary network input. After structural validation, enforce cross-field invariants. Intervals must be ordered, non-overlapping, and complete for the requested target. Duration and resolution must agree. The target date must match the query. Freshness and revision lineage must pass. Hash the canonical validated payload and bind that hash to the generated schedule. On failure, quarantine the payload and expose an explicit incompatibility reason. Do not continue with nulls, zeroes, repeated prior values, or guessed units. Keep a locally declared appliance-safe fallback independent of the remote schema. Permit additive changes only under a documented policy; require deliberate adapter support for incompatible versions. ## Reproducibility Verify frontmatter and evidence identity, then confirm all five provenance hashes and both evidence-manifest artifact hashes. Recreate the four fixture labels—8, 12, 16, and 20 fields—and the registered condition that each removes or changes one required contract. Run the frozen detection calculation and confirm four 100 outcomes, a mean of 100%, and no reported interval. A stronger replication should publish every mutation, expected error, validator version, and valid paired control. It should separately report false acceptance of breaking payloads and false rejection of compatible payloads. If production responses are sampled, their receipts and schema versions must be distinguished from fixtures. Changing fixture classes or validator rules creates a new experiment. Preserve this artifact and publish a new protocol, cutoff, and evidence hash rather than expanding the meaning of the frozen 100%. ## Disclosure Analysis and drafting were model-assisted. This is a public working paper. It is not peer reviewed. The fixture assumptions, evidence paths, code hash, and limitations are disclosed. Voltcast publishes the cited internal architecture and produced the aggregate. The primary result comes from deterministic fixtures, not production failures, customer devices, or a claimed repository-test run. Volt has no live traders or live capital; C0R is its only paper strategy, and production weather forecasting is non-trading. This paper is not trading advice, integration certification, or a guarantee against all breaking changes. ## References 1. Google Search Central, [Article structured data](https://developers.google.com/search/docs/appearance/structured-data/article). 2. Google Search Central, [Introduction to structured data markup in Google Search](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data). 3. Google Search Central, [Spam Policies for Google Web Search — Scaled content abuse](https://developers.google.com/search/docs/essentials/spam-policies). 4. ENTSO-E, [Single Day-ahead Coupling (SDAC)](https://www.entsoe.eu/network_codes/cacm/implementation/sdac/). 5. Voltcast, [Voltcast Architecture](https://github.com/ossedk/voltcast/blob/main/docs/voltcast/ARCHITECTURE.md).