Fetch Requirements for External Accounts V2

Overview

This document provides comprehensive guidance for frontend and integrations teams on interpreting and utilizing JSON Schema Draft-07 requirements and their corresponding uiSchema for External Accounts V2 payloads.

The guide details how to:

Render dynamic forms based on schema specifications

Apply proper validations for data integrity

Handle default values appropriately

Process jurisdiction-specific account requirements

This ensures seamless integration between client implementations and backend services, creating a consistent user experience while maintaining data quality standards.

The goal is to enable:

Frontend to render dynamic, user-friendly forms, prefill default values, and enforce real-time validations based on JSON Schema and uiSchema.

Integrations to validate, process, and handle payloads, ensuring compatibility with backend expectations.

The External Account Payload Requirements API provides comprehensive information about required fields, validation rules, and UI rendering guidelines for different jurisdictions. Please refer to the API Reference documentation also for detailed endpoint specifications, request/response formats, and implementation examples.

1. Interpreting JSON Schema

JSON Schema Draft-07 defines the structure, validation rules, and default values for account payloads.

Field	Description	Type
`id`	Unique identifier for the schema	String
`jurisdiction`	Jurisdiction identifier this schema applies to	String
`title`	Human-readable title of the schema	String
`description`	Detailed description of the schema purpose	String
`type`	JSON Schema type (typically "object")	String
`additionalProperties`	Whether additional properties are allowed	Boolean
`required`	Array of required property names	Array
`properties`	Object containing all field definitions	Object
`if`, `then`, `else`	Conditional logics for dynamic validation	Object

1.1 Common Validation Keywords

These keywords guide form rendering, validation, and default value handling.

Category	Keyword	Description	Frontend Action
Any Type	`type`	Data type (`string`, `number`, `integer`, `object`, `array`, `boolean`, `null`).	Use appropriate input (e.g., text for `string`).
	`enum`	Allowed values.	Render `select` or `radio`.
	`const`	Fixed value.	Use `hidden` widget or prefill.
	`default`	Default value for the field.	Prefill form field with this value if no user input is provided.
Strings	`minLength`, `maxLength`	String length limits.	Validate input length.
	`pattern`	Regex pattern.	Apply regex validation.
	`format`	Predefined format (e.g., `email`, `date`).	Use specific widgets (e.g., `email`, `date`).
Numbers	`minimum`, `maximum`	Inclusive bounds.	Restrict number range.
Arrays	`items`	Schema for array items.	Render repeatable sections.
Objects	`properties`	Field schemas.	Render nested sections.
	`required`	Mandatory fields.	Mark as required (e.g., with `*`).
Conditional	`if`, `then`, `else`	Conditional rules.	Show/hide fields dynamically.

Handling the `default` Keyword

Purpose: Specifies a default value for a field, used when no value is provided by the user.

Frontend Action: Prefill the form field with the default value during initialization. Allow users to override it unless ui:readonly or ui:disabled is set.

Integrations Action: Use the default value when processing payloads if the field is missing or null.

1.2 Custom Validations

The x-customValidation keyword defines non-standard validation rules for any field, with the structure:

"x-customValidation": {
  "rule": "<ruleName>",
  "value": "<expectedValue>",
  "errorMessage": "<errorMessage>"
}

Supported Rules:

Rule	Description	Example
`startsWith`	Value must start with the specified string.	`{ "rule": "startsWith", "value": "AR-", "errorMessage": "Must start with AR-" }`
`endsWith`	Value must end with the specified string.	`{ "rule": "endsWith", "value": "-AR", "errorMessage": "Must end with -AR" }`
`customRegex`	Value must match the specified regex.	`{ "rule": "customRegex", "value": "^\\+54\\d{9}$", "errorMessage": "Must be a valid AR phone number" }`
`contains`	Value must contain the specified substring.	`{ "rule": "contains", "value": " ", "errorMessage": "Must include a space (e.g., full name)" }`

1.3 Conditional Logic

The if, then, and else keywords enable conditional validation (e.g., requiring different fields based on accountType).

Frontend Action: Use form library support (e.g., react-jsonschema-form) to dynamically show/hide fields based on conditions.

Integrations Action: Validate payloads against conditional rules using a JSON Schema validator.

2. Interpreting uiSchema

The uiSchema, located at data.schema.uiSchema, provides UI-specific hints for form rendering, typically used with react-jsonschema-form.

2.1 Common Properties

Property	Description	Frontend Action
`ui:widget`	Input widget type.	Use specified widget (e.g., `select`).
`ui:placeholder`	Placeholder text.	Display in input fields.
`ui:options`	Widget options (e.g., `enumNames`).	Customize widget (e.g., dropdown labels).
`ui:order`	Field display order.	Arrange fields in order.
`ui:help`	Help text below field.	Show as tooltip or text.
`ui:title`	Overrides schema `title`.	Use as field label.
`ui:description`	Overrides schema `description`.	Display as field description.
`ui:autofocus`	Focus on form load.	Set focus on field.
`ui:disabled`	Disables field.	Disable input interaction.
`ui:readonly`	Makes field read-only.	Prevent editing.
`ui:classNames`	CSS classes for styling.	Apply to field elements.

2.2 Supported Widgets

Widget	Use Case
`text`	Text input (default for strings).
`password`	Password input.
`email`	Email input (`format: "email"`).
`tel`	Telephone input.
`select`	Dropdown menu (`enum`).
`radio`	Radio buttons (`enum`).
`checkbox`	Single checkbox (`boolean`).
`checkboxes`	Multiple checkboxes (`array` with `enum`).
`textarea`	Multi-line text input.
`date`	Date picker (`format: "date"`).
`datetime-local`	Date-time picker (`format: "date-time"`).
`file`	File upload (`format: "data-url"`).
`hidden`	Hidden input (e.g., `const` fields).

3. Handling Custom Validations

To handle x-customValidation:

Traverse Schema:

Implement Validation Logic:

Integrate with Form:

4. Handling Default Values

The default keyword specifies a default value for a field when no user input is provided.

Frontend Implementation:

Prefill form fields with default values during initialization.

Example (React with react-jsonschema-form):

Integrations Implementation:

Apply default values to missing or null fields before processing.

Example (Node.js):

5. Resources

JSON Schema Draft-07: http://json-schema.org/draft-07/schema#

react-jsonschema-form: https://rjsf-team.github.io/react-jsonschema-form/

AJV Validator: https://ajv.js.org

ISO 3166-1 Codes: https://www.iso.org/iso-3166-country-codes.html

Fetch Requirements for External Accounts V2

Overview#

1. Interpreting JSON Schema#

1.1 Common Validation Keywords#

Handling the default Keyword#

1.2 Custom Validations#

1.3 Conditional Logic#

2. Interpreting uiSchema#

2.1 Common Properties#

2.2 Supported Widgets#

3. Handling Custom Validations#

4. Handling Default Values#

5. Resources#