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.