Skip to main content

Create Asset Schema

POST 
/api/v1/assetschemas

Create a new Asset Schema definition.

Note: When creating custom schema, please follow these guidelines to get the best performance:-

  • Limit maximum size of a text field to 1000 characters, particularly fields marked as searchable
  • Limit maximum metadata JSON payload per asset to 3000 characters

Warning: Do not provide id when creating a schema — it is assigned by the server.

Permission required

Creating schemas requires the SCHEMA_ADMIN permission. Typically, only ADMIN users have this.

Designing a custom schema​

A schema has name, status, and a schema object with JSON Schema properties. Each property uses filespin_properties for UI and search behavior.

Supported field types​

TypeExample
string"type": "string", "maxLength": 500
string (email)"type": "string", "format": "email"
string (date)"type": "string", "format": "date" (YYYY-MM-DD)
enum"type": "string", "enum": ["draft", "approved"]
array"type": "array", "items": {"type": "string"}
number"type": "number"
boolean"type": "boolean"

filespin_properties​

PropertyEffect
searchableField is included in full-text search
keyword_searchableField contributes to keyword search
ui.orderDisplay order in forms (lower numbers first)
ui.multilineRender as text area instead of single-line input
ui.hiddenDon't show in the form

Request body example​

{
  "name": {"en": "Product Assets"},
  "status": "ACTIVE",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "product_name": {
        "type": "string",
        "maxLength": 200,
        "filespin_properties": {
          "title": {"en": "Product Name"},
          "searchable": true,
          "keyword_searchable": true,
          "ui": {"order": 1}
        }
      },
      "sku": {
        "type": "string",
        "maxLength": 50,
        "filespin_properties": {
          "title": {"en": "SKU"},
          "searchable": false,
          "ui": {"order": 2}
        }
      },
      "category": {
        "type": "string",
        "enum": ["clothing", "accessories", "footwear", "electronics"],
        "filespin_properties": {
          "title": {"en": "Category"},
          "searchable": false,
          "ui": {"order": 3}
        }
      },
      "tags": {
        "type": "array",
        "items": {"type": "string", "maxLength": 100},
        "filespin_properties": {
          "title": {"en": "Tags"},
          "searchable": true,
          "keyword_searchable": true,
          "ui": {"order": 4}
        }
      }
    }
  }
}

Response​

Returns the ID of the newly created schema:

{
  "id": 3
}

For assigning schemas to assets, search integration, and best practices, see Organizing Assets with Custom Metadata Schemas.

Request​

Responses​

Schema created successfully