mdqmodels

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 9 Imported by: 0

README

mdq-models

Go Tests Go Lint Go Reference Python Tests Python Coverage Python Lint Python Formatting Proto Packaging Test

Data models of the canonical meter-reading schema, version 1: Messwert (one value per market location and quarter hour), Zaehlerstand (a meter reading, the second input of the schema) and Einflusswert (one value of an influencing quantity such as weather, per market location and period).

This repository holds

  • Go types (package mdqmodels, module github.com/hochfrequenz/mdq-models),
  • Python frozen pydantic v2 models (package mdq_models) and an optional Polars table schema (mdq_models.polars, extra polars),
  • the shared fixtures in testdata/ that define the JSON contract, and
  • the gRPC contract in proto/mdq/v1.

Everything is written by hand. No code is generated and no generated code is committed: every type, validator and (un)marshaller is ordinary, readable code. Field names and enum values are German (malo, herkunft, vorlaeufig, ...) and are part of the contract. Both languages parse every valid fixture, write it back byte-for-byte as pinned in testdata/serialized.golden and reject every invalid fixture, so Go and Python agree on the contract by construction.

The contract in short

Topic Rule
Messwert keys In this order on output: malo, timestamp, resolution, value, status, herkunft, profiltyp, richtung. All eight are required; value and herkunft are required-but-nullable (always written, null when unset). A missing key is rejected, also when its value would be null.
Zaehlerstand keys malo, timestamp, value, all required; value is never null.
Einflusswert keys In this order on output: malo, timestamp, resolution, groesse, value, quelle. All six are required; value is required-but-nullable (always written, null when the value is missing).
Strict reading Unknown keys and duplicate keys are rejected (at every nesting level), so a typo fails loudly and two parsers cannot read different data from the same bytes. Key order matters only for output; parsing accepts any order. The top level must be a JSON object. Invalid UTF-8, a byte order mark and UTF-16 are rejected.
malo ^[1-9][0-9]{10}$ (ASCII digits only) with a valid BDEW check digit.
timestamp RFC 3339, upper-case T, offset exactly Z, whole seconds, years 1900-9999, ASCII digits only. For Messwert it is the start of the quarter hour (00:00 is the first of a day, 23:45 the last; it equals the start of a [from, to) interval) and must be on the raster (minute divisible by 15, second 0). For Zaehlerstand it is a point in time with any whole second. Built in code, a timestamp in any time zone is accepted and written in UTC; a naive timestamp is rejected.
resolution Messwert: only "PT15M" in v1. Einflusswert: "PT1H" or "PT15M".
groesse Einflusswert only: temperatur (air temperature 2 m above ground, mean or representative value of the period, degrees Celsius) or globalstrahlung (mean irradiance over the period, W/m²). Case-sensitive.
quelle Einflusswert only: where the value comes from, 1 to 64 printable ASCII characters without spaces, for example dwd:01993.
Einflusswert raster timestamp is the start of the period [timestamp, timestamp + resolution). For PT1H it is on the full hour, for PT15M on the quarter hour.
Einflusswert value A decimal string as for Messwert, or null for a missing value. "0" is the value 0, not a missing value. There is no sign rule: a temperature below zero is a normal value.
value A decimal string in its shortest canonical form ("160", "0.022", "-3.5"), never a JSON number. At most 12 integer digits and at most 6 decimals (counted after stripping trailing zeros). No exponent, no plus sign, no leading zeros, no trailing zeros after the point ("1.0" is rejected), no negative zero, no separators. Negative values are allowed. Producers that compute in floating point must round to 6 decimals first: "0.1234567" is rejected, not rounded.
status wahr, vorlaeufig, ersatzwert, fehlend. Case-sensitive; the retired gemessen is rejected.
herkunft fremd, mqa. null iff status is fehlend; wahr requires fremd.
value and status value is null iff status is fehlend.
profiltyp haushalt, gewerbe, industrie, unbekannt.
richtung bezug, einspeisung.
Decimals built in code Go NewDecimal and Python's Decimal input normalise trailing zeros ("1.5000000" becomes "1.5") and reject more than 6 decimals, more than 12 integer digits, NaN and Infinity; they never round.
JSON vs. proto The .proto files are the gRPC contract only. The JSON form is produced by the hand-written models, never by protojson (which would write "STATUS_VORLAEUFIG" and omit unset optional fields instead of writing null).

Install

pip install "mdq-models[polars]"   # the extra is only needed for mdq_models.polars
go get github.com/hochfrequenz/mdq-models

Python 3.11 or newer; mdq_models itself depends only on pydantic and never imports polars.

Go

Read untrusted bytes with ParseMesswert / ParseZaehlerstand / ParseEinflusswert: every failure is a *ValidationError. Plain json.Unmarshal reports syntax errors as *json.SyntaxError and leaves a *Messwert nil on a top-level null.

raw := []byte(`{"malo":"68283561554","timestamp":"2026-03-29T00:45:00Z","resolution":"PT15M",` +
	`"value":"1.5","status":"wahr","herkunft":"fremd","profiltyp":"haushalt","richtung":"bezug"}`)
m, err := mdq.ParseMesswert(raw) // every failure is a *mdq.ValidationError
if err != nil {
	log.Fatal(err)
}
fmt.Println(m.Malo, m.Timestamp.Format(time.RFC3339), *m.Value, m.Status)

// Build a row in code. NewDecimal drops trailing zeros: "2.50" becomes "2.5".
value, err := mdq.NewDecimal("2.50")
if err != nil {
	log.Fatal(err)
}
mqa := mdq.HerkunftMqa
built := mdq.Messwert{
	Malo:       "68283561554",
	Timestamp:  time.Date(2026, 3, 29, 3, 0, 0, 0, time.FixedZone("CEST", 2*3600)), // written as UTC
	Resolution: mdq.PT15M,
	Value:      &value,
	Status:     mdq.StatusErsatzwert,
	Herkunft:   &mqa,
	Profiltyp:  mdq.ProfiltypHaushalt,
	Richtung:   mdq.RichtungBezug,
}
out, err := built.MarshalJSON() // validates; an invalid row does not marshal
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(out))

// Reading is strict: duplicate (and unknown) keys are rejected.
_, err = mdq.ParseMesswert([]byte(`{"malo":"68283561554","malo":"68283561554"}`))
var invalid *mdq.ValidationError
fmt.Println(errors.As(err, &invalid))
// Output:
// 68283561554 2026-03-29T00:45:00Z 1.5 wahr
// {"malo":"68283561554","timestamp":"2026-03-29T01:00:00Z","resolution":"PT15M","value":"2.5","status":"ersatzwert","herkunft":"mqa","profiltyp":"haushalt","richtung":"bezug"}
// true

(with import mdq "github.com/hochfrequenz/mdq-models"). This snippet is the body of ExampleParseMesswert in example_test.go; a test fails if the two drift apart. Zaehlerstand works the same way. Every type validates itself in UnmarshalJSON and refuses to marshal when invalid; Validate() checks values built in code.

Python

from datetime import datetime, timedelta, timezone
from decimal import Decimal

from pydantic import ValidationError

from mdq_models import Herkunft, Messwert, Profiltyp, Richtung, Status

raw = (
    '{"malo":"68283561554","timestamp":"2026-03-29T00:45:00Z","resolution":"PT15M",'
    '"value":"1.5","status":"wahr","herkunft":"fremd","profiltyp":"haushalt","richtung":"bezug"}'
)
m = Messwert.model_validate_json(raw)  # rejects duplicate and unknown keys
print(m.malo, m.timestamp.isoformat(), m.value, m.status.value)  # 68283561554 2026-03-29T00:45:00+00:00 1.5 wahr

# Build a row in code. Trailing zeros are dropped: Decimal("2.50") is written as "2.5".
built = Messwert(
    malo="68283561554",
    timestamp=datetime(2026, 3, 29, 3, 0, tzinfo=timezone(timedelta(hours=2))),  # written as UTC
    resolution="PT15M",
    value=Decimal("2.50"),
    status=Status.ERSATZWERT,
    herkunft=Herkunft.MQA,
    profiltyp=Profiltyp.HAUSHALT,
    richtung=Richtung.BEZUG,
)
print(built.model_dump_json())  # the same bytes the Go models write

# Reading is strict: duplicate keys are rejected. Only Messwert.model_validate_json checks this by itself; for
# TypeAdapter and nested models call check_json(raw) on the raw document first.
try:
    Messwert.model_validate_json('{"malo":"68283561554","malo":"68283561554"}')
except ValidationError:
    print("rejected")

Plain pydantic keeps the last of two duplicate keys; mdq_models.check_json(raw) is the explicit check for paths that bypass model_validate_json. Use Messwert.model_validate_json (or Zaehlerstand.model_validate_json, Einflusswert.model_validate_json) for raw JSON; the duplicate-key check applies to all three. All parse failures are pydantic.ValidationError.

Polars

mdq_models.polars is the table form Python consumers compute with: seven columns (malo, timestamp, value, status, herkunft, profiltyp, richtung, without resolution, which is always PT15M), value as Float64 and timestamp in Europe/Berlin (UTC is only the wire format). The schema is available as CANONICAL_COLUMNS, CANONICAL_DTYPES and TIMESTAMP_DTYPE.

from mdq_models.polars import from_frame, to_frame

frame = to_frame([m, built])  # seven columns, timestamps in Europe/Berlin
print(frame["timestamp"][0])  # 2026-03-29 01:45:00+01:00
assert from_frame(frame) == [m, built]  # lossless for |value| < 10^9

Float64 keeps a decimal exactly only up to 15 significant digits, so the table form is bounded: to_frame raises ValueError for |value| >= 10^9 and from_frame for a float of that size; neither rounds silently. from_frame converts each float through its shortest representation and quantizes to 6 decimals. Both are strict about the table: unknown columns and wrong dtypes raise ValueError. Importing mdq_models.polars without the extra raises an ImportError that names it.

Einflusswert has its own table, the Einfluss table, with six columns: malo, timestamp, resolution, groesse, value and quelle (the schema is EINFLUSS_COLUMNS and EINFLUSS_DTYPES). Unlike the Messwert table it keeps resolution as a column, because two rasters (PT1H, PT15M) are allowed. timestamp is in Europe/Berlin, value is Float64 with null for a missing value, and NaN is forbidden. einfluss_to_frame and einfluss_from_frame convert from and to Einflusswert rows; pruefe_einfluss_frame(frame) validates a table (for example one read from a file) without building model objects and raises ValueError naming the column and the first affected row.

from mdq_models import Einflusswert
from mdq_models.polars import einfluss_from_frame, einfluss_to_frame, pruefe_einfluss_frame

temperatur = Einflusswert.model_validate_json(
    '{"malo":"68283561554","timestamp":"2026-01-15T10:00:00Z","resolution":"PT1H",'
    '"groesse":"temperatur","value":"-3.5","quelle":"dwd:01993"}'
)
strahlung = Einflusswert.model_validate_json(
    '{"malo":"68283561554","timestamp":"2026-01-15T10:00:00Z","resolution":"PT1H",'
    '"groesse":"globalstrahlung","value":null,"quelle":"dwd:01993"}'
)
frame = einfluss_to_frame([temperatur, strahlung])  # six columns, timestamps in Europe/Berlin
print(frame["timestamp"][0])  # 2026-01-15 11:00:00+01:00
pruefe_einfluss_frame(frame)  # raises ValueError if the table breaks a rule
assert einfluss_from_frame(frame) == [temperatur, strahlung]

The Python snippets above are run by unittests/test_readme.py, so they cannot rot.

Fixtures

testdata/
  messwert/{valid,invalid}/        one JSON document per file (DST days, boundaries, every rejected rule, ...)
  zaehlerstand/{valid,invalid}/
  einflusswert/{valid,invalid}/    one JSON document per file (both rasters, DST days, missing value, ...)
  invalid_reasons.json             why each invalid fixture is rejected
  malo_ids.json                    valid and invalid MaLo IDs, check digits
  herkunft_status.json             all status x herkunft combinations
  proto_enums.json                 proto enum constants, numbers and JSON values
  proto_fields.json                proto messages, field labels, types and numbers
  serialized.golden                the exact bytes both languages write for every valid fixture

testdata/README.md documents every file. Consumers in other languages should run the same fixtures.

serialized.golden pins the output bytes (<fixture>\t<JSON> per line), so Go and Python output is identical: compact JSON, keys in contract order, timestamps in UTC with Z. Every invalid fixture has an entry in testdata/invalid_reasons.json, so a fixture cannot pass by being rejected for the wrong reason.

Einflusswert aus Bright Sky

Rules for everyone who maps Bright Sky responses (hourly DWD weather data) to Einflusswert. The model only knows "the period starting at timestamp"; what a source timestamp means is decided by the mapping.

Request with Bright Sky's default units=dwd (degrees Celsius, kWh/m²). With units=si (K, J/m²) the rules below do not apply as written.

  1. Time reference. Convert every Bright Sky timestamp T to UTC first, then shift. Never calculate in local time.
  2. Global irradiance. solar at T covers the previous 60 minutes, so timestamp = T - 1 h, resolution = PT1H, groesse = globalstrahlung and value = solar * 1000 (kWh/m² per hour is the mean W/m²). Calculate it as a decimal from the JSON text, not via float, so that at most 6 decimals result.
  3. Temperature. temperature at T is an instantaneous value held for [T, T + 1 h), so timestamp = T, resolution = PT1H, groesse = temperatur, degrees Celsius unchanged.
  4. Source. quelle = "dwd:" + dwd_station_id of the entry in sources whose id equals fallback_source_ids[<field>] if present, otherwise the record's source_id.
  5. Missing values. If the source has null, store a missing value ("value": null). Never fill or interpolate it, and never up-sample to 15 minutes.
  6. Licence. DWD data is CC BY 4.0: credit "Quelle: Deutscher Wetterdienst" and state any changes you made. Bright Sky itself is MIT licensed.
  7. Worked example. A Bright Sky record with timestamp "2026-03-29T03:00:00+02:00", source_id 1, temperature 4.2, solar 0.123 and fallback_source_ids {"solar": 2}, with sources id 1 -> dwd_station_id "01993" and id 2 -> "03096" (station ids are illustrative), gives these two documents for the market location 68283561554:
{"malo":"68283561554","timestamp":"2026-03-29T01:00:00Z","resolution":"PT1H","groesse":"temperatur","value":"4.2","quelle":"dwd:01993"}
{"malo":"68283561554","timestamp":"2026-03-29T00:00:00Z","resolution":"PT1H","groesse":"globalstrahlung","value":"123","quelle":"dwd:03096"}

Note the irradiance hour: it runs from 01:00 CET to 03:00 CEST, which is one real hour (UTC 00:00 to 01:00) on the day of the clock change. The 02:00 to 03:00 wall-clock hour does not exist that day.

How CI keeps Go, Python and proto in step

  • Same fixtures. fixtures_test.go and unittests/test_fixtures.py read the same files: every valid fixture must parse and write back the exact bytes of its serialized.golden line, every invalid one must be rejected. Go and Python tests run on every pull request (Python 3.11-3.15, with and without the polars extra).
  • Golden file. Only Go writes it (go test -run Golden -update .); Python compares against it.
  • Proto drift tests. proto_contract_test.go and unittests/test_proto_contract.py fail when a proto field, its number or label, or an enum constant differs from testdata/proto_fields.json / proto_enums.json, or when proto and models disagree on field names or JSON enum values.
  • buf. The Proto workflow runs buf build, buf lint, buf format --diff --exit-code and, on pull requests, buf breaking against the base branch.
  • Lint, format, types, spelling. golangci-lint, ruff, mypy (strict) and codespell.
  • Packaging. The wheel is built and imported in a fresh environment, with and without the extra.

Adding a field

A new field must reach every consumer at once, because reading rejects unknown keys. Do it in one pull request:

  1. Add the field to the .proto message (next free number; never reuse or renumber) and to testdata/proto_fields.json.
  2. Add it to the Go struct (Validate, MarshalJSON, UnmarshalJSON, the key list) and to the Python model, in contract key order.
  3. Add valid and invalid fixtures (each rule one fixture, plus an entry in invalid_reasons.json).
  4. Regenerate the golden file with go test -run Golden -update ., review the diff and check that uv run pytest writes the same bytes.
  5. If it is a table column, extend mdq_models.polars and its tests.
  6. Update this README and testdata/README.md.

Versioning

While the major version is 0, minor releases may contain breaking changes (announced in the release notes). From 1.0 on the JSON and proto contract of v1 is frozen: a breaking change needs a new proto package version (mdq.v2) and, for Go, a new module path github.com/hochfrequenz/mdq-models/v2. Readers are strict on purpose: unknown and duplicate JSON keys are rejected, so a typo fails loudly. The price: adding a JSON field is a breaking change for every consumer still on an older version, even though buf breaking accepts the additive proto change. Consumers update together; from 1.0 on, a new field needs a new major version. Releases are tags (vX.Y.Z); the Python package takes its version from the same tags.

Development

go test ./...                      # Go
golangci-lint run && golangci-lint fmt --diff
uv sync --group dev --extra polars # Python (the extra is needed for the Polars module and mypy)
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy src unittests
uv run codespell --ignore-words=domain-specific-terms.txt src unittests README.md doc.go
buf build && buf lint && buf format --diff --exit-code

License

MIT

Documentation

Overview

Package mdqmodels holds the hand-written data models of the canonical meter-reading schema: Messwert (one value per quarter hour), Zaehlerstand (a meter reading) and Einflusswert (an influence value such as the air temperature).

The contract is the JSON form of the types in this package, pinned by the shared fixtures in testdata/, which the Go and the Python models both parse and round-trip. The gRPC contract lives in proto/mdq/v1.

Reading is strict on purpose: unknown and duplicate keys are rejected, so a typo fails loudly and two parsers can never read different data from the same bytes. Every rejection is a *ValidationError naming the field and the rule.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func HerkunftMatchesStatus

func HerkunftMatchesStatus(status Status, herkunft *Herkunft) bool

HerkunftMatchesStatus reports whether a herkunft is allowed for a status. A nil herkunft means "not set" (null in JSON); a non-nil pointer to the empty string is not "not set" but an unknown value and never matches (Python's herkunft_passt_zu_status treats "" the same way). The rules: fehlend if and only if herkunft is nil (a missing value has no origin); wahr requires fremd (the agent only forms provisional and substitute values, so a true value is always fremd); vorlaeufig and ersatzwert may have either. An unknown status or herkunft never matches.

func IsValidMaLoID

func IsValidMaLoID(id string) bool

IsValidMaLoID reports whether id is 11 ASCII digits, does not start with 0, and ends in the correct check digit.

func MaLoCheckDigit

func MaLoCheckDigit(first10 string) (int, error)

MaLoCheckDigit computes the check digit of a MaLo ID (BDEW algorithm) from its first ten digits: the digits at odd positions (1st, 3rd, ...) are summed once, those at even positions twice, and the check digit is (10 - sum % 10) % 10. It returns an error unless first10 is exactly ten ASCII digits (a leading zero is fine here; the ID rule in IsValidMaLoID is stricter).

Types

type Decimal

type Decimal string

Decimal is a decimal number in its shortest canonical string form with at most 12 integer digits (|value| < 10^12) and at most 6 decimal places, for example "0", "160", "0.000001", "25.25" or "-3.5".

It is a string on the wire so that no consumer loses precision by parsing it as a float. The accepted syntax is ^-?(0|[1-9][0-9]*)(\.[0-9]{0,5}[1-9])?$: no exponent, no plus sign, no leading zeros, no trailing zeros after the point ("1.0" is rejected), no negative zero ("-0"), no "NaN" or "Infinity", no separators. A value with more than 6 decimals ("0.1234567") is rejected, never rounded, and so is a value of 10^12 or more (the storage column is numeric(18,6)): producers that compute in floating point round to 6 decimals first. Negative values are allowed; the consumer flags them.

Converting a string directly (Decimal("1.50")) does not normalise: Validate then rejects it. Use NewDecimal to get the canonical form from "1.50" or "1.5000000". To build one from a float64, round to 6 decimals first and format the shortest representation:

d, err := NewDecimal(strconv.FormatFloat(math.Round(x*1e6)/1e6, 'f', -1, 64))

NaN and the infinities fail in NewDecimal.

func NewDecimal

func NewDecimal(s string) (Decimal, error)

NewDecimal builds a canonical Decimal from s (at most 12 integer digits, see Decimal), which may carry trailing zeros: "1.5000000" becomes "1.5", "2.0" becomes "2" and "-0.00" becomes "0". Why: the Python models normalise a decimal built in code the same way, so both languages accept and write the same values. Decimals are counted after the trailing zeros are removed, so "1.0000001" (7 decimals) is rejected, never rounded. Anything else non-canonical (exponent, plus sign, leading zeros, ".5", "5.", NaN, separators) is rejected.

func (Decimal) MarshalJSON

func (d Decimal) MarshalJSON() ([]byte, error)

MarshalJSON writes d as a JSON string after validating it.

func (*Decimal) UnmarshalJSON

func (d *Decimal) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it. JSON numbers and null are rejected: a number would be parsed as a float by most consumers and lose precision.

func (Decimal) Validate

func (d Decimal) Validate() error

Validate checks that d is a canonical decimal with at most 12 integer digits and at most 6 decimal places.

type EinflussResolution added in v0.2.0

type EinflussResolution string

EinflussResolution is the time raster of an Einflusswert, written as an ISO 8601 duration. Unlike Resolution (Messwert, PT15M only) it also allows hourly values.

const (
	// EinflussPT1H is one value per hour.
	EinflussPT1H EinflussResolution = "PT1H"
	// EinflussPT15M is one value per quarter hour.
	EinflussPT15M EinflussResolution = "PT15M"
)

The values of EinflussResolution.

func (EinflussResolution) MarshalJSON added in v0.2.0

func (r EinflussResolution) MarshalJSON() ([]byte, error)

MarshalJSON writes r as a JSON string after validating it.

func (*EinflussResolution) UnmarshalJSON added in v0.2.0

func (r *EinflussResolution) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected.

func (EinflussResolution) Validate added in v0.2.0

func (r EinflussResolution) Validate() error

Validate checks that r is one of the EinflussResolution constants.

type Einflusswert added in v0.2.0

type Einflusswert struct {
	// Malo is the market location ID: 11 ASCII digits, no leading 0, valid check digit.
	Malo string
	// Timestamp is the START of the period [Timestamp, Timestamp + Resolution), on the quarter-hour
	// raster, and on the full hour for EinflussPT1H. The raster is checked on the UTC instant. In code
	// any time zone is accepted and written in UTC.
	Timestamp time.Time
	// Resolution is the raster of the series: EinflussPT1H or EinflussPT15M.
	Resolution EinflussResolution
	// Groesse is the measured quantity; its unit is fixed per Groesse.
	Groesse Groesse
	// Value is the value, or nil if it is missing. Negative values are allowed.
	Value *Decimal
	// Quelle is the source of the value: 1 to 64 printable ASCII characters without spaces, for
	// example "dwd:01993".
	Quelle string
}

Einflusswert is one row of an influence series: an influence value (for example the air temperature) for one MaLo and one period.

The period is [Timestamp, Timestamp + Resolution): Timestamp is its START, as for Messwert. All six JSON keys are required. Value is required-nullable: it is always written, as null when missing (nil here), and a missing key is rejected on read. A Value of 0 is a value, not a gap. Parsing is strict on purpose: unknown and duplicate keys are rejected.

func ParseEinflusswert added in v0.2.0

func ParseEinflusswert(b []byte) (Einflusswert, error)

ParseEinflusswert reads one Einflusswert from JSON bytes. It is the recommended entry point: every failure, including null, a non-object, a syntax error, trailing data, a byte order mark and invalid UTF-8, is a *ValidationError. The strictness is that of UnmarshalJSON.

func (Einflusswert) MarshalJSON added in v0.2.0

func (e Einflusswert) MarshalJSON() ([]byte, error)

MarshalJSON validates e and writes it with the keys in contract order and the timestamp in UTC with a literal Z; a missing Value is written as null. It has a value receiver so that both Einflusswert and *Einflusswert marshal the same way.

func (*Einflusswert) UnmarshalJSON added in v0.2.0

func (e *Einflusswert) UnmarshalJSON(b []byte) error

UnmarshalJSON reads one Einflusswert strictly: all six keys required (in any order), no unknown or duplicate keys, timestamps exactly in the form YYYY-MM-DDTHH:MM:SSZ, and every rule of Validate. On error the receiver is left unchanged.

Called through json.Unmarshal, syntax errors surface as *json.SyntaxError (not a *ValidationError), and a top-level null into a *Einflusswert pointer (var p *Einflusswert) sets the pointer to nil without any error, because encoding/json never calls UnmarshalJSON for it. Use ParseEinflusswert for untrusted input.

func (Einflusswert) Validate added in v0.2.0

func (e Einflusswert) Validate() error

Validate checks every rule of the contract on a value built in code and returns a *ValidationError naming the first broken field.

type Groesse added in v0.2.0

type Groesse string

Groesse is the physical quantity of an Einflusswert. The unit is fixed per value and there is no unit field.

const (
	// GroesseTemperatur is the air temperature at 2 m in degrees Celsius (mean or representative value
	// of the period).
	GroesseTemperatur Groesse = "temperatur"
	// GroesseGlobalstrahlung is the global irradiance in W/m2 (mean irradiance over the period).
	GroesseGlobalstrahlung Groesse = "globalstrahlung"
)

The values of Groesse.

func (Groesse) MarshalJSON added in v0.2.0

func (g Groesse) MarshalJSON() ([]byte, error)

MarshalJSON writes g as a JSON string after validating it.

func (*Groesse) UnmarshalJSON added in v0.2.0

func (g *Groesse) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected.

func (Groesse) Validate added in v0.2.0

func (g Groesse) Validate() error

Validate checks that g is one of the Groesse constants.

type Herkunft

type Herkunft string

Herkunft says where a Messwert comes from.

const (
	// HerkunftFremd is a value that was not formed by the meter data quality agent (MQA), for example
	// one delivered from the source system.
	HerkunftFremd Herkunft = "fremd"
	// HerkunftMqa is a value formed by the meter data quality agent (MQA, German "Messdatenqualitaetsagent"),
	// the software that forms provisional and substitute values, in an earlier run.
	HerkunftMqa Herkunft = "mqa"
)

The values of Herkunft.

func (Herkunft) MarshalJSON

func (h Herkunft) MarshalJSON() ([]byte, error)

MarshalJSON writes h as a JSON string after validating it.

func (*Herkunft) UnmarshalJSON

func (h *Herkunft) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected (a nullable herkunft is a *Herkunft, and the null is handled by the owning struct).

func (Herkunft) Validate

func (h Herkunft) Validate() error

Validate checks that h is one of the Herkunft constants.

type Messwert

type Messwert struct {
	// Malo is the market location ID: 11 ASCII digits, no leading 0, valid check digit.
	Malo string
	// Timestamp is the START of the quarter hour: 00:00 is the first quarter hour of a day and 23:45
	// the last, and the value equals the start of a [from, to) interval, so intervals never overlap
	// and never leave a gap. In code any time zone is accepted and written in UTC.
	Timestamp time.Time
	// Resolution is the raster; only PT15M in v1.
	Resolution Resolution
	// Value is the quantity, or nil if and only if Status is StatusFehlend. Negative values are
	// allowed: the consumer flags them, the schema does not reject them.
	Value *Decimal
	// Status says how trustworthy the value is.
	Status Status
	// Herkunft is the origin of the value, or nil if and only if Status is StatusFehlend;
	// StatusWahr requires HerkunftFremd.
	Herkunft *Herkunft
	// Profiltyp is the load profile kind.
	Profiltyp Profiltyp
	// Richtung is the flow direction.
	Richtung Richtung
}

Messwert is one row of the canonical meter-reading schema: the quantity of one MaLo for one quarter hour.

All eight JSON keys are required. Value and Herkunft are required-nullable: they are always written, as null when unset (nil here), and a missing key is rejected on read even though null would be fine. Parsing is strict on purpose: unknown and duplicate keys are rejected.

func ParseMesswert

func ParseMesswert(b []byte) (Messwert, error)

ParseMesswert reads one Messwert from JSON bytes. It is the recommended entry point: every failure, including null, a non-object, a syntax error, trailing data, a byte order mark and invalid UTF-8, is a *ValidationError. The strictness is that of UnmarshalJSON.

Example

ExampleParseMesswert is the Go snippet of the README; TestReadmeGoSnippet keeps the two identical.

package main

import (
	"errors"
	"fmt"
	"log"
	"time"

	mdq "github.com/hochfrequenz/mdq-models"
)

func main() {
	raw := []byte(`{"malo":"68283561554","timestamp":"2026-03-29T00:45:00Z","resolution":"PT15M",` +
		`"value":"1.5","status":"wahr","herkunft":"fremd","profiltyp":"haushalt","richtung":"bezug"}`)
	m, err := mdq.ParseMesswert(raw) // every failure is a *mdq.ValidationError
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(m.Malo, m.Timestamp.Format(time.RFC3339), *m.Value, m.Status)

	// Build a row in code. NewDecimal drops trailing zeros: "2.50" becomes "2.5".
	value, err := mdq.NewDecimal("2.50")
	if err != nil {
		log.Fatal(err)
	}
	mqa := mdq.HerkunftMqa
	built := mdq.Messwert{
		Malo:       "68283561554",
		Timestamp:  time.Date(2026, 3, 29, 3, 0, 0, 0, time.FixedZone("CEST", 2*3600)), // written as UTC
		Resolution: mdq.PT15M,
		Value:      &value,
		Status:     mdq.StatusErsatzwert,
		Herkunft:   &mqa,
		Profiltyp:  mdq.ProfiltypHaushalt,
		Richtung:   mdq.RichtungBezug,
	}
	out, err := built.MarshalJSON() // validates; an invalid row does not marshal
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(out))

	// Reading is strict: duplicate (and unknown) keys are rejected.
	_, err = mdq.ParseMesswert([]byte(`{"malo":"68283561554","malo":"68283561554"}`))
	var invalid *mdq.ValidationError
	fmt.Println(errors.As(err, &invalid))
}
Output:
68283561554 2026-03-29T00:45:00Z 1.5 wahr
{"malo":"68283561554","timestamp":"2026-03-29T01:00:00Z","resolution":"PT15M","value":"2.5","status":"ersatzwert","herkunft":"mqa","profiltyp":"haushalt","richtung":"bezug"}
true

func (Messwert) MarshalJSON

func (m Messwert) MarshalJSON() ([]byte, error)

MarshalJSON validates m and writes it with the keys in contract order and the timestamp in UTC with a literal Z; unset Value and Herkunft are written as null. It has a value receiver so that both Messwert and *Messwert marshal the same way.

func (*Messwert) UnmarshalJSON

func (m *Messwert) UnmarshalJSON(b []byte) error

UnmarshalJSON reads one Messwert strictly: all eight keys required (in any order), no unknown or duplicate keys, timestamps exactly in the form YYYY-MM-DDTHH:MM:SSZ, and every rule of Validate. On error the receiver is left unchanged.

Called through json.Unmarshal, syntax errors surface as *json.SyntaxError (not a *ValidationError), and a top-level null into a *Messwert pointer (var p *Messwert) sets the pointer to nil without any error, because encoding/json never calls UnmarshalJSON for it; plan 0.1 rejects top-level null. Use ParseMesswert for untrusted input.

func (Messwert) Validate

func (m Messwert) Validate() error

Validate checks every rule of the contract on a value built in code and returns a *ValidationError naming the first broken field.

type Profiltyp

type Profiltyp string

Profiltyp is the kind of load profile of a Messwert's MaLo.

const (
	// ProfiltypHaushalt is a household profile.
	ProfiltypHaushalt Profiltyp = "haushalt"
	// ProfiltypGewerbe is a commercial profile.
	ProfiltypGewerbe Profiltyp = "gewerbe"
	// ProfiltypIndustrie is an industrial profile.
	ProfiltypIndustrie Profiltyp = "industrie"
	// ProfiltypUnbekannt is an unknown profile.
	ProfiltypUnbekannt Profiltyp = "unbekannt"
)

The values of Profiltyp.

func (Profiltyp) MarshalJSON

func (p Profiltyp) MarshalJSON() ([]byte, error)

MarshalJSON writes p as a JSON string after validating it.

func (*Profiltyp) UnmarshalJSON

func (p *Profiltyp) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected.

func (Profiltyp) Validate

func (p Profiltyp) Validate() error

Validate checks that p is one of the Profiltyp constants.

type Resolution

type Resolution string

Resolution is the time raster of a Messwert, written as an ISO 8601 duration.

const PT15M Resolution = "PT15M"

PT15M is the only resolution in v1: one value per quarter hour. It is a field of its own (and not implied) so that another raster can be added later without changing the shape of the data.

func (Resolution) MarshalJSON

func (r Resolution) MarshalJSON() ([]byte, error)

MarshalJSON writes r as a JSON string after validating it.

func (*Resolution) UnmarshalJSON

func (r *Resolution) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected.

func (Resolution) Validate

func (r Resolution) Validate() error

Validate checks that r is a resolution known to v1.

type Richtung

type Richtung string

Richtung is the flow direction of a Messwert.

const (
	// RichtungBezug is consumption from the grid.
	RichtungBezug Richtung = "bezug"
	// RichtungEinspeisung is feed-in to the grid.
	RichtungEinspeisung Richtung = "einspeisung"
)

The values of Richtung.

func (Richtung) MarshalJSON

func (r Richtung) MarshalJSON() ([]byte, error)

MarshalJSON writes r as a JSON string after validating it.

func (*Richtung) UnmarshalJSON

func (r *Richtung) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected.

func (Richtung) Validate

func (r Richtung) Validate() error

Validate checks that r is one of the Richtung constants.

type Status

type Status string

Status says how trustworthy a Messwert is.

const (
	// StatusWahr is a measured value.
	StatusWahr Status = "wahr"
	// StatusVorlaeufig is a provisional value that may still change.
	StatusVorlaeufig Status = "vorlaeufig"
	// StatusErsatzwert is a substitute value that replaces a missing or implausible measurement.
	StatusErsatzwert Status = "ersatzwert"
	// StatusFehlend marks a missing value; value and herkunft are null.
	StatusFehlend Status = "fehlend"
)

The values of Status. The JSON value is the constant's name without the prefix, lower-case, and matches the proto enum constants (STATUS_WAHR and so on).

func (Status) MarshalJSON

func (s Status) MarshalJSON() ([]byte, error)

MarshalJSON writes s as a JSON string after validating it.

func (*Status) UnmarshalJSON

func (s *Status) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a JSON string and validates it; null is rejected.

func (Status) Validate

func (s Status) Validate() error

Validate checks that s is one of the Status constants.

type ValidationError

type ValidationError struct {
	// Field is the JSON key the rule belongs to ("malo", "value", ...). It is empty when the rule
	// concerns the document as a whole (for example "must be a JSON object").
	Field string
	// Rule is a short human-readable statement of the rule that was broken.
	Rule string
}

ValidationError says which field broke which rule. Every error returned by this package when it rejects data is a *ValidationError, so callers can use errors.As to find the field and the rule instead of matching text. That holds for Validate, MarshalJSON, ParseMesswert and ParseZaehlerstand; it does NOT hold for json.Unmarshal, which reports syntax errors (including trailing data) as *json.SyntaxError before this package sees the input. Use the Parse functions to read untrusted bytes.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Error implements error.

type Zaehlerstand

type Zaehlerstand struct {
	// Malo is the market location ID: 11 ASCII digits, no leading 0, valid check digit.
	Malo string
	// Timestamp is the instant of the reading, a whole second. In code any time zone is accepted and
	// written in UTC.
	Timestamp time.Time
	// Value is the register value; required, never null.
	Value Decimal
}

Zaehlerstand is a meter reading: the cumulative register value of one MaLo at one point in time. It is the second input of the schema, next to Messwert.

All three JSON keys are required and parsing is strict like for Messwert (unknown and duplicate keys are rejected). Unlike Messwert there is no raster: Timestamp is a point in time with any whole second, not the start of a quarter hour, and Value is never null.

func ParseZaehlerstand

func ParseZaehlerstand(b []byte) (Zaehlerstand, error)

ParseZaehlerstand reads one Zaehlerstand from JSON bytes. It is the recommended entry point: every failure, including null, a non-object, a syntax error, trailing data, a byte order mark and invalid UTF-8, is a *ValidationError. The strictness is that of UnmarshalJSON.

func (Zaehlerstand) MarshalJSON

func (z Zaehlerstand) MarshalJSON() ([]byte, error)

MarshalJSON validates z and writes it with the keys in contract order and the timestamp in UTC with a literal Z.

func (*Zaehlerstand) UnmarshalJSON

func (z *Zaehlerstand) UnmarshalJSON(b []byte) error

UnmarshalJSON reads one Zaehlerstand strictly: all three keys required (in any order), no unknown or duplicate keys, and every rule of Validate. On error the receiver is left unchanged.

Called through json.Unmarshal, syntax errors surface as *json.SyntaxError (not a *ValidationError), and a top-level null into a *Zaehlerstand pointer (var p *Zaehlerstand) sets the pointer to nil without any error, because encoding/json never calls UnmarshalJSON for it. Use ParseZaehlerstand for untrusted input.

func (Zaehlerstand) Validate

func (z Zaehlerstand) Validate() error

Validate checks every rule of the contract on a value built in code and returns a *ValidationError naming the first broken field.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL