Versions

Authentication: JWT | API Key

Schema versions enable you to evolve data structures over time while maintaining backwards compatibility. Both collection folders and components support versioning, allowing you to iterate on your schemas without breaking existing content. Each schema can have multiple draft versions, but only one published version at a time.

Versions are used to manage the evolution of:

Collection folder models - define the structure of content items within collection folders
Component schemas - define the structure and validation rules for reusable components

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)

URL Pattern

Schema versions use a unified URL pattern: /v1/:env/:path/model/versions/

Examples:

Collection Folder: /v1/7c9h4pwu/folders/6b4qd369/model/versions/
Component: /v1/7c9h4pwu/components/40zahze9815f/model/versions/

Version Object

Name
key
Type
string
Description
Unique identifier for the version within the system.
Name
version_number
Type
integer
Description
Sequential version number. null for draft versions, assigned when published.
Name
name
Type
string
Description
Display name of the version for easier identification.
Name
description
Type
string
Description
Optional description explaining changes in this version.
Name
created_at
Type
datetime
Description
Timestamp when the version was created, in ISO 8601 format.
Name
published_at
Type
datetime
Description
Timestamp when the version was published. null for draft versions.
Name
archived_at
Type
datetime
Description
Timestamp when the version was archived. null for active versions.
Name
json_schema
Type
object
Description
The JSON schema definition for this version. This field is null for draft versions and populated when the version is published.

POSTapi.foxnose.net/v1/:env/:path/model/versions/

Create Version

Creates a new draft version for a schema (collection folder or component).

Success Response: 201 Created

Attributes

Name
name
Type
string
Default
default:''
Description
Version display name
- Maximum length: 255
Name
description
Type
string
Default
default:''
Description
Optional description of changes in this version
- Maximum length: 500

Query Parameters

Name
copy_from
Type
string
Description
Key of an existing version to copy fields and schema from

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 versions.
- 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 versions)
- component_not_found - the specified component does not exist (for component versions)
- source_version_not_found - the specified source version for copying does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- non_collection_folder_cannot_have_model - only collection folders can have schema versions
- too_many_versions - maximum number of versions for this schema has been reached

Request

POST

/v1/:env/:path/model/versions/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Version 2.0",
    "description": "Added new fields for user preferences"
}'

Response

{
    "key": "vr8x2k9m",
    "version_number": null,
    "name": "Version 2.0",
    "description": "Added new fields for user preferences",
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "published_at": null,
    "archived_at": null,
    "json_schema": null
}

GETapi.foxnose.net/v1/:env/:path/model/versions/

List Versions

Retrieves all versions for a schema, including both draft and published versions.

Success Response: 200 OK

Ordering

Name
created_at
Type
datetime
Description
Order by creation date. Use -created_at for descending order (latest first).

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 versions.
- 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 versions)
- component_not_found - the specified component does not exist (for component versions)
Name
422 Unprocessable Content
Description
Business logic error. Specific codes:
- non_collection_folder_cannot_have_model - only collection folders can have schema versions

Request

GET

/v1/:env/:path/model/versions/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Response

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "vr8x2k9m",
            "version_number": null,
            "name": "Version 2.0",
            "description": "Added new fields for user preferences",
            "created_at": "2025-06-16T15:30:01.514282-05:00",
            "published_at": null,
            "archived_at": null,
            "json_schema": null
        },
        {
            "key": "vr7x1k8l",
            "version_number": 1,
            "name": "Initial Version",
            "description": "Basic user schema with essential fields",
            "created_at": "2025-06-15T10:15:00.000000-05:00",
            "published_at": "2025-06-15T14:30:00.000000-05:00",
            "archived_at": null,
            "json_schema": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    }
                },
                "required": ["name", "email"]
            }
        }
    ]
}

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

Retrieve Version

Retrieves details of a specific version by its identifier.

Success Response: 200 OK

Query Parameters

Name
unwind_schema
Type
boolean
Default
default:false
Description
When true, transforms localizable fields in the JSON schema to show separate properties for each locale in the environment. Useful for understanding the localized structure of the schema.

Localized Schema Transformation

When unwind_schema=true, localizable fields are expanded to show locale-specific properties:

Original schema:

{
  "title": {
    "type": "string",
    "x-localizable": true
  }
}

Unwound schema (with locales "en" and "es"):

{
  "title": {
    "type": "object",
    "properties": {
      "en": { "type": "string" },
      "es": { "type": "string" }
    },
    "required": ["en"],
    "x-localizable": true
  }
}

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 version.
- 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 versions)
- component_not_found - the specified component does not exist (for component versions)
- version_not_found - the specified version does not exist

Request

GET

/v1/:env/:path/model/versions/:version/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Response

{
    "key": "vr8x2k9m",
    "version_number": null,
    "name": "Version 2.0",
    "description": "Added new fields for user preferences",
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "published_at": null,
    "archived_at": null,
    "json_schema": null
}

PUTapi.foxnose.net/v1/:env/:path/model/versions/:version/

Update Version

Updates a version's metadata. Only draft versions can be updated.

Success Response: 200 OK

Attributes

Name
name
Type
string
Default
default:''
Description
Version display name
- Maximum length: 255
Name
description
Type
string
Default
default:''
Description
Optional description of changes in this version
- Maximum length: 500

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 version.
- 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 versions)
- component_not_found - the specified component does not exist (for component versions)
- version_not_found - the specified version does not exist
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - validation errors in request data
- cannot_update_published_model - published versions cannot be modified

Request

PUT

/v1/:env/:path/model/versions/:version/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Version 2.1",
    "description": "Updated user preferences with new privacy settings"
}'

Response

{
    "key": "vr8x2k9m",
    "version_number": null,
    "name": "Version 2.1",
    "description": "Updated user preferences with new privacy settings",
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "published_at": null,
    "archived_at": null,
    "json_schema": null
}

DELETEapi.foxnose.net/v1/:env/:path/model/versions/:version/

Delete Version

Permanently deletes a version. Draft and archived versions can be deleted, but active (published) versions cannot be deleted.

Active published versions cannot be deleted. They can only be archived after a new version is published.

Success Response: 204 No Content

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 version.
- 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 versions)
- component_not_found - the specified component does not exist (for component versions)
- version_not_found - the specified version does not exist
Name
422 Unprocessable Content
Description
Business logic error. Specific codes:
- cannot_delete_published_schema - active published versions cannot be deleted

Request

DELETE

/v1/:env/:path/model/versions/:version/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

POSTapi.foxnose.net/v1/:env/:path/model/versions/:version/publish/

Publish Version

Publishes a draft version, making it the active schema. This assigns a version number and sets the published timestamp.

Publishing a version will automatically archive the previously published version. Only one version can be published at a time.

Success Response: 200 OK

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 publish this version.
- 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 versions)
- component_not_found - the specified component does not exist (for component versions)
- version_not_found - the specified version does not exist
Name
422 Unprocessable Content
Description
Business logic error. Specific codes:
- version_already_published - this version is already published
- cannot_publish_empty_schema - version must have at least one field to be published
- cannot_publish_archived_version - archived versions cannot be published

Request

POST

/v1/:env/:path/model/versions/:version/publish/

curl -X POST https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/model/versions/vr8x2k9m/publish/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Response

{
    "key": "vr8x2k9m",
    "version_number": 2,
    "name": "Version 2.1",
    "description": "Updated user preferences with new privacy settings",
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "published_at": "2025-06-16T16:45:00.000000-05:00",
    "archived_at": null,
    "json_schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
            },
            "email": {
                "type": "string",
                "format": "email"
            },
            "preferences": {
                "type": "object",
                "properties": {
                    "newsletter": {
                        "type": "boolean"
                    },
                    "privacy_level": {
                        "type": "string",
                        "enum": ["public", "private", "restricted"]
                    }
                }
            }
        },
        "required": ["name", "email"]
    }
}

JSON Schema Generation

When a version is published, FoxNose automatically generates a complete JSON Schema based on the defined fields. This process includes advanced validation logic and structural patterns.

Advanced Array Validation

For object arrays with the match parameter, the system generates sophisticated JSON Schema constructs:

match: "any" → Generates anyOf - array items must contain at least one of the defined child fields
match: "all" → Generates allOf - array items must contain all defined child fields
match: "one" → Generates oneOf - array items must contain exactly one of the defined child fields

Example Generation

Given these fields:

contacts (object, multiple: true, match: "any")
├── email (string, format: email)
└── phone (string)

The published JSON Schema will include:

{
  "contacts": {
    "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 enables flexible validation where each contact can have either an email, phone, or both, depending on your match configuration.