Update a schema and returns the updated schema.

put

https://api.seismic.com/css/v1/schemas/{id}

Update requires a full object replacement.

Suppose we created a schema like this:

  {
    "name": "Expense Report Schema",
    "description": "A minimal report",
    "spaceIds": ["b04965e6-a9bb-591f-8f8a-1adcb2c8dc39"],
    "fields": [
      {
        "type": "text",
        "name": "Employee Name",
        "ext": {}
      },
      {
        "type": "numeric",
        "name": "Expense",
        "ext": {}
      }
    ]
  }

We then can take the response, modify it and replace in full:

PUT

{
  "id": "bd1a4c6a-4470-4eba-bb26-4a76c26fd7ae",
  "tenantId": "ebe4d9c8-6d49-4766-8cd6-bfb0375628b5",

  // Updated description
  "description": "A very simple expense report for demo!!",

  "status": "draft",
  "spaceIds": [
    "b04965e6-a9bb-591f-8f8a-1adcb2c8dc39"
  ],
  "fields": [
    {
      "id": "ad79076d-a03d-42f9-8588-66b6b26cee17",
      "optional": true,
      "defaultValue": null,
      "name": "Employee Name",
      "description": "",
      "type": "text",
      "hasDomainOfValues": false,
      "allowMultipleValues": false,
      "valueType": "string",
      "ext": {
        "choices": null,
        "possibleValues": [],
        "placeholder": "",
        "max": 2147483647.0,
        "min": 0.0
      }
    },
    {
      "id": "dd00dbbd-355a-4f90-974d-179738d1d803",
      "optional": true,
      "defaultValue": null,
      "name": "Expense",
      "description": "",
      "type": "numeric",
      "hasDomainOfValues": false,
      "allowMultipleValues": false,
      "valueType": "double",
      "ext": {
        "choices": null,
        "possibleValues": [],
        "placeholder": null,
        "max": 1.7976931348623157E+308,
        "min": 0.0
      }
    }
  ],
  "version": {
    "id": "35d30a4b-e74b-4699-89e0-617da252ee46",
    "number": {
      "major": 1,
      "minor": 0,
      "tag": "v1.0"
    },
    "previousNumber": null,
    "latest": true
  },
  "createdAt": "2023-01-06T16:47:59.38Z",
  "updatedAt": "2023-01-06T16:50:42.552Z",
  "spaces": []
}

Remarks:

All non-updatable fields will be ignored. i.e. createdAt, id, tenantId and etc.
Fields without ID will be treated as new field (with a new auto generated ID) even everything remains the same.

Schema States:

State has 3 possible values: draft, active and inactive.
- draft
  - Schema can only be in this state from initial creation.
  - Integrations should not create object association to schemas in this state, because schemas under draft state can be modified and deleted without version bump.
  - All modifications result in inline update as non-breaking changes.
  - Allows deletion.
- active
  - It can be transitioned from draft or inactive.
  - Modifications will result in either breaking or non-breaking changes.
  - No deletion.
- inactive
  - It can be transitioned from active.
  - Cannot be modified nor deleted.
State is shared across all versions. That means changing a state on v3 will also affect v2, v1. In another
word, state is not versioned.
State transition cannot be done in the same request with other modifications. E.g. One cannot transition a schema
from draft to active with fields removal.

Schema Versioning:

Modifications can result in either breaking or non-breaking change. In general,
a breaking change is needed because the schema can be changed in a way that is no
longer "correct" for all the existing data of the schema.

For instance, a schema with an optional field can be updated to become a
required field as a new version of it but still able to retain the historical
context of the existing data. Version chain is linear without branching.
E.g Next version of 1.0 is 2.0 and 3.0 is the one after.
Non-breaking changes will result in an inline-update without creating a new version. E.g. "v1" -> updates -> "v1" (id: bd1a4c6a-4470-4eba-bb26-4a76c26fd7ae and version number: 1.0).
- New choices in single-select or multi-select must be a superset.
- Field type cannot be changed.
- New field must be optional.
- No fields can be deleted.
- Optional field must remain optional.
Breaking changes will result in a new version. E.g. "v1" -> updates -> "v2" (id: bd1a4c6a-4470-4eba-bb26-4a76c26fd7ae and version number: 2.0)
- Any changes that are not listed in the non-breaking changes section will be treated as breaking. For example:
  - Field deletion.
  - New required fields.
  - Single/Multi select choices are not superset of the original.

Note:
Version chain is linear without branching.
E.g Next version of 1.0 is 2.0 and 3.0 is the one after.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

uuid

required

(Required) The schema id, which identifies a schema across all versions. Note: This is not the version id, which identifies a specific version of the schema.

Body Params

The request body for updating a schema.

Note:

Update requires a full object replacement.
All non-updatable fields will be ignored. i.e. createdAt, id, tenantId and etc.
Fields without ID will be treated as new field (with a new auto generated ID) even everything remains the same.

fields

array of objects

length between 1 and 200

The fields of the schema to be created, which is required and must have at least one item and at most 200 items. Note: no null values are allowed in the fields array.

fields

name

string

required

The name of the field, which is required and must be unique across the schema. Note: name cannot be updated after the field is created.

optional

boolean

Whether the field is optional, which is required. If the value is not provided in the request, it will be defaulted set to true, which means the field is not required.

defaultValue

object

A default value for this field if no data is provided. Validity of the input depends on field type. For example, for a string type field, it can be any string; for a number type field, it should be a number; for a boolean type field, it should be true or false; for a single-select or multi-select field, it should be the name of the choices. This is an optional property and if not provided, there will be no default value for this field.

description

string

The description of the field, which is optional.

type

string

enum

required

The type of the field, which is required. Supported field types include: boolean, single-select, multi-select, text, text-area, rich-text, datetime, datetime-range, numeric, string-array and attachment. Note: single-select means only one choice can be selected while multi-select means multiple choices can be selected.

ext

object

This holds field type specific data. Use null for field type without options (e.g. datetime). E.g. possibleValues can be specified for select and multiSelect.

name

string

length ≤ 255

The name of the schema to be created, which is required and must be unique across the tenant, a duplicated name will result in a Bad Request error.

description

string

length ≤ 1000

The description of the schema to be created, which is optional. If not provided, it will be defaulted to an empty string.

spaceIds

array of uuids

The IDs of the spaces where the schema will be distributed. If not provided, the schema will not be distributed to any space. Note: ShortGuid of the space can also be used and the system will convert it to spaceId automatically.

spaceIds

status

string

enum

The schema status, e.g. draft, active and inactive.
The status can only be updated from

draft to active
active to inactive
inactive to active
Other status updates will result in a Bad Request error.

Allowed:

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200OK, means the schema is successfully updated, and the updated schema will be returned in the response body.

400Bad Request, means the request is invalid. Ensure the schema ID is properly formatted, the request body is valid and includes all required fields.

401Unauthorized, meaning the request is not authorized. Ensure you have a valid tenant-level JWT token to access this endpoint.

403Forbidden, means you don't have permission to access this resource. Ensure your JWT token has the necessary permissions to access this endpoint.

404Not Found, meaning the requested schema could not be found. Ensure the schema ID is correct and the schema exists.

500Internal Server Error, meaning an unexpected error occurred while processing the request. Ensure the server is functioning properly and try again later.