Objekt: Kennung und Eigenschaften

Stand · Bauplan

Ein Objekt beschreibt eine eindeutig benannte Sache mit Eigenschaften, Quellenbezug und Version. Dieser geplante Vertrag trennt die Identität einer Sache von den Datensätzen, die etwas über sie behaupten.

Ein geplanter Vertrag, kein erreichbarer Endpunkt

Die Felder beschreiben eine prüfbare Entwurfsrichtung. Es gibt hier keinen zugesagten HTTP-Endpunkt, keine SDK-Methode und keine Kompatibilitätsgarantie. Vor einer Implementierung müssen Authentifizierung, Grenzwerte, Serialisierung und Fehlertransport festgelegt und getestet werden.

Identität ist kein Abgleich per Namen

Zwei Quellen können denselben Vorgang unterschiedlich benennen. Für die Zuordnung braucht es eine explizite Abgleichregel mit Herkunft und Konfliktbehandlung. Gleiche Namen allein sind kein Identitätsbeweis. Eine zusammengeführte Sicht bewahrt die ursprünglichen Quellkennungen.

Lesen und Ändern auseinanderhalten

Ein Leseresultat ist eine Momentaufnahme. Eine geplante Handlung nennt zusätzlich die erwartete Version. Hat sich die Sache inzwischen geändert, wird neu gelesen und geprüft. Der Vertrag erlaubt keine stille Überschreibung einer jüngeren Änderung.

Schutz am Objekt erhalten

Begriff · Beziehung

Eine benannte Verbindung zwischen Objekten, etwa: Objekt A gehört zu Objekt B. Die Verbindung braucht selbst einen Quellenbezug.

Beziehungen im Abbild modellieren

Das Objekt darf nur Eigenschaften enthalten, die der aufrufende Kontext lesen darf. Ein abgeleiteter Name, eine Beziehung oder eine Trefferzahl kann ebenfalls geschützte Information verraten. Die Zugriffskontrolle muss deshalb auch Ausgaben und Verknüpfungen behandeln.

Zusammengesetzter Typ: SourceRef

Jeder Eintrag in sources benennt genau eine Beobachtung in einer Quelle. Die Zeit gehört zur jeweiligen Beobachtung; die Frische des Gesamtobjekts ersetzt sie nicht. Auch dieser zusammengesetzte Typ ist ein Entwurf.

sourceId: string, Pflicht: Stabile Kennung der angebundenen Quelle.
recordId: string, Pflicht: Kennung des Datensatzes innerhalb dieser Quelle.
observedAt: string (date-time), Pflicht: Zeitpunkt, zu dem genau dieser Datensatz beobachtet wurde.
sourceRevision: string | null, Pflicht: Quellrevision, falls verfügbar. null bedeutet unbekannt und darf nicht als unverändert gelten.

Die Kennung der Quelle überträgt kein Zugriffsrecht. Vor dem Lesen muss der aktuelle Zugriffskontext gegen die Quelle geprüft werden.

Schema

{
  "id": "<objekt-kennung>",
  "type": "<objekttyp>.v1",
  "version": <version>,
  "properties": {
    "state": "<zustand>"
  },
  "sources": [
    {
      "sourceId": "<quelle>",
      "recordId": "<datensatz>",
      "observedAt": "<zeitpunkt>",
      "sourceRevision": null
    }
  ],
  "observedAt": "<zeitpunkt>",
  "classification": "internal",
  "accessPolicyRef": "<zugriffsregel>"
}

Schema 1JSON · Schema mit Platzhaltern

Felder

Feld	Typ	Pflicht	Bedeutung
`id`	`string`	ja	Stabile, innerhalb der Organisation eindeutige Kennung. Ein Namenswechsel ändert sie nicht.
`type`	`string`	ja	Versionierter Objekttyp, etwa <objekttyp>.v1. Kein frei interpretierter Modelltext.
`version`	`integer`	ja	Monoton steigende Revision. Grundlage für die Erkennung konkurrierender Änderungen.
`properties`	`object`	ja	Eigenschaften gemäß dem Schema des Objekttyps. Unbekannte Felder werden zurückgewiesen.
`sources`	`SourceRef[]`	ja	Quellenkennung, Datensatzkennung und Beobachtungszeit. Kein Kopieren geheimer Zugangsdaten.
`observedAt`	`string (date-time)`	ja	Zeitpunkt der Beobachtung in der Quelle. Kein Beweis für Aktualität ohne Frischegrenze.
`classification`	`string`	ja	Schutzklasse. Ein Standardwert darf fehlende Einstufung nicht als öffentlich ausgeben.
`accessPolicyRef`	`string`	ja	Referenz auf die geltende Zugriffsregel. Die Referenz erteilt selbst kein Recht.

Fehlerfälle

Kennung	Bedeutung
`OBJECT_SCHEMA_INVALID`	Ein Pflichtfeld oder dessen Typ passt nicht zum Objektschema.
`SOURCE_NOT_READABLE`	Der aufrufende Kontext darf die Herkunft nicht lesen.
`VERSION_CONFLICT`	Eine Änderung basiert auf einer überholten Revision.

Grenze

Grenze: Dieser Schnittstellenvertrag ist geplant. Ein lokaler Kontrollprototyp belegt weder eine veröffentlichte API noch organisationsweiten Betrieb.