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

From: Carsten Bormann <[email-masked]>
Date: Thu, 12 Nov 2020 07:24:40 +0100

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

---

From: "Wouter van der Beek (wovander)" <[email-masked]>
Date: Thu, 12 Nov 2020 10:46:33 +0000

Hi Carsten, et all.

I think this email does not report out well on the discussion.

As indicated before, the current draft version of ASDF is working for +200 models.
Hence it is fit for purpose.
Yes there are things it can't convey, but solving those will delay work in oneDM on selecting and improving on those +200 models.
To indicate: OCF only wants to use the RFC not the draft version. OCF has been hurt by referencing draft specs that changed during the process in becoming an RFC. Hence I voiced and still think what is currently being a draft can be adopted as an RFC so that oneDM can start doing work based on the stable SDF RFC.

About the discussion below.
It was voiced that it would be good to align with JSON schema syntax.
It was also voice that for an action it would be good to have named input and output variables.
Reason to change: to avoid positional arguments, which are quite common in programming languages, but have the issue that one has to annotate the what the ordering means. The actual conversion to a transport can do positional argument list if they want to. Such solution can be part of the mapping.

Hence the suggested issue is just a notational issue.
I voice that I like to align the notation with JSON schema, since this notation is already known in the world.
e.g. the construct does not have to be explained if one already understands JSON schema.
Hence the construct of having objects called sdfInputData/sdfoutputData are just containers to group the input and output definitions.
This maps very well to POST/SOAP/.. to indicate what goes in and out (request(input) and response (output) ).

Kind Regards,
Wouter

-----Original Message-----
From: ASDF <[email-masked]> On Behalf Of Carsten Bormann
Sent: Thursday, November 12, 2020 6:25 AM
To: [email-masked]
Subject: [Asdf] sdfInputData: from an array to a map and then to just a data schema (dataqualities) item?

          "sdfInputData": [

The above is a bit like

          "sdfInputData": [

          "sdfInputData": {
            identifier: {

Which is more like

Great.

          "sdfInputData": {
            type: object,
            properties: {
              identifier: {

Grüße, Carsten

-- 
ASDF mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/asdf