Utilities API - JSON Forms

Utility functions for common operations in JSON Forms including path manipulation, schema resolution, validation, and runtime evaluation.

Path Utilities

composePaths

Compose two paths into a single path.

function composePaths(path1: string, path2: string): string

path1

string

required

First path component

path2

string

required

Second path component

return

string

Combined path with proper separator handling

Example:

import { composePaths } from '@jsonforms/core';

composePaths('person', 'address.city'); // 'person.address.city'
composePaths('items', '[0]');           // 'items[0]'
composePaths('', 'name');               // 'name'

toDataPath

Convert a schema path (JSON Pointer) to a data path.

function toDataPath(schemaPath: string): string

schemaPath

string

required

Schema path in JSON Pointer format (e.g., ’#/properties/person/properties/name’)

return

string

Data path in dot notation (e.g., ‘person.name’)

Example:

import { toDataPath } from '@jsonforms/core';

toDataPath('#/properties/person/properties/address/properties/city');
// Returns: 'person.address.city'

toDataPath('#/properties/items/items/properties/name');
// Returns: 'items.name'

toDataPathSegments

Convert schema path to an array of data path segments.

function toDataPathSegments(schemaPath: string): string[]

schemaPath

string

required

Schema path in JSON Pointer format

return

string[]

Array of path segments

Example:

import { toDataPathSegments } from '@jsonforms/core';

toDataPathSegments('#/properties/person/properties/name');
// Returns: ['person', 'name']

encode

Encode a string segment for use in a JSON Pointer.

function encode(segment: string): string

segment

string

required

String segment to encode

return

string

Encoded segment with ’~’ → ‘~0’ and ’/’ → ‘~1’

Example:

import { encode } from '@jsonforms/core';

encode('foo/bar');  // 'foo~1bar'
encode('~test');    // '~0test'

decode

Decode a JSON Pointer segment to its normal representation.

function decode(pointerSegment: string): string

pointerSegment

string

required

Encoded JSON Pointer segment

return

string

Decoded segment with ‘~1’ → ’/’ and ‘~~0’ → '~~'

Example:

import { decode } from '@jsonforms/core';

decode('foo~1bar');  // 'foo/bar'
decode('~0test');    // '~test'

getPropPath

Convert a dotted path to a schema properties path.

function getPropPath(path: string): string

path

string

required

Dotted property path (e.g., ‘person.address.city’)

return

string

Schema properties path (e.g., ‘/properties/person/properties/address/properties/city’)

Example:

import { getPropPath } from '@jsonforms/core';

getPropPath('person.address.city');
// Returns: '/properties/person/properties/address/properties/city'

Schema Resolution

resolveSchema

Resolve a schema path to obtain a subschema.

function resolveSchema(
  schema: JsonSchema,
  schemaPath: string,
  rootSchema: JsonSchema
): JsonSchema | undefined

schema

JsonSchema

required

Schema to start resolution from

schemaPath

string

required

Schema path (JSON Pointer) to resolve

rootSchema

JsonSchema

required

Root schema for $ref resolution

return

JsonSchema | undefined

Resolved subschema or undefined if not found

Example:

import { resolveSchema } from '@jsonforms/core';

const schema = {
  type: 'object',
  properties: {
    person: {
      type: 'object',
      properties: {
        name: { type: 'string' }
      }
    }
  }
};

const nameSchema = resolveSchema(
  schema,
  '#/properties/person/properties/name',
  schema
);
// Returns: { type: 'string' }

Features:

Resolves $ref references
Handles oneOf, anyOf, allOf combinators
Prevents infinite recursion with circular references
Falls back to combinator schemas when direct path fails

resolveData

Resolve a data path to obtain a value.

function resolveData(instance: any, dataPath: string): any

instance

any

required

Data object to resolve from

dataPath

string

required

Data path in dot notation

return

any

Value at the path or undefined

Example:

import { resolveData } from '@jsonforms/core';

const data = {
  person: {
    address: {
      city: 'New York'
    }
  }
};

resolveData(data, 'person.address.city'); // 'New York'
resolveData(data, 'person.phone');        // undefined

findAllRefs

Find all $ref references in a schema.

function findAllRefs(
  schema: JsonSchema,
  result?: ReferenceSchemaMap,
  resolveTuples?: boolean
): ReferenceSchemaMap

schema

JsonSchema

required

Schema to search

result

ReferenceSchemaMap

Initial result map (for recursion)

resolveTuples

boolean

Whether to resolve tuple schemas (default: false)

return

ReferenceSchemaMap

Map of $ref strings to schema objects

Example:

import { findAllRefs } from '@jsonforms/core';

const schema = {
  type: 'object',
  properties: {
    person: { $ref: '#/definitions/Person' },
    address: { $ref: '#/definitions/Address' }
  },
  definitions: {
    Person: { type: 'object', properties: { name: { type: 'string' } } },
    Address: { type: 'object', properties: { city: { type: 'string' } } }
  }
};

const refs = findAllRefs(schema);
// Returns: {
//   '#/definitions/Person': { $ref: '#/definitions/Person' },
//   '#/definitions/Address': { $ref: '#/definitions/Address' }
// }

Validation

createAjv

Create a configured AJV instance for validation.

function createAjv(options?: Options): Ajv

options

Options

AJV configuration options (merged with defaults)

return

Ajv

Configured AJV instance with formats support

Default Options:

{
  allErrors: true,
  verbose: true,
  strict: false,
  addUsedSchema: false
}

Example:

import { createAjv } from '@jsonforms/core';

const ajv = createAjv();
const validator = ajv.compile(schema);

validate

Validate data using a compiled validator.

function validate(
  validator: ValidateFunction | undefined,
  data: any
): ErrorObject[]

validator

ValidateFunction | undefined

required

Compiled AJV validator or undefined

data

any

required

Data to validate

return

ErrorObject[]

Array of validation errors (empty if valid or validator is undefined)

Example:

import { createAjv, validate } from '@jsonforms/core';

const ajv = createAjv();
const validator = ajv.compile({
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 3 }
  },
  required: ['name']
});

const errors1 = validate(validator, { name: 'Jo' });
// errors1.length > 0 (minLength violation)

const errors2 = validate(validator, { name: 'John' });
// errors2.length === 0 (valid)

Schema Utilities

isEnumSchema

Test if a schema defines an enum.

function isEnumSchema(schema: JsonSchema): boolean

schema

JsonSchema

required

Schema to test

return

boolean

True if schema has enum or const property

Example:

import { isEnumSchema } from '@jsonforms/core';

isEnumSchema({ enum: ['a', 'b', 'c'] });  // true
isEnumSchema({ const: 'value' });         // true
isEnumSchema({ type: 'string' });         // false

isOneOfEnumSchema

Test if a schema defines an enum using oneOf with const values.

function isOneOfEnumSchema(schema: JsonSchema): boolean

schema

JsonSchema

required

Schema to test

return

boolean

True if schema has oneOf where all items have const

Example:

import { isOneOfEnumSchema } from '@jsonforms/core';

const schema = {
  oneOf: [
    { const: 'red', title: 'Red' },
    { const: 'green', title: 'Green' },
    { const: 'blue', title: 'Blue' }
  ]
};

isOneOfEnumSchema(schema); // true

getFirstPrimitiveProp

Get the first primitive property from a schema.

function getFirstPrimitiveProp(schema: unknown): string | undefined

schema

unknown

required

Schema to search

return

string | undefined

Name of first property with type ‘string’, ‘number’, or ‘integer’

Example:

import { getFirstPrimitiveProp } from '@jsonforms/core';

const schema = {
  type: 'object',
  properties: {
    id: { type: 'number' },
    nested: { type: 'object' },
    name: { type: 'string' }
  }
};

getFirstPrimitiveProp(schema); // 'id'

Label Utilities

createLabelDescriptionFrom

Create a label description from a control element.

function createLabelDescriptionFrom(
  withLabel: ControlElement,
  schema?: JsonSchema
): LabelDescription

withLabel

ControlElement

required

Control element that may have label configuration

schema

JsonSchema

Schema to derive label from if not explicitly set

return

LabelDescription

Object with text and show properties

Label Resolution Priority:

label.text if label is an object
label if label is a string
schema.title if available
Derived from scope (last segment, converted to start case)

Example:

import { createLabelDescriptionFrom } from '@jsonforms/core';

// String label
const label1 = createLabelDescriptionFrom(
  { type: 'Control', scope: '#/properties/name', label: 'Full Name' }
);
// { text: 'Full Name', show: true }

// Object label
const label2 = createLabelDescriptionFrom(
  {
    type: 'Control',
    scope: '#/properties/name',
    label: { text: 'Name', show: false }
  }
);
// { text: 'Name', show: false }

// Derived from schema
const label3 = createLabelDescriptionFrom(
  { type: 'Control', scope: '#/properties/firstName' },
  { title: 'First Name', type: 'string' }
);
// { text: 'First Name', show: true }

// Derived from scope
const label4 = createLabelDescriptionFrom(
  { type: 'Control', scope: '#/properties/firstName' }
);
// { text: 'First Name', show: true }

createCleanLabel

Create a clean label from a string by converting to start case.

function createCleanLabel(label: string): string

label

string

required

Label string to clean

return

string

Start case version of the label

Example:

import { createCleanLabel } from '@jsonforms/core';

createCleanLabel('first_name');     // 'First Name'
createCleanLabel('emailAddress');   // 'Email Address'

Runtime Evaluation

isVisible

Evaluate if a UI schema element is visible based on rules.

function isVisible(
  uischema: UISchemaElement,
  data: any,
  path?: string,
  ajv: Ajv,
  config: unknown
): boolean

uischema

UISchemaElement

required

UI schema element with potential rule

data

any

required

Current form data

path

string

Current data path

ajv

Ajv

required

AJV instance for schema-based conditions

config

unknown

required

Form configuration

return

boolean

True if element should be visible

Example:

import { isVisible, createAjv } from '@jsonforms/core';

const uischema = {
  type: 'Control',
  scope: '#/properties/city',
  rule: {
    effect: 'SHOW',
    condition: {
      scope: '#/properties/hasAddress',
      schema: { const: true }
    }
  }
};

const ajv = createAjv();

isVisible(uischema, { hasAddress: true }, '', ajv, {});  // true
isVisible(uischema, { hasAddress: false }, '', ajv, {}); // false

isEnabled

Evaluate if a UI schema element is enabled based on rules.

function isEnabled(
  uischema: UISchemaElement,
  data: any,
  path?: string,
  ajv: Ajv,
  config: unknown
): boolean

uischema

UISchemaElement

required

UI schema element with potential rule

data

any

required

Current form data

path

string

Current data path

ajv

Ajv

required

AJV instance for schema-based conditions

config

unknown

required

Form configuration

return

boolean

True if element should be enabled

Example:

import { isEnabled, createAjv } from '@jsonforms/core';

const uischema = {
  type: 'Control',
  scope: '#/properties/zip',
  rule: {
    effect: 'ENABLE',
    condition: {
      scope: '#/properties/country',
      schema: { const: 'US' }
    }
  }
};

const ajv = createAjv();

isEnabled(uischema, { country: 'US' }, '', ajv, {});  // true
isEnabled(uischema, { country: 'CA' }, '', ajv, {}); // false

evalVisibility

Evaluate visibility rule effect.

function evalVisibility(
  uischema: UISchemaElement,
  data: any,
  path?: string,
  ajv: Ajv,
  config: unknown
): boolean

evalEnablement

Evaluate enablement rule effect.

function evalEnablement(
  uischema: UISchemaElement,
  data: any,
  path?: string,
  ajv: Ajv,
  config: unknown
): boolean

hasShowRule

Check if UI schema has a SHOW or HIDE rule.

function hasShowRule(uischema: UISchemaElement): boolean

hasEnableRule

Check if UI schema has an ENABLE or DISABLE rule.

function hasEnableRule(uischema: UISchemaElement): boolean

Generators

JSON Forms provides utilities to generate JSON Schema from data instances and UI Schema from JSON Schema.

Generate.jsonSchema

Generate a JSON Schema from a data instance.

Generate.jsonSchema(instance: Object, options?: any): JsonSchema

instance

Object

required

Data instance to generate schema from

options

any

Optional generation options

return

JsonSchema

Generated JSON Schema describing the data structure

Example:

import { Generate } from '@jsonforms/core';

const data = {
  name: 'John Doe',
  age: 30,
  email: '[email protected]'
};

const schema = Generate.jsonSchema(data);
// Returns a JSON Schema with string and number types

Generate.uiSchema

Generate a default UI Schema from a JSON Schema.

Generate.uiSchema(
  jsonSchema: JsonSchema,
  layoutType?: string,
  prefix?: string,
  rootSchema?: JsonSchema
): UISchemaElement

jsonSchema

JsonSchema

required

JSON Schema to generate UI Schema from

layoutType

string

Layout type to use (e.g., ‘VerticalLayout’, ‘HorizontalLayout’). Defaults to ‘VerticalLayout’

prefix

string

Prefix for scope generation

rootSchema

JsonSchema

Root schema for resolving references

return

UISchemaElement

Generated UI Schema with layout and controls

Example:

import { Generate } from '@jsonforms/core';

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  }
};

const uischema = Generate.uiSchema(schema, 'VerticalLayout');
// Returns a VerticalLayout with controls for name and age

Generate.controlElement

Create a control element for a specific property.

Generate.controlElement(ref: string): ControlElement

ref

string

required

JSON Pointer reference to the property (e.g., ’#/properties/name’)

return

ControlElement

Control element with the specified scope

Example:

import { Generate } from '@jsonforms/core';

const control = Generate.controlElement('#/properties/email');
// Returns: { type: 'Control', scope: '#/properties/email' }

generateJsonSchema

Direct function to generate JSON Schema (also available via Generate.jsonSchema).

function generateJsonSchema(instance: Object, options?: any): JsonSchema

generateDefaultUISchema

Direct function to generate default UI Schema (also available via Generate.uiSchema).

function generateDefaultUISchema(
  jsonSchema: JsonSchema,
  layoutType?: string,
  prefix?: string,
  rootSchema?: JsonSchema
): UISchemaElement

createControlElement

Direct function to create a control element (also available via Generate.controlElement).

function createControlElement(ref: string): ControlElement

Core Package

React Package

Angular Package

Vue Package

Types

​Path Utilities

​composePaths

​toDataPath

​toDataPathSegments

​encode

​decode

​getPropPath

​Schema Resolution

​resolveSchema

​resolveData

​findAllRefs

​Validation

​createAjv

​validate

​Schema Utilities

​isEnumSchema

​isOneOfEnumSchema

​getFirstPrimitiveProp

​Label Utilities

​createLabelDescriptionFrom

​createCleanLabel

​Runtime Evaluation

​isVisible

​isEnabled

​evalVisibility

​evalEnablement

​hasShowRule

​hasEnableRule

​Generators

​Generate.jsonSchema

​Generate.uiSchema

​Generate.controlElement

​generateJsonSchema

​generateDefaultUISchema

​createControlElement

Build docs developers (and LLMs) love

Path Utilities

composePaths

toDataPath

toDataPathSegments

encode

decode

getPropPath

Schema Resolution

resolveSchema

resolveData

findAllRefs

Validation

createAjv

validate

Schema Utilities

isEnumSchema

isOneOfEnumSchema

getFirstPrimitiveProp

Label Utilities

createLabelDescriptionFrom

createCleanLabel

Runtime Evaluation

isVisible

isEnabled

evalVisibility

evalEnablement

hasShowRule

hasEnableRule

Generators

Generate.jsonSchema

Generate.uiSchema

Generate.controlElement

generateJsonSchema

generateDefaultUISchema

createControlElement