syntax clarifications on odmThing, required tag

[WAvdBeek]

how can we specify which odmObjects are required when the the list of includes only includes references?

e.g. this validates against the schema

"odmThing": {
"oic.d.washer" : {
"id" : 1,
"name" : "oic.d.washer",
"title" : "washing machine",
"include" : [
{"$ref": "#/odmObject/oic.r.switch.binary"},
{"$ref": "#/odmObject/oic.r.operational.state"}
]
}
}

{
"info": {
"title": "OCF washer",
"version": "20190530",
"copyright": "Copyright 2019 Open Connectivity Foundation, Inc. All rights reserved.",
"license": "https://github.com/openconnectivityfoundation/core/blob/master/LICENSE-3C.md"
},

for example making sure that the switch binary is the only required odmObject we can do the following:

"odmThing": {
"oid.d.washer" : {
"id" : 1,
"name" : "oic.d.washer",
"title" : "washing machine",
"include" : [

    {"$ref": "<library>#/odmObject/oic.r.switch.binary"},
    {"$ref": "<library>#/odmObject/oic.r.operational.state"}
  ],
  "required" : [ "$ref[0]" ]
  
}

}
}

however this solution is now position dependend, e.g. swapping the contents in the array around will give different results
note this validates

[mjkoster]

Maybe we need to think about it more but I assumed it would be like this:

  "odmThing": {
    "oic.d.washer" : {
      "id": 1,
      "name" : "oic.d.washer",
      "title" : "washing machine",
      "required": [
        { "$ref": "0/odmObject/powerswitch" },
        { "$ref": "0/odmObject/washerstate" }
      ],
      "odmObject": {
        "powerswitch": {
          "odmType": { "$ref": "<library>#/odmObject/oic.r.switch.binary" }
        },
        "washerstate": {
            "odmType": { "$ref": "<library>#/odmObject/oic.r.operational.state" }
        },
        "washermode": {
            "odmType": { "$ref": "<library>#/odmObject/oic.r.mode" }
        },
        "watertemperature": {
            "odmType": { "$ref": "<library>#/odmObject/oic.r.temperature" }
        }
      }
    }
  }

[WAvdBeek]

the required tag definition is an array of objects, instead of just doing a label.
which solves the issue.

not sure about the redefinition of the tag names under odmObject.
has that an meaning or is that just a label?

I rather have this simplified (which is currently validating with the schema) as indicated above.

full definition of the thing can be (without the external reference definition):

"odmThing": {
"oid.d.washer" : {
"id" : 1,
"name" : "oic.d.washer",
"title" : "washing machine",
"include" : [

{"$ref": "<library file>#/odmObject/oic.r.switch.binary"},
{"$ref": "<library file>#/odmObject/oic.r.operational.state"}

],
"required" : [ { "$ref": "#/odmObject/oic.r.switch.binary"} ]

}
}
}

[mjkoster]

The tag names under "odmObject" are new definitions in the local scope.

For reusing the already-defined definition names using references, we need a new term other than "include" because "include" refers to a pre-existing instance.

In addition, when we want to re-use a definition we should be able to set additional qualities and maybe even over-ride some of the defined qualities.

I propose a new keyword "define" with a value consisting of an array, just like "include", but define creates new definitions (hence the word "define") using the existing definition. So here is the washer example using "define".

  "odmThing": {
    "oic.d.washer" : {
      "id": 1,
      "name" : "oic.d.washer",
      "title" : "washing machine",
      "required": [
        { "$ref": "odm:/library/odmObject/oic.r.switch.binary" },
        { "$ref": "odm:/library/odmObject/operational.state" }
      ],
      "define": [
         { "$ref": "odm:/library/odmObject/oic.r.switch.binary" },
         { "$ref": "odm:/library/odmObject/oic.r.operational.state" },
         { "$ref": "odm:/library/odmObject/oic.r.mode" },
         { "$ref": "odm:/library/odmObject/oic.r.temperature" }
      ]
    }
  }

We can allow "define" to modify or extend the referenced definition, for example to add a "semantic-tag" quality that differentiates one instance from another of the same type. For example:

"odmThing": {
  "oic.d.thermostat":  {
  "define": [
         { 
           "$ref": "odm:/library/odmObject/oic.r.temperature",
           "minimum": -22,
           "maximum": 40,
           "semantic-tag": "FreezerMeasuredTemperature"
         },
         { 
           "$ref": "odm:/library/odmObject/oic.r.temperature" ,
           "minimum": -22,
           "maximum": 40,
           "semantic-tag": "FreezerSetpointTemperature"
         },
         { 
           "$ref": "odm:/library/odmObject/oic.r.mode",
           "odmType": { "$ref": "odm:/library/enumTypes/freezerModes" },
           "semantic-tag": "FreezerMode"
         }
  ]

[WAvdBeek]

looks a bit strange to point to the actual definition again from required point of view.
this should point to an entry in the define.

"required": [
    { "$ref": "odm:/library/odmObject/oic.r.switch.binary" },
    { "$ref": "odm:/library/odmObject/operational.state" }
  ],

note that the scheme can work if we do something like

• definition_required
• definition_optional
  as definition & required tags
  drawback: 2 lists...
  other option: adding a tag called "odmRequired" : true, e.g. circulating back to the original idea.

adding more things to the definition like overuling min/max is nice.. but that should be then listed somewhere to which standard properties/tag names can be overruled in this way.
and it indeed is nice to have the semantic tag there in this way.

[asoloway64]

F2F4: Change "include" to "odmInclude". Add "odmRequired" at odmThing layer. Add note that odmRequired must be equal to or a subset of odmInclude. "odmRequired" applies to all definition lists.