Flatten `plugin.config.properties`

At the moment plugin configuration properties can be declared like this:

module.exports = {
  name: 'netlify-plugin-example',
  config: {
    properties: {
      url: { type: 'string' }
    }
  },
  onInit({ pluginConfig: { url } }) {
    console.log(url)
  }
}

We had a discussion with @DavidWells where he proposed flattening it to simply config.

module.exports = {
  name: 'netlify-plugin-example',
  config: {
    url: { type: 'string' }
  },
  onInit({ pluginConfig: { url } }) {
    console.log(url)
  }
}

I agree this is a simpler and more natural DX. There are two reasons config.properties is currently used instead of simply config.

1. This follows the JSON schema standard, where required is an array of property names, not a boolean.

module.exports = {
  name: 'netlify-plugin-example',
  config: {
    required: ['url'],
    properties: {
      url: { type: 'string' }
    }
  },
  onInit({ pluginConfig: { url } }) {
    console.log(url)
  }
}

If we were to use a boolean instead, users would need to remove that property if they wanted to re-use the JSON schema.

const plugin = {
  name: 'netlify-plugin-example',
  config: {
    url: { type: 'string', required: true }
  },
  onInit({ pluginConfig: { url } }) {
    console.log(url)
  }
}

// Invalid: this is not a standard JSON schema
validateWithJsonSchema(data, plugin.config.url)

1. This allows validating properties as a whole instead of individually with the JSON schema validation keywords related to object properties: minProperties, maxProperties, additionalProperties, patternProperties, propertyNames and dependencies. This allows for properties validation like:

• if foo is defined, then bar should be defined.
• foo and bar are exclusive
• foo can also be called foo-* where * is any sequence of digits
• explicitly forbidding or allowing custom properties
• and more

module.exports = {
  name: 'netlify-plugin-example',
  config: {
    // If 'url' is defined, 'host' must be defined too
    dependencies: { url: ['host'] },
    properties: {
      url: { type: 'string' },
      host: { type: 'string' }
    }
  },
  onInit({ pluginConfig: { url } }) {
    console.log(url)
  }
}

Now if we chose not to follow the JSON schema standard, we could instead whitelist specific validation keywords and forbid those as property names, so they can be use while still flattening config.properties.* to config.*.

module.exports = {
  name: 'netlify-plugin-example',
  config: {
    url: { type: 'string' },
    host: { type: 'string' },
    dependencies: { url: ['host'] }, 
  },
  onInit({ pluginConfig: { url } }) {
    console.log(url)
  }
}

We could also introduce a separate property to put those validation keywords together in the same namespace.

Working with outputs (#611) I realized that flattening properties might make sense from a DX standpoint, but I still have concerns about the two points above.

I wanted to know if I could gather other people’s opinions here to reach the best solution? @RaeesBhatti @erquhart @verythorough @jlengstorf @philhawksworth

[erquhart]

The core requirement of placing properties directly on config makes sense. The only reason not to do it is strict adherence to JSON schema, which I’m okay with not being tied to - we can consider the config/inputs API “inspired by” JSON schema.

@ehmicky communicated the following understood requirements for implementing:

• flatten plugin.config.properties.* to plugin.config.*
• use a required boolean option instead of an array of properties
• remove the cross-properties validation keywords for the moment

I’ll also add the following:

• update any repo documentation stating that we use JSON schema to the “inspired” verbiage

We’ll move forward with that plan, any other topics covered in the conversation above should be moved to dedicated issues.

[verythorough]

Good points about the object vs array question. In either case, it doesn’t seem to impact the question of flattening (which is mainly why I brought it up). If anyone did want discuss whether to change from objects to arrays, we should probably start a separate issue for that conversation. 😃