StackStorm / StackStorm/st2

Add better support for references ($ref) to config schemas and action parameter definition JSON schemas

Open
#3,276 4 comments 1 reaction 1 assignee View on GitHub

@Kami is already working on this.

Since Mar 7, 2017.

complexity:medium enhancement
Dominant language
Python
Stars
6.5k
Forks
787
PR merge metrics
No merged PRs in 30d

Description

We should add better support for JSON schema references ($ref) inside JSON schemas used for config schemas and action parameter definitions.

Right now the example shown below works, but it's a hacky. host attribute is only used as a reference definition, but because of the way it's defined and the way it currently works, user could also specify it as a top-level host attribute in the actual config which is not desired.

config.schema.yaml

---
  elastic:
    type: "object"
    required: true
    additionalProperties: false
    properties:
      nodes:
        type: "array"
        required: true
        additionalProperties: false
        items:
          "$ref": "#/properties/node"
          required: true

  # top level definition only used by $ref
  node:
    type: "object"
    required: false
    additionalProperties: false
    properties:
        ip_address:
            type: "string"
            required: true
        port:
            type: "integer"
            required: true

examples.yaml (actual config)

---
   elastic:
     nodes:
       -
          ip_address: "127.0.0.1"
          port: 5555
       -
          ip_address: "127.0.0.2"
          port: 5556

One option is to introduce a reserved top-level attribute inside the config schema which would be used to specify schemas which are only used for references.

For example, something like this:

config.schema.yaml

---
  elastic:
    type: "object"
    required: true
    additionalProperties: false
    properties:
      nodes:
        type: "array"
        required: true
        additionalProperties: false
        items:
          "$ref": "#/definitions/node"
          required: true

  # top level definition only used by $ref
  top_level_ref_schemas:
    node:
      type: "object"
      required: false
      additionalProperties: false
      properties:
        ip_address:
            type: "string"
            required: true
        port:
            type: "integer"
            required: true

Inside the code, we would do some mangling so the actual value / object under top_level_ref_schemas attribute would be moved inside "definitions" of the JSON schema so user could then reference it using this notation - "$ref": "#/definitions/node".

I'm of course also open to better name for the attribute than top_level_ref_schemas. It's worth nothing though that this would be a reserved keyword so it needs to be something which is unlikely to come up as the actual actual parameter name / config attribute name.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.