Fields

Authentication: JWT | API Key

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:

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
  • Name
    :version
    Type
    string
    Description

    Unique identifier of the version (the key field)

Use /v1/:env/folders/:folder_key/model/versions/:version/schema/tree/ for collection folders and /v1/:env/components/:component_key/model/versions/:version/schema/tree/ for component schemas.

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 fields
    • siblings - fields at the same level
    • descendants - all nested fields recursively
    • ancestors - 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, including FoxNose extensions such as x-localizable and x-searchable.

  • 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.

  • Name
    private
    Type
    boolean
    Description

    Whether the field is excluded from public API responses.

  • Name
    vectorizable
    Type
    boolean
    Description

    Whether the field is enabled for automatic embedding generation and vector search. Only available for string and text fields. Vector embeddings are stored in dedicated vector storage, which is billed separately from regular data usage.

Field Types

Primitive Types

  • Name
    string
    Description

    Text data with length and format validation. Supports patterns, enums, string formats, and optional vectorization when vectorizable=true.

  • Name
    text
    Description

    Long-form text content. Supports length validation, optional vectorization, and full-text search with typo tolerance.

  • 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.

  • Name
    json
    Description

    Free-form JSON objects. Cannot be multiple. No searchable support.

  • Name
    vector
    Description

    User-provided embedding vector with fixed length. Requires meta.dimensions. Cannot be multiple, localizable, searchable, or vectorizable. Use with Vector Field Search to query stored vectors by cosine similarity.

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. Targets must exist in the same environment.

  • Name
    reference
    Description

    Single reference to an item in the specified collection folder (which can be the same folder or a different one). Cannot be multiple or localizable. Targets must exist in the same environment.

Structural Types

  • Name
    object
    Description

    Container for nested fields. Cannot be localizable or searchable. When used with multiple: true, supports advanced validation logic through the match parameter.

  • Name
    nested
    Description

    Reference to a component schema. Only available for components, not collections, and the target component must have an active published version.

Field Type 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.

String Fields

  • Name
    max_length
    Type
    integer
    Description

    Maximum character length (default: 255, max: 255)

  • Name
    min_length
    Type
    integer
    Description

    Minimum character length (min: 0)

  • Name
    pattern
    Type
    string
    Description

    Regular expression pattern for validation

  • Name
    format
    Type
    string
    Description

    Built-in format validation: email, hostname, uuid, ipv4, ipv6, uri, uri-reference

  • Name
    enum
    Type
    array
    Description

    Array of allowed string values

Number & Integer Fields

  • Name
    minimum
    Type
    number
    Description

    Minimum allowed value

  • Name
    maximum
    Type
    number
    Description

    Maximum allowed value

  • Name
    exclusive_minimum
    Type
    boolean
    Description

    Whether minimum is exclusive

  • Name
    exclusive_maximum
    Type
    boolean
    Description

    Whether maximum is exclusive

  • Name
    multiple_of
    Type
    number
    Description

    Value must be multiple of this number

  • Name
    enum
    Type
    array
    Description

    Array of allowed numeric values

Date, Time & DateTime Fields

  • 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)
  • Name
    to
    Type
    string
    Description

    Maximum allowed date/time value (same format as from)

Relation & Reference Fields

  • Name
    target
    Type
    string
    Required
    required
    Description

    Key of the target collection folder (6-36 characters)

  • Name
    max_items
    Type
    integer
    Description

    Maximum number of relations (relation only, default: 100, max: 100)

  • Name
    enum
    Type
    array
    Description

    Array of allowed reference keys. Cannot be used together with const.

  • Name
    const
    Type
    string
    Description

    Single allowed key. Cannot be used with enum or default.

  • Name
    default
    Type
    string
    Description

    Default reference key. Must be in enum if specified.

Nested Fields

  • Name
    component
    Type
    string
    Required
    required
    Description

    Key of the target component schema (6-36 characters)

Vector Fields

Vector fields store user-provided embedding arrays for similarity search. Unlike vectorizable fields (where Flux generates embeddings automatically), vector fields let you bring your own embeddings from external models (e.g., OpenAI, Cohere, or custom pipelines). Query them via Vector Field Search.

  • Name
    dimensions
    Type
    integer
    Required
    required
    Description

    Fixed vector size. Supported values: 256, 384, 768, 1024, 1536.

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

  • 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 (generates anyOf in JSON Schema)
    • all - All child fields must be present (generates allOf in JSON Schema)
    • one - Exactly one child field must be present (generates oneOf 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.

How it works:

  1. Create an object field with multiple: true
  2. Add child fields to define the object structure
  3. Set the match parameter to control validation:
    • any: Array items must contain at least one of the defined child fields
    • all: Array items must contain all defined child fields
    • one: 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" } }
      }
    ]
  }
}

This allows flexible validation where array items can have different but controlled structures.

GETapi.foxnose.net/v1/:env/:path/model/versions/:version/schema/tree/

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
  • Name
    mode
    Type
    string
    Default
    default:children
    Description

    Defines which related fields to return when path is specified

    • children - Direct child fields
    • siblings - Fields at the same level (excluding the field itself)
    • descendants - All nested fields below
    • ancestors - All parent fields above
  • Name
    limit
    Type
    integer
    Description

    Maximum number of results to return. Default: 100.

  • Name
    offset
    Type
    integer
    Description

    Number of results to skip for pagination.

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 exist
    • folder_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 exist
    • field_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 fields
    • validation_error - invalid query parameters

Request

GET
/v1/:env/:path/model/versions/:version/schema/tree/
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,
            "vectorizable": 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,
            "vectorizable": false
        }
    ]
}
POSTapi.foxnose.net/v1/:env/:path/model/versions/:version/schema/tree/

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
  • 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

  • Name
    vectorizable
    Type
    boolean
    Default
    default:false
    Description

    Enables automatic embedding generation and vector search for string and text fields when vectorization is available in your workspace.

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 exist
    • folder_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 exist
    • field_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 data
    • key_already_exists - field key already exists in this scope
    • parent_is_not_object - parent field must be of type object
    • reference_cannot_be_embedded - reference fields cannot be nested under embedded objects
    • relation_folder_not_found - target folder for relation/reference does not exist
    • component_not_found - target component for nested field does not exist
    • collection_cannot_have_nested_schema - collection folders cannot use nested fields
    • self_nested_component_not_allowed - components cannot reference themselves through nested fields
    • too_many_fields - maximum number of fields exceeded
    • change_published_collection_schema - cannot modify published schema

Request

POST
/v1/:env/:path/model/versions/:version/schema/tree/
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,
    "vectorizable": false
}
GETapi.foxnose.net/v1/:env/:path/model/versions/:version/schema/tree/field/

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 exist
    • folder_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 exist
    • field_not_found - the specified field does not exist
  • Name
    422 Unprocessable Content
    Description

    Business logic error. Specific codes:

    • validation_error - invalid query parameters

Request

GET
/v1/:env/:path/model/versions/:version/schema/tree/field/
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,
    "vectorizable": false
}
PUTapi.foxnose.net/v1/:env/:path/model/versions/:version/schema/tree/field/

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
    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
  • 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

  • Name
    vectorizable
    Type
    boolean
    Default
    default:false
    Description

    Enables automatic embedding generation and vector search for string and text fields when supported.

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 exist
    • folder_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 exist
    • field_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 data
    • key_already_exists - field key already exists in target scope
    • field_cannot_be_parent_of_itself - field cannot be its own parent
    • parent_is_not_object - parent field must be of type object
    • reference_cannot_be_embedded - reference fields cannot be nested under embedded objects
    • relation_folder_not_found - specified relation/reference target folder does not exist
    • component_not_found - nested component target does not exist or lacks a published version
    • self_nested_component_not_allowed - components cannot reference themselves through nested fields
    • change_published_collection_schema - cannot modify published schema

Request

PUT
/v1/:env/:path/model/versions/:version/schema/tree/field/
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 '{
    "type": "string",
    "key": "title",
    "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,
    "vectorizable": false
}
DELETEapi.foxnose.net/v1/:env/:path/model/versions/:version/schema/tree/field/

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 exist
    • folder_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 exist
    • field_not_found - the specified field does not exist
  • Name
    422 Unprocessable Content
    Description

    Business logic error. Specific codes:

    • validation_error - invalid query parameters
    • change_published_collection_schema - cannot modify published schema

Request

DELETE
/v1/:env/:path/model/versions/:version/schema/tree/field/
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"

Was this page helpful?