Schemas API¶

A Schema specifies the fields in a Document to index by the search engine. Schemas are specific to a Vault so you may update schemas in one Vault without affecting the schemas in another Vault. When a Schema is updated, all Documents associated with the updated Schema will be automatically re-indexed by our search engine.

An account’s User Schema is used to index the attributes fields of all the Users in the Account. There is only one User Schema per Account. Thus, you do not need to specify the User Schema ID when creating a new User.

Warning

A Schema with Documents associated with it cannot be deleted. You must delete or disassociate all documents first.

A Schema definition has two key/value pairs:

name: string(req’d) - the name of the schema
fields: array(req’d) - an array of field

Each field in the fields array has three key/value pairs:

name: string(req’d) - the name of the field in the Document that is to be indexed
index: boolean(req’d) - indicates if the field should be indexed
type: string(optional) - indicates the datatype of the field. Defaults to string if absent.

Warning

Field names must be case-insensitive unique. For example, two fields with name ‘first_name’ and ‘First_Name’ will not be accepted.

Accepted Datatypes: string, integer, long, float, double, boolean, date (yyyy-MM-dd), and geo_point.

In order to best represent a datetime object, you should store it as a string in ISO 8601 format or as a Unix timestamp integer.

Warning

Only one geo_point field is allowed per schema (indexed or no).

Example Schema Definition

{
   "name": "user",
   "fields": [
      {
         "name": "first_name",
         "index": true,
         "type": "string"
      },
      {
         "name": "street",
         "index": false,
         "type": "string"

      },
      {
         "name": "internal_id",
         "index": true,
         "type": "integer"
      },
      {
         "name": "created_date",
         "index": true,
         "type": "date"
      }
   ]
}

Create a Schema¶

https://d33wubrfki0l68.cloudfront.net/8513b318bb356a4044b0b241683868db1da61329/895a1/_images/plans-available-standard-plus.png

POST /v1/vaults/(string: vault_id)/schemas¶

Creates a new Schema in the specified Vault.

Form Parameters:
Parameters:	vault_id – string(req’d)
	schema – b64 string(req’d) - the Schema definition as a base64 encoded JSON Document
Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 400 Bad Request – invalid `vault_id`, invalid base64 encoded JSON Document, Schema definition missing required fields, Schema name already exists

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas \
    -X POST \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWEiLCJmaWVsZHMiOltdfQ=="

Example Response

{
    "schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Read a Schema¶

GET /v1/vaults/(string: vault_id)/schemas/(string: schema_id)¶

Gets an existing Schema.

Request Headers:
Parameters:	vault_id – string(req’d) schema_id – string(req’d)
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 400 Bad Request – invalid `vault_id` 404 Not Found – Vault does not exist

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas/00000000-0000-0000-0000-000000000000 \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

List all Schemas¶

GET /v1/vaults/(string: vault_id)/schemas¶

Returns all Schemas in the specified Vault.

Request Headers:
Parameters:	vault_id – string(req’d)
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 400 Bad Request – invalid `vault_id` 404 Not Found – Vault does not exist

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "schemas": [
        {
            "fields": [],
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "test_schema",
            "vault_id": "00000000-0000-0000-0000-000000000000"
        }
    ],
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Update a Schema¶

PUT /v1/vaults/(string: vault_id)/schemas/(string: schema_id)¶

Updates an existing Schema in the specified Vault.

Note

This endpoint consumes one operation for every document in this schema. For example, if you have 10k documents in a schema and you update the schema, that costs 10k operations from your monthly allotment.

Form Parameters:
Parameters:	vault_id – string(req’d) schema_id – string(req’d)
	schema – b64 string(req’d) - Schema definition as a base64 encoded JSON document
Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 400 Bad Request – invalid `vault_id`, invalid base64 encoded JSON document, Schema definition missing required field, Schema name already exists

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas/00000000-0000-0000-0000-000000000000 \
    -X PUT \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWFfMCIsImZpZWxkcyI6W119"

Example Response

{
    "schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema_0",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Delete a Schema¶

DELETE /v1/vaults/(string: vault_id)/schemas/(string: schema_id)¶

Deletes a specified Schema. Must not have any associated documents.

Request Headers:
Parameters:	vault_id – string(req’d) schema_id – string(req’d)
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 400 Bad Request – invalid `vault_id`, invalid `schema_id` 404 Not Found – Vault or Schema does not exist 409 Conflict – at least one Document is still associated with the specified Schema

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas/00000000-0000-0000-0000-000000000000 \
    -X DELETE \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success",
    "schema_id": "00000000-0000-0000-0000-000000000000",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Create the User Schema¶

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png

POST /v1/accounts/(string: account_id)/user_schema¶

Create the Account’s UserSchema.

Requires Policy C on UserSchema::

Note

Accounts are created with a default schema that only supports searching on system fields. If you want to add fields to the User Schema, see the Update User Schema endpoint.

Form Parameters:
Parameters:	account_id – string(req’d)
	schema – string(req’d) - Schema definition
Request Headers:
	Authorization – `API_KEY` \| `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – missing resource

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X POST \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWEiLCJmaWVsZHMiOltdfQ=="

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Read the User Schema¶

GET /v1/accounts/(string: account_id)/user_schema¶

Retrieve the account’s UserSchema.

Requires Policy R on UserSchema::

Request Headers:
Parameters:	account_id – string(req’d)
	Authorization – `API_KEY` \| `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – missing resource

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Update the User Schema¶

PUT /v1/accounts/(string: account_id)/user_schema¶

Update the Account’s UserSchema.

Note

This endpoint consumes one operation for every user in the account. For example, if you have 10k users in your account and you update the user schema, that costs 10k operations from your monthly allotment.

Requires Policy U on UserSchema::

Request Headers:
Parameters:	account_id – string(req’d)
	Authorization – `API_KEY` \| `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – missing resource

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X PUT \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWEiLCJmaWVsZHMiOltdfQ=="

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Delete the User Schema¶

DELETE /v1/accounts/(string: account_id)/user_schema¶

Delete the Account’s UserSchema.

Requires Policy D on UserSchema::

Request Headers:
Parameters:	account_id – string(req’d)
	Authorization – `API_KEY` \| `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – missing resource

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X DELETE \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}