Fields
Fields define the structure and validation rules for data within schemas. Both collection folder models and component schemas use fields to create flexible, type-safe data structures. Fields support hierarchical organization, advanced validation, and rich metadata for enhanced JSON Schema generation.
Fields are used to define:
- Collection folder models - structure of content items within collection folders
- Component schemas - reusable component structures with nested field support
Learn more about schema versioning:
- Versions API - manage schema versions and publication lifecycle
Path Parameters
- Name
:env
- Type
- string
- Description
Unique identifier of the environment
- Name
:path
- Type
- string
- Description
Resource path that varies by type:
- Collection Folders:
folders/:folder
where:folder
is the folder identifier - Components:
components/:component
where:component
is the component identifier
- Collection Folders:
- Name
:version
- Type
- string
- Description
Unique identifier of the version (the
key
field)
URL Pattern
Schema fields use a unified URL pattern: /v1/:env/:path/model/versions/:version/schema/tree/
Examples:
- Collection Folder:
/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/schema/tree/
- Component:
/v1/7c9h4pwu/components/40zahze9815f/model/versions/vr8x2k9m/schema/tree/
Query Parameters
- Name
path
- Type
- string
- Description
Filter fields by path. When specified, the
mode
parameter controls which related fields are returned.
- Name
mode
- Type
- string
- Description
Relationship mode when
path
is specified:children
(default) - direct child fieldssiblings
- fields at the same leveldescendants
- all nested fields recursivelyancestors
- parent fields up to root
Field Object
- Name
key
- Type
- string
- Description
Unique identifier for the field within its parent scope.
- Name
name
- Type
- string
- Description
Human-readable display name for the field.
- Name
description
- Type
- string
- Description
Optional description explaining the field's purpose and usage.
- Name
path
- Type
- string
- Description
Full hierarchical path to the field (e.g.,
user.profile.email
).
- Name
parent
- Type
- string
- Description
Path to the parent field.
null
for root-level fields.
- Name
type
- Type
- string
- Description
Field data type. See Field Types for available options.
- Name
meta
- Type
- object
- Description
Type-specific metadata and validation rules. Structure varies by field type. See Field Type Validation for details.
- Name
json_schema
- Type
- object
- Description
Generated JSON Schema definition for this field.
- Name
required
- Type
- boolean
- Description
Whether the field is required when creating content.
- Name
nullable
- Type
- boolean
- Description
Whether the field accepts
null
values.
- Name
multiple
- Type
- boolean
- Description
Whether the field accepts arrays of values.
- Name
localizable
- Type
- boolean
- Description
Whether the field supports localization for multiple languages.
- Name
searchable
- Type
- boolean
- Description
Whether the field is indexed for search functionality. Searchable fields increase the size of search indexes, which are billed separately from storage.
- Name
private
- Type
- boolean
- Description
Whether the field is excluded from public API responses.
Field Types
Primitive Types
- Name
string
- Description
Text data with length and format validation. Supports patterns, enums, and string formats.
- Name
text
- Description
Long-form text content. Supports length validation.
- Name
number
- Description
Floating-point numbers with range and precision validation.
- Name
integer
- Description
Whole numbers with range validation and multiple constraints.
- Name
boolean
- Description
True/false values with enum and const support.
Date & Time Types
- Name
date
- Description
Date values in YYYY-MM-DD format with range validation.
- Name
time
- Description
Time values in HH:MM:SS[.SSS]Z format (UTC only).
- Name
datetime
- Description
Combined date and time in ISO 8601 format (UTC only).
Relationship Types
- Name
relation
- Description
References to items in other collection folders. Supports arrays and filtering. This is a simple document relationship that cannot be used for joins during search operations. Can be multiple (arrays) and localizable.
- Name
reference
- Description
Single reference to an item in another collection folder. Cannot be multiple or localizable. Works like a foreign key in relational databases and can be used for joins during search operations.
Key Differences:
-
reference
works like a foreign key field in relational databases. This field can be used for joins during search operations, which is why it cannot be multiple or localizable. -
relation
is simply a relationship between documents that acts as a link to another document. This relationship does not allow joins during search operations but is much more flexible, as it can be an array and can be localizable (for example, when document versions for different languages point to different related documents).
Structural Types
- Name
object
- Description
Container for nested fields. Cannot be localizable or searchable. When used with
multiple: true
, supports advanced validation logic through thematch
parameter.
- Name
nested
- Description
Reference to a component schema. Only available for components. Cannot be multiple, localizable, or searchable.
- Name
json
- Description
Free-form JSON objects. Cannot be multiple, localizable, or searchable.
Field Type Limitations
Certain field types have restrictions on the localizable
, searchable
, and multiple
properties.
Attempting to set these properties for restricted field types will result in a validation error.
- Name
object
- Description
Cannot be localizable or searchable. These properties must be
null
or omitted. Can be multiple (arrays of objects).
- Name
json
- Description
Cannot be localizable, searchable, or multiple. These properties must be
null
or omitted.
- Name
reference
- Description
Cannot be localizable or multiple. These properties must be
null
or omitted.
- Name
nested
- Description
Only available in component schemas. Cannot be localizable, searchable, or multiple. These properties must be
null
or omitted.
Fields Validation
The meta
field in the Field object contains type-specific validation rules and metadata. The structure and available parameters depend on the selected field type.
Common Meta
All fields support the following common meta parameters:
- Name
title
- Type
- string
- Description
Human-readable title for the field. This value will be used as the "title" field in the resulting JSON Schema.
- Max length: 255 characters
- Name
description
- Type
- string
- Description
Human-readable description for the field. This value will be used as the "description" field in the resulting JSON Schema.
- Max length: 500 characters
String Fields Meta
- Name
max_length
- Type
- integer
- Default
- default:255
- Description
Maximum character length.
- Max length: 255 characters
- Name
min_length
- Type
- integer
- Description
Minimum character length.
- Cannot be less than 0
- Name
pattern
- Type
- string
- Description
Regular expression pattern for validation
- Name
format
- Type
- string
- Description
Built-in format validation. Possible values:
email
,hostname
,uuid
,ipv4
,ipv6
,uri
,uri-reference
Works the same as in JSON Schema format validation.
- Name
enum
- Type
- array[string]
- Description
Array of allowed string values
- Name
const
- Type
- string
- Description
Single allowed value. Cannot be used with
enum
ordefault
.
- Name
default
- Type
- string
- Description
Default value. Must be in
enum
if specified.
Text Fields Meta
- Name
max_length
- Type
- integer
- Description
Maximum character length.
- Name
min_length
- Type
- integer
- Description
Minimum character length.
- Cannot be less than 0
Number & Integer Fields Meta
- Name
minimum
- Type
- number
- Description
Minimum allowed value
- Name
maximum
- Type
- number
- Description
Maximum allowed value
- Name
exclusive_minimum
- Type
- number
- Description
Specifies that values must be greater than this number (e.g. if
exclusive_minimum
is 5, only values > 5 are valid)
- Name
exclusive_maximum
- Type
- number
- Description
Specifies that values must be less than this number (e.g. if
exclusive_maximum
is 10, only values < 10 are valid)
- Name
multiple_of
- Type
- number
- Description
Value must be multiple of this number
- Name
enum
- Type
- array[number]
- Description
Array of allowed numeric values
- Name
const
- Type
- number
- Description
Single allowed value. Cannot be used with
enum
ordefault
.
- Name
default
- Type
- number
- Description
Default value.
- Cannot be used with
const
. - Must be in
enum
if specified.
- Cannot be used with
Date, Time & DateTime Fields Meta
- Name
from
- Type
- string
- Description
Minimum allowed date/time value
- Date:
YYYY-MM-DD
- Time:
HH:MM:SS[.SSS]Z
(UTC only) - DateTime:
YYYY-MM-DDTHH:MM:SS[.SSS]Z
(UTC only)
- Date:
- Name
to
- Type
- string
- Description
Maximum allowed date/time value (same format as
from
)
- Name
enum
- Type
- array[string]
- Description
Array of allowed date/time values
- Name
const
- Type
- string
- Description
Single allowed value. Cannot be used with
enum
ordefault
.
- Name
default
- Type
- string
- Description
Default value.
- Cannot be used with
const
. - Must be in
enum
if specified.
- Cannot be used with
Relation Fields Meta
Relation fields are simple references to other resources. Unlike reference fields, they can be multiple (arrays), but cannot be used for joins in search operations.
- Name
target
- Type
- string
- Required
- required
- Description
Key of the target collection folder (6-36 characters)
- Name
max_items
- Type
- integer
- Default
- default:100
- Description
Maximum number of relations.
- Max items: 100
- Name
enum
- Type
- array[string]
- Description
Array of allowed target collection folder keys
- Name
const
- Type
- string
- Description
Single allowed target collection folder key. Cannot be used with
enum
ordefault
.
- Name
default
- Type
- string
- Description
Default target collection folder key.
- Cannot be used with
const
. - Must be in
enum
if specified.
- Cannot be used with
Reference Fields Meta
Reference fields are used to create joins between collections during search operations. The multiple
parameter must always be set to false
for reference fields. Note that joins are only available for collection folders and cannot be used when searching component data.
- Name
target
- Type
- string
- Required
- required
- Description
Key of the target collection folder (6-36 characters)
- Name
enum
- Type
- array[string]
- Description
Array of allowed target collection folder keys
- Name
const
- Type
- string
- Description
Single allowed target collection folder key.
- Cannot be used with
enum
ordefault
.
- Cannot be used with
- Name
default
- Type
- string
- Description
Default target collection folder key.
- Cannot be used with
const
. - Must be in
enum
if specified.
- Cannot be used with
Nested Fields Meta
- Name
component
- Type
- string
- Required
- required
- Description
Key of the target component schema (6-36 characters)
Array Validation (when multiple: true)
- Name
min_items
- Type
- integer
- Description
Minimum number of items in array
- Name
max_items
- Type
- integer
- Description
Maximum number of items in array
- Name
unique_items
- Type
- boolean
- Description
Whether all items must be unique. Cannot be used with
object
type.
- Name
match
- Type
- string
- Description
Validation logic for object arrays. Only available for
object
type arrays.any
- At least one child field must be present (generatesanyOf
in JSON Schema)all
- All child fields must be present (generatesallOf
in JSON Schema)one
- Exactly one child field must be present (generatesoneOf
in JSON Schema)
Object Array Validation
When creating arrays of objects (multiple: true
with object
type), you can use the match
parameter to control validation logic.
This feature generates advanced JSON Schema constructs (anyOf
, allOf
, oneOf
) based on child fields.
This allows flexible validation where array items can have different but controlled structures.
How it works:
- Create an
object
field withmultiple: true
- Add child fields to define the object structure
- Set the
match
parameter to control validation:any
: Array items must contain at least one of the defined child fieldsall
: Array items must contain all defined child fieldsone
: Array items must contain exactly one of the defined child fields
Example JSON Schema output:
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"required": ["email"],
"properties": { "email": { "type": "string", "format": "email" } }
},
{
"type": "object",
"required": ["phone"],
"properties": { "phone": { "type": "string" } }
}
]
}
}
List Fields
Retrieves fields for a schema version. By default returns all fields, or related fields when using query parameters.
Success Response: 200 OK
Query Parameters
- Name
path
- Type
- string
- Description
Path to a specific field (e.g., "user.profile")
- When provided, returns fields based on the
mode
parameter
- When provided, returns fields based on the
- Name
mode
- Type
- string
- Default
- default:children
- Description
Defines which related fields to return when
path
is specifiedchildren
- Direct child fieldssiblings
- Fields at the same level (excluding the field itself)descendants
- All nested fields belowancestors
- All parent fields above
Errors
- Name
401 Unauthorized
- Description
Authentication credentials are missing or invalid.
authentication_failed
- authentication credentials were not provided or are invalid
- Name
403 Forbidden
- Description
Insufficient permissions to view schema fields.
permission_denied
- insufficient permissions to perform this action
- Name
404 Not Found
- Description
The specified resource could not be found. Specific codes:
environment_not_found
- the specified environment does not existfolder_not_found
- the specified folder does not exist (for folder fields)component_not_found
- the specified component does not exist (for component fields)version_not_found
- the specified version does not existfield_not_found
- the specified field path does not exist (when using path parameter)
- Name
422 Unprocessable Content
- Description
Business logic error. Specific codes:
non_collection_folder_cannot_have_model
- only collection folders can have schema fieldsvalidation_error
- invalid query parameters
Request
curl https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/schema/tree/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"key": "name",
"name": "Full Name",
"description": "User's full name",
"path": "name",
"parent": null,
"type": "string",
"meta": {
"max_length": 100,
"min_length": 1
},
"json_schema": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"x-type": "string",
"x-localizable": true,
"x-searchable": true
},
"required": true,
"nullable": false,
"multiple": false,
"localizable": true,
"searchable": true,
"private": false
},
{
"key": "email",
"name": "Email Address",
"description": "User's email address",
"path": "email",
"parent": null,
"type": "string",
"meta": {
"format": "email",
"max_length": 255
},
"json_schema": {
"type": "string",
"format": "email",
"maxLength": 255,
"x-type": "string",
"x-localizable": false,
"x-searchable": false
},
"required": true,
"nullable": false,
"multiple": false,
"localizable": false,
"searchable": false,
"private": false
}
]
}
Create Field
Creates a new field in a schema version. Only draft versions can be modified.
Success Response: 201 Created
Attributes
- Name
key
- Type
- string
- Required
- required
- Description
Unique field identifier within parent scope
- Maximum length: 255
- Must contain only alphanumeric characters and single underscores
- Cannot start or end with underscore
- Cannot contain consecutive underscores
- Name
name
- Type
- string
- Required
- required
- Description
Human-readable field name
- Maximum length: 100
- Name
description
- Type
- string
- Default
- default:''
- Description
Field description
- Maximum length: 255
- Name
type
- Type
- string
- Required
- required
- Description
Field data type. See Field Types
- Name
parent
- Type
- string
- Description
Path to parent field for nested fields
- Parent must be of type
object
- Maximum length: 100
- Parent must be of type
- Name
meta
- Type
- object
- Default
- default:{}
- Description
Type-specific metadata and validation rules
- Name
required
- Type
- boolean
- Default
- default:false
- Description
Whether field is required
- Name
nullable
- Type
- boolean
- Default
- default:false
- Description
Whether field accepts null values
- Name
multiple
- Type
- boolean
- Default
- default:false
- Description
Whether field accepts arrays
- Name
localizable
- Type
- boolean
- Default
- default:false
- Description
Whether field supports localization
- Name
searchable
- Type
- boolean
- Default
- default:false
- Description
Whether field is searchable
- Name
private
- Type
- boolean
- Default
- default:false
- Description
Whether field is private
Errors
- Name
401 Unauthorized
- Description
Authentication credentials are missing or invalid.
authentication_failed
- authentication credentials were not provided or are invalid
- Name
403 Forbidden
- Description
Insufficient permissions to create schema fields.
permission_denied
- insufficient permissions to perform this action
- Name
404 Not Found
- Description
The specified resource could not be found. Specific codes:
environment_not_found
- the specified environment does not existfolder_not_found
- the specified folder does not exist (for folder fields)component_not_found
- the specified component does not exist (for component fields)version_not_found
- the specified version does not existfield_not_found
- the specified parent field does not exist
- Name
422 Unprocessable Content
- Description
Validation or business logic error. Specific codes:
validation_error
- validation errors in request datakey_already_exists
- field key already exists in this scopeparent_is_not_object
- parent field must be of type objectreference_cannot_be_embedded
- reference fields cannot be nested under embedded objectsrelation_folder_not_found
- target folder for relation/reference does not existcomponent_not_found
- target component for nested field does not existcollection_cannot_have_nested_schema
- collection folders cannot use nested fieldstoo_many_fields
- maximum number of fields exceededchange_published_collection_schema
- cannot modify published schemaself_nested_component_not_allowed
- a component schema cannot reference itself via a nested field
Request
curl https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/schema/tree/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"key": "title",
"name": "Article Title",
"description": "The main title of the article",
"type": "string",
"meta": {
"max_length": 200,
"min_length": 1
},
"required": true,
"localizable": true,
"searchable": true
}'
Response
{
"key": "title",
"name": "Article Title",
"description": "The main title of the article",
"path": "title",
"parent": null,
"type": "string",
"meta": {
"max_length": 200,
"min_length": 1
},
"json_schema": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"x-type": "string",
"x-localizable": true,
"x-searchable": true
},
"required": true,
"nullable": false,
"multiple": false,
"localizable": true,
"searchable": true,
"private": false
}
Retrieve Field
Retrieves a specific field by its path.
Success Response: 200 OK
Query Parameters
- Name
path
- Type
- string
- Required
- required
- Description
Full path to the field (e.g.,
user.profile.email
)
Errors
- Name
401 Unauthorized
- Description
Authentication credentials are missing or invalid.
authentication_failed
- authentication credentials were not provided or are invalid
- Name
403 Forbidden
- Description
Insufficient permissions to view this field.
permission_denied
- insufficient permissions to perform this action
- Name
404 Not Found
- Description
The specified resource could not be found. Specific codes:
environment_not_found
- the specified environment does not existfolder_not_found
- the specified folder does not exist (for folder fields)component_not_found
- the specified component does not exist (for component fields)version_not_found
- the specified version does not existfield_not_found
- the specified field does not exist
- Name
422 Unprocessable Content
- Description
Business logic error. Specific codes:
validation_error
- invalid query parameters
Request
curl "https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/schema/tree/field/?path=user.email" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"
Response
{
"key": "email",
"name": "Email Address",
"description": "User's email address",
"path": "user.email",
"parent": "user",
"type": "string",
"meta": {
"format": "email",
"max_length": 255
},
"json_schema": {
"type": "string",
"format": "email",
"maxLength": 255,
"x-type": "string",
"x-localizable": false,
"x-searchable": false
},
"required": true,
"nullable": false,
"multiple": false,
"localizable": false,
"searchable": false,
"private": false
}
Update Field
Updates an existing field. Only draft versions can be modified.
Success Response: 200 OK
Query Parameters
- Name
path
- Type
- string
- Required
- required
- Description
Full path to the field to update
Attributes
- Name
type
- Type
- string
- Required
- required
- Description
Field data type. See Field Types
- Name
key
- Type
- string
- Required
- required
- Description
Field identifier (changing this updates the path)
- Maximum length: 255
- Must contain only alphanumeric characters and single underscores
- Cannot start or end with underscore
- Cannot contain consecutive underscores
- Name
name
- Type
- string
- Required
- required
- Description
Human-readable field name
- Maximum length: 100
- Name
description
- Type
- string
- Default
- default:''
- Description
Field description
- Maximum length: 255
- Name
parent
- Type
- string
- Description
Path to parent field (changing this moves the field)
- Parent must be of type
object
- Maximum length: 100
- Parent must be of type
- Name
meta
- Type
- object
- Default
- default:{}
- Description
Type-specific metadata and validation rules
- Name
required
- Type
- boolean
- Default
- default:false
- Description
Whether field is required
- Name
nullable
- Type
- boolean
- Default
- default:false
- Description
Whether field accepts null values
- Name
multiple
- Type
- boolean
- Default
- default:false
- Description
Whether field accepts arrays
- Name
localizable
- Type
- boolean
- Default
- default:false
- Description
Whether field supports localization
- Name
searchable
- Type
- boolean
- Default
- default:false
- Description
Whether field is searchable
- Name
private
- Type
- boolean
- Default
- default:false
- Description
Whether field is private
Errors
- Name
401 Unauthorized
- Description
Authentication credentials are missing or invalid.
authentication_failed
- authentication credentials were not provided or are invalid
- Name
403 Forbidden
- Description
Insufficient permissions to modify this field.
permission_denied
- insufficient permissions to perform this action
- Name
404 Not Found
- Description
The specified resource could not be found. Specific codes:
environment_not_found
- the specified environment does not existfolder_not_found
- the specified folder does not exist (for folder fields)component_not_found
- the specified component does not exist (for component fields)version_not_found
- the specified version does not existfield_not_found
- the specified field does not exist
- Name
422 Unprocessable Content
- Description
Validation or business logic error. Specific codes:
validation_error
- validation errors in request datakey_already_exists
- field key already exists in target scopefield_cannot_be_parent_of_itself
- field cannot be its own parentparent_is_not_object
- parent field must be of type objectreference_cannot_be_embedded
- reference fields cannot be nested under embedded objectschange_published_collection_schema
- cannot modify published schemaself_nested_component_not_allowed
- a component schema cannot reference itself via a nested field
Request
curl -X PUT "https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/schema/tree/field/?path=title" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"name": "Article Title (Updated)",
"description": "The main title of the article with SEO optimization",
"meta": {
"max_length": 150,
"min_length": 10
},
"searchable": true
}'
Response
{
"key": "title",
"name": "Article Title (Updated)",
"description": "The main title of the article with SEO optimization",
"path": "title",
"parent": null,
"type": "string",
"meta": {
"max_length": 150,
"min_length": 10
},
"json_schema": {
"type": "string",
"maxLength": 150,
"minLength": 10,
"x-type": "string",
"x-localizable": true,
"x-searchable": true
},
"required": true,
"nullable": false,
"multiple": false,
"localizable": true,
"searchable": true,
"private": false
}
Delete Field
Permanently deletes a field and all its descendants. Only draft versions can be modified.
Deleting a field will also remove all nested fields within it. This operation cannot be undone.
Success Response: 204 No Content
Query Parameters
- Name
path
- Type
- string
- Required
- required
- Description
Full path to the field to delete
Errors
- Name
401 Unauthorized
- Description
Authentication credentials are missing or invalid.
authentication_failed
- authentication credentials were not provided or are invalid
- Name
403 Forbidden
- Description
Insufficient permissions to delete this field.
permission_denied
- insufficient permissions to perform this action
- Name
404 Not Found
- Description
The specified resource could not be found. Specific codes:
environment_not_found
- the specified environment does not existfolder_not_found
- the specified folder does not exist (for folder fields)component_not_found
- the specified component does not exist (for component fields)version_not_found
- the specified version does not existfield_not_found
- the specified field does not exist
- Name
422 Unprocessable Content
- Description
Business logic error. Specific codes:
change_published_collection_schema
- cannot modify published schema
Request
curl -X DELETE "https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/schema/tree/field/?path=user.profile" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"