Introduction

What is ZEST Specification (ZSPEC)?

ZSPEC - ZEST Specification file is an XML file with pre-defined XML schema (XSD). It is the super-set of OpenAPI 3.0.i.e ZEST has all the supports that Open API 3.0 provides.

Creating the ZSPEC - ZEST Specification file is the crucial and mandatory step to use ZEST as the configurations lay the base for its constituents (source codes & SDKs generation, automation testing and help documentation).

Why ZSPEC?

ZSPEC is the superset of OpenAPI 3.0. In additon to the supports of OpenAPI 3.0 , ZSPEC provides the following supports in Properties/Keys.

1.1. Enable automated quality check using ‘Extra Value Validation’

Use Case

Consider a field Department with the list of possible values as “Mechanical”, “Electronics” and “Computer Science”.

Scenario 1: Permit the new value

When the user enters a value “Civil” (other than these three values), the requirement is to allow the new value. Here the requirement is to allow additional values for the field Department.

---

Scenario 2: Deny the new value

When the user enters a value “Civil” (other than these three values), the requirement is to deny the new value. Here the requirement is to deny additional values for the field Department and show error.

---

Scenario 3: Assign a default value

When the user enters a value “Civil” (other than these three values), the requirement is to assign a default value. Here the requirement is to ignore the new value and assign a default value for the field Department and show error.

In these scenarios, the requirement is to handle additional values for the field Department and all these can be achieved using ZEST Specification Format but not using OpenAPI3.0.

ZSPEC enables you to handle additional values for a particular property. The possible values are map-default, deny and allow.

1.2. Achieve Tailored API Interactions using ‘Conditional Requests and Responses’

A. Condition for Request

Use Case

Consider the fields Country, Postal Code and Zip Code. The requirement is

• Whenever the Country is “India”, then you have to construct the request body with Postal Code and
• Whenever the Country is “US”, then you have to construct the request body with Zip Code.

Here the requirement is to construct request body based on the value of Country.
This use case can be achieved using ZEST Specification Format but not using OpenAPI3.0.

ZSPEC enables you to construct the body of the request based on custom criteria.

B. Condition for Response

Use Case

Consider the fields Country, Postal Code and Zip Code. The requirement is

• If the Country is “India”, then you need to validate whether the response has Postal Code and
• If the Country is “US”, then you need to validate whether the response has Zip Code

Here the requirement is to validate the response based on the value of the country. This use case can be achieved using ZEST Specification Format but not using OpenAPI 3.0.

ZSPEC enables you to validate the response to match the criteria.

1.3. Ensure Data Integrity with ‘Invalid Value Validation’

Use Case

Consider the field “Username” in a SignUp Form. Let’s say you have defined the following criteria for valid usernames

• Should be unique
• Minimum length should be 9
• Should not begin with special characters

Scenario 1: Assign a default value

If the username doesn’t meet these criteria, the requirement is to assign an auto-generated username that meets your criteria. Here the requirement is to assign a default value to the field Username.

---

Scenario 2: Deny the value

If the username doesn’t meet these criteria, the requirement is to deny the value. Here the requirement is to deny the value that does not meet your criteria.

In the above scenarios, there is a need to check if the values are as per your criteria and handle by assigning a default value or denying the value. This use case can be achieved using ZEST Specification Format but not using OpenAPI3.0.

ZSPEC enables you to handle values that do not satisfy your criteria by assigning a default value or denying the value.

1.4. Effortless Data Retrieval using ‘DataPath Property’

Use Case

In Zoho CRM, there are a set of standard modules along with the custom modules that every account has. While handling an API lets say you want to fetch the list of API names of all modules. Here the requirement is to pick values from a particular path. This use case can be achieved using datapath= $.modules.API_Name in the ZEST Specification Format.

ZSPEC enables the API to fetch the values from a specified path.

1.5. Achieve data completeness ‘Emptiable Property’

Use Case

Consider an organization ABC. Every employee will have an Employee ID. You don’t want to allow empty values in this field. Here the requirement is to deny empty values in the field Employee ID. This use case can be achieved using ZEST Specification Format but not using OpenAPI 3.0.

You can allow or deny empty values in all requests and responses of an API.

1.6. Maintain data distinction with ‘Unique Property’

Use Case

Consider an organization ABC. Every employee will have an Employee ID.You don’t want to allow duplicate values in this field. Here the requirement is to deny duplicate values in the field Employee ID. This use case can be achieved using ZEST Specification Format but not using OpenAPI 3.0.

You can define whether values in all requests and responses of an API should be unique or not.

1.7. Customize validation using ‘Include-for Property’

Use Case

Consider the field “email” in a SignUp Form. The requirement is that you want to perform validation of email only during the account creation operation. However, during other operations like updating customer details, email validation is not required. Here you want to enable the validation for email only during create operation of REQUEST. This use case can be achieved using ZEST Specification Format but not using OpenAPI 3.0.

Using ZSPEC, you can perform validations only for specific operations of request or for specific operations of response.

1.8. Fortify your API’s structure with ‘Additional Property Name and Value Validation’

Use Case

Consider a scenario similar to Variables in CRM. The requirement is to restrict the maximum length of the name to 15 and the value to 50. Here the requirement is to allow additional variables but imposing restrictions to the length of the value these variables hold.

Using ZSPEC, you can allow additional properties and add constraints to the name and value these properties hold.

2. Resource Config

Use Case

Consider an organization ABC. Every employee will have an Employee ID. You want to set this field as the primary field.Here the requirement is to define the Employee ID as the primary property. This use case can be achieved using ZEST Specification Format but not using OpenAPI 3.0.

You can define the primary properties for your resource using this element.

3. Path config

Use Case

Consider an e-commerce platform which has a primary key for every product as “Product ID”. Overtime, this platform collaborates with third party vendors also. Now overriding the primary key definition is necessary. So the requirement is that the “VendorProductID” column should be the primary field for the third party products. Here you want to override the primary properties defined in the resource config. This can be achieved using the ZEST Specification format.

ZSPEC allows you to define the primary properties for your resource using this element. You can also override the primary properties that you have defined in the resource config and mention its path.

4. Error Condition

Use Case

Consider the field Location in a weather data API. The requirement is that if the location is not found in the database, you want to define the response as an error response. Here you want to define the error condition for an API. This can be achieved using the ZEST Specification format and not using Open API 3.0.

Using ZSPEC you can define the condition that makes the response of the API an error using this property.