Happy Business Starts Here

Highlighted
Zuora Documentation

Advance notice of change to custom field support in the Zuora Swagger spec

On April 15 we will be improving the way our API Reference documents custom fields. This change should have minimal impact on the way the API Reference is presented, the Zuora Swagger spec file, and any code libraries generated after this change.

 

When we make the improvement, our API Changelog will detail the modifications to our Swagger spec. Please reply to this post if you have any questions or concerns before we make the changes. Thank you!

 

What is the current situation?

 

Our Swagger spec currently represents tenant-specific custom fields by placeholder fields called customField__c, which look like this in the API Reference:

 

custom_fields_current.png

 

The corresponding portion of our Swagger spec looks like this:

 

currency:
description: 'Currency used by the account. For example, `USD` or `EUR`.'
type: string
customField__c:
description: 'Any custom fields defined for this object. The custom field name is case-sensitive.'
type: string

 

What is going to change?

 

To better represent tenant-specific custom fields in our Swagger spec, we are planning to replace these placeholder customField__c fields by a dedicated model for each object type that supports custom fields.

 

For example, the custom fields model for Rate Plan Charge objects will be:

 

RatePlanChargeObjectCustomFields:
type: object
title: ratePlanChargeFieldsCustom
description: 'Container for custom fields of a Rate Plan Charge object.'
additionalProperties:
description: 'Custom fields of the Rate Plan Charge object. The name of each custom field has the form <code>*customField*__c</code>. Custom field names are case sensitive. See [Manage Custom Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields) for more information.'


The use of additionalProperties indicates that tenant-specific custom fields do not have predefined names.

  

The custom fields models will then be referenced in the appropriate places using allOf. For example:

 

GETSubscriptionRatePlanChargesType:
allOf:
- properties:
applyDiscountTo:
description: "[...]"
type: string
billingDay:
description: "[...]"
type: string

// Other fixed properties of the
// GETSubscriptionRatePlanChargesType model

type: object
- $ref: '#/definitions/RatePlanChargeObjectCustomFields'

 

After we have made this improvement, the API Reference will display “<Additional Properties> *” in locations that custom fields are supported. For example:

 

custom_fields_new.png

 

To make our request and response samples accessible to as many customers as possible, we are also planning to remove customField__c fields and other placeholder custom fields from our request and response samples.

 

How will the changes affect code library generation?

 

If you use swagger-codegen to generate code libraries from our Swagger spec, some classes in the code library currently have an attribute called custom_field__c (or similar, depending on the language of the code library). This attribute is not usable unless you have actually created a custom field in your Zuora tenant that is called customField__c.

 

After we make the changes to our Swagger spec, no classes in generated code libraries will have an attribute called custom_field__c. Classes corresponding to models that reference custom fields via allOf and additionalProperties (as explained above) will not have any attributes or methods related to custom fields. This is because additionalProperties has no effect in generated code libraries.

1 REPLY 1
Zuora Documentation

Re: Advance notice of change to custom field support in the Zuora Swagger spec

We are now planning to make these changes on, or shortly after, April 15. Please watch our API Changelog for further updates.