Définition de groupe d’options Model-Driven

Identifiant du schéma : model-driven-option-set@1 Schéma lisible par machine : model-driven-option-set.schema.json

La représentation canonique d’un groupe d’options — une liste nommée et réutilisable des valeurs autorisées qu’un champ peut prendre (section 6.14). Dataverse appelle ce même concept un choix. Validée de manière identique, qu’elle provienne du concepteur, d’un appel d’API, d’un assistant IA ou d’une importation de solution.

Structure

Champ	Type	Obligatoire	Remarques
logicalName	string	oui	Préfixé par l’éditeur, en snake-case minuscule (p. ex. par_invoicestatus).
displayName	string	oui	Nom lisible.
description	string	non	À quoi sert le groupe.
publisherPrefix	string	non	Le préfixe de l’éditeur propriétaire. Porté afin que la définition nomme elle-même son éditeur, plutôt que de laisser un importateur le déduire du nom logique.
optionValueBase	integer	oui	La base des valeurs d’option de l’éditeur propriétaire ; la value de chaque option est absolue dans cette base — 110000001, jamais 1. Obligatoire depuis le 12/09/2026 : une définition qui n’en a pas est refusée à l’importation, et la première solution produit avait été écrite ainsi en passant tous les tests.
nextOptionValue	integer	non	Le niveau le plus haut atteint par le groupe — la prochaine valeur qu’il attribuera. Stocké plutôt que déduit de options, afin que le numéro d’une option retirée ne soit jamais réattribué. Voir ci-dessous.
options	array	oui	Les options, dans l’ordre d’affichage. Au moins une — un groupe dans lequel personne ne peut choisir n’est pas un groupe.

Option

Champ	Type	Obligatoire	Remarques
value	integer	oui	La valeur stockée. Attribuée par la plateforme à partir de la base de l’éditeur propriétaire, et immuable une fois attribuée. Minimum 1 — voir ci-dessous.
displayName	string	oui	Ce que choisit l’utilisateur.
description	string	non	Ce que signifie l’option.

Pourquoi les valeurs sont de grands nombres, jamais 0/1/2

La value est ce que la base de données stocke réellement. Chaque éditeur possède une plage de nombres (p. ex. 270150000–270159999), et les options d’un groupe sont numérotées de façon croissante à partir de sa base :

270150000, 270150001, 270150002, …

Si chaque éditeur commençait à 0, importer dans un même environnement des solutions de deux éditeurs ferait silencieusement signifier au « Brouillon » de l’un l’« Annulé » de l’autre — puisque les deux seraient stockés sous 0. La plage propre à chaque éditeur rend cela impossible. C’est le pendant numérique du préfixe d’éditeur, qui remplit la même fonction pour les noms.

Deux règles en découlent, et toutes deux sont appliquées :

• Vous ne choisissez pas les valeurs. L’API de création ne prend aucune valeur ; la plateforme attribue la suivante dans la plage de l’éditeur. Lors d’une mise à jour, une option qui porte une valeur est une option que vous conservez — une valeur non reconnue est rejetée, et non acceptée.
• Une valeur ne change jamais. Renommer une option est libre et sans risque ; la renuméroter réorienterait chaque enregistrement qui la stocke déjà. Le numéro d’une option supprimée est retiré plutôt que réattribué.

Importation et exportation

Les valeurs voyagent avec la définition ; elles ne sont pas réattribuées à l’importation. Les enregistrements de l’environnement source les contiennent déjà : une solution importée en Test ou en Prod doit donc s’accorder avec Dev sur la signification de 270150001.

nextOptionValue voyage pour la même raison, à un degré près. C’est la prochaine valeur que le groupe attribuera, et elle est stockée plutôt que calculée à partir des options présentes. Si une option a été supprimée, le repère reste au-dessus du numéro qu’elle occupait — ce numéro est donc retiré au lieu d’être attribué à la prochaine nouvelle option, ce qui compte parce qu’un enregistrement quelque part peut encore le contenir. Un environnement importateur qui recalculerait le repère à partir des options reçues annulerait précisément cette protection. Une définition sans nextOptionValue se rabat sur le repère calculé, la meilleure réponse possible pour un document qui n’en a jamais enregistré.

Une importation vérifie ce que l’attribution aurait autrement garanti : chaque valeur doit se trouver dans la plage de l’éditeur, deux options ne peuvent partager ni une valeur ni un libellé, et le nom logique doit être libre dans l’environnement cible. Une valeur issue de la plage d’un autre éditeur est rejetée plutôt que stockée — l’accepter introduirait précisément la collision que le système de plages est censé empêcher.

Lier un champ à un groupe

Un champ de table référence un groupe par son nom, dans la définition de table :

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

La colonne est un bigint contenant la valeur de l’option choisie. Le serveur rejette une écriture dont la valeur n’est pas l’une des options du groupe.

Exemple

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