accounts.setSchema REST

Skip to end of metadata
Go to start of metadata

 

This method enables you to specify a schema for Gigya's Accounts Storage. 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 and makes content required. 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 and making content required. The data object schema acts as metadata, guiding Gigya in 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, and Gigya will add them as is, without special treatment.

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

Notes:

  • For security reasons this method is not available for client side SDKs, only for server side SDKs.
  • This method is part of the Registration-as-a-Service and the Profile Management - IDS packages. Both packages are premium platforms that require separate activation. If neither are part of your site package, please contact your Gigya Account Manager or contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.
  • For additional information relating to Site Groups and/or SSO, see Site Groups and Single Sign-on.

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

profileSchema

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

dataSchema

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

subscriptionsSchema

JSON object A JSON object defining the schema to be set on the Subscriptions object. See the format definition of the subscriptions schema object below.
scopestring

When calling this method on a member of a site group, this parameter determines if the schema being set is applied to the entire site group or a specific child site. You may specify one of the following:

  • group (default) - When setSchema is called on the master site, the schema will be applied to all members of the site group unless explicitly overridden by a child site (required property only).
  • site - The schema will be applied to a specific child site.

When using this parameter, setSchema behaves differently based on the api key used in the call.

             
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 optional properties are:
  • required - A Boolean value ("false" by default), specifying whether this field is required. If set to "true", when registering for a new account you are required to supply an initial value for this field, otherwise the registration fails.
  • writeAccess - Specifies whether to allow unsigned requests to write into this field. This property applies when using the accounts.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 new data into this field, but not modify existing values.
    • "clientModify" - Unsigned requests coming from the client are allowed to write new data into this field as well as modify existing values.
  • languages - An array of strings containing languages with which a text field is compatible, in addition to the default languages. A maximum of 4 such languages is supported. The values passed in this property are added to the existing languages in the field, and if the total number exceeds 4 languages, the operation fails. Note: the only language currently supported for this functionality is Japanese.

Data Schema Object

FieldTypeDescription

fields

JSON object

This object defines properties for data fields. The object contains field names and their corresponding list of properties (see the example below).

Requirements for field names:

  1. The field name should be the full path name with dots, e.g. "moreInfo.bio".
  2. Field names can consist of letters, digits, underscores ("_") and periods (".") only.

Properties that can be set for each field:

  • 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('<regex-pattern>')". The regex syntax can be found in: Regular Expression Language Reference.

  • required - A Boolean value ("false" by default), specifying whether this field is required. If set to "true", when registering for a new account you are required to supply an initial value for this field, otherwise the registration fails.

  • type - Defines the data type of this field. The supported values are:

    • "integer" (range: -2,147,483,648 to 2,147,483,647, size: signed 32-bit integer).
    • "long" (range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, size: signed 64-bit integer).
    • "float" (approximate range: ±1.5e−45 to ±3.4e38, size: 7 digits).
    • "string" (up to 16 KB in size - a multi-field with analyzed  entries (searchable using partial case-insensitive searches)).
    • "basic-string":(up to 16 KB in size - a field with non-analyzed entries (non-searchable)).

    • "text" (up to 64 KB - an analyzed multi-field (only searchable using exact match)).
    • "date"
    • "boolean"

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 a 'binary' field type, it is not  in ferred from the data and must be declared explicitly through the 'type' parameter. 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 accounts.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.
  • languages - An array of strings containing languages with which a text field is compatible, in addition to the default languages. A maximum of 4 such languages is supported. The values passed in this property are added to the existing languages in the field, and if the total number exceeds 4 languages, the operation fails. The only language currently supported for this functionality is Japanese.

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.

dynamicSchema

Boolean

Specifies 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.

If dynamicSchema is set to false you must make sure to set field types on creation. Failure to declare a type will prevent the field from being indexed and returned by accounts.search.

Note that the dynamicSchema parameter only applies to server side setAccountInfo calls, and it enables the server to create/modify fields outside of the schema.

When creating Dynamic fields using accounts.setAccountInfo, the write access of these fields is always serverOnly and may impact your implementation. It is recommended best practice to ONLY ever create new schema fields using accounts.setSchema, except in very rare scenarios.

 

Subscriptions Schema Object

FieldTypeDescription
fieldsJSON object

This contains the unique name for this subscription in the schema and must be in the format below:

// Where mySubscriptionOne is the unique name of this subscription
{
	"mySubscriptionOne": {
    	email: {
			type:"subscription",
			required: true
		}
	}
}

 

 

Schema Object Example

dataSchema: {
    fields: {
        "field1": {
            writeAccess:"clientCreate",
            format:"regex('^[a-z0-9_-]{3,16}$')"
        },
        "field4": {
            type:"float"
        },
        "field5": {
            encrypt:"AES"
        },
        "field6": null,     // Delete field6
        "field7": {
           type: "text",
           languages: ["ja"]
        }
    },
    dynamicSchema: false
}
profileSchema: {
    fields: {
        "gender": {
            "writeAccess": "clientModify",
            "required": false
         },
         "birthYear": {
             "writeAccess": "clientModify",
             "required": true
         },
         "email": {
             "writeAccess": "clientModify",
             "required": true
         }
    }
}
subscriptionsSchema: {
    "fields": {
		"mySubscriptionOne": {
            email: {
				type:"subscription",
				required: true // Warning: If you set a subscription as required, it must be included on all registration completion screens!
			}
        },
		"mySubscriptionTwo": {
            email: {
				type:"subscription",
				required: false
			}
        }
    }
}

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"
}

 

Additional Information

For information relating to Site Groups or SSO, see Site Groups and Single Sign-On.