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:
The corresponding portion of our Swagger spec looks like this:
description: 'Currency used by the account. For example, `USD` or `EUR`.'
description: 'Any custom fields defined for this object. The custom field name is case-sensitive.'
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:
description: 'Container for custom fields of a Rate Plan Charge object.'
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:
// Other fixed properties of the
// GETSubscriptionRatePlanChargesType model
- $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:
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
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
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.
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.