params field could be a restricted JSON schema instead of custom contentDescriptorObject

[rmedaer]

According to JSON RPC specs (4.2 Parameter Structures), params member can either be:

• omitted: (4 Request object, params) "This member MAY be omitted."
• an array (aka by-position): with ordered value
• an object (aka by-name): with named parameter (as object-key)

The OpenRPC params member and its item type contentDescriptorObject should reflect the JSON RPC spec described above. However I see multiple mismatches or issues in the current OpenRPC spec:

• already described in paramStructure should have an "either" value #190 , we can't specify an optional params value with either array or object
• if paramStructure is by-position:
  • the contentDescriptorObject > name is not required
  • the required field is not relevant
  • there is no way to define generic item schema or validate number of items, etc.
• if paramStructure is by-name:
  • we cannot enforce the uniqueness of the name (aka. object key)
    (this is the same kind of issue then methods field could be an object instead of an array  #224)

To solve all these issues I would propose to replace the OpenRPC params field by a restricted JSON schema. Restricted means "limited to types allowed in the JSON RPC spec". Btw, with this change, we don't need anymore the paramStructure field.

by-name example

Currently:

{
  "openrpc": "1.0.0-rc1",
  "methods": [
    {
      "name": "addition",
      "params": [
        { "name": "a", "schema": { "type": "integer" } },
        { "name": "b", "schema": { "type": "integer" } }
      ],
    }
  ]
}

Proposal:

{
  "openrpc": "1.0.0-rc1",
  "methods": [
    {
      "name": "addition",
      "params": {
        "type": "object",
        "properties": {
          "a": { "type": "integer" },
          "b": { "type": "integer" }
        }
      }
    }
  ]
}

by-position example

Proposal:

{
  "openrpc": "1.0.0-rc1",
  "methods": [
    {
      "name": "addition",
      "params": {
        "type": "array",
        "items": {
          "type": "integer"
        },
        "minItems": 2
      }
    }
  ]
}

either by-position or by-name (#190)

Proposal:

{
  "openrpc": "1.0.0-rc1",
  "methods": [
    {
      "name": "addition",
      "params": {
        "oneOf": [
          {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "minItems": 2
          }, {
            "type": "object",
            "properties": {
              "a": { "type": "integer" },
              "b": { "type": "integer" }
            }
          }
        ]
      }
    }
  ]
}

[BelfordZ]

Potentially fixes
#229

[BelfordZ]

The content descriptor is key in the ability to separate the domain specific languages.

For example, consider the method "division".

{
  "name": "division",
  "params": [
    { "name": "numerator", schema: { $ref: "#/components/schemas/Number } },
    { "name": "denominator", schema: { $ref: "#/components/schemas/NonZeroNumber } }
  ]
}

In this example, it reads very clearly, and you need not have schema.title that matches the names of the data returning from the api. This is especially important in client generation, where the parameter names -> type becomes very clear.

[BelfordZ]

to address some of your other points:

• if paramStructure is by-position:
  • the contentDescriptorObject > name is not required
    • While you may not require names to manipulate the data if its by position, it greatly complicates things to accommodate these types of conditionally optional fields. It also makes generated documentation much better, among many other benefits.
    • the required field is not relevant
      • Its still relevant. you can mark trailing content descriptors as optional
    • there is no way to define generic item schema or validate number of items, etc.
      • see https://github.com/open-rpc/schema-utils-js/blob/master/src/method-call-validator/method-call-validator.ts Im not sure what you mean by generic item schema

[BelfordZ]

I've opened an issue for the only thing I can think of from this that we really need to address.

#229

[BelfordZ]

Thanks for opening the issue and bringing these to our attention.