Squidex
  • Welcome to Squidex
  • Getting Started
    • Squidex Cloud
    • Installation Instructions
      • Platforms
        • Install on Kubernetes
        • Install on AWS (Deprecated)
        • Install on AWS EC2 using Docker
        • Install on Azure
        • Install on Azure using ARM
        • Install on Google Cloud Platform (GCP)
        • Install on Docker
        • Install on Heroku
        • Install on IIS
        • Install on Render
        • Install on Vultr
      • Configuration
        • Deploying the Image Resizer Service
      • Troubleshooting and Support
        • Diagnose Runtime Issues
        • Restoring Deleted Apps
      • Install Identity (Deprecated)
      • External Identity Providers
        • Azure AD (OAuth) with Squidex
    • Contributing and Developing
      • Building
      • Developing
      • Extensions
        • Custom Rule Action
      • Contributing
      • Architecture
      • Translating
      • Squidex Docs Program
    • Roadmap
    • Quick Start Guides
      • Vue.js Blog with Squidex
      • React.js Blog with Squidex
      • Angular Blog with Squidex
  • Documentation
    • Introduction and Use Case
    • Concepts
      • Apps
      • Teams
      • Schemas
        • Field Rules
      • Content
        • Scheduled Publishing
      • Assets
        • Querying Assets
      • Localization
      • Migrations
      • Roles & Permissions
      • Rules
        • Publish an Event to Azure Queues using Rules
        • Populate Elasticsearch Index
      • Backups
      • Subscriptions
        • App Subscriptions v/s Team Subscriptions
      • Notifications
      • Dashboard
      • Workflows
    • Software Development Kits
      • TypeScript
      • .NET
        • Version v14 (and Earlier)
        • Version v15 (and Later)
      • PHP
      • Java
    • Developer Guides
      • API
        • Authentication
        • Postman
        • Queries
        • Assets
      • Automation Tools (CLI)
      • Scripting
        • Scripting Helper Methods
      • Embed Content
      • Custom Workflows
      • Custom Editors
      • Custom Sidebars
      • Preview Content
      • Rule Formatting
        • Simple
        • Script
        • Liquid
      • Tutorials
        • Building a Blog with Squidex and Next.js
  • Next
    • Squidex 3.0: API Compatibility
Powered by GitBook
On this page
  • Introduction
  • Field States
  • Field Types
  • String
  • Number
  • Boolean
  • DateTime
  • Assets
  • References
  • Array
  • Component
  • Components
  • Geolocation
  • Tags
  • Json
  • UI

Was this helpful?

  1. Documentation
  2. Concepts

Schemas

Schemas Define the Structure of Your Content.

PreviousTeamsNextField Rules

Last updated 2 years ago

Was this helpful?

This documentation is based on the FoodCrunch use case. Please open the link below alongside this page to understand the examples.

Introduction

Schemas define the structure of your content. Creating one or more schemas to organize your content is usually the first step after creating an App.

There can be more than 1 schema in an App.

To create a schema click + (1) button under Schemas, give it a Name (2) and select the Type (3). Click Create (4).

A schema consists of multiple fields of various data types. Each field in a schema is identified by the following important properties:

State
Immutable
Description

Name

No

The name of the field in the API. It cannot be changed anymore, but you can add a optional label that is used in UI.

Type

No

The data type of this field.

Editor

Yes

Most fields have an editor, which depends on the type of the field. The editor can be changed, but it will not change the value. If you change a field editor from HTML to Markdown you will probably face issues.

Partitioning

No

Defines whether the field content is localizable and managed in multiple languages or not.

Validation

Yes

A set of validation properties, which depend on the type of the field. For example they define the maximum length of a string or the maximum number of assets you can reference.

To create a field, click + Add Field (1) and select the Field Type (2), give it a Name (3) and optionally select if it is a Localizable field. Click Create and close (4) when done.

To add multiple fields simultaneously, click Create and add field or to immediately edit additional properties on the field click Create and edit field.

There are additional properties that can be set in the field after it is created.

The screenshot above shows the final schema of the startups database for FoodCrunch.

Furthermore, a schema has a published change. Only published schemas can have content. To publish a schema, click Published.

Field States

A field has multiple states:

  1. Enabled: This is is the default state.

  2. Disabled: The field cannot be manipulated in the Management UI. Do not use it together with the required validator, because by doing so, will not be able to update invalid content items.

  3. Hidden: The field will not be returned by the API and is only visible in the Management UI.

  4. Locked: The field cannot be updated or deleted anymore.

To change the state, click on the elipsis (three dots) next to the field and select the right option.

Field Types

Field types define how a field is structured in the API and in the processing pipeline. You can define the editor for each field, so a string field can either be a HTML, text, markdown or a list of allowed values with a dropdown editor.

If a field is not required it can also be null or omitted. A field is also null when it has been added or marked as required, after content items have already been added to the schema.

String

A string is the most used field type and can be used for any type of text, such as product names, descriptions and additional information. It is also the most flexible field and the usage depends very much on the editor you are using:

  1. HTML: With a WYSIWYG editor.

  2. Markdown: With a Markdown editor.

  3. Simple Text: With an input control for texts in one line.

  4. Multiline Text: With a TextArea control.

  5. Selection of Predefined Values: With a dropdown control or radio boxes.

API Representation

"title": {
    "iv": "Sustainable eating by FoodCo"
},
// OR
"title": {
    "iv": null
}

Number

A number can either be a point number or an integer. Typical examples of when to use numbers are quantities, IDs and prices.

API Representation

"fundingInMn": {
    "iv": 234
}
// OR
"fundingInMn": {
    "iv": null
}

Boolean

Booleans have only 2 states: True or false, yes or no, 1 or 0.

API Representation

"givenUp": {
    "iv": false
}
// OR
"givenUp": {
    "iv": true
}
// OR
"givenUp": {
    "iv": null
}

DateTime

Date and time in the ISO8601 standard. The format is: YYYY-MM-DDTHH:mm:ssZ.

API Representation

"foundingDate": {
    "iv": 2021-01-10T00:00:00z"
},
// OR
"foundingDate": {
    "iv": null
}

Assets

API Representation

"image": {
    "iv": [
        "287a2948-8992-4e65-990f-3ee486c9a4b5"
    ]
},
// OR
"image": {
    "iv": null
}

References

References fields are used to model relationships to other content items. For example, you could have a schema for products and a schema for product categories. A product has a field with references to the categories it belongs to. Both products and categories can be created, updated and managed independently. Please think about the direction of the reference very carefully. For example, a typical product may only be in very few categories, but a product category could have thousand of products. Therefore, it is not recommended to reference the products from the categories. When you delete content, a clean-up process will remove the referenced ID from all content. This process is executed in the background to improve performance and it can take several minutes to complete. This is why it's highly recommended to handle cases where a piece of content has a reference to a deleted content.

API Representation

"startup": {
    "iv": [
        "3a20690a-c40b-44bc-832e-0a6e3e708d93"
    ]
},
// OR
"startup": {
    "iv": null
}

Array

Some content items only exist as child content for another content item. For example, a product could consist of variations such as different sizes and prices. These content items can be represented with array fields, where each item in the field has a specified structure, this is called a Nested Schema.

API Representation

"founders": {
    "iv": [{
        "name": "John Doe",
        "position": "CEO"
    }, {
        "name": "Jane Doe",
        "position": "CMO"
    }]
},
// OR
"founders": {
    "iv": null
}

Component

A component is a content item (defined by another schema) that is embedded into the current content.

API Representation

"component1": {
    "iv": {
        "schemaId": "3e6b3c9f-6de7-44a2-bdd0-4cc6ec255480",
        "title": "My Title",
        "text": "My Text"
    }
},
// OR
"component2": {
    "iv": null
}

Components

The components field is used to embed multiple content items (defined by other schemas) into the current item. The order is defined when creating or updating the content item and can be changed in the UI.

API Representation

"components1": {
    "iv": [{
            "schemaId": "3e6b3c9f-6de7-44a2-bdd0-4cc6ec255480",
            "title": "My Title",
            "text": "My Text"
        }, {
            "schemaId": "410a07f2-a89e-4d77-9a43-46fff835ff8c",
            "image": "http://url/to/image",
            "alt": "My Image"
        }
    ]
},
// OR
"components2": {
    "iv": []
},
// OR
"components3": {
    "iv": null
}

Geolocation

The geolocation field represents a sequence of latitude and longitude and is designed to be used in combination with maps. It does not store additional data about the location, such as names, addresses or other information. You have to add additional fields for this purpose.

API Representation

"location": {
    "iv": {
        "longitude": 32.0237703,
        "latitude": -92.0390231
    }
},
// OR
"location": {
    "iv": null
}

Tags

Tags are lists of strings that are use in the combination tag editor in the Management UI. They are especially useful if you enrich your content with external systems. At the moment, the tag editor does not support advanced tag management, such as global lists of tags, renaming and merging of tags.

API Representation

"tags": {
    "iv": [
        "sustainability",
        "food",
        "healthy"
    ]
},
// OR
"tags": {
    "iv": null
}

Json

API Representation

"metadata": {
    "iv": {
        "createBy": "auto-importer"
    }
},
// OR
"location": {
    "iv": null
}

UI

Separator for editing UI.

Asset fields are used to maintain a list of asset IDs. You can also restrict the number of assets with a minimum and maximum limit, for example, when you want to have a single avatar or preview image for a content. You can use the IDs to load the asset. Read more . When you delete an asset, a clean-up process will remove the asset id from your content. This process is executed in the background to improve performance and it can take several minutes to complete. Therefore, it is highly recommended to handle cases where a piece of content has an ID added to a deleted asset.

A json field is for developers. Whenever you have some structured or unstructured content, that you can't cover with the built-in field types or editors, you should use the json field. You should either write a when the content editors can edit the field or disable the field when the content for this field comes from an external source. Editing the json manually is delicate and can easily dismantle your processes.

here
custom editor
Introduction and Use Case
Creating a schema
Creating a field
An example of a schema with fields of different data types
Publishing a schema
Changing the state of a field
String
Number
Boolean
DateTime
Assets
References
Arrays
Component
Components
Geolocation
Tags
Json
UI