Definitie van een modelgestuurde keuzeset

Schema-id: model-driven-option-set@1 Machineleesbaar schema: model-driven-option-set.schema.json

De canonieke weergave van een keuzeset — een herbruikbare lijst met een naam van toegestane waarden die een veld kan aannemen (sectie 6.14). Dataverse noemt hetzelfde concept een Choice. Wordt op dezelfde manier gevalideerd, of hij nu uit de ontwerper komt, uit een API-aanroep, van een AI-assistent of uit een oplossingsimport.

Structuur

Veld	Type	Verplicht	Opmerkingen
logicalName	tekenreeks	ja	Met uitgeversvoorvoegsel, in kleine letters snake_case (bijv. par_invoicestatus).
displayName	tekenreeks	ja	Leesbare naam.
description	tekenreeks	nee	Waar de set voor dient.
publisherPrefix	tekenreeks	nee	Het voorvoegsel van de eigenaar-uitgever. Meegenomen zodat de definitie haar eigen uitgever noemt, in plaats van een importeur die uit de logische naam te laten afleiden.
optionValueBase	geheel getal	ja	De optiewaardebasis van de eigenaar-uitgever; de value van elke optie is daarbinnen absoluut — 110000001, nooit 1. Verplicht sinds 2026-09-12: een definitie zonder basis wordt bij import geweigerd, en de eerste productoplossing was zo geschreven en slaagde voor elke test.
nextOptionValue	geheel getal	nee	De hoogwatermarkering van de set — de volgende waarde die ze uitdeelt. Opgeslagen in plaats van afgeleid uit options, zodat het nummer van een buiten gebruik gestelde optie nooit opnieuw wordt uitgegeven. Zie hieronder.
options	array	ja	De opties, in weergavevolgorde. Minstens één — een set waaruit niemand kan kiezen, is geen set.

Optie

Veld	Type	Verplicht	Opmerkingen
value	geheel getal	ja	De opgeslagen waarde. Door het platform toegewezen uit de basis van de eigenaar-uitgever en onveranderlijk zodra ze is toegekend. Minimaal 1 — zie hieronder.
displayName	tekenreeks	ja	Wat een gebruiker kiest.
description	tekenreeks	nee	Wat de optie betekent.

Waarom waarden grote getallen zijn, nooit 0/1/2

De value is wat de database daadwerkelijk opslaat. Elke uitgever bezit een reeks getallen (bijv. 270150000–270159999), en de opties van een set worden vanaf de basis oplopend genummerd:

270150000, 270150001, 270150002, …

Als elke uitgever bij 0 begon, zou het importeren van oplossingen van twee uitgevers in één omgeving ongemerkt de "Concept" van de ene uitgever laten betekenen wat "Geannuleerd" bij de andere betekent — omdat beide als 0 zouden worden opgeslagen. Het bereik per uitgever maakt dat onmogelijk. Het is de numerieke tegenhanger van het uitgeversvoorvoegsel, dat hetzelfde doet voor namen.

Daaruit volgen twee regels, en beide worden afgedwongen:

• Je kiest geen waarden. De create-API neemt geen waarde; het platform wijst de volgende toe uit het bereik van de uitgever. Bij een update is een optie met een waarde er een die je behoudt — een onbekende waarde wordt geweigerd, niet geaccepteerd.
• Een waarde verandert nooit. Een optie hernoemen is vrij en veilig; haar hernummeren zou elke record die haar al opslaat, laten verwijzen naar iets anders. Het nummer van een verwijderde optie wordt buiten gebruik gesteld in plaats van opnieuw uitgegeven.

Importeren en exporteren

De waarden reizen met de definitie mee; bij import worden ze niet opnieuw toegewezen. De records van de bronomgeving bevatten ze al, dus een oplossing die in Test of Prod wordt geïmporteerd, moet het met Dev eens zijn over wat 270150001 betekent.

nextOptionValue reist om dezelfde reden mee, één stap verder. Het is de volgende waarde die de set uitdeelt, en die wordt opgeslagen in plaats van berekend uit de aanwezige opties. Is er een optie verwijderd, dan blijft de markering boven het nummer dat die optie had — zodat het nummer buiten gebruik wordt gesteld in plaats van aan de volgende nieuwe optie te worden gegeven. Dat is belangrijk, want ergens kan een record het nog bevatten. Een importerende omgeving die de markering opnieuw zou afleiden uit de opties die ze ontvangt, zou precies die bescherming tenietdoen. Een definitie zonder nextOptionValue valt terug op de afgeleide markering; dat is het beste antwoord dat er is voor een document dat er nooit een heeft vastgelegd.

Een import controleert wat de toewijzing anders zou hebben gegarandeerd: elke waarde moet binnen het bereik van de uitgever liggen, geen twee opties mogen een waarde of een label delen, en de logische naam moet in de doelomgeving vrij zijn. Een waarde uit het bereik van een andere uitgever wordt geweigerd in plaats van opgeslagen — haar accepteren zou precies de botsing veroorzaken die het bereiksysteem moet voorkomen.

Een veld aan een set koppelen

Een tabelveld verwijst op naam naar een set, in de tabeldefinitie:

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

De kolom is een bigint met de waarde van de gekozen optie. De server weigert een schrijfactie waarvan de waarde niet een van de opties van de set is.

Voorbeeld

{
  "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" }
  ]
}