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.

preferencesSchema

JSON object A JSON object defining the schema to be set on the Preferences object .
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.

Some REST APIs may function without these authorization parameters, however, when that occurs, these calls are treated as client-side calls and all client-side rate limits will apply. In order to not reach client-side rate limits that may impact your implementation when using server-to-server REST calls, it is Recommended Best Practice to always sign the request or use a secret. A non-exhaustive list of REST APIs that this may apply to are as follows:

  • accounts.login
  • socialize.login
  • accounts.notifyLogin
  • socialize.notifyLogin
  • accounts.finalizeRegistration
  • accounts.linkAccounts

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.setAccountInfo 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.
  • format - * Applies only to profile.email: Allows assigning a regular expression (regex) that defines the legitimate value acceptable in the profile.email field. Gigya will check the value passed by users to this data field to make sure it answers to the defined format. If the value passed in this field doesn't match the format, Gigya will not save the data and will return an error. The best practice is to validate the 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.
    The following code sample demonstrates passing the profile.email field in the fields JSON with a regex that validates the email format in the profile.email field:

    "profile.email": {
    			"type": "string",
    			"format" : "regex('^(?=(.{1,64}@.{1,255}))([!#$%&'*+\\-\\/=?\\^_`{|}~a-zA-Z0-9}]{1,64}(\\.[!#$%&'*+\\-\\/=?\\^_`{|}~a-zA-Z0-9]{0,}){0,})@((\\[(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}\\])|([a-zA-Z0-9-]{1,63}(\\.[a-zA-Z0-9-]{2,63}){1,}))$')"
    		},

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.
    (*When using (".") in a field name you are creating a hierarchical nested field. This can be useful when setting up complex objects, for example:
    -  data.parents.father
    -  data.parents.mother
    Creates the following structure in the schema:

    "data": {
    	"parents": {
    		"father": "",
    		"mother": ""
    	}
    }

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 (regex) that defines the format of this data field. Gigya will check the value passed by users to this data field to make sure it answers to the defined format. If the value passed in this field doesn't match the format, Gigya will not save 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#. For details about the size of a KB, see this article.

  • writeAccess - Specifies whether to allow unsigned requests to write into this field. This property applies when using the accounts.setAccountInfo 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

Creates a new Subscriptions Object in the schema. The optional properties are as follows. See the structure of the JSON object below:

  • type: Must be set to subscription
  • required: A Boolean value ("false" by default), specifying whether this field must be seen by the user in order for a registration to be completed successfully. If set to "true", you should include this subscription in all profile completion screens, or the user will never be able to complete their registration. For instructions on adding subscriptions to screens, see Subscription Management.
  • description: The description of the current subscription. This may be used in the double opt-in confirmation email template.
  • doubleOptIn: A Boolean field, specifying whether this subscription requires double opt-in confirmation.

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
			description: "My Subscription",
			doubleOptIn: true
		}
	}
}

 

Preferences Schema Object

FieldTypeDescription
fieldsJSON object

Creates a new Preferences Object in the schema. The optional properties are as follows. See the structure of the JSON object below:

  • type: Must be set to consent
  • currentDocVersion: You must supply a currentDocVersion or currentDocDate.
  • currentDocDate: You must supply a currentDocVersion or currentDocDate.
  • description: A description of the consent object.
  • required: This applies to the requirement of the isConsentGranted field of the Preferences object and defines whether consent is required.
  • format: Defines whether the isConsentGranted field requires validation in order to be submitted. Possible values are:
    • true
    • false
    • any
  • writeAccess: Specifies whether to allow unsigned requests to write into this object. This property applies when using the accounts.setAccountInfo 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.
  • minDocVersion: The re-consent cut-off point. Users who consented to an earlier version of this consent statement will be requested to renew their consent.
  • legalStatements: A JSON object that contains a list of language-specific templates, which include:
    • The purpose of this consent statement
    • The documentUrl, which is a link to the PDF of the document to which the user is agreeing
  • customdata: an array of custom data objects, where each data set is comprised of a key-value pair. Both of these are strings.

    The maximum number of characters for the key is 20, and 256 for the value. The maximum number of custom key-value pairs per consent statement is 50. 

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

preferencesSchema: {
 "fields": {
   "tos": {
     "type: "consent",
     "required": "true",
     "format": "True",
     "currentDocDate: "2017-05-15T12:00:00Z",
     "minDocDate: "2017-01-01T00:00:00Z",
     "legalStatements": {
           "en": {
               "purpose": "This is my purpose",
               "documentUrl": "https://www.site.com/doc.pdf"
           },
           "fr": {
               "purpose": "This is my purpose",
               "documentUrl": "https://www.site.com/doc.pdf"
           },
     "writeAccess": "clientCreate"
   },
   "dataSharing.share_pii": {
     "type: "consent",
     "currentDocVersion: 2.1,
     "minDocVersion": 2.0,
     "writeAccess": "clientModify"
   },
   "dataSharing.share_anonymous": {
     "type: "consent",
     "currentDocVersion: 1.0
     "writeAccess": "clientModify"
   }
 }
}

 

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!
				description: "My Subscription",
				doubleOptIn: true
			}
        },
		"mySubscriptionTwo": {
            email: {
				type:"subscription",
				required: false
				description: "My Subscription",
				doubleOptIn: true
			}
        }
    }
}

Sample Requests

 

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 that is not always returned and should not be relied upon by your implementation.
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.