[Asdf] sdfInputData: from an array to a map and then to just a data schema (dataqualities) item?

[Carsten Bormann <[e-mail]>]

Yesterday, at the hackathon, we had a discussion about sdfInputData.

In SDF 1.0, this is an array of JSON pointers (to sdfData items, i.e. “types” (data schema definitions, which are called »dataqualities« in the current syntax)).

          "sdfInputData": [
            "#/sdfObject/OnOff/sdfAction/OffWithEffect/sdfData/EffectIdentifier", 
            "#/sdfObject/OnOff/sdfAction/OffWithEffect/sdfData/EffectVariant"
          ],

(Note that this is not an array at the data schema definition level; it is an array at the specification syntax level.  One has to be very careful about these distinctions in a specification language that uses JSON both as the generic data model as well as the representation language for the specification itself.)

There are two problems with this:

— the input parameters are just typed, but not named.  It can get confusing very quickly if the same type is used for multiple parameters.

The above is a bit like

  void OffWithEffect(EffectIdentifier, EffectVariant)

which works as long as the types happen to be descriptive of the parameters.
But, in, say:

          "sdfInputData": [
            "#/sdfData/Channelvalue", 
            "#/sdfData/Channelvalue", 
            "#/sdfData/Channelvalue", 
          ],

which of these is R, G, or B?

— there is some ceremony here in requiring setting up separate sdfData items and then pointing to them; we don’t require those for (SDF) properties (which can define their types inline).

So we came up with replacing the array of pointers with a map, and using data schema definitions (dataqualities) as values in the map — if a reference is indeed required, that can be put in as sdfRef.
So, in the example, if an sdfRef were actually desirable, this becomes:

          "sdfInputData": {
            identifier: {
              sdfRef: “#/.../EffectIdentifier"
            },
            variant: {
              sdfRef: “#/.../EffectVariant"
            }
          },

Which is more like

  void OffWithEffect(identifier: EffectIdentifier, variant: EffectVariant)

Great.
Now this is where the discussion derailed and then time ran out.
It was noted that an sdfInputData now superficially looked like a map (sure, its specification is represented as a map at the specification syntax level) and, once we start supporting complex types in SDF (this is where the discussion derailed) we could use json-schema.org’s »type: object« to specify this map:

          "sdfInputData": {
            type: object,
            properties: {
              identifier: {
                sdfRef: “#/.../EffectIdentifier"
              },
              variant: {
                sdfRef: “#/.../EffectVariant"
              }
            }
          },

This is the equivalent of always having to build a structure to supply multiple parameters:

  void OffWithEffect(struct {
      identifier: EffectIdentifier, variant: EffectVariant
    }
  )

Of course, once we do this, there is no reason to only allow »type: object« here, so people could use integers, arrays, … there as well.

Is this really the direction we want to go?
I’m not aware of any programming language that only ever can supply a single parameter to a procedure call.  Actions are not exactly procedure calls, but I still think the analogy holds well.

On the other hand, protocol bindings such as that to CoAP’s FETCH could directly pick up the map (»type: object«) as the request body, so this may seem natural to some.

(Behind this is the related complex data discussion, issue #4: We avoided introducing »type: object« into SDF 1.0 because we wanted to understand where aggregation is needed and whether that always is appropriately described as aggregation on the data schema level, or whether we would be better off with aggregation at the SDF structural level.  The above goes into the direction of offloading more of the aggregation into data schema level land, which may be the lazy thing to do, but also may be missing some opportunities.  In the extreme, why don’t we define an entire sdfThing as a »type: object« then?)

Grüße, Carsten