Structure

This element acts as a wrapper for <property> and signifies the structural information of the request / response / argument bodies.

Possible Locations

• Components
• Content
• Structure Group
• Property

Child Elements

• Deprecate
• Property recurrent
• Extra Property recurrent

Attributes

Name	Type	Description
name	String	Name of the structure. This name will be used for the spring source models and will get reflected in the help document. The value need not be unique since, we will be using so many structures for a resource. Refer to the note for more information.
ref-name	String	A unique name to refer the current structure in other places of either the same or different ZSPEC. The purpose of this attribute is completely for the internal use of referring the structure across the product. Click here for more details.
discriminator-name	String	Value of the discriminator key based on which the desired structure should be picked. Click here for more details.
extend	String	Holds the value of the structure's ref-name which you are trying to extend. Click here for more details.
cases	String (enum)	Name of the case, for which you are configuring a specific structure. In automation, test cases are executed to verify if they return the specified structure as configured. Click here for more details about this attribute and the list of possible test cases in ZEST.
lookup	String	Name of the resource to which the properties of the structure point.
visibility	String (enum)	Decides who can view and use the element. The possible values are internal, private, public. The default value is public.

Samples

Ref Name

Within same resource

Consider in the trips resource, you want to use a structure in multiple places. Your very first step for this requirement is to add the structure under <components> with the ref-name attribute as shown here.

    

        
copy
        

            

        
    
    

         
<components>
    <structure ref-name="trips_data" name="trips">
        <property name="trip_name" type="string"/>
        <property name="trip_budget" type="integer"/>
        <property name="no_of_days" type="integer"/>
        <property name="start_time" type="datetime"/>
        <property name="end_time" type="datetime"/>
    </structure>
</components>


    

Now, whenever you want to use the above structure, just use the value of ref-name in the place of name attribute of <structure-ref>.

    

        
copy
        

            

        
    
    

         
<structure-ref name="trips_data" />

    

Across different resources

Imagine you want to use a structure from the destinations resource in the trips resource. For this requirement, you should follow the following format while referring to that structure.
<structure-ref name="{resource-name}.{component-name}" />

Following is a structure in the <components> of destination resource,

    

        
copy
        

            

        
    
    

         
<components>
    <structure ref-name="quick_view" name="external_resource_use">
        <property name="destination_name" type="string" />
        <property name="rating" type="integer" range="1,10" />
        <property name="tourist_spots" type="file" length="5">
            <file-meta size="500,1500" overall-size="6000" import-url="false" continue-on-error="true">
                <extension name="png" size="500,1000" length="3"/>
                <extension name="jpg" length="2"/>
                <file-name regex="^[^\"0-9]+$" length="5,10" />
            </file-meta>
        </property>
        <property name="travelogue" type="string" content-types="text/html" />
    </structure>
</components>


    

To use the above structure in the trips resource, write the name attribute as follows:

    

        
copy
        

            

        
    
    

         
<structure-ref name="destinations.quick_view" />


    

---

Discriminator Name

Utilize the discriminator-name attribute when defining a new structure. The <discriminator> specified in a <structure-group> functions based on the map details provided in this attribute.

These structures can also be declared in the <components>, facilitating their use in a different resource. This minimizes the effort of manually associating values to their respective structures every time you use a discriminator.

In the trips resource, we provide two services - Flight and Accommodation services for customers. Depending on the chosen service, we need to assign a specific structure. Following is a sample created using the discriminator-name for this scenario,

    

        
copy
        

            

        
    
    

         
<property name="service" type="map">
    <structure-group name="services" type="one-of">
        <structure name="flight" discriminator-name="Flight">
            <property name="flight_no" type="string" />
            <property name="departure_airport" type="string" />
            <property name="arrival_airport" type="string" />
        </structure>
        <structure name="accommodation" discriminator-name="Accommodation">
            <property name="hotel_name" type="string" />
            <property name="check_in_date" type="string" />
            <property name="check_out_date" type="string" />
        </structure>
        <discriminator property-name="type" /> <!-- discriminator property not included in structure -->
    </structure-group>
</property>


    

---

Extend

This attribute allows you to override the <property> of an existing structure. The overriding is done using the property’s name attribute, so you can override all other attributes of a property except the name attribute. Additionally, you can add as many new properties as needed to the existing structure.

Assume that in the trips resource, we have the following structure,

    

        
copy
        

            

        
    
    

         
<structure ref-name="trips" name="trips_data">
    <property name="trip_name" type="string" />
    <property name="travelers" type="string" />
    <property name="trip_budget" type="integer" />
    <property name="no_of_days" type="integer" />
</structure>


    

Adding property

Now, you want to add an additional <property> to the above structure. To achieve this, you have to extend the existing structure and define that one more property in the following way.

    

        
copy
        

            

        
    
    

         
<structure name="new_keys" extend="trips">
    <property name="destination" type="string"/>
</structure>

    

You can add as many new properties as you want, using this extend attribute.

Overriding property

For the same structure, you want to change the data type of the no_of_days <property> from integer to string. So, extend the structure and override the data type of that property as shown here.

    

        
copy
        

            

        
    
    

         
<structure name="new_keys" extend="trips">
    <property name="no_of_days" type="string" />
</structure>


    

Adding and overriding properties

In the same structure, now you want to change the data type of the travelers <property> from string to collection and add a new property to the structure. So, you have to extend the structure as follows,

    

        
copy
        

            

        
    
    

         
<structure name="new_keys" extend="trips">
    <property name="travelers" type="collection">
        <structure>
            <property type="string" />
        </structure>
    </property>
    <property name="accommodation_type" type="string" values="Hotel,Resort,Vacation Rental,Hostel"/>
</structure>


    

---

Cases

Consider that we have two structures in the trips resource. For MandatoryParam case in automation, you want to configure the ParameterMissing structure and InvalidParameter structure for InvalidParam case.

Now, use the cases attribute in the structures as follows,

    

        
copy
        

            

        
    
    

         
<structure-group type="one-of">
    <structure name="ParameterMissing" cases="MandatoryParam">
        <property name="code" type="string" values="REQUIRED_PARAM_MISSING"/>
        <property name="status" type="string" values="error"/>
        <property name="message" type="string" values="one of the expected parameter is missing"/>
        <property name="details" type="map">
            <structure name="Details">
                <property name="param_name" type="string"/>
            </structure>
        </property>
    </structure>
    <structure name="InvalidParameter" cases="InvalidParam">
        <property name="code" type="string" values="INVALID_DATA"/>
        <property name="status" type="string" values="error"/>
        <property name="message" type="string" values="the given param is invalid"/>
        <property name="details" type="map">
            <structure name="Details">
                <property name="param_name" type="string"/>
            </structure>
        </property>
    </structure>
</structure-group>


    

To learn more about grouping of structures and the type attribute used in this sample, refer to the <structure-group>.