Ereignis: Satz mit Zeit, Quelle, Vertrauen

Was gebaut ist

Ein Ereignis hält fest, dass etwas zu einer Zeit an einer Quelle gemeldet wurde, und wie sehr man der Meldung traut. Dieser geplante Vertrag legt fest, welche Angaben jedes Ereignis trägt, damit Meldungen aus verschiedenen Systemen vergleichbar sind und ein Ereignis weder doppelt noch ungeordnet wirkt.

Ein geplanter Vertrag, kein erreichbarer Endpunkt

Die Felder beschreiben die vorgesehene Form eines Ereignisses. Der Umschlag folgt der Spezifikation CloudEvents mit den Pflichtfeldern id, source und type; die übrigen Felder sind Erweiterungen. Eine Verarbeitung von Ereignissen ist nicht gebaut, und diese Seite belegt keine.

Drei Zeiten, drei Herkünfte

Begriff · Ereignis

Eine beobachtete Änderung mit Identität, Zeitpunkt und Herkunft. Doppelte oder verspätete Zustellung muss behandelt werden.

Ereignis im Zusammenhang

Ein Ereignis trägt die Zeit des Geschehens, die Zeit der Aufnahme und die Angabe, woher die Zeit des Geschehens stammt: vom Gerät, vom Server der Quelle oder aus dem Eingang. Die Zeit des Geschehens wird zur Gültigkeitszeit, die Zeit der Aufnahme zur Erfassungszeit der Ontologie. Ist der Zeitpunkt unsicher, steht ein Intervall.

Eine Gerätezeit, die stark von der Aufnahmezeit abweicht, wird nicht stillschweigend korrigiert. Sie bleibt, wie gemeldet, mit dem Hinweis auf die Abweichung.

Vertrauen mit Beiträgen

Das Vertrauen ist kein einzelner Wert. Es nennt seine Beiträge, also Quelle, Güte der Angaben und Bestätigungen, jeweils mit Grund. Ein Wert ohne Beiträge ist ungültig. Wer das Vertrauen eines Pfads oder einer Gruppe berechnet, kann so zeigen, welche Meldung es trägt.

Doppel, Reihenfolge, Verspätung

Das Feld subject bestimmt die Ordnung: Ereignisse mit demselben Subjekt werden in der Reihenfolge ihrer Nummer angewandt. Eine Nummer, die nicht größer ist als die zuletzt angewandte, gilt als Doppel und wird verworfen. Eine Lücke stellt das Ereignis zurück, bis der Vorgänger eintrifft. Ein Ereignis nach dem Wasserzeichen wird als Korrektur abgelegt und nicht verworfen.

Schutz am Ereignis

Begriff · Schema

Ein versionierter Vertrag über Felder, Typen und erlaubte Werte. Die Prüfung muss unbekannte und ungültige Eingaben behandeln.

Schnittstellen: geplante Verträge

Jedes Ereignis trägt seine Markierung und verweist auf die Rohmeldung, die unverändert bleibt. Der Inhalt der Nutzlast ist nach dem Schema des Typs geprüft. Freitext in einer Nutzlast gilt als Inhalt einer Quelle mit niedrigem Vertrauen und nie als Anweisung.

Schema

{
  "specversion": "1.0",
  "id": "<ereignis-kennung>",
  "type": "<ereignistyp>.v1",
  "source": "<quelle>",
  "subject": "<objekt-kennung>",
  "sequence": <nummer>,
  "eventTime": "<zeitpunkt>",
  "timeSource": "device",
  "receivedAt": "<zeitpunkt>",
  "location": { "crs": "EPSG:4326", "coordinates": [<laenge>, <breite>] },
  "confidence": { "value": <wert>, "contributions": [{ "reason": "<grund>" }] },
  "classification": "internal",
  "raw": "<verweis-auf-rohmeldung>",
  "data": { }
}

Schema 1JSON · Schema mit Platzhaltern

Felder

Feld	Typ	Pflicht	Bedeutung
`id`	`string`	ja	Kennung des Ereignisses, von der Quelle vergeben oder aus dem Inhalt gebildet. Grundlage zum Erkennen von Doppeln.
`type`	`string`	ja	Versionierter Ereignistyp, etwa <ereignistyp>.v1. Die Nutzlast folgt dem Schema dieses Typs.
`source`	`string`	ja	Quelle und Adapter, über die das Ereignis kam. Kein Ersatz für die Herkunft in der Rohzone.
`subject`	`string`	nein	Kennung des Objekts, auf das sich das Ereignis bezieht. Schlüssel für Ordnung und Nummer.
`sequence`	`integer`	nein	Fortlaufende Nummer je subject, wo die Quelle sie liefert. Nicht größer als die zuletzt angewandte heißt Doppel.
`eventTime`	`string (date-time)`	ja	Zeit des Geschehens in UTC. Wird zur Gültigkeitszeit der Ontologie.
`eventTimeEnd`	`string (date-time)`	nein	Ende eines Intervalls, wenn die Zeit des Geschehens unsicher ist.
`timeSource`	`string`	ja	Herkunft der Zeit: device, server oder intake. Eine Meldung ohne eigene Zeit trägt intake.
`receivedAt`	`string (date-time)`	ja	Zeit der Aufnahme. Wird zur Erfassungszeit und nie nachträglich geändert.
`location`	`object`	nein	Ort als Koordinate in WGS 84 mit Genauigkeit; die ursprüngliche Angabe bleibt erhalten.
`confidence`	`object`	ja	Vertrauen als Wert mit Beiträgen und Gründen. Ohne Beiträge ungültig.
`classification`	`string`	ja	Markierung des Ereignisses. Ein fehlender Wert gilt nicht als öffentlich.
`raw`	`string (ref)`	ja	Verweis auf die unveränderte Rohmeldung in der Rohzone.
`data`	`object`	ja	Nutzlast nach dem Schema des Typs. Freitext darin ist Inhalt, keine Anweisung.

Fehlerfälle

Kennung	Bedeutung
`EVENT_SCHEMA_INVALID`	Pflichtfeld oder Nutzlast passen nicht zum Schema des Typs; das Ereignis geht in die Fehlerspur.
`EVENT_DUPLICATE`	Nummer nicht größer als die zuletzt angewandte; das Ereignis wird verworfen und gezählt.
`EVENT_GAP`	Eine Nummer fehlt; das Ereignis wird zurückgestellt, bis der Vorgänger eintrifft.
`EVENT_LATE`	Das Ereignis kommt nach dem Wasserzeichen; es wird als Korrektur mit neuer Erfassungszeit abgelegt.
`TIME_UNTRUSTED`	Gerätezeit und Aufnahmezeit weichen stark ab; die Zeit bleibt wie gemeldet, mit Hinweis.

Grenze

Grenze: Dieser Schnittstellenvertrag ist geplant. Er belegt weder eine veröffentlichte Schnittstelle noch eine laufende Verarbeitung von Ereignissen, und die Beiträge zum Vertrauen sind Angaben der Quelle, keine Prüfung durch das System.

Quellen

CloudEvents SpecificationCNCF. Umschlag mit den Pflichtfeldern id, source, specversion und type.
RFC 3339: Date and Time on the Internet: TimestampsIETF. Schreibweise der Zeitangaben.

Ein Ereignis ist ein Satz mit Zeit, Quelle und Vertrauen.