A property defines one configurable field on a type. In Jetstack, a property is not just a storage column. It can also define relation behavior, form behavior, defaulting, validation, visibility, display formatting, query participation, and API exposure.
Most implementation quality problems in Jetstack eventually trace back to property design. A property decides:
If a type is the structural model, properties are the detailed contract.
This chapter follows the same configuration groups the Property builder uses:
For each option, this page explains:
Use this page together with:
Before going option by option, keep these distinctions clear:
property_name is the main human-readable name of the property.caption and caption_short are presentation labels. If left empty, they fall back to property_name.property_type decides the runtime family of the property. That one choice changes which other options matter.default_value, form_initial_value, calculation, mask, show_conditions, add_conditions, edit_conditions, and often value_switch are dynamic fields. They should be designed with the expression system in mind, not as static text.These fields define the identity and structural role of the property.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
id |
Stable internal identifier of the property record. | You do not normally configure this manually. It is assigned by the platform and shown mainly for reference and linking. | Use it when troubleshooting sync, exports, or internal references. |
of_type |
The parent type that owns the property. | Select the target type when creating the property. | This is the primary ownership link. Changing it effectively moves the property to another model context. |
property_name |
Main business-facing name of the property. | Enter a clear, human-readable field name such as Invoice number, Due date, or Assigned consultant. |
This is the default caption source. If caption and caption_short are empty, Jetstack falls back to this value. |
system_name |
Stable machine-friendly identifier for implementation exports, sync, and more technical references. | Enter only English letters, digits, and underscores. The configured validation pattern is [a-zA-Z0-9][a-zA-Z0-9_]*, so the name must start with a letter or digit and cannot contain spaces. |
Use a predictable naming style such as invoice_number or assigned_consultant. Prefer stability over prettiness. |
property_type |
Runtime field type and capability family. | Choose the property type that matches the value you need to store or reference. | This is one of the most important decisions. It controls value parsing, filters, relation behavior, and which later options are relevant. |
role |
Semantic role of the property within the type. | Assign a role when the property has special meaning, such as title, identifier, thumbnail, or another platform-recognized role. | Roles reduce the need for hard-coded property names elsewhere. Use them for semantically important fields. |
is_unique |
How uniqueness conflicts are handled. | Choose one of the built-in strategies: Not unique, Unique - drop value on conflict, Unique - fail on conflict, or Unique - add suffix on conflict. |
Fail on conflict is the safest when duplicates must never silently pass. Add suffix is useful for slug-like identifiers. |
is_multiple |
Whether the property stores a single value or a list of values. | Enable this when a field should hold multiple entries, such as multiple tags, roles, files, or references. | This changes payload shape, filter behavior, rendering, and separator handling. Treat it as a modeling choice, not a cosmetic one. |
allow_duplicate_values |
Whether a multi-value property may contain repeated identical items. | Use this only when is_multiple is enabled. Turn it off for set-like behavior, turn it on only if duplicate entries have business meaning. |
Most implementations should keep duplicates disallowed. |
refers_to_upstream |
Marks the property as referring to an upstream source. | Enable only when the property should be interpreted as an upstream reference in your implementation model. | This is an advanced modeling flag. Keep it off unless your tenant uses explicit upstream/downstream patterns. |
These options control how the property behaves in add and edit forms.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
is_required_add |
Whether the field must be filled when creating an object. | Enable when the value is mandatory at creation time. | This is different from is_required_edit. A field may be optional on create and required later, or the other way around. |
is_required_edit |
Whether the field must be filled when editing an object. | Enable when the field may not be left empty during edits. | Useful for fields that become mandatory only after the object exists. |
is_required_message |
Custom message shown when a required field is left empty. | Enter a short, direct validation message such as Please select an owner. |
Use this when the default validation text is too generic. |
caption |
Full label shown in forms. | Enter the preferred user-facing label. Leave empty if property_name already matches what users should see. |
Use this to tailor the UI label without renaming the underlying property. |
caption_short |
Short display label used by tighter UI surfaces. | Enter a shorter version of the caption, for example for cards, kanban, or compact layouts. | If empty, it falls back to property_name. |
description |
Help text or implementation hint shown with the field. | Enter concise guidance explaining what belongs in the field or how the value is used. | Prefer task guidance over technical commentary. |
form_control_class |
Custom CSS or control-class hook for the form control. | Enter the control class name expected by your implementation. | Use sparingly. This is for adapting rendering or custom controls, not for general styling experiments. |
form_control_html_attributes |
Extra HTML attributes for the input control. | Configure this as a struct-like key/value map, for example placeholders, data attributes, or custom control metadata. | This is an advanced escape hatch. Use it when the built-in property options are not enough. |
form_initial_value |
Value used to prefill the field when the form opens. | Provide a literal value or an expression, depending on the use case. | Prefer this for create-time suggestions. See Expressions. |
form_onchange |
Hook or function reference to run when the form value changes. | Enter the configured onchange handler name or expression expected by your implementation. | Use only when the field must trigger reactive form logic. Pair carefully with refresh_form_on_change. |
refresh_form_on_change |
Whether the form should refresh after the field changes. | Enable when changing this field should recompute conditions, dependent options, or other dynamic UI parts. | This is important for fields that affect show_conditions, value_switch, placeholder visibility, or other form-time evaluation. |
add_instances_on_the_fly |
Whether users can create related records directly from the selector. | Choose Off, On adding, On editing, or Always. |
This matters mainly for relation-like property types. Use it when the flow benefits from in-context creation of missing related items. |
tokenize |
Whether multi-value entry should use token-like selection behavior. | Enable for selector-style controls where separate chosen items should be rendered as tokens. | Usually helpful for multi-select relations and tag-like inputs. |
render_as_gallery_select |
Alternative gallery-style selector rendering. | Enable when option selection benefits from visual, tile-based presentation. | Best for image-like or strongly visual option sets. |
render_as_multilevel_checkbox_selector |
Alternative hierarchical checkbox rendering. | Enable when the selectable values are better understood as nested or grouped choices. | Use only when the target data has a real hierarchy. |
replicator_canvas |
Canvas used to render items in replicator-style contexts. | Select a canvas when repeated entries need custom presentation. | Read this together with Canvases. This is a presentation choice, not a data-model choice. |
replicator_wrapper |
HTML wrapper tag used around replicator output. | Enter the wrapper tag or wrapper markup expected by the implementation, for example div, li, or another appropriate wrapper. |
Keep it simple and semantically correct. Use only when replicator output needs specific structure. |
These settings control option sources, defaults, editability, calculations, and validation constraints.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
options_query |
Query used to produce selectable values. | Select a query that returns the option set for the property. | This is the preferred way to populate dynamic selectors. Read Queries before designing complex option sources. |
value_switch |
Advanced conditional switching of value or option behavior. | Configure it as an expression-driven definition when the property should behave differently under different runtime conditions. | In practice, this is mainly relevant for query-backed option scenarios. Use it only when one selector must adapt to context. |
select_options |
Inline static option list. | Configure it as a struct-like associative map of value to label. | The source itself advises using this only when really intended. Prefer options_query for maintainability and reuse. |
select_options_filter |
Conditional removal of selected option values from the option list. | Configure it as an object where keys are conditions and values are arrays of values to filter out. | Use this when a mostly static option set needs conditional exclusions. Keep the logic readable. |
display_placeholder |
Whether a placeholder option should be shown in the selector. | Enable this for pSelect properties when users should actively choose instead of defaulting immediately. |
This option is shown only for pSelect. |
display_placeholder_text |
Text of the placeholder option. | Enter the placeholder label such as Select status or Choose customer. |
This field appears only when display_placeholder is enabled. |
snap_to_option |
Whether entered value should snap to the nearest valid option semantics used by the selector. | Enable when the property must resolve strictly to known options rather than arbitrary free-form input. | Use carefully when user-entered text might otherwise drift from allowed values. |
is_editable |
Whether the value can be edited directly by users. | Turn off for read-only, calculated, externally controlled, or derived values. | This is about user editing, not whether the platform can fill the value through defaults, calculations, or automation. |
shorthand_enabled |
Whether the property can be edited through shorthand interfaces. | Enable only if shorthand entry improves speed and the value format is safe for shorthand editing. | Keep disabled for complex structured values or fields with subtle constraints. |
is_audited |
Whether changes to this property should be audited. | Enable for fields where change tracking matters operationally or legally. | Common candidates are status, ownership, approval fields, and sensitive business values. |
default_value |
Default value or fallback logic for the property. | Enter a literal value or an expression. Use expressions when the default depends on context, dates, current user, or related values. | This is one of the most important dynamic fields. Use it for model-level defaulting rather than form-only prefills. |
no_value_placeholder |
Text shown when the property has no value. | Enter a display fallback such as Not set, No owner, or No due date. |
This improves readability in detail and list contexts. It does not create a stored value. |
calculation |
Logic for deriving the property's value from other values. | Configure this as an expression when the field should be computed rather than entered directly. | Use calculations for derived values, totals, helper labels, and similar model-driven outputs. |
value_step |
Numeric input step granularity. | Enter a numeric step such as 1, 0.5, or 0.01. |
Useful for decimal precision and more user-friendly numeric controls. |
min_value |
Minimum allowed numeric or comparable value. | Enter a literal boundary or a value expression if supported by your use case. | Use this for business constraints like non-negative amounts or bounded percentages. |
max_value |
Maximum allowed numeric or comparable value. | Enter a literal boundary or a value expression if needed. | Use alongside min_value to define valid numeric ranges. |
min_length |
Minimum allowed text length. | Enter the minimum number of characters. | Useful for IDs, codes, and fields where very short values are invalid or meaningless. |
max_length |
Maximum allowed text length. | Enter the maximum number of characters. | Set this intentionally for identifiers, labels, and integration-facing text fields. |
input_mask |
Input formatting mask applied while users type. | Enter the input mask pattern expected by the control, for example for phone numbers, codes, or structured identifiers. | This guides entry. It is not the same thing as mask, which controls display formatting. |
reg_exp |
Regular-expression-based validation rule. | Enter a regular expression when the value must match a strict pattern. | Use this sparingly and document the intent in description so implementers know what qualifies as valid input. |
struct_schema |
Fixed JSON-like schema for pStruct values. |
Configure the schema using the struct schema editor. Define the root type, nested fields, enum values, defaults, and required markers as needed. | This field is shown only for pStruct. Use it whenever structured payloads need a controlled contract. |
This group exists only for rich-text properties.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
rich_text_valid_elements |
Policy for which rich-text elements and attributes are allowed. | Configure it through the rich-text valid-elements editor. Choose the policy mode and define allowed or blocked elements and attribute rules as needed. | This field appears only for pRichText. Use it when you need to balance editor flexibility with content safety and consistency. |
These options are available for pFile and pImage properties.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
max_upload_size |
Maximum allowed upload size in bytes. | Enter the byte limit appropriate for the use case and your infrastructure. | Use explicit limits for user-facing upload fields so failures happen early and predictably. |
file_uploader_start_opened |
Whether the uploader UI starts expanded. | Enable when users should immediately see the upload interface without an extra click. | Helpful for upload-heavy workflows. |
file_auto_upload |
Whether upload begins immediately after selection. | Enable for streamlined upload flows where users do not need a separate confirmation step. | Keep disabled when users often review multiple files before committing. |
image_compress |
Whether uploaded images are converted and compressed. | Enable to convert uploaded images to WebP and optionally reduce quality. | Use this when storage size and delivery performance matter more than original fidelity. |
image_quality |
Compression quality target between 0 and 1. |
Enter a decimal value such as 0.8 when image_compress is enabled. |
This field is shown only when image_compress is true. Lower values reduce size more aggressively. |
cdn_enabled |
Whether files should use CDN delivery. | Leave enabled unless your deployment intentionally bypasses CDN behavior. | This affects delivery strategy, not the stored business meaning of the file. |
These fields control how the property participates in search, lists, grouping, and rendered output.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
is_searchable |
Whether the property participates in text search. | Enable for fields users are likely to search by, such as names, codes, emails, or titles. | Do not enable this blindly on every field. Search relevance drops when too many low-signal fields are included. |
is_filterable |
Whether list and query layers may filter by this property. | Enable when the property has meaningful filter semantics for users. | Filter behavior depends on the property family. Read Filter Operators. |
is_sortable |
Whether records may be sorted by this property. | Enable when ordering by this field is useful and stable. | Sorting on noisy or highly variable fields often harms usability. |
is_groupable |
Whether the property may be used for grouping. | Enable when grouping by this field creates meaningful buckets, such as status, owner, month, or type. | Multi-value or high-cardinality fields are often poor grouping candidates. |
is_calculable |
Whether the property should participate in calculation-aware contexts. | Keep enabled for fields that should be available in calculated or aggregation scenarios; disable where calculations do not make sense. | Some options such as file size limits intentionally turn this off. |
hide_if_empty |
Whether the field should disappear from display contexts when empty. | Enable for optional fields that add noise when blank. | This improves object-detail readability, especially on dense types. |
visible_as_column |
Whether the property may be shown as a column in table-like views. | Leave enabled for fields that make sense in listings. | Disable for highly verbose, internal, or layout-only fields. |
tag_like |
Whether the property should prefer tag-style rendering. | Enable when the value is conceptually categorical, label-like, or badge-like. | Useful for status, labels, categories, and multi-value chips. |
title_property |
Which property of the related target should be used as the display title. | Enter the property selector or target property name when a relation-like field should display something other than the default title-role property. | Leave empty to fall back to the target type's title role. Use this for selectors and rendered relation labels. |
mask |
Display transformation or formatting rule for the property. | Configure the mask when the stored value is correct but its rendered output should be formatted differently. | Use this for display formatting, not for input validation. Pair with Expressions when the mask is dynamic. |
multiple_separator |
Separator used when rendering multiple values as text. | Enter a separator such as , , /, or <br> depending on the context. |
This matters only for multi-value properties. Choose a separator that matches the target UI surface. |
These options decide when the property appears and whether it is exposed beyond the UI.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
visible_show |
Whether the property is visible on object detail views. | Enable when users should see the field in the read-only object context. | This is the base visibility switch for show mode. |
show_conditions |
Conditional logic for show-mode visibility. | Enter an expression that resolves to a boolean. | Use this when visibility depends on state, type, relation presence, or another field. Read Expressions. |
visible_add |
Whether the property is shown when creating an object. | Enable when the field should appear on create forms. | Turn off for system-filled, later-stage, or derived fields. |
add_conditions |
Conditional logic for add-form visibility. | Enter an expression that resolves to a boolean in add context. | Use this for progressive forms and conditional onboarding fields. |
add_conditions_inherit_show |
Whether add visibility should also respect show_conditions. |
Leave enabled when the add form should inherit the same general visibility rule as show mode. Disable when add visibility needs to stand on its own. | This setting prevents duplicated logic when add and show visibility are mostly aligned. |
visible_edit |
Whether the property is shown when editing an object. | Enable when the field should appear on edit forms. | A field may be editable in principle and still hidden in some workflows. |
edit_conditions |
Conditional logic for edit-form visibility. | Enter an expression that resolves to a boolean in edit context. | Use this for state-sensitive editing, approvals, or post-creation restrictions. |
edit_conditions_inherit_show |
Whether edit visibility should also respect show_conditions. |
Leave enabled when the field should use the same base visibility rule everywhere. Disable when editing requires a different rule. | Like the add equivalent, this helps avoid repeated conditions. |
is_api_exposed |
Whether the property is included in API responses for the parent object, subject to permissions. | Enable when integrations should consistently receive this field in API output. | This is an exposure decision. Review it together with Roles And Permissions. |
These fields are important, but they should be changed deliberately and with a clear use case.
| Option | What it controls | How to configure it | Notes |
|---|---|---|---|
relationship_roles |
Structured list of allowed or meaningful roles inside a relationship context. | Configure this as a struct when relation values need explicit role metadata. | Use this only when the relation itself carries a role dimension. |
virtual_reference |
Target-side definition for a virtual or reflected relationship. | Select or configure the reflected target property when the relation should be represented from the opposite side rather than stored independently on both sides. | This is advanced relation modeling. Use it when one relationship must be browsed from both directions. |
virtual_from |
Source-side definition for a virtual relationship. | Set this when the property should derive its relation from another property's stored relationship rather than maintain its own independent storage. | Leave empty for ordinary direct properties. |
personal_data |
Whether the property contains personal data. | Enable for names, contact details, identifiers, profile data, or any value that should be treated as personal data in governance processes. | This is a governance flag and should be set intentionally. |
ignore_cache |
Whether the property should bypass cache-sensitive behavior. | Enable only when caching creates incorrect results for this field's runtime behavior. | This is an advanced troubleshooting and correctness option, not a default optimization strategy. |
settings |
Free-form structured settings object for advanced property-specific behavior. | Configure it as a structured object only when an extension, customization, or property type explicitly expects additional settings here. | Treat this as controlled extension space. Document any tenant-specific use of it. |
Some property options are not simple values. They are small runtime programs.
These fields should be treated as logic:
show_conditionsadd_conditionsedit_conditionsdefault_valueform_initial_valuecalculationmaskvalue_switchConfigure them with these rules in mind:
Read:
The most common expression-driven fields are the visibility conditions.
show_conditions controls visibility on object detailadd_conditions controls visibility while creatingedit_conditions controls visibility while editingThe two inheritance flags let add and edit mode either:
Use inheritance when the same business rule applies everywhere. Disable inheritance when the create or edit journey needs a different rule.
Use the dynamic value fields for different purposes:
form_initial_value for a starting suggestion when the form opensdefault_value for property-level fallback behaviorcalculation when the property should be derived rather than typedmask when the stored value is right, but the displayed form should be transformedThose are not interchangeable. Choosing the wrong one usually creates confusing form behavior later.
When a property presents a list of possible values, choose the source model deliberately.
options_queryUse options_query when:
This is usually the most maintainable choice.
select_options Only For Truly Static SetsUse select_options when:
Good examples include a few fixed modes or technical states that will not evolve into managed data.
select_options_filter For Conditional ExclusionsUse select_options_filter when:
Keep the conditions explicit and easy to explain.
Property validation can be layered:
min_value and max_value limit numeric rangesmin_length and max_length limit text lengthinput_mask helps users type in the expected shapereg_exp enforces strict pattern matchingUse the simplest configuration that communicates intent clearly. Do not combine masks and regular expressions unless there is a real need for both.
Read Expression Parsing And Shortcodes.
Three options often need to be designed together:
is_multipleallow_duplicate_valuesis_uniqueUse this combination deliberately:
If you enable is_multiple, also review:
multiple_separatorSome fields matter mainly for relation-like properties:
options_querytitle_propertyadd_instances_on_the_flyvirtual_referencevirtual_fromrelationship_rolesUse them to answer these questions:
If the field is not relation-oriented, most of these should stay empty.
For file properties, define the user experience and delivery strategy clearly:
max_upload_size for operational limitsfile_uploader_start_opened for form ergonomicsfile_auto_upload for interaction flowimage_compress and image_quality for storage and delivery tradeoffscdn_enabled for serving strategyUse compression intentionally. It improves delivery performance, but it also changes the original upload output.
Use:
visible_add = trueis_required_add = truevisible_edit = falseThis is useful for initialization fields that should not change later.
Use:
is_required_add = falseis_required_edit = trueedit_conditions tied to the state where the value becomes mandatoryThis works well for approval or fulfillment workflows.
Use:
options_querytitle_property when the default relation title is not enoughadd_instances_on_the_fly if users should create missing related items inlineThis is the standard pattern for maintainable relation fields.
Use:
is_editable = falsecalculationhide_if_empty = trueThis works well for computed summaries and helper outputs.
Use:
is_audited = truepersonal_data = true when applicableis_api_exposed reviewed carefullyThis is the right pattern for fields that affect governance, compliance, or accountability.
property_type, is_multiple, and uniqueness rules before tuning UI details.options_query over large inline select_options.caption and caption_short to improve usability without destabilizing identifiers.show_conditions, default_value, and calculation.virtual_from, virtual_reference, settings, and ignore_cache as advanced tools that deserve explicit design notes.