Meter Data CSV Schema Changes: A Version Contract for Safe Imports
A meter data CSV schema version contract defines what each column means, which values are permitted and which importer versions can safely read the file. Before changing an export, agree that contract with the receiving system, test both compatible and incompatible examples, and make unknown versions fail visibly. A file opening successfully in a spreadsheet is not evidence that its electrical measurements will be interpreted correctly.
This guide covers the agreement between an external data exporter and importer. It does not prescribe a built-in CSV function for any meter. For an industrial installation, measurements may pass through a gateway, supervisory application or reporting service before a CSV file exists.
Separate file syntax from measurement meaning
CSV describes a text arrangement, not the full engineering meaning of its contents. RFC 4180 documents common CSV conventions, including records, fields and quoting. It is informational; it does not define your meter identifiers, energy direction, quality codes or time boundaries. Two files can follow the same quoting convention while representing entirely different measurements.
The W3C tabular data model provides a useful distinction between tabular values and metadata that helps describe or validate them. Use that distinction when specifying your own exchange. Document both how a value is written and what a receiving system is allowed to conclude from it.
For example, a column called energy could represent a cumulative register or interval consumption. Renaming it is less consequential than changing that meaning without a new contract. State the measurement boundary, direction and unit explicitly. Otherwise an importer may create a plausible chart from the wrong quantity.
Identify the contract before processing rows
Assign a stable identifier to the format and a controlled revision to its interpretation. Record where the receiving system obtains them: a companion metadata record, an agreed file envelope or an explicitly specified column. A filename alone is only suitable if the receiving workflow validates it and preserves the association throughout processing.
Do not infer a revision from the number of columns. Different revisions can have the same field count. Similarly, do not guess from a recent date in the filename. The date could indicate extraction time rather than the version under which the data was produced.
Keep the exporter software version separate from the exchange contract version. A software patch may leave the file unchanged; a configuration adjustment may change field meaning without updating the executable. The contract must describe the actual exchange, while a separate provenance record identifies what created it.
Write the minimum field agreement
Create a short controlled document that a second engineer can use without asking the original author. For every field, record its stable name, meaning, type, allowed empty state and validation rule. Include examples that expose ambiguity rather than examples that only show the easiest case.
| Contract item | Record explicitly | Reject or quarantine when |
|---|---|---|
| Meter identity | Stable asset identifier and approved mapping | Identifier is unknown or maps to multiple assets |
| Quantity | Physical quantity, direction and measurement boundary | Meaning differs from the approved calculation |
| Unit and scale | Unit, multiplier and application location | Scaling would be applied twice or cannot be established |
| Time | Zone, interval convention and timestamp interpretation | A timestamp cannot be assigned unambiguously |
| Missing reading | Difference between missing, invalid and measured zero | A blank would silently become zero |
| Quality | Permitted codes and downstream handling | A new code has no agreed interpretation |
| Revision | Supported contract identifiers and transition rule | The receiver does not recognize the version |
These are project design checks, not universal meter specifications. The syntax and metadata references above support the distinction; the actual allowed values come from your documented installation and receiving application.
Classify a change by its effect on the receiver
An added optional field may be compatible with a receiver that selects known columns by name and deliberately ignores approved extras. It can break a receiver that expects an exact positional layout. Therefore optional does not automatically mean safe. Compatibility is a property of the documented producer and consumer pair.
Removing a required field, changing a unit, reversing the energy direction or altering an interval boundary normally requires explicit migration work. Treat a changed quality-code meaning with the same care as a changed numeric field. The number may remain identical while its permitted use changes.
Column reordering deserves its own test. If the contract promises name-based mapping, verify that the receiver honors that promise. If the exchange is positional, reject an unexpected sequence. Never rely on a person noticing that a spreadsheet heading has moved.
Build a small but deliberate test pack
Keep one approved file for each supported revision and a separate set of intentionally rejected examples. Include quoted commas, a blank field, an unknown asset identifier, an unsupported quality code and a timestamp that exercises the chosen time convention. Label invented test readings as test data and keep them away from production ingestion.
For a unit change, choose a synthetic example whose wrong interpretation is unmistakable. Compare the expected interpreted quantity with the actual receiver output, not just the import-success message. A test that proves only that a file was accepted says nothing about whether its measurements were preserved.
Also test the transition boundary. A batch may contain files produced before and after the change. Decide whether both revisions can coexist, whether they use separate queues, and how corrected historic files are handled. Store the decision with the test evidence so that a later re-import does not rely on memory.
A practical migration example
Suppose an external reporting service currently sends cumulative energy and a planned update adds interval energy. Keep the cumulative field meaning intact and give the additional quantity a distinct name. Specify its unit, interval duration, timestamp boundary and missing-data behavior before anyone updates the receiving report.
Run an approved sample through a nonproduction receiver. Check that the existing cumulative display remains unchanged and that the new interval series is calculated or stored according to the contract. Then send an intentionally mislabeled sample and confirm that the importer rejects it with a useful explanation.
If the proposed update replaces the original field rather than adding a new one, do not reuse the old contract identifier. Prepare a migration mapping and decide which historical outputs need a version marker. This example describes exchange design; it does not establish an export feature, accuracy rating or billing approval for a particular instrument.
Preserve the original evidence during rejection
A rejected file should remain available in a controlled evidence location, alongside the reason, receiving software version and attempted contract identifier. Preserve the received bytes. If a corrected file is supplied, give it a distinct revision and record what it supersedes rather than overwriting the rejected original.
The receiver should distinguish syntax errors from contract errors and engineering validation errors. An unmatched quote differs from an unsupported unit, and both differ from an implausible reading. Separate reasons help the right person resolve the problem without repeatedly modifying a valid source file.
For related controls, use the meter export file integrity guide to preserve received files and the CSV header and encoding guide to address text interpretation. Those checks complement a version contract; neither establishes semantic compatibility alone.
Assign approval and operational ownership
Name the owner of the exporter configuration, the receiving import rules and the electrical interpretation. One person may fill several roles, but the approval record should still answer each question. A data specialist can validate field types without being authorized to approve a change in the measurement boundary.
Set a transition date and a rollback decision point. Record what happens to files waiting in a queue during the change. If the receiver is reverted, determine whether newer files remain quarantined or require a separately validated conversion. Never silently reinterpret them under an older contract because the older software happens to accept their shape.
A support handover should include the approved contract, sample files, expected results, known rejection messages and the current compatibility matrix. This makes future changes testable and reduces the chance that a replacement integrator reverse engineers the format from one convenient file.
Relate the exchange to the actual installed meter
Begin with the correct device and its documented settings. The BY194 multifunctional instrument product page is the product reference for this article. Confirm the exact ordered variant and available measurements separately; a product photograph cannot establish an export format, gateway function or archive capability.
Use the three-phase electric power meter overview for measurement context, then trace each external field back through the approved point mapping. A well-written CSV contract cannot repair an incorrect current-transformer ratio or a mismatched register interpretation upstream.
The following Computerphile lesson explains race conditions in shared processes. It is conceptual background for coordinating producer and consumer changes, not a meter-specific configuration procedure or a substitute for the tests described here.
Frequently asked questions
Does a new optional column always require a new contract revision?
Record the change under your controlled revision policy even when it is backward compatible. Whether a receiver can accept the column depends on its documented mapping and validation behavior. Verify that behavior with an actual test rather than assuming every importer ignores extra fields safely.
Can the receiver automatically guess an unknown CSV version?
Automatic guessing risks assigning the wrong meaning to valid-looking numbers. Quarantine an unknown version and report the evidence needed for review. A conversion may be approved later, but it should be explicit, tested and traceable to the original file.
Is a checksum enough to prove compatibility?
A checksum helps detect a byte change relative to a trusted reference. It does not describe field meaning, measurement units or whether the receiver supports the format. Preserve integrity evidence and validate the contract as separate steps.
Should historical files be rewritten when the contract changes?
Preserve original evidence and its original contract association. If a normalized copy is required, record its transformation, version and relationship to the source. Review retention and reporting obligations before deciding whether any historical derived outputs also need regeneration.