Property

It is the functional unit of ZSPEC. It has the details of keys in argument / request / response.

Possible Location

Structure

Child Elements

Deprecate
Description
XML Format
File Meta
Ordered Structures
Structure or Structure Group or Composite Structure Groups
Extend Property recurrent

Attributes

Name	Type	Description
name required	String	Name of the property. This name is mandatory if you add more than one property to a structure.
type required	String	Data type of the property. Click here to get the list of possible data types.
content-types	String (CSV)	The content type of the particular structure created for the property. Click here for samples.
values	String (CSV)	Possible value(s) of the property.
default-value	String	Default value of the property.
extra-value	String (enum)	Decides whether the property should accept extra values other than the list of possible values. The possible values of this attribute are - allow, deny, map-default. The default value is deny. Click here for more details and samples.
invalid-value	String (enum)	Behavior of the property when invalid values are provided (a value that does not satisfy the criteria provided in the attributes of property). The possible values are deny and map-default. The default value is deny. Click here for more details and samples.
example-value	String	Example value of the property which will be published in the API help document. The example configured at the <content> level is given the higher priority and will be published in the help document. If it is not configured in the content, all the example-values of different properties will be grouped together and added to the help document.
regex	String	The regex pattern to which the value of the property should match.
length	String (CSV)	The minimum and maximum possible length/size of the property value like length="0,10". You can also opt to configure only the maximum length/size. Click here to get the list of possible types.
path	String	Data path from which the data must be fetched. Click here for samples and to learn more about data path construction, check here.
include-for	String (enum)	Decides in which categories of request and response, the property has to be included. The format of this attribute is *Request[list of categories (CSV)], Response[list of categories (CSV)]. The possible categories are read, create, update, delete* and action. Click here for more details and samples.
required-for	String (enum)	Represents whether the property has to appear in request / response. The possible values are none, all, request, response. The default value is none. Click here for more details and samples.
nullable-for	String (enum)	Denotes whether the property can be null in the request / response. The possible values are none, all, request, response. The default value is none. Click here for more details and samples.
unique-for	String (enum)	Decides whether the value of the property should be unique in request / response. The possible values are none, all, request, response. The default value is none. Click here for more details and samples.
emptiable-for	String (enum)	Represents whether the property can be empty values in request / response. The possible values are none, all, request, response. The default value is none. Click here for more details and samples.
condition-for-request	String	The condition based on which the request body should be constructed. Click here for samples and to learn more about conditions, see here.
condition-for-response	String	The condition to which the response should match. Click here for samples and refer to this document for additional details about conditions.
condition-for-all	String	The common condition to which the request and response should match. Click here for sample and refer to this document for additional details about conditions.
value-condition	String	The condition up on which the value of the property should be constructed. Click here for samples and check this document for the construction of conditions.
range	String	Range of values. For example range="0,99999" for Integer type and range="A-Z" for string.
format	String	Date and Date Time formats of the value. The default format is "yyyy-MM-dd'T'HH:mm:ss+/-hh:mm". Click here for more details.
decimal-place	Integer	The number of allowed decimal places. This is applicable only when the property is of type double. If decimal-place="2" , will allow 2 digits after the decimal point.
visibility	String (enum)	Decides who can view and use the element. The possible values are internal, private, public. The default value is public.

Note:

When “map-default” is specified for either extra-value or invalid-value attributes, the value mentioned in the “default-value” will be used. If default value is not provided, then it will be null.
<left-operand><relational-operator><right-operand> is the syntax of any condition in ZSPEC. In value-condition attribute, the left operand is the specified property by default. So, the condition will start with the relational operator.

Content Types

The content type of a particular <structure> created for the property.

Let us say that we have a property called travelogue in the destinations resource, which contains the comprehensive details about the destination and places to explore. You want the blog content to be given only in the HTML format. Here is a sample JSON in which the HTML content will be received in the key.

For example,

    
        copy
        
            
        
    
    
         
{
    "destinations": [
        {
            "travelogue": " Paris, often called the City of Love or the City of Light, is a captivating metropolis in France.
Known for its timeless art, enchanting architecture, and delectable cuisine, Paris is a destination like no other.
 From the iconic Eiffel Tower to the world-class Louvre Museum, this city is a treasure trove of history and culture.
 Wander through charming streets, enjoy croissants at a local café, or take a romantic Seine River cruise.
 Paris is a place where history, art, and romance converge, making it a must-visit for every traveler."
        }
    ]
}

Now, use the content-types attribute in this property as shown below to provide the content in HTML format,

    
        copy
        
            
        
    
    
         
<property name="travelogue" type="string" content-types="text/html" />

Extra Values

Using this attribute, you can decide whether the property should accept extra value other than the list of possible values provided in the values attribute.

For example, we have the following property in the trips resource.

    
        copy
        
            
        
    
    
         
<property name="transport_medium" type="string" values="Roadways,Airways,Waterways" />

Let us configure different behaviors for this property using the extra-value attribute.

Allow

Consider that you want to allow extra value to the above property.

    
        copy
        
            
        
    
    
         
<property name="transport_medium" type="string" values="Roadways,Airways,Waterways" extra-value="allow" />

Deny

You does not want to allow any extra values to the property.

    
        copy
        
            
        
    
    
         
<property name="transport_medium" type="string" values="Roadways,Airways,Waterways" extra-value="deny" />

Map Default

You have declared a default value for the property and want to map it whenever an extra value is provided. So, you have to specify it as follows,

    
        copy
        
            
        
    
    
         
<property name="transport_medium" type="string" values="Roadways,Airways,Waterways" extra-value="map-default" default-value="Roadways"/>

Invalid Value

It helps in defining the behavior of the property when invalid values are provided (a value that does not satisfy the attributes that define the property).

Let us take the following <structure> from the trips resource and configure different values for the invalid-value attribute for the ease of understanding.

    
        copy
        
            
        
    
    
         
<structure>
    <property name="accommodation_type" type="string" values="Hotel,Resort,Vacation Rental,Hostel" />
</structure>

Deny

If the values for the property violate the data type or the possible values, you want to deny the value.

    
        copy
        
            
        
    
    
         
<property name="accommodation_type" type="string" values="Hotel,Resort,Vacation Rental,Hostel" invalid-value="deny" />

Map Default

To map a default value when invalid values are provided for the property, you have to declare one of the possible values as a default value and use this attribute as,

    
        copy
        
            
        
    
    
         
<property name="accommodation_type" type="string" values="Hotel,Resort,Vacation Rental,Hostel" invalid-value="map-default" default-value="Hotel" />

Length

The length attribute restricts the value(s) of a property in terms of characters for all data types except collections, map, and file. In the case of maps, it functions in terms of the number of key-value pairs within it, and for collections, it operates in terms of the number of map properties within it. Regarding the file datatype, the length attribute controls the number of files that can be uploaded.

String

You want the minimum length of the string to be 5 and the maximum length to be 10 in the trips resource. This should be written as,

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" length="5,10" />

If you want to declare only the maximum length of the string, then it should be written as follows:

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" length="50" />

If you want to declare only the minimum length of the string, then it should be written as follows:

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" length="5,-1" />

Map

Imagine that we have used the <extra-property> in trips resource, to let the users add custom properties that describe their personal requirements for the trip. But, you want to limit the number of custom properties to 2.

For example, the default properties contribute 3 key-value paris and you further accept only 2 custom key-value pairs. Thus, the map property of the trips resource will accept 5 key-value pairs in total.

Now, you have to write the map property of the trips resource as follows,

    
        copy
        
            
        
    
    
         
<structure>
    <property type="map" length="5">
        <structure>
            <property name="trip_name" type="string" />
            <property name="travelers" type="collections">
                <structure>
                    <property name="string" />
                </structure>
            </property>
            <property name="destination" type="string" />
            <extra-property name-regex="^custom-[a-z]+$" type="object" />
        </structure>
    </property>
</structure>

Collections

Assume we want a collection property in the trips resource to have a minimum of 3 values while remaining open to accepting as many values as users provide. To obtain this requirement, you have to use the length attribute as follows,

    
        copy
        
            
        
    
    
         
<property name="adventure_activities" type="collections" length="3,-1">
    <structure>
        <property type="string" />
    </structure>
</property>

File

Imagine that we have a file property in the travelers resource, to which you want to restrict the number files that a user can upload. For this case, you have to use the length attribute as follows,

    
        copy
        
            
        
    
    
         
<property name="id_proofs" type="file" length="3">
    <file-meta size="500,1500" overall-size="6000" import-url="false" continue-on-error="true">
        <extension name="png" size="500,1000" length="2"/>
        <extension name="jpg" length="1"/>
        <file-name regex="^[^\"0-9]+$" length="5,10" />
    </file-meta>   
</property>

Path

The path attribute aids in fetching data from a different resource. This data will be used as the possible values of the specified property. The provided data path will help in narrow downing the resource’s data to the desired key. To learn more about data path, check here.

Without condition

In the trips resource, we have a property called destination whose possible values are the destination_name specified in the the destinations resource. Now, the travelers property has to be written as shown here,

    
        copy
        
            
        
    
    
         
<property name="destination" type="string" path="destinations:$.destination_name" />

With condition

Consider that we have a property called accommodation in the trips resource for which the possible values are the accommodation_name from the accommodation resource. You want to further filter the possible values only with accommodations those have available rooms.

For this property, you have to write the data path as,

    
        copy
        
            
        
    
    
         
<property name="accommodation" type="string" path="accommodations:$.{rooms=='Available'}.accommodation_name" />

This condition fetches the name of the accommodations, whose rooms property is ‘Available’. To learn more about constructing conditions, refer to this document.

Include For

By default, the property will be included in both request and response of all five categories (read, create, update, delete and action). If you want to include the property only in specific categories, use the Request[list of categories (CSV)], Response[list of categories (CSV)]. The property will be excluded for the remaining categories that are not mentioned in the format.

To include all the categories, you can either use an asterisk(*) in the place of list of categories, or you can opt to not specify the request / response format. For example, Request[*], Response[create,update] and Response[create,update] mean the same that is the property has to be included in all the categories of request and only create, update categories of response. To exclude all the categories, specify an empty array([]) in the request / response based on your requirement.

Now, consider that we have a property called trip_name in the component <structure> of trips resource.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" />

The structure of this property will be used for both request and response in all the five categories. Let us see, how we can use this attribute to achieve various requirements.

Specific categories in both

Say that you do not want this key to appear in the request body of update, delete and action. In the response body, you do not want the key to appear for read and create categories. So, you have to specify only the corresponding categories in which the key has to appear.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[read,create], Response[update,delete,action]" />

All categories in both

You want this key to appear in the request and response body of all the five categories.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[*], Response[*]" />

— or —

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" />

Only in response categories

You want this key to appear only in the response body of read and create categories. It should not appear in the request body of any categories.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[], Response[read,create]" />

Only in request categories

You do not want this key to appear in the response body of any categories. It should appear only in the request body of update and action categories.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[update,action], Response[]" />

Specific categories in request and all categories in response

You want this key to appear in the response body of all categories and the request body of update and create categories.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[update,create], Response[*]" />

— or —

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[update,create]" />

Specific categories in response and all categories in request

You want to include this key in the request body of all categories and the response body of update and create categories.

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Request[*], Response[update,create]" />

— or —

    
        copy
        
            
        
    
    
         
<property name="trip_budget" type="integer" include-for="Response[update,create]" />

Required For

This attribute decides the appearance of a property in the request / response of a resource.

Consider that we have a property called trip_name in a component <structure>.

    
        copy
        
            
        
    
    
         
<property name="no_of_days" type="integer" />

The structure of this property will be used for both the request and response of the planets resource.

Request

You want the property to appear only in the request body. This will not affect the old records in which the key was optionally visible in the request.

    
        copy
        
            
        
    
    
         
<property name="no_of_days" type="integer" required-for="request" />

Response

You want to make the key appear only in the response. The new records may or may not have the key in the request body depending on the use case.

If the key was not specified in the request body of the new records, then in response, this key will appear and will have either null value or the default value (as provided).

    
        copy
        
            
        
    
    
         
<property name="no_of_days" type="integer" nullable-for="response" required-for="response" />

All

You want the key to appear in both the request and response body.

    
        copy
        
            
        
    
    
         
<property name="no_of_days" type="integer" required-for="all" />

None

You do not want the key to compulsorily appear in both request and response body. So, the keys will appear only if they have values.

    
        copy
        
            
        
    
    
         
<property name="no_of_days" type="integer" type="string" required-for="none" />

    
        copy
        
            
        
    
    
         
<property name="no_of_days" type="integer" />

Nullable For

It helps in deciding whether a property can be null in the request and response body.

Consider that we have the following component <structure> in the trips resource which you use for both request and response.

    
        copy
        
            
        
    
    
         
<structure>
    <property name="traveler_email" type="string" />
</structure>

Let us try to assign different behaviors for this property based on null values.

Request

You want to allow null value for the above property in request.

    
        copy
        
            
        
    
    
         
<property name="traveler_email" type="string" nullable-for="request" />

Response

You decide that the property may contain null values in the response but should not accept null values in the request.

    
        copy
        
            
        
    
    
         
<property name="traveler_email" type="string" nullable-for="response" />

All

You want to accept null values for the property in both request and response.

    
        copy
        
            
        
    
    
         
<property name="traveler_email" type="string" nullable-for="all" />

None

You do not want the property to accept null values in both request and response.

    
        copy
        
            
        
    
    
         
<property name="traveler_email" type="string" nullable-for="none" />

Unique For

This attribute will help you to specify whether a property should have unique value in the request and response body.

Consider that we have the following <structure> in the trips resource. The same structure will be used for both the request and response.

    
        copy
        
            
        
    
    
         
<structure>
    <property name="trip_name" type="string" />
</structure>

Now, we will configure the same property with different unique-for attribute values to execute different behaviors of the property.

Request

You want the property value to be unique in the requests.

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" unique-for="request" />

Response

You want to maintain unique values for the property in the response.

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" unique-for="response" />

All

You do not want to allow any duplicate values for the property in both request and response.

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" unique-for="all" />

None

You want to allow duplicate values in both request and response for the property.

    
        copy
        
            
        
    
    
         
<property name="trip_name" type="string" unique-for="none" />

Emptiable For

Use this attribute to decide whether a property should contain empty value in the request and response body of the resource.

Consider the following component <structure> from the trips resource which will be used for both the request and response.

    
        copy
        
            
        
    
    
         
<structure>
    <property name="destination" type="string" />
</structure>

Let us configure different behaviors of the property based on empty values.

Request

You want to allow the destination property to be left unfilled in the request.

    
        copy
        
            
        
    
    
         
<property name="destination" type="string" emptiable-for="Request" />

Response

You want the property to show empty values in the response, if the user has provided it.

    
        copy
        
            
        
    
    
         
<property name="destination" type="string" emptiable-for="Response" />

All

You have decided that the property can carry empty values in both request and response.

    
        copy
        
            
        
    
    
         
<property name="destination" type="string" emptiable-for="all" />

None

You have decided not to accept any empty values in the property.

    
        copy
        
            
        
    
    
         
<property name="destination" type="string" emptiable-for="none" />

Condition For Request

It holds the condition based on which the request body should be constructed.

There are a couple of fields in the trips resource - transport_medium and hybrid_details. In the request body, the hybrid_details key has to appear only when the value of transport_medium is ‘Hybrid’.

So, you need to construct the condition for the request body based on the value of transport_medium.

    
        copy
        
            
        
    
    
         
<request-body>
    <content>
        <encode type="application/json"/>
        <structure>
            <property name="transport_medium" type="string" values="Roadways,Airways,Waterways,Hybrid"/>
            <property name="hybrid_details" type="string" condition-for-request="REQUEST:$.body.transport_medium == 'Hybrid'"/>
        </structure>
    </content>
</request-body>

Condition For Response

This attribute contains the condition to which the response should match.

For the same properties as discussed in the above sample, the hybrid_details key has to appear in the response only when the value of transport_medium is ‘Hybrid’.

Following is how you need to configure this using condition,

    
        copy
        
            
        
    
    
         
<response>
    <content>
        <encode type="application/json"/>
        <structure>
            <property name="transport_medium" type="string" values="Roadways,Airways,Waterways,Hybrid"/>
            <property name="hybrid_details" type="string" condition-for-response="RESPONSE:$.body.transport_medium == 'Hybrid'"/>
        </structure>
    </content>
</response>

Condition For All

It has the common condition to which the request and response should match.

Let us take the above two scenarios discussed for the condition-for-response and condition-for-request. Despite the response or request, the hybrid_details key has to appear only when the value of transport_medium is ‘Hybrid’.

For requirements like this, you need not write two conditions in the property. Instead you can easily declare them using the condition-for-all attribute as follows,

    
        copy
        
            
        
    
    
         
<structure>
    <property name="transport_medium" type="string" values="Roadways,Airways,Waterways,Hybrid"/>
    <property name="hybrid_details" type="string" condition-for-all="$.body.transport_medium == 'Hybrid'"/>
</structure>

Value Condition

Using this attribute, you can set conditions which has to be satisfied to provide value for the respective property. You need not provide the left operand because, the left operand is the property in which you are specifying the value-condition.

In the trips resource, you have a couple of fields that denotes the start and end time of the trip. The end time of the trip should always be greater than the start time.

Here is how you have to write the property for the end_time with condition,

    
        copy
        
            
        
    
    
         
<property name="end_time" type="datetime" format="yyyy-MM-dd'T'HH:mm:ss+/-hh:mm" value-condition=">REQUEST:$.body.start_time" />

In this condition, left operand is the specified property by default. So, the condition starts with the operator.

Format

You can use the following symbols in your formatting pattern:

Symbol	Description
G	Era designator (before christ, after christ)
y	Year (e.g. 12 or 2012). Use either yy or yyyy
M	Month in year. Number of M’s determine length of format (e.g. MM, MMM or MMMMM)
d	Day in month. Number of d’s determine length of format (e.g. d or dd)
h	Hour of day, 1-12 (AM / PM) (normally hh)
H	Hour of day, 0-23 (normally HH)
m	Minute in hour, 0-59 (normally mm)
s	Second in minute, 0-59 (normally ss)
S	Millisecond in second, 0-999 (normally SSS)
E	Day in week (e.g Monday, Tuesday etc.)
D	Day in year (1-366)
F	Day of week in month (e.g. 1st Thursday of December)
w	Week in year (1-53)
W	Week in month (0-5)
a	AM / PM marker
k	Hour in day (1-24, unlike HH’s 0-23)
K	Hour in day, AM / PM (0-11)
z	Time Zone
'	Escape for text delimiter
'	Single quote

Pattern

Here are a few Java SimpleDateFormat date pattern examples.

Pattern	Example
dd-MM-yy	31-01-12
dd-MM-yyyy	31-01-2012
MM-dd-yyyy	01-31-2012
yyyy-MM-dd	2012-01-31
yyyy-MM-dd HH:mm:ss	2012-01-31 23:59:59
yyyy-MM-dd HH:mm:ss.SSS	2012-01-31 23:59:59.999
yyyy-MM-dd HH:mm:ss.SSSZ	2012-01-31 23:59:59.999+0100
EEEE MMMMM yyyy HH:mm:ss.SSSZ	Saturday November 2012 10:45:42.720+0100

Type

The possible data type values are,

object
string
integer
long_string
long
float
double
serial
boolean
date
time
datetime
timezone
collections
map
password
byte
binary
file
array

Last Updated 2025-05-30 16:54:59 +0530 +0530

Yes

Thank you for your feedback!

Send your feedback to us

Skip

Submit