Schema Definitions -

Schema Definitions are a catalog to describe properties/signals, means of validation and to set indexing.

Path

Each schema definition has a path.

/(bots|users|globals)/(properties|signals)/PROPERTY_OR_SIGNAL_NAME

This pattern responds to a property or signal with the given name for either bots,users,globals. A pattern can only be used once and has to be unique. The structure is the same as used in a script path.

JSON Schema

Property and Signal values can be validated using the JSON Schema vocabulary. Saga is using AJV version8. When a property is added to Saga or a signal is emitted, it checks whether there is schema definition for the path of the property/signal and will verify the property/signal value. When the verification fails the property/signal value is refused. If enabled is set to false the validation will not take place.

Indexing

If indexed is set so true the actual property in either bot or user is indexed by the database which leads to greater performance if the property is routinely used in sorting or searching bots or users. Indexing has no effect on global properties as they are stored in a single object.

HTTP Resources

GET /schema_definitions

Lists the available schema definitions. Each definition has the following

path - has to be unique. permitted naming:
json_schema - the actual JSON Schema
enabled - whether the schema definition is enabled
indexed - whether the property indexing is enabled
notes - notes on the schema

RESPONSE

[
    {
        "_id": "60ecba60e65b360033c96f2c",
        "path": "/bots/properties/dimensions",
        "enabled": true,
        "indexed": false,
        "json_schema": {
          "type": "object",
          "properties": {
            "width": {
              "type": "number"
            },
            "height": {
              "type": "number"
            }
          }
        },       
        "notes": "",
        "tags": [ ]
    },
    {
        "_id": "60ef3137451ce00038bf781f",
        "path": "/globals/properties/score",
        "enabled": true,
        "indexed": true,
        "json_schema": {
            "type": "integer"            
        },
        "notes": "holds the score",
        "tags": [ ]
    }
]

POST /schema_definitions

Create a property definition

POST

{
  "path": "/bots/properties/dimensions",
  "enabled": true,
  "indexed": false,
  "json_schema": {
    "type": "object",
    "properties": {
      "width": {
        "type": "number"
      },
      "height": {
        "type": "number"
      }
    }
  }
}

RESPONSE

{
  "_id": "60ecba60e65b360033c96f2c",
  "path": "/bots/properties/dimensions",
  "enabled": true,
  "indexed": false,
  "json_schema": {
    "type": "object",
    "width": {
      "width": {
        "type": "number"
      },
      "height": {
        "type": "number"
      }
    }
  },
  "createdAt":"2021-07-20T23:15:44.060Z",
  "updatedAt":"2021-07-20T23:15:44.060Z"
}

PUT /schema_definitions/:id

Update a property definition

POST

{"enabled": false}

RESPONSE

{
  "_id": "60ecba60e65b360033c96f2c",
  "path": "/bots/properties/dimensions",
  "enabled": false,
  "json_schema": {
    "type": "object",
    "properties": {
      "width": {
        "type": "number"
      },
      "height": {
        "type": "number"
      }
    }
  },
  "createdAt":"2021-07-20T23:15:44.060Z",
  "updatedAt":"2021-07-20T23:15:44.060Z"
}

DELETE /schema_definitions/:id

Delete a property definition.