ids.setSchema REST

Skip to end of metadata
Go to start of metadata

 

Note: If you plan on integrating Gigya's Profile Management (IDS), we highly recommend reading the Identity Storage Guide. Profile Management (IDS) is a premium platform that requires separate activation. If it is not yet a part of your existing site package, please contact Gigya Support via the Support link in the top menu of your Console Dashboard or email support@gigya.com.

Description

This API allows specifying a schema for Profile Management. Schemas apply either to the Profile object or to a single user defined Data object which is stored in the User account and holds site specific custom data. Note that the data object can, itself, contain other objects.

  • Profile object - the schema sets client side access restrictions. Other field definitions in the Profile object are fixed and cannot be changed.  
  • Data object - the schema sets field names, data types, formatting and encryption as well as client side access restrictions. Data object schemas act as meta-data, guiding Gigya how to handle the data in the specified fields. If the schema is defined as dynamic, other fields can be added to the storage outside the schema, Gigya will add them as is without special treatment. Field deletion: a field in the Data object schema is eligible for deletion if no data has been saved to it. To delete a field in the schema, you need to set it to null (see example below).

Changes to Data object and Profile schema are incremental, when setting the schema for part of the fields, the properties of the omitted fields remain unchanged. 

Note: For security reasons this method is not available for client side SDKs, only for server side SDKs.

 

Request URL

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription
profileSchemaJSON object 

A JSON object defining the schema to be set on the Profile object. See the format definition of the profile schema object below, please note that you may only set the writeAccess and the required properties on the Profile fields.

* You are required to pass at least one of the parameters: profileSchema or dataSchema.

dataSchemaJSON object 

A JSON object defining the schema to be set on the Data object (the site specific data stored in the User account). See the format definition of the data schema object below.

* You are required to pass at least one of the parameters: profileSchema or dataSchema.

             
format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - If the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is required only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurs.

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Please refer to the Authorization Parameters section for details. 

 

Profile Schema Object

FieldTypeDescription
fieldsJSON objectThis object defines properties per data fields. The object contains field names and their corresponding list of properties (see the example below). 
The properties in option are:
  • writeAccess - Specifies whether to allow unsigned requests to write into this field. This property applies when using the ids.getAccountInfo method, or when setting fields through the usage of a Screen-Set. The supported values are:
    • "serverOnly" (default) - Only signed requests coming from the server are allowed.
    • "clientCreate" - Unsigned requests coming from the client are allowed to write into this field, only if it wasn't set before.
    • "clientModify" - Unsigned requests coming from the client are allowed to write into this field and modify existing values.

Data Schema Object

FieldTypeDescription
fieldsJSON objectThis object defines properties per data fields. The object contains field names and their corresponding list of properties (see the example below). The field name should be the full path name with dots, e.g. "moreInfo.bio".
The properties in option are:
  • allowNull - A Boolean value ("true" by default), specifying whether null values are allowed.
  •  

    encrypt - An encryption algorithm to use for encrypting data when writing in and reading from this field. Currently the only supported value is "AES". The binary data after hashing will be stored as a Base64 string. If set, data placed in this field is stored encrypted. When you retrieve the data, Gigya decrypts it (you receive the original data). Searches on encrypted data are limited to exact matches (such as x = 20); comparative searches (x > 20, x < 20 etc.) are not available. String search values are case sensitive.

    The only data Type fields that currently support encryption are:

    • string
    • text

    If you set the encrypt property on a field that already contains data, the existing data will remain un-encrypted. Only new data will be encrypted.

    Once a field is set to encrypt, it is not possible to remove encryption for that field.

  • format - Allows assigning a regular expression that defines the format of this data field. Gigya will verify that data set in this data field matches the format. If the data set in this field doesn't match the format, Gigya will not set the data and will return an error. The best practice is to validate the data format on your client application. The format property accepts a string of the form: "regex('')". The regex syntax can be found in: Regular Expression Language Reference.
  • type - Defines the data type of this field. The supported values are "integer", "float", "boolean", "string", "date", "long" and "binary". When the type property is not specified the type will be deduced from the field name extension or automatically according to the content of the first item.
    When defining 'binary' field types,  the type must be declared explicitly through the 'type' parameter.
    Please note that a field's type cannot be changed after it contains data. Size limitations for numerical fields are the same as those defined for C#.
  • writeAccess - Specifies whether to allow unsigned requests to write into this field. This property applies when using the ids.getAccountInfo method, or when setting fields through the usage of a Screen-Set. The supported values are:
    • "serverOnly" (default) - Only signed requests coming from the server are allowed.
    • "clientCreate" - Unsigned requests coming from the client are allowed to write into this field, only if it wasn't set before.
    • "clientModify" - Unsigned requests coming from the client are allowed to write into this field and modify existing values.

To delete a field from the schema, you must ensure that data has never been saved to it (even if said data has been deleted), it has no defined type, and then set it to null (see "field6" in the example below). Saving data to a field automatically assigns a type.

Setting a field's properties to null will reset the writeAccess property to "serverOnly" (without deleting the field), if the field contains/contained data and/or has a type setting.

dynamicSchemaBooleanSpecifies whether the schema is strict or dynamic. The default value of this parameter is true i.e. dynamic schema. In a dynamic schema you may add new fields that are not defined in the schema to the storage. The new fields are automatically added to the dynamic schema. In a strict schema you can only write into fields that are already defined in the schema.
Note: The dynamicSchema parameter only applies to server side setAccountInfo calls, and it enables the server to create/modify fields outside of the schema. 

Schema Object Example

dataSchema: {
    fields:  {
        "field1": {writeAccess:"clientCreate", format:"regex('^[a-z0-9_-]{3,16}$')" },
        "field4": {type:"float"},
        "field5": {hash:"sha1", encrypt:"AES" },
        "field6": null  // Delete field6
              },
    dynamicSchema: false 
            }
profileSchema: {
    fields: {
         "gender": {"writeAccess":"clientModify"},
         "birthYear": {"writeAccess":"clientModify"},
         "email": {"writeAccess":"clientModify"}
            }
               }

 

Response Data

FieldTypeDescription
 
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
statusReason string A brief explanation of the status code.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter and not always returned.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or

 

 

 

Response Example

{
        "statusCode": 200,
        "errorCode": 0,
        "statusReason": "OK",
        "callId": "31ba039fb8d340ceb2f43d52c89bf187",
        "time": "2015-03-22T11:42:25.943Z"
}