Open Source Web Application Framework for ASP.NET Core
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

135 lines
7.8 KiB

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "entity-property-descriptor.schema.json",
"title": "EntityPropertyDescriptor",
"description": "Describes one dynamic entity property. Properties define persisted data fields, enum fields, foreign keys, upload fields, primitive collections, calculated formulas, rollups, server-only fields, defaults, uniqueness, and validators.",
"markdownDescription": "AI guidance: use PascalCase property names. Use `type` for primitive fields, `type: \"enum\"` with `enumType` for enum fields, and a `foreignKey` object for lookup fields. FK property names should normally end with `Id`. Add `collection` for ordered value lists, `formula` for virtual calculated values, and `rollup` for aggregates over related records; these three and `foreignKey` are mutually exclusive. Keep sensitive values `serverOnly: true`. Do not add legacy UI configuration here; page columns/filters and form fields own UI behavior.",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Stable PascalCase property name, unique within the entity. Examples: 'Name', 'EmailAddress', 'CustomerId', 'StartDate'.",
"minLength": 1
},
"type": {
"$ref": "entity-property-type.schema.json",
"description": "Primitive or special property type. If omitted, runtime treats the property as string (or enum when enumType is set). Use 'enum' only with enumType; use 'file'/'image' for first-class upload fields."
},
"displayName": {
"type": "string",
"description": "Default display label for this property. Page columns and form fields can override it. Omit when the label can be derived from the property name.",
"minLength": 1
},
"enumType": {
"type": "string",
"description": "Name of a JSON-defined enum from the enums collection or a full type name for code enums. Required when type is 'enum'; setting it without type implies 'enum'."
},
"allowSetByClients": {
"type": "boolean",
"description": "Controls whether create/update clients may set the property. Use false for server-computed or protected fields that can still be returned to clients. Forced to false for formula and rollup properties."
},
"serverOnly": {
"type": "boolean",
"description": "When true, this property is completely hidden from clients, API responses, and UI definitions. Use for secrets, internal notes, hashes, or backend-only workflow state."
},
"isMappedToDbField": {
"type": "boolean",
"description": "Where a scalar property keeps its values. true: a dedicated physical column. false: the entity's JSON Data column. Omitted: follows the UseJsonDataStorage option (the JSON Data column by default, a dedicated column when the option is false). Forced to false for formula and rollup properties; not applicable to collections."
},
"defaultValue": {
"type": ["string", "null"],
"description": "Default value for new records. Stored as a string in descriptor JSON and converted to the declared property type at runtime. Examples: '0' for int/enum, 'true' for boolean, '2026-05-18T09:00:00Z' for datetime. Ignored for formula and rollup properties."
},
"isUnique": {
"type": "boolean",
"description": "Whether this property value must be unique across records of this entity. Use for codes, slugs, natural keys, and names only when duplicates are not allowed."
},
"isRequired": {
"type": "boolean",
"description": "When true, the property is required/not nullable. This affects database schema, backend validation, and generated UI validation. Existing data may need defaults before turning this on."
},
"foreignKey": {
"$ref": "foreign-key-descriptor.schema.json",
"description": "Foreign key/lookup relation. The current property's value stores the referenced entity id. The property name should usually be '<ReferencedEntity>NameId', for example 'CustomerId'."
},
"fileMaxSizeBytes": {
"type": "integer",
"description": "Maximum allowed file size in bytes for File and Image properties. Example: 5242880 for 5 MiB.",
"minimum": 1
},
"fileAllowedContentTypes": {
"type": "array",
"description": "Allowed MIME content types or wildcard patterns for File and Image properties. Examples: 'image/*', 'application/pdf'.",
"items": {
"type": "string",
"minLength": 1
}
},
"imageMaxWidth": {
"type": "integer",
"description": "Optional maximum image width in pixels.",
"minimum": 1
},
"imageMaxHeight": {
"type": "integer",
"description": "Optional maximum image height in pixels.",
"minimum": 1
},
"imageResizeMode": {
"type": "string",
"description": "How uploaded images should be resized when image dimensions are configured. 'fit' preserves the full image inside the bounds; 'fill' crops/fills the target bounds (requires both imageMaxWidth and imageMaxHeight).",
"enum": ["fit", "fill"]
},
"decimalPlaces": {
"type": "integer",
"description": "Decimal scale for 'decimal' and 'money' properties. Controls storage precision and default UI formatting. Defaults to 2 when omitted.",
"minimum": 0
},
"currencySymbol": {
"type": "string",
"description": "Optional currency symbol or code displayed by money-aware controls for 'money' properties, for example '$' or 'EUR'.",
"minLength": 1
},
"collection": {
"$ref": "entity-property-collection-descriptor.schema.json",
"description": "Turns this property into an ordered list of values of the declared type. Cannot be combined with foreignKey, formula, or rollup."
},
"formula": {
"$ref": "entity-formula-descriptor.schema.json",
"description": "Virtual calculated value evaluated from other properties of the same record. Makes the property read-only and non-persisted."
},
"rollup": {
"$ref": "entity-rollup-descriptor.schema.json",
"description": "Virtual aggregate over related records that reference this record. Makes the property read-only and non-persisted."
},
"validators": {
"type": "array",
"description": "Backend/UI validators for this property. Use required, length, range, pattern, email, phone, url, or creditCard as appropriate. Duplicate required can be omitted when isRequired is true unless a custom message is needed.",
"items": {
"$ref": "validator-descriptor.schema.json"
}
}
},
"required": [
"name"
],
"allOf": [
{ "not": { "required": ["formula", "rollup"] } },
{ "not": { "required": ["formula", "foreignKey"] } },
{ "not": { "required": ["rollup", "foreignKey"] } },
{ "not": { "required": ["collection", "foreignKey"] } },
{ "not": { "required": ["collection", "formula"] } },
{ "not": { "required": ["collection", "rollup"] } }
],
"additionalProperties": false,
"examples": [
{ "name": "Name", "type": "string", "isRequired": true, "validators": [{ "type": "maxLength", "length": 128 }] },
{ "name": "Status", "type": "enum", "enumType": "Acme.Events.EventStatus", "defaultValue": "0" },
{ "name": "CustomerId", "foreignKey": { "entityName": "Acme.Crm.Customer", "displayPropertyName": "Name" } },
{ "name": "CoverImage", "type": "image", "fileAllowedContentTypes": ["image/*"], "fileMaxSizeBytes": 5242880, "imageResizeMode": "fit" },
{ "name": "Price", "type": "money", "decimalPlaces": 2, "currencySymbol": "$" },
{ "name": "Tags", "type": "string", "collection": { "maxCount": 20, "uniqueItems": true } },
{ "name": "Total", "type": "decimal", "formula": { "expression": "Round(UnitPrice * Quantity, 2)", "resultType": "decimal" } },
{ "name": "OrderCount", "type": "long", "rollup": { "sourceEntityName": "Acme.Crm.Order", "foreignKeyPropertyName": "CustomerId", "operation": "count" } }
]
}