// This module is included in the following assembly:
// as_developing-extensions.adoc

[id='about-extension-definitions_{context}']
= Requirements in an extension definition JSON file

Each extension must have a `.json` file that defines the extension 
by specifying values for data structures such as name, description, 
supported actions, and dependencies. For each extension type, the
following table indicates whether Maven can generate the 
extension definition JSON file and which data structures are required. 

[options="header"]
[cols="3,1,2"]
|===
|Extension Type
|Maven Can Generate Extension Definition
|Required Data Structures

|Step extension in Java
|Yes
|`schemaVersion` + 
`name` +
`description` +
`version` +
`extensionId` +
`extensionType` +
`actions` +
`dependencies` *

|Step extension in XML
|No
|`schemaVersion` + 
`name` +
`description` +
`version` +
`extensionId` +
`extensionType` +
`actions` +
`dependencies` *

|Connector extension
|No
|`schemaVersion` + 
`name` +
`description` +
`version` +
`extensionId` +
`extensionType` +
`properties` +
`actions` +
`dependencies` * + 
`componentScheme` +
`connectorCustomizers` +
`connectorFactory`

|Library extension
|No
|`schemaVersion` + 
`name` +
`description` +
`version` +
`extensionId` +
`extensionType` +
`dependencies` *

|===

*While specification of `dependencies` is not strictly required, 
in practice, there are almost always dependencies that you need
to specify. 

Typically, an extension definition file has the following layout:

[source,json]
----
{
  "schemaVersion": "v1",
  "name": "",
  "description": "",
  "version": "",
  "extensionId": "",
  "extensionType": "",
  "properties": {
  },
  "actions": [
  ],
  "dependencies": [
  ],
}
----

* *schemaVersion* defines the version of the extension definition schema. 
Internally, Syndesis uses *schemaVersion* to determine how to map the 
extension definition to the 
internal model. This allows extensions that were developed against an old version of 
Syndesis to be deployed on newer versions of Syndesis.

* *name* is the name of the extension. When you upload an extension
to {prodname}, this name appears. 

* *description* is any useful information that you want to specify. 
{prodname} does not operate on this value. 

* *version* is for your convenience to help you distinguish updates
to an extension. {prodname} does not operate on this value. 

* *extensionId* defines a unique ID for the extension. This should be unique 
at least across a Syndesis environment. 
* *extensionType* indicates to Syndesis what the extension provides. As of 
Syndesis version 1.3, the following extension types are supported:
** `Steps`
** `Connectors`
** `Libraries`

* *properties* at the top level in a connector extension is required. It controls 
what {prodname} displays when a {prodname} user selects the connector
to create a connection. This `properties` object contains a set 
of properties for each form control for creating a connection.
For example: 
+
[source,json]
----
"myControlName": {
  "deprecated": true|false,
  "description": "",
  "displayName": "",
  "group": "",
  "kind": "",
  "label": "",
  "required": true|false,
  "secret": true|false,
  "javaType": "",
  "type": "",
  "defaultValue": "",
  "enum": {
  }
}
----
+
In connector extensions, nested `properties` objects define HTML form controls for 
configuring connection actions. 
In step extensions, the `actions` object contains a `properties`
object. The `properties` object defines a set of properties for 
each form control for configuring the step. See also:  
link:{LinkSyndesisIntegrationGuide}#descriptions-of-user-interface-properties-in-extension-definitions_extensions[Descriptions of user interface properties].

* *actions* defines the operations that a connector can perform or the
operation that a step between connections can perform. Only connector
and step extensions use actions that you specify. 
The format for an action specification looks like this:
+
[source,json]
----
{
    "id": "", 
    "name": "", 
    "description": "", 
    "actionType": "step|connector", 
    "descriptor": { 
    }
}
----
** *id* is a unique ID for the action. This should be unique at least
within a Syndesis environment. 
** *name* is the action name that appears in {prodname}. An integrator
sees this value as the name of a connection action or as the name of a step
that operates on integration data between connections.
** *description* is the action description that appears in {prodname}.
Use this field to help the integrator understand what the action does. 
** *actionType* indicates whether the action is performed by a connection 
or a step that is between connections.
** *descriptor* specifies nested attributes such as `kind`, `entrypoint`,
`inputDataType`, `outputDatatype` and more. 

* *dependencies* defines the resources that this extension 
requires {prodname} to provide.
+
Define a dependency as follows:
+
[source,json]
----
{
  "type": "MAVEN", 
  "id"   : "org.apache.camel:camel-telegram:jar:2.21.0" 
}
----
** *type* indicates the type of the dependency. Specify *MAVEN*. (It is 
expected that other types will be supported in the future.)
** *id* is the ID of the Maven dependency, which is a Maven GAV. 
