Definición de conjunto de opciones basado en modelo

Id del esquema: model-driven-option-set@1 Esquema legible por máquina: model-driven-option-set.schema.json

La representación canónica de un conjunto de opciones: una lista reutilizable y con nombre de los valores permitidos que puede tomar un campo (sección 6.14). Dataverse llama a este mismo concepto Choice (elección). Se valida de forma idéntica tanto si procede del diseñador como de una llamada a la API, de un asistente de IA o de una importación de solución.

Forma

Campo	Tipo	Obligatorio	Notas
logicalName	string	sí	Con el prefijo del editor, en snake_case en minúsculas (p. ej., par_invoicestatus).
displayName	string	sí	Nombre legible.
description	string	no	Para qué sirve el conjunto.
publisherPrefix	string	no	El prefijo del editor propietario. Se incluye para que la definición nombre a su propio editor en lugar de dejar que un importador lo deduzca del nombre lógico.
optionValueBase	integer	sí	La base de valores de opción del editor propietario; el value de cada opción es absoluto dentro de ella: 110000001, nunca 1. Obligatorio desde el 12-09-2026: una definición sin él se rechaza al importar, y la primera solución de producto se escribió así y superó todas las pruebas.
nextOptionValue	integer	no	La marca máxima del conjunto: el siguiente valor que asignará. Se almacena en lugar de derivarse de options, para que el número de una opción retirada no vuelva a asignarse nunca. Vea más abajo.
options	array	sí	Las opciones, en orden de presentación. Al menos una: un conjunto del que nadie puede elegir no es un conjunto.

Opción

Campo	Tipo	Obligatorio	Notas
value	integer	sí	El valor almacenado. Lo asigna la plataforma a partir de la base del editor propietario y es inmutable una vez asignado. Mínimo 1; vea más abajo.
displayName	string	sí	Lo que elige un usuario.
description	string	no	Qué significa la opción.

Por qué los valores son números grandes y nunca 0/1/2

El value es lo que realmente almacena la base de datos. Cada editor posee un rango de números (p. ej., 270150000–270159999), y las opciones de un conjunto se numeran en orden ascendente a partir de su base:

270150000, 270150001, 270150002, …

Si todos los editores empezaran en 0, importar soluciones de dos editores en un mismo entorno haría, sin ningún aviso, que el «Borrador» de un editor significara el «Cancelado» del otro, porque ambos se almacenarían como 0. El rango por editor lo hace imposible. Es el equivalente numérico del prefijo del editor, que cumple la misma función para los nombres.

De ello se derivan dos reglas, y ambas se aplican:

• Usted no elige los valores. La API de creación no acepta ningún valor; la plataforma asigna el siguiente del rango del editor. Al actualizar, una opción que incluye un valor es una que usted conserva: un valor no reconocido se rechaza, no se acepta.
• Un valor nunca cambia. Cambiar el nombre de una opción es libre y seguro; renumerarla haría apuntar a otro sitio cada registro que ya la almacena. El número de una opción eliminada queda retirado en lugar de volver a asignarse.

Importación y exportación

Los valores viajan con la definición; no se reasignan al importar. Los registros del entorno de origen ya los contienen, así que una solución importada en Pruebas o Producción tiene que coincidir con Desarrollo en lo que significa 270150001.

nextOptionValue viaja por el mismo motivo, un paso más allá. Es el siguiente valor que asignará el conjunto, y se almacena en lugar de calcularse a partir de las opciones presentes. Si se eliminó una opción, la marca se queda por encima del número que tenía esa opción, de modo que el número queda retirado en lugar de asignarse a la siguiente opción nueva, lo cual importa porque algún registro puede seguir conteniéndolo. Un entorno de importación que volviera a derivar la marca a partir de las opciones recibidas desharía exactamente esa protección. Una definición sin nextOptionValue recurre a la marca derivada, que es la mejor respuesta disponible para un documento que nunca registró una.

Una importación comprueba lo que la asignación habría garantizado de otro modo: todos los valores deben estar dentro del rango del editor, dos opciones no pueden compartir valor ni etiqueta, y el nombre lógico debe estar libre en el entorno de destino. Un valor del rango de otro editor se rechaza en lugar de almacenarse: aceptarlo plantaría precisamente la colisión que el sistema de rangos existe para evitar.

Enlazar un campo a un conjunto

Un campo de entidad hace referencia a un conjunto por su nombre, en la definición de entidad:

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

La columna es un bigint que contiene el valor de la opción elegida. El servidor rechaza una escritura cuyo valor no sea una de las opciones del conjunto.

Ejemplo

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