Definition eines modellgesteuerten Optionssatzes

Schema-ID: model-driven-option-set@1 Maschinenlesbares Schema: model-driven-option-set.schema.json

Die maßgebliche Darstellung eines Optionssatzes – einer wiederverwendbaren, benannten Liste zulässiger Werte, die ein Feld annehmen kann (Abschnitt 6.14). Dataverse nennt dasselbe Konzept Choice (Auswahl). Er wird identisch validiert, ob er aus dem Designer, einem API-Aufruf, einem KI-Assistenten oder einem Lösungsimport stammt.

Aufbau

Feld	Typ	Pflicht	Hinweise
logicalName	string	ja	Mit Herausgeberpräfix, Snake-Case in Kleinbuchstaben (z. B. par_invoicestatus).
displayName	string	ja	Lesbarer Name.
description	string	nein	Wofür der Satz gedacht ist.
publisherPrefix	string	nein	Das Präfix des besitzenden Herausgebers. Wird mitgeführt, damit die Definition ihren eigenen Herausgeber nennt, statt es einem Importer zu überlassen, ihn aus dem logischen Namen abzuleiten.
optionValueBase	integer	ja	Die Optionswert-Basis des besitzenden Herausgebers; der value jeder Option ist innerhalb davon absolut – 110000001, niemals 1. Pflicht seit dem 12.09.2026: Eine Definition ohne diese Angabe wird beim Import abgewiesen – die erste Produktlösung war so geschrieben und bestand trotzdem jeden Test.
nextOptionValue	integer	nein	Der Höchststand des Satzes – der nächste Wert, den er vergibt. Gespeichert statt aus options abgeleitet, damit die Nummer einer stillgelegten Option nie erneut vergeben wird. Siehe unten.
options	array	ja	Die Optionen in Anzeigereihenfolge. Mindestens eine – ein Satz, aus dem niemand wählen kann, ist kein Satz.

Option

Feld	Typ	Pflicht	Hinweise
value	integer	ja	Der gespeicherte Wert. Wird von der Plattform aus der Basis des besitzenden Herausgebers vergeben und ist nach der Zuweisung unveränderlich. Mindestens 1 – siehe unten.
displayName	string	ja	Was ein Benutzer auswählt.
description	string	nein	Was die Option bedeutet.

Warum Werte große Zahlen sind, niemals 0/1/2

Der value ist das, was die Datenbank tatsächlich speichert. Jeder Herausgeber besitzt einen Zahlenbereich (z. B. 270150000–270159999), und die Optionen eines Satzes werden ab seiner Basis aufwärts nummeriert:

270150000, 270150001, 270150002, …

Würde jeder Herausgeber bei 0 beginnen, würde der Import von Lösungen zweier Herausgeber in eine Umgebung stillschweigend dazu führen, dass „Entwurf“ des einen Herausgebers „Storniert“ des anderen bedeutet – weil beide als 0 gespeichert würden. Der Bereich pro Herausgeber macht das unmöglich. Er ist das numerische Gegenstück zum Herausgeberpräfix, das dieselbe Aufgabe für Namen erfüllt.

Daraus folgen zwei Regeln, und beide werden durchgesetzt:

• Sie wählen keine Werte. Die Erstellungs-API nimmt keinen Wert entgegen; die Plattform vergibt den nächsten aus dem Bereich des Herausgebers. Bei einer Aktualisierung ist eine Option, die einen Wert trägt, eine, die Sie behalten – ein unbekannter Wert wird abgewiesen, nicht übernommen.
• Ein Wert ändert sich nie. Eine Option umzubenennen, ist kostenlos und sicher; sie umzunummerieren, würde jeden Datensatz umleiten, der sie bereits speichert. Die Nummer einer entfernten Option wird stillgelegt statt neu vergeben.

Import und Export

Die Werte reisen mit der Definition; sie werden beim Import nicht neu vergeben. Die Datensätze der Quellumgebung enthalten sie bereits, daher muss eine in Test oder Produktion importierte Lösung mit der Entwicklungsumgebung darin übereinstimmen, was 270150001 bedeutet.

nextOptionValue reist aus demselben Grund mit, nur einen Schritt weiter entfernt. Es ist der nächste Wert, den der Satz vergibt, und er wird gespeichert, statt aus den vorhandenen Optionen ermittelt zu werden. Wurde eine Option entfernt, bleibt der Höchststand über der Nummer, die diese Option hatte – die Nummer wird also stillgelegt, statt an die nächste neue Option vergeben zu werden. Das ist wichtig, weil irgendwo noch ein Datensatz sie enthalten kann. Eine importierende Umgebung, die den Höchststand aus den empfangenen Optionen neu ableitete, würde genau diesen Schutz aufheben. Eine Definition ohne nextOptionValue greift auf den abgeleiteten Höchststand zurück – die beste verfügbare Antwort für ein Dokument, das nie einen festgehalten hat.

Ein Import prüft, was die Vergabe sonst garantiert hätte: Jeder Wert muss im Bereich des Herausgebers liegen, keine zwei Optionen dürfen sich einen Wert oder eine Beschriftung teilen, und der logische Name muss in der Zielumgebung frei sein. Ein Wert aus dem Bereich eines anderen Herausgebers wird abgewiesen statt gespeichert – ihn zu übernehmen, würde genau die Kollision einpflanzen, die das Bereichsschema verhindern soll.

Ein Feld an einen Satz binden

Ein Tabellenfeld verweist in der Tabellendefinition per Name auf einen Satz:

{ "logicalName": "par_status", "displayName": "Status", "dataType": "OptionSet", "optionSet": "par_invoicestatus" }

Die Spalte ist ein bigint, das den Wert der gewählten Option enthält. Der Server weist einen Schreibvorgang ab, dessen Wert keine der Optionen des Satzes ist.

Beispiel

{
  "logicalName": "par_invoicestatus",
  "displayName": "Invoice Status",
  "description": "The lifecycle of an invoice",
  "publisherPrefix": "par",
  "optionValueBase": 270150000,
  "nextOptionValue": 270150003,
  "options": [
    { "value": 270150000, "displayName": "Draft", "description": "Not yet sent to the customer" },
    { "value": 270150001, "displayName": "Sent" },
    { "value": 270150002, "displayName": "Paid" }
  ]
}