Input Parameter Layout Guide

JSON-Region APEX Properties Quick Reference

This document provides a comprehensive reference for all properties that can be configured in the JSON-Region plugin for Oracle APEX. Properties are organized by category with the most commonly used properties highlighted at the top of each section.

Table of Contents

• JSON-Region APEX Properties Quick Reference
  • Table of Contents
  • Common Properties (Start Here)
  • Basic Properties
  • Layout Properties
  • Validation Properties
  • Display \& Formatting Properties
  • Item Types (apex.itemtype)
    • Text Input Types
    • Selection Types
    • Boolean Types
    • Number/Rating Types
    • Special Input Types
    • File/Image Types
  • Array/Collection Properties
  • File Upload Properties
  • Conditional Properties
  • Oracle 23ai Specific Properties
  • Content Encoding Properties
  • Flows for APEX Integration Guide
    • Overview
    • Common Parameter Type Mappings
    • Mapping Flow Parameter Attributes to JSON Schema
    • Layout Configuration Example
    • Common Flows for APEX Scenarios
      • 1. Simple Text Input
      • 2. Date Selection
      • 3. Approval Choice (Yes/No)
      • 4. Selection from List
      • 5. Multiple Selections
      • 6. Amount with Currency
    • Best Practices for Flows for APEX
    • Property Priority Recommendations
  • Additional Resources
  • Version Notes

---

Common Properties (Start Here)

These are the most frequently used properties for creating dynamic input forms.

Property	JSON Path	Type	Description	Example Value	APEX Version
type	type	string	Data type of the property (required)	"string", "integer", "number", "boolean", "array", "object", "null"	All
label	apex.label	string	Custom label for the input item	"Customer Name"	All
placeholder	apex.placeholder	string	Placeholder text shown when field is empty	"Enter your name"	All
default	default	any	Default value for the property	"John", 123, true, "now" (for dates)	All
required	Parent object’s required array	array	List of required property names	["lastname", "email"]	All
enum	enum	array	List of valid values (creates select list)	["Option1", "Option2", "Option3"]	All
readOnly	readOnly	boolean	Makes field read-only (display only)	true	All
itemtype	apex.itemtype	string	APEX item type to use	"select", "textarea", "switch", "date"	All
format	format	string	Data format (date, email, uri, etc.)	"date", "date-time", "email", "uri"	All
maxLength	maxLength	integer	Maximum length for string inputs	100	All
newRow	apex.newRow	boolean	Start a new row for this field	true (default: false)	All
colSpan	apex.colSpan	integer	Column width (1-12)	6 (spans 6 columns)	All

---

Basic Properties

Core properties that define the data structure and basic behavior.

Property	JSON Path	Type	Description	Example Value	APEX Version
type	type	string	Data type (required for all properties)	"string", "integer", "number", "boolean", "array", "object", "null"	All
properties	properties	object	Defines properties for type: "object"	{"name": {"type": "string"}}	All
items	items	object	Defines items for type: "array"	{"type": "string"}	All
enum	enum	array	List of valid values	["value1", "value2"]	All
const	const	any	Constant value (read-only)	"FIXED_VALUE"	All
default	default	any	Default value. Use "now" for current date/time on date fields	"default text", 123, true, "now"	All
title	title	string	Schema title (for documentation)	"User Profile Schema"	All
description	description	string	Property description (for documentation)	"User's full legal name"	All
$ref	$ref	string	Reference to schema definition	"#/$defs/address", "/defs/country"	All
$defs	$defs	object	Local schema definitions	{"address": {"type": "object", ...}}	All
additionalProperties	additionalProperties	boolean	Allow properties not in schema	true, false	All
readOnly	readOnly	boolean	Makes property read-only	true	All
writeOnly	writeOnly	boolean	Write-only (used for passwords, prevents display of existing value)	true	All

---

Layout Properties

Properties that control the positioning and layout of form fields.

Property	JSON Path	Type	Description	Example Value	APEX Version
newRow	apex.newRow	boolean	Start this field on a new row	true (default: false)	All
newColumn	apex.newColumn	boolean	Start this field in a new column	true (default: true)	All
colSpan	apex.colSpan	integer	Column width (1-12, where 12 is full width)	3, 6, 12	All
textBefore	apex.textBefore	string	Text displayed above the field (creates section header)	"Personal Information"	All
template	apex.template	string	Label template style	"floating", "left", "above", "hidden"	All
css	apex.css	string	CSS classes to add to the field	"my-custom-class another-class"	All

---

Validation Properties

Properties for validating user input.

Property	JSON Path	Type	Description	Example Value	APEX Version
required	Parent required	array	Array of required property names	["firstname", "lastname", "email"]	All
minLength	minLength	integer	Minimum string length	5	All
maxLength	maxLength	integer	Maximum string length	100	All
minimum	minimum	number	Minimum value (number/integer) or date	0, "1900-01-01" (for dates)	All
maximum	maximum	number	Maximum value (number/integer) or date	100, "2099-12-31" (for dates)	All
pattern	pattern	string	Regular expression for validation	"^[A-Z][a-z]+$", "[0-9]{3}-[0-9]{4}"	All
dependentRequired	dependentRequired	object	Properties required when another property has a value	{"creditcard": ["cvv", "expiry"]}	All

---

Display & Formatting Properties

Properties that control how values are displayed and formatted.

Property	JSON Path	Type	Description	Example Value	APEX Version
format	format	string	Standard JSON Schema format	"date", "date-time", "time", "email", "uri", "ipv4", "ipv6", "uuid"	All
format	apex.format	string	APEX-specific format (overrides standard format)	"currency", "DD-MON-YYYY", "999,999.99"	All
label	apex.label	string	Custom label text (overrides auto-generated label)	"Customer Full Name"	All
placeholder	apex.placeholder	string	Placeholder text for empty fields	"Enter your email address"	All
help	apex.help	string	Help text shown as popup (requires “Show Help” enabled)	"Enter your primary contact email"	All
inlinehelp	apex.inlinehelp	string	Inline help text (requires “Show Help” enabled)	"Format: user@domain.com"	All
align	apex.align	string	Text alignment for numbers	"left", "center", "right"	All
textcase	apex.textcase	string	Force text case	"upper", "lower"	All
enum (display mapping)	apex.enum	object	Map enum values to display values	{"M": "Male", "F": "Female"}	All
display	apex.display	object	Custom display template	See Tutorial	All

---

Item Types (apex.itemtype)

Different APEX item types that can be used for rendering inputs. Set via apex.itemtype.

Text Input Types

Item Type	Compatible Types	Description	Example Schema	APEX Version
(default)	string	Standard text input	{"type": "string"}	All
textarea	string	Multi-line text area	{"type": "string", "apex": {"itemtype": "textarea", "lines": 5}}	All
richtext	string	Rich text editor (Markdown only)	{"type": "string", "apex": {"itemtype": "richtext", "colSpan": 12}}	23.2+
password	string	Password field (masked input)	{"type": "string", "apex": {"itemtype": "password", "showPassword": true}}	All (showPassword: 24.2+)

Selection Types

Item Type	Compatible Types	Description	Example Schema	APEX Version
select	string, integer, number with enum	Standard select list	{"type": "string", "enum": ["A", "B", "C"]}	All
radio	string, integer, number with enum	Radio button group	{"type": "string", "enum": ["Yes", "No"], "apex": {"itemtype": "radio", "direction": "horizontal"}}	All
checkbox	array with string items + enum	Checkbox group (multi-select)	{"type": "array", "items": {"type": "string", "enum": ["A", "B", "C"]}}	All
combobox	array with string items + enum	Combobox with chips (allows custom values)	{"type": "array", "items": {"type": "string", "enum": ["A", "B"]}, "apex": {"itemtype": "combobox"}}	23.2+
selectone	string, integer, number with enum	APEX 24.1 select dropdown	{"type": "string", "enum": ["A", "B"], "apex": {"itemtype": "selectone"}}	24.1+
selectmany	array with enum	APEX 24.1 multi-select	{"type": "array", "items": {"type": "string", "enum": ["A", "B"]}, "apex": {"itemtype": "selectmany", "asChips": true}}	24.1+
shuttle	array with enum	Shuttle (dual list box)	{"type": "array", "items": {"type": "string", "enum": ["A", "B", "C"]}, "apex": {"itemtype": "shuttle"}}	24.1+
popuplov	string with enum	Popup List of Values	{"type": "string", "enum": ["A", "B"], "apex": {"itemtype": "popuplov"}}	All

Boolean Types

Item Type	Compatible Types	Description	Example Schema	APEX Version
(default)	boolean	Single checkbox	{"type": "boolean"}	All
switch	boolean	Toggle switch	{"type": "boolean", "apex": {"itemtype": "switch"}}	All

Number/Rating Types

Item Type	Compatible Types	Description	Example Schema	APEX Version
starrating	integer, number	Star rating input	{"type": "integer", "maximum": 5, "apex": {"itemtype": "starrating"}}	All
pctgraph	integer, number	Percentage graph (read-only)	{"type": "number", "apex": {"itemtype": "pctgraph"}}	All

Special Input Types

Item Type	Compatible Types	Description	Example Schema	APEX Version
color	string	Color picker	{"type": "string", "apex": {"itemtype": "color", "colormode": "HEX"}}	23.1+
qrcode	string, integer, number	QR code display (read-only)	{"type": "string", "apex": {"itemtype": "qrcode"}, "readOnly": true}	23.2+

File/Image Types

Item Type	Compatible Types	Description	Example Schema	APEX Version
fileupload	object	File upload (stores as base64)	{"type": "object", "apex": {"itemtype": "fileupload", "maxFilesize": 128, "mimetypes": "pdf,.png"}}	23.2+
imageupload	object	Image upload (stores as base64)	{"type": "object", "apex": {"itemtype": "imageupload", "maxFilesize": 256, "mimetypes": ".png,.jpg"}}	23.2+
image	string with format: "uri" OR with contentEncoding: "base64"	Display image from URL or base64	{"type": "string", "format": "uri", "apex": {"itemtype": "image"}}	All

---

Array/Collection Properties

Properties specific to array types and collections.

Property	JSON Path	Type	Description	Example Value	APEX Version
items	items	object	Schema for array items (required for arrays)	{"type": "string"}	All
hasInsert	apex.hasInsert	string	Where to allow inserting new rows	"begin", "end", "none" (default: "end")	All
hasDelete	apex.hasDelete	boolean	Allow deleting rows	true, false	All
direction	apex.direction	string	Layout direction for radio/checkbox groups	"horizontal", "vertical" (default)	All
asChips	apex.asChips	boolean	Display selectmany items as chips	true	24.1+

---

File Upload Properties

Properties for file and image upload item types.

Property	JSON Path	Type	Description	Example Value	APEX Version
maxFilesize	apex.maxFilesize	integer	Maximum file size in KB	128, 1024	23.2+
download	apex.download	boolean	Enable download link for uploaded files	true, false	23.2+
mimetypes	apex.mimetypes	string	Allowed MIME types (comma-separated)	"pdf,.png,.jpg", "image/png,image/jpeg"	23.2+

Note: File upload items use a special object structure:

{
  "name": "filename.pdf",
  "type": "application/pdf",
  "size": 123456,
  "content": "BASE64_ENCODED_CONTENT..."
}

---

Conditional Properties

Properties for creating conditional/dynamic schemas.

Property	JSON Path	Type	Description	Example Value	APEX Version
if	if	object	Condition to evaluate	{"properties": {"field1": {"const": "value1"}}}	All
then	then	object	Schema to apply if condition is true	{"properties": {"field2": {"type": "string"}}}	All
else	else	object	Schema to apply if condition is false	{"properties": {"field3": {"type": "number"}}}	All
allOf	allOf	array	All schemas must match (AND logic)	[{"properties": {...}}, {"required": [...]}]	All
anyOf	anyOf	array	At least one schema must match (OR logic)	[{"properties": {...}}, {"properties": {...}}]	All
oneOf	oneOf	array	Exactly one schema must match	[{"properties": {...}}, {"properties": {...}}]	All
not	not	object	Schema must NOT match	{"required": ["field1"]}	All
dependentRequired	dependentRequired	object	Properties required based on another property	{"field1": ["field2", "field3"]}	All
dependentSchemas	dependentSchemas	object	Additional properties shown based on another property	{"field1": {"properties": {"field2": {...}}}}	All

Note: When using conditionals, set "additionalProperties": false at the object level to prevent storing hidden fields.

See Tutorial - Conditional Fields for detailed examples.

---

Oracle 23ai Specific Properties

Properties specific to Oracle 23ai JSON features.

Property	JSON Path	Type	Description	Example Value	APEX Version
extendedType	extendedType	string	Oracle-specific type extension	"date", "timestamp", "string", "number", "integer", "array", "object"	All (Oracle 23ai)
sqlScale	sqlScale	integer	SQL decimal scale (from Oracle metadata)	0, 2	All (Oracle 23ai)
dbPrimaryKey	properties.dbPrimaryKey	array	Primary key fields (ignored/removed by plugin)	N/A - Auto-removed	All (Oracle 23ai)
_metadata	Special handling	object	Duality view metadata (ignored/not displayed)	N/A - Auto-ignored	All (Oracle 23ai)

Notes:

• Oracle 23ai extendedType: "date" maps to type: "string", format: "date" in standard JSON Schema
• Oracle 23ai extendedType: "timestamp" maps to type: "string", format: "date-time"
• The plugin automatically retrieves JSON Schema from JSON VALIDATE constraints when no schema is specified
• The plugin automatically retrieves JSON Schema from Duality Views using DBMS_JSON_SCHEMA.describe()

---

Content Encoding Properties

Properties for encoding binary content (primarily images) as base64 strings.

Property	JSON Path	Type	Description	Example Value	APEX Version
contentEncoding	contentEncoding	string	Encoding type for binary data	"base64"	All
contentMediaType	contentMediaType	string	MIME type of encoded content	"image/png", "image/jpg", "image/gif"	All

Example for displaying base64-encoded image:

{
  "profile_photo": {
    "type": "string",
    "contentEncoding": "base64",
    "contentMediaType": "image/png"
  }
}

The field will be automatically set to read-only and display the image.

---

Flows for APEX Integration Guide

Overview

When using JSON-Region with Flows for APEX 26.1, you configure these properties in the Flow Modeler Properties Panel when defining task parameters. The JSON schema is then auto-generated from your parameter definitions.

Common Parameter Type Mappings

Use these mappings when configuring parameters in the Flows for APEX Modeler:

Flow Parameter Type	Recommended JSON Schema Configuration	Notes
Text/String	type: "string"	Use maxLength to limit input
Long Text	type: "string", apex.itemtype: "textarea", apex.lines: 5	For multi-line input
Number	type: "number"	Use minimum/maximum for range validation
Integer	type: "integer"	Whole numbers only
Date	type: "string", format: "date"	Date picker (no time)
DateTime	type: "string", format: "date-time"	Date + time picker
Boolean/Yes-No	type: "boolean"	Checkbox by default
Boolean/Switch	type: "boolean", apex.itemtype: "switch"	Toggle switch UI
Selection List	type: "string", enum: [...]	Dropdown list
Radio Group	type: "string", enum: [...], apex.itemtype: "radio"	Radio buttons
Multi-Select	type: "array", items: {type: "string", enum: [...]}	Checkbox group
Email	type: "string", format: "email"	Email validation
Password	type: "string", apex.itemtype: "password", writeOnly: true	Masked input
File Upload	type: "object", apex.itemtype: "fileupload"	File upload (base64 stored)

Mapping Flow Parameter Attributes to JSON Schema

Flow Parameter Attribute	JSON Schema Property	Example
Parameter Name	Property key in properties object	"customer_name"
Data Type	type	"string", "integer", "boolean"
Description	apex.help or apex.inlinehelp	"Enter the customer's full legal name"
Is Required	Parent object’s required array	"required": ["customer_name"]
Default Value	default	"John Doe", 100, true
Label	apex.label (auto-generated from name if not specified)	"Customer Name"

Layout Configuration Example

When configuring a form in Flows for APEX, you can control the layout:

{
  "type": "object",
  "required": ["firstname", "lastname", "email"],
  "properties": {
    "firstname": {
      "type": "string",
      "maxLength": 50,
      "apex": {
        "label": "First Name",
        "colSpan": 6,
        "placeholder": "Enter first name"
      }
    },
    "lastname": {
      "type": "string",
      "maxLength": 50,
      "apex": {
        "label": "Last Name",
        "colSpan": 6,
        "newColumn": true,
        "placeholder": "Enter last name"
      }
    },
    "email": {
      "type": "string",
      "format": "email",
      "apex": {
        "label": "Email Address",
        "colSpan": 12,
        "newRow": true,
        "placeholder": "user@example.com"
      }
    }
  }
}

Common Flows for APEX Scenarios

1. Simple Text Input

{
  "approval_comments": {
    "type": "string",
    "maxLength": 500,
    "apex": {
      "label": "Approval Comments",
      "itemtype": "textarea",
      "lines": 5,
      "placeholder": "Enter your comments here"
    }
  }
}

2. Date Selection

{
  "start_date": {
    "type": "string",
    "format": "date",
    "default": "now",
    "apex": {
      "label": "Start Date",
      "minimum": "2024-01-01"
    }
  }
}

3. Approval Choice (Yes/No)

{
  "approved": {
    "type": "boolean",
    "apex": {
      "label": "Approve Request?",
      "itemtype": "switch"
    }
  }
}

4. Selection from List

{
  "priority": {
    "type": "string",
    "enum": ["Low", "Medium", "High", "Critical"],
    "default": "Medium",
    "apex": {
      "label": "Priority Level",
      "itemtype": "radio",
      "direction": "horizontal"
    }
  }
}

5. Multiple Selections

{
  "departments": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": ["Sales", "Marketing", "Engineering", "Support", "Finance"]
    },
    "apex": {
      "label": "Notify Departments",
      "itemtype": "checkbox"
    }
  }
}

6. Amount with Currency

{
  "amount": {
    "type": "number",
    "minimum": 0,
    "maximum": 999999.99,
    "apex": {
      "label": "Amount",
      "format": "currency",
      "placeholder": "0.00"
    }
  }
}

Best Practices for Flows for APEX

1. Use Descriptive Labels: Set apex.label explicitly to ensure user-friendly form labels
2. Add Help Text: Use apex.inlinehelp to provide guidance to users
3. Set Appropriate Defaults: Use default to pre-populate common values (especially useful with "now" for dates)
4. Control Layout: Use newRow, colSpan, and newColumn to create organized, multi-column forms
5. Add Validation: Use minimum, maximum, maxLength, pattern to validate input at the client side
6. Group Related Fields: Use apex.textBefore to add section headers
7. Required Fields: Always specify required fields in the required array
8. Placeholder Text: Use apex.placeholder to show examples of expected input format

Property Priority Recommendations

Essential for every parameter:

• type
• apex.label

Recommended for most parameters:

• apex.placeholder (for text/number inputs)
• Add to parent’s required array if mandatory
• maxLength (for strings to prevent excessive input)

Use when needed:

• default (when you have sensible default values)
• apex.help or apex.inlinehelp (for complex or important fields)
• format (for dates, emails, URIs)
• Layout properties like colSpan, newRow (to create organized multi-column forms)

---

Additional Resources

• Tutorial with Examples - Step-by-step examples with complete schemas
• Main Documentation - Full plugin documentation
• Installation Guide - How to install the plugin
• JSON Schema Specification: https://json-schema.org

---

Version Notes

• APEX 20.1-20.2: Base item types (text, select, radio, checkbox, textarea, password, switch, starrating)
• APEX 23.1+: Color picker
• APEX 23.2+: Combobox, Rich text editor, QR code, File/Image upload
• APEX 24.1+: SelectOne, SelectMany, Shuttle
• APEX 24.2+: Password showPassword button

Always check the APEX Version column in tables above for feature availability.