Improve schema files

[chadrik]

Looking through the schema files I realized that these are quite a few problems and shortcomings with the current schema files:

• The schema files actually contain many schemas: one for each message type under "output" and "input". While it might make it easier to edit and read, there seems to be some expectation in the json-schema spec and community that there is only one schema per document. For example, each schema doc is expected to have an "id" attribute specifying where the file can be downloaded on the web. more here. One-file-per-schema also makes it easier when working with command-line tools which seem to have this expectation.

• we can improve the schemas by using the $ref keyword to avoid duplication. Note that this can be used to refer to other objects in the same doc { "$ref": "#/definitions/address" } or in another doc { "$ref": "definitions.json#/address" }.

• no $schema keyword: it's good form to indicate what version of the draft is being used

• many required properties are not indicated as such (there are none in component.json). easy enough to cross reference properties with "optional" in their description.

• the "required" keyword must be a list of properties and can only exist for compound schemas. e.g. this is bad:

  "changenode": {
    "description": "Change the metadata associated to a node in the graph",
    "properties": {
      "id": {
        "type": "string",
        "description": "identifier for the node",
        "required": true
      },
      "metadata": {
        "type": "object",
        "description": "structure of key-value pairs for node metadata",
        "required": true
      },
      "graph": {
        "type": "string",
        "description": "graph the action targets",
        "required": true
      }
    }
  }

  this is good:

  "changenode": {
    "description": "Change the metadata associated to a node in the graph",
    "properties": {
      "id": {
        "type": "string",
        "description": "identifier for the node",
      },
      "metadata": {
        "type": "object",
        "description": "structure of key-value pairs for node metadata",
      },
      "graph": {
        "type": "string",
        "description": "graph the action targets",
      }
    },
    "required": ["id", "metadata", "graph"]
  }

• nested schemas don't indicate "type": "object". it's implicit, but should probably be there.

• "outPorts" and "inPorts" should indicate that they are an array of objects

• by default, extra keywords in the document are allowed. I think we should set "additionalProperties": false for all schemas to prevent typos from slipping through without error.

I tried using one of our schemas for validation (after extracting it from its parent doc) and got an error ("schema/json/component.json#/properties/name: true is not a valid "required", must be a array."), so I think technically our schemas are not valid as they are. we should definitely be running validation of our schema files in the tests for this repo

This ticket should be done in conjunction with converting fbp-test to use the schemas.

Some resources for learning more about json-schema:

• http://spacetelescope.github.io/understanding-json-schema/index.html
• https://brandur.org/elegant-apis
• https://github.com/brandur/json_schema
• http://www.jsonschemavalidator.net/

[chadrik]

Looks like many-schemas-per-file may be ok, you just have to assign an "id" to each document: http://stackoverflow.com/questions/8179137/how-to-manage-multiple-json-schema-files

[jonnor]

Looks like the schemas are valid now? So guess if we want to keep this issue open, it should be renamed to "Split schemas into one per request/response"? Or we just close it after adding ids?

[chadrik]

Closed with #17