Description

The SaveSchema API allows the Account Owner to create or update a Schema. Documents can be created based on the Schema to take advantage of the validation and security that the Schema offers.

What is a Schema?

In apstrata, Schemas are used to define the kind of data you expect to store for a certain business entity, along with the validation and security rules, in a declarative way. You can think of a Schema as a template for business entities. For example, you might want to have an employee entity in your application. You can define a schema for that entity, specifying that first name, last name, age, and employment date represent the data to be collected by default for each employee. For each of these employee attributes, you can associate validation and security rules. Hence, a Schema provides a uniform way of dealing with employees. Note that employee attributes that are not defined in the schema can still be persisted as part of an employee Document; however, no specific validation or security rules can be applied to them. Such fields or attributes are called dynamic fields.

Apstrata does not enforce the use of Schemas. Alternatively, you can always persist data without specifying a Schema. In this case, no security or validation rules can be applied at the level of the fields. Note that "schema-less" Documents are actually Documents with a default Schema, which gets created for each account upon registration. The default Schema is not exposed, and hence cannot be customized. The default Schema is totally based on dynamic fields, implying that no field-level security or validation rules can be applied. This "schema-less" mode is meant for prototyping and experimenting purposes. We fully recommend that business applications be built in a "schema-full" mode.

Please refer to Document Schema Definitions or Saved Query Schema Definition to showcase a schema example as well as the schema syntax (XSD) that you should use to create your schemas.

For specific details on schema creation, please check the SaveSchema API.

See the Document Schema Definition or the Saved Query Schema Definition for all the schema options available.

A simple example schema:

< schema >
     < aclGroups >
          < aclGroup name="admin" >
               < read >userA< /read >
               < write >userB< /write >
               < fields >
                    < field >fieldone< /field >
               < /fields >
          < /aclGroup >
          < aclGroup name="users" >
               < read >userC< /read >
               < write >userD< /write >
               < fields >
                    < field >fieldtwo< /field >
               < /fields >
          < /aclGroup >
          < defaultAcl >
               < read >userA< /read >
               < write >userB< /write >
               < delete >userC< /delete >
          < /defaultAcl >
     < /aclGroups >
     < fields >
          < field name="fieldone" >
               < validation >
                    < regex >---regex validation---< /regex >
               < /validation >
          < /field >
          < field name="fieldtwo" type="numeric" searchable="true" >
               < validation >
                    < regex >thereg2< /regex >
                    < cardinality min="1" max="3" >< /cardinality >
                    < range min="1" max="3" >< /range >
               < /validation >
          < /field >
     < /fields >
< /schema >

Schema ACL: Set read, write, delete ACLs for a schema

The developer can create a schema and specify users or groups who can read/write/delete to it. Note the <schemaACL>s:

< schema >
    < aclGroups >
     < aclGroup name="aclGroup1" >
         < read >user1;user2< /read >
         < fields >
             < field >field1< /field >
             < field >picture< /field >
         < /fields >
     < /aclGroup >
     < defaultAcl >
         < read >all< /read >
         < write >all< /write >
     < /defaultAcl >
     < schemaAcl >
         < read >user1;user2;group:group1< /read >
         < write >user1;user2;group:group1< /write >
         < delete >user1;user2;group:group1< /delete >
     < /schemaAcl >
< /aclGroups >
< fields >
     < field name="field1" type="string" / >
     < field name="picture" type="file" / >
< /fields >
< /schema >

If the user is not within the schema ACL, getSchema, and saveSchema (over existing schemas) will fail and trigger a permission denied error. Note that the user is responsible for managing the schema ACL and that schema ACLs are required. Schema ACLs can be set using predefined ACL identifiers:

1. creator, meaning the creator of the document can read/write from/to existing documents (<read>creator</read>).

2. anonymous, anyone can read/write from/to existing documents (<read>anonymous</read>)

3. authenticated-users, only authenticated users will have access

4. nobody, no one can read/write from/to existing document. Owner on the other side will have access even if ACL is set to "nobody"

Versioning

< schema versioning="disabled" >
    < aclGroups >
     < aclGroup name="aclGroup1" >
         < read >user1;user2< /read >
         < fields >
             < field >field1< /field >
             < field >picture< /field >
         < /fields >
     < /aclGroup >
     < defaultAcl >
         < read >all< /read >
         < write >all< /write >
     < /defaultAcl >
     < schemaAcl >
         < read >user1;user2;group:group1< /read >
         < write >user1;user2;group:group1< /write >
         < delete >user1;user2;group:group1< /delete >
     < /schemaAcl >
< /aclGroups >
< fields >
     < field name="field1" type="string" / >
     < field name="picture" type="file" / >
< /fields >
< /schema >

Document versioning can be set at the schema level. Versioning can be "disabled", "enabled", or "forced" and will affect documents of the schema. If not specified, versioning will be disabled. Please refer to the SaveDocument documentation for more details.

Schema Validation

The schema sent by the user should conform to the xsd. Further restrictions include:

1. All ACLs should be of the form ((group:){0,1}[0-9A-Za-z-_]{1,128}(;){0,1})*

2. Minimum cardinality should always be less than or equal to maximum cardinality.

3. Minimum range should always be less than or equal to maximum range.

4. Range validation can be only applied to fields of type numeric.

5. Duplicate fields are not allowed.

6. Duplicate aclGroups are not allowed.

7. All fields should belong to an aclGroup.

Specific Request Parameters

(Refer to Common Request Parameters)

Name	Description	Required	Default	Possible Values
apsdb.schemaName	Represents the full schema name that can consists of up to 5 folders and the schema file name separated by the character '/'. e.g., application/provisioning/user/profile In the example above the profile schema is saved under the three folders application > provisioning > user	Yes		The same set of rules applies to a schema name and a directory name: Must begin with an alphabetic character. Must end with an alphanumeric character or underscore (_). Can contain alphanumeric characters, underscores (_) and periods (.). Cannot have two or more consecutive periods. Note: the full schema name including any folders must be minimum 3 characters and maximum 64 characters long.
apsdb.schema	Represents the schema xml (content)	No
apsdb.update	Should be set in order to update existing schema	No
apsdb.default	If apsdb.default is set to true, the parameter apsdb.schema should not be sent. If it is, an error occurs.	No	False	True False
apsdb.newSchemaName	This is sent when the user wishes to rename the schema. Note that users are not allowed to rename a schema if there are documents using it.	No

Specific Response Elements

(Refer to Common Response Elements)

Specific Logical Errors

(Refer to Common Logical Error Codes)

Error	Message	Status Code
SCHEMA_IN_USE	The schema is being used, please delete all the documents using this schema before updating it.	400
DUPLICATE_SCHEMA_NAME	Schema already exists, please choose another name.	400
SCHEMA_NOT_FOUND	The schema sent in the request is not found.	404
INVALID_SCHEMA_NAME	Invalid schema name [schemaName].	400
INVALID_XML	Error parsing XML.	400
PARAMETER_REQUIRED		400

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/SaveSchema?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsdb.schemaName = [schema_name]
apsdb.schema = [schema_xml_definition]
apsdb.update = [true|false]
apsdb.default = [true|false]

Sample XML Response

Success XML:

< response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd" >
    < metadata >
        < requestId >xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx< /requestId >
        < status >success< /status >        
    < /metadata >
< /response >

Failure XML:

< response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd" >
    < metadata >
        < requestId >xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx< /requestId >
        < status >failure< /status >
        < errorCode >[errorCode]< /errorCode >
        < errorDetail >[failMsg]< /errorDetail >
    < /metadata >
< /response >

Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "success"
  }
}}

Child pages

SaveSchema