API Reference
Guides

Overview

Storing custom metadata in structured format

Asset Schema provides the ability to store custom metadata (provided as JSON) that conform to a standard schema. Asset Schema is defined using JSON Schema 2020-12 with a simple FileSpin envelope as below. FileSpin extends JSON Schema to support additional properties using filespin_properties for rendering in frontend UI.

JSON Schema Support

FileSpin supports JSON Schema with some caveats to ensure normal usage scenarios are addressed without sacrificing performance. Please note the following:-

  • JSON array and object type fields support is limited to storage and retrieval
  • Array and Object field types do not support field search

Using Custom Asset Schema

You can create and use custom asset schemas using Asset Schema API. This is the recommended method to manage asset metadata for various classes of assets with distinct metadata requirements.

Default Asset Schema

When a new Asset is created, it is assigned a default Asset Schema with a single field filespin_search_txt which is a searchable text field. This field is a build-in field that cannot be altered. It can be used to store keywords for searching.

{
  "id": 0,
  "name": { "en": "FileSpin Asset Schema" },
  "status": "ACTIVE",
  "schema": {
    "$id": "<<API_HOST>>/json-schema/Asset.CustomMetadata.v1.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "Default Asset Metadata",
    "required": [],
    "properties": {
      "filespin_search_txt": {
        "type": "string",
        "description": "Searchable keywords",
        "minLength": 0,
        "maxLength": 200,
        "filespin_properties": {
          "title": { "en": "Searchable keywords" },
          "hint": { "en": "Keywords associated with this asset for seaching" },
          "placeholder": { "en": "Enter keywords separated by a space" },
          "searchable": true,
          "keyword_searchable": true,
          "ui": {
            "order": 1,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      }
    }
  }
}

Example Schema with a custom field

This example shows a custom schema with a single field a_name of type string and a field a_date of type string with format set to date according to JSON Schema 2020-12 specification

🚧

Asset Schema ID ("id") should not be supplied when creating a new Asset Schema. Schema ID will be generated and returned by FileSpin on successful API call.

{
  "name": { "en": "Sample Asset Schema" },
  "status": "ACTIVE",
  "schema": {
    "$id": "<<API_HOST>>/json-schema/Asset.CustomMetadata.v1.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "Default Asset Metadata",
    "required": ["a_date"],
    "properties": {
      "a_name": {
        "type": "string",
        "description": "A name",
        "minLength": 0,
        "maxLength": 200,
        "filespin_properties": {
          "title": { "en": "A name" },
          "hint": { "en": "A name" },
          "placeholder": { "en": "A name" },
          "searchable": true,
          "keyword_searchable": true,
          "ui": {
            "order": 1,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      },
      "a_date": {
        "type": "string",
        "description": "A date",
        "minLength": 0,
        "maxLength": 24,
        "format": "date",
        "filespin_properties": {
          "title": { "en": "Important date" },
          "hint": { "en": "Important date" },
          "placeholder": { "en": "Important date" },
          "searchable": true,
          "ui": {
            "order": 1,
            "readonly": false,
            "disabled": false,
            "hidden": false
          }
        }
      }
    }
  }
}

Built-in support for string sub-types

JSON Schema string type has built-in support for these optional format sub-types: "date", "email".

For a more details, please consult with your FileSpin technical contact who can help setup appropriate schema for your asset data.

FileSpin Asset Schema properties

filespin_properties within $schema->properties contains FileSpin specific properties per field defined as below:-

KeyTypeDescription
titleJSONDisplayable title in multiple languages. Language keys are ISO 639-1 codes (two-letter codes). en is mandatory. Example: {"en": "My Custom Field"}
hintJSONHelp text for the field in multiple languages. Language keys are ISO 639-1 codes (two-letter codes). en is mandatory. Example: {"en": "Your email id"}
placeholderJSONPlaceholder text in multiple languages. Language keys are ISO 639-1 codes (two-letter codes). en is mandatory. Example: {"en": "Enter your email id here"}
searchablebooleanIndicates if this field is searchable using schema_criteria search parameter
keyword_searchablebooleanIndicates if this field is searchable using keyword search parameter
uiJSONA dictionary of key-value pairs to support rendering of the field in frontend UI. Supported keys: order, readonly, disabled, hidden. See below UI rendering.

UI rendering

{"order": 1, "readonly": false, "disabled": false, "hidden": false }

where order is for display order of the field, readonly is to make the field read-only, disabled is non-selectable read-only, hidden is to render as hidden field