When I run...

civix generate:api foo bar

...civix generates the following code:

function _civicrm_api3_foo_Bar_spec(&$spec) {
  $spec['magicword']['api.required'] = 1;

From this example, I can see how to make fields required when writing APIs. Cool. But what else can I do with this $spec array? Can I set default values? Can I indicate what type of value to accept? Can I specify an array of valid values? Or a regex pattern to test for validity?

Really, I'm not looking for answers to those specific questions, I'm looking for a comprehensive list of everything I can type in place of 'api.required' above (and an explanation of how each one works).

2 Answers 2


After a bit of research I added documentation which explains how to write _spec functions:



As per https://github.com/civicrm/civicrm-core/blob/master/api/v3/Dashboard.php#L64 you can set default values, You can also specify the type and even limit to specific options see https://github.com/civicrm/civicrm-core/blob/master/api/v3/Contribution.php#L552 also https://github.com/civicrm/civicrm-core/blob/master/api/v3/Contribution.php#L723. Also as per https://github.com/civicrm/civicrm-core/blob/master/api/v3/Contribution.php#L360 you can specify aliases or alternate field names for legacy or similar handling

  • 1
    These are useful examples, but what I'm really looking for is a comprehensive list, in part because I'd like to write new documentation for on this subject to help other developers in the future.
    – Sean
    Jul 10, 2017 at 0:41
  • Hi Sean i looked around and i struggled to build a comprehensive list for myself, However it seems to do similar things to getFields, So my hunch is that you can put in anything that the xml files would accept, + api.required and api.default to specify if you need the field or not and what the default value of the field is
    – Seamus Lee
    Jul 11, 2017 at 21:12
  • 1
    Seamus, yeah I had the same thought. But even that rule of thumb doesn't seem "complete" to me because I've also noticed 'api.unique' and 'api.aliases', 'api.filter', 'api.return', 'description', 'FKClassName', 'FKApiName', 'supports_joins', 'options', ... yada yada. Personally it's very important to me that documentation be complete, so I'm searching for some sort of authoritative way to verify a complete list here.
    – Sean
    Jul 11, 2017 at 21:47
  • Sean i think apart from checking in with the folks in the API channel there really isn't much other documentation on the _spec functions. Eileen probably knows as much as anyone else
    – Seamus Lee
    Jul 11, 2017 at 22:58

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.