# T2TRG/WISHI work meeting 2019-10-04

Notes:
* https://hackmd.io/YcgV56AMR6a33R7P6pltiQ

Attendees:
* Ari Keränen (remote)
* Edgar Ramos (remote)
* Carsten Bormann
* Kerry Lynn (remote)
* Klaus Hartke
* Michael Koster
* Niklas Widell

Schedule:
* Block 1 - 09:30..11:00
* Block 2 - 11:30..13:00
* (13..14 is taken by lecture)
* Block 3 - 14:00..15:30
* Block 4 - 16:00..17:30
* (Niklas to leave ~15:30)

All times in CEST (+0200)

Agenda:

* Block 1 (1) Extract architecture from sdf.md

SDF is OneDM’s “Simple Definition Format”, which is the common format in which data models are going to be exchanged and agreed upon. It is being developed at https://github.com/one-data-model/language

SDF has various components, including missing ones that still need to be defined. A more formal view of what these components are, do, and how they interact, might help in making use of SDF and in further refining it without losing architectural integrity. Of course, we also might be able to identify gaps/opportunities for further development.

Numbering the above as (1), a few more items that came up:

* Block 1 (2) Terminology

This is, of course, closely related to architecture. Can we further improve on the terminology used to describe SDF? (E.g., one breakthrough this week was when we found that we have to distinguish “definitions” from “declarations”.)

* Block 2 (3) JSON Pointers, CURIEs, Naming for Cross-Referencing within and between Specs

How does the spec refer to definitions done at a different point in the same spec or in a different spec?
The current spec provides a mix of RFC 6901 JSON Pointers (with the draft-handrews-relative-json-pointer-02.txt extension) and CURIEs.
Is there a way to clean this up and simplify it?

* Block 2 (4) Breadcrumbs

We found that referring to some other part of the spec might not only simply want to copy the referred-to part, but also might want to preserve the identity (whatever that is) of the referred-to part. Is preserving the JSON pointer (after normalizing it to absolute/CURIE resolution) all that is needed?
(This is related to the age-old issue of “name equivalence” vs. “structural equivalence”.)

* Block 2 (5) Semantic Processing

What else do we need to enable reasoning on the results of applying an SDF spec to an interaction?

* Block 3 (6) Versioning of Model Specifications

OneDM hasn’t tackled the difficult issue of versioning of model specifications yet.
There are interesting potential objectives for versioning beyond simply keeping track of them the way git does, e.g., how can a spec be updated and that update become usable for other specs making use of the original spec? Does “semver” (semantic versioning, https://semver.org, draft-claise-semver-02.txt, draft-verdt-netmod-yang-semver-00.txt) help?
Is there some advice we can give?

* Block 3 (7) Reuse

Probably closely related to versioning: How can we maximize reuse of specification components (within a spec, between specs, over time, …)? Derivation is one way (may be closely related to what is called inheritance in object oriented languages); how does that work precisely; are there other ways?

* Block 4 (8) Modelling Hypermedia State in SDF

* Block 4 (9) Intelligent Services, Machine Learning Models

Description of Intelligent Services: Formative contribution from Edgar.

MJK: E.g., PID Algorithm

# ODM Products, Things, and Objects:
- We define an ODMobject based on its properties, actions, and events (the ODMobject is a base class, conceptually)
- Objects are irreducible (hence "atom-like")
- This is not really like Booch's def'n of object, "an entity with state, behavior, and identity."
- Term "object" is based on "IPSO smart objects"

- ODMthings are composed of ODMobjects and ODMthings

- ODMproducts likewise are composed of ODMthings (or products?)

(These really should be called SDFxyz, not ODMxyz)

# What's the difference between a Thing and a Product?

I keep coming back to this notion of "intrinsic" and "extrinsic" behavior. The latter might also be called "context". If I purchase a smart light bulb, its capabilities are more or less fixed (modulo downloading new firmware). OTOH, the fact that it's in my kitchen or living room are extrinsic properties that are somehow bound at installation time. It could be that 'products' contain things plus context.

ODM does not model extrinsics in this sense, but any modeling technology should be able to model these, too; MJK: Bluetooth Mesh Models are starting to do that; CB: manufacturer doesn't know those extrinsics; KL: triples might help; ER: to express intent, i.e., what you like the system to do, you need this

MJK: getting back to "just changing lightbulbs"

# Running notes,

MJK:
... description of SDF components: ...

objects irreducible, highly reusable, useful granular entities. Other term could be capabilities

(NW: Object as term comes from OMA DM where objects are managed entities in a device)

properties (RW)
actions (IO)
events (O)

PAE can be reusable, but essentially form part of object.

Things are the same kind, but a higher level of composition, composed of objects
(e.g. an electricity outlet strip w many sockets. One socket is a thing, the strip is combined of many such sockets + extra things for outlet control etc. ) and things

Product is similar again, but the top level

keep neutral of protocol, but include constructions to recreate lower level features.

CB: has-a vs is-a. has-a is a "declaration", used for things

MJK: Schema.org uses rdf property tags to describe the semantic relationship vertexes. We can say that the generic relationship is a has-a

CB: has-a declaration gives a component a _name_ (points to a definition)

MJK: Properties is really data with additional semantics to allow reading/writing, maybe units. Actions behave like procedure calls (just pass data in and out). Events emit data. People see these terms as badly overloaded, but we don't have any better.

We need to talk about qualities (ie metadata to describe the entities (the word property was already used).)

A definition is composed of qualities.

CB: metadata qualities are the keywords, plus the actual declarations

CB/MJK: ...
declaration blocks are members of a particular quality like ODMProperty (label members). A definition is a set of qalities. a quality is always a name ad a value. Some are declaration objects (maps that map member names ot definitions.
ODMProperty indicates a set of declarations with a certain structure, you need the context to understand the declaration. Declraration context tells ths class of teh declrataion

Quality name tells you the class of the definitions that are contained in the declaration block of the quality.

Definitions can be either

1. stand-alone (not in context of declaration block)
2. root qualities

The linking of the thing being defined is different from the definition themselves

Declrataion may include their own definitions (ie inline).

Use JSON Pointers to point to definitions.

JSONPointers odmrefs
derivation: add qualities (assumes you have types)
Polymorphism? Do we have types? Not really, we should be careful with terminology here.

Maybe use _refinement_, keep semantic tags intact, modification instead? RDF tags are cumulative (what happens If I redefine a Temperature thing from Farenheit to Celsius).

KL: Presentation or conversion (e.g. Celsius vs Fahrenheit) could be handled on local level if a property can be expressed in base units (e.g. Kelvin)

MJK: maybe need to add more tags

CB: we are building a tree, using a JSON pointers so we don't need to replicate (the breadcrumb idea to to ensure that processing can be optimized). (=> picture of JSON Poiner tree with breadcrumb). Breadcrumbs are JSON Pointers that allow for reuse, pointing to the same part, can be used for reasoning. Representatoin TBD (CURIES?). An efficient way to do breadcrumb is to use hash of the tree (versioning makes this hard).

MJK: the semantic breadcrumb can be pretty sophisticated. What additional things are needed in SDF to make them easier to process.

CB: provenance/x-dash problem, makes things complicated to track. Two provenance tags "copy-of" (use odmref, unharmed copy) and "modified-from" (odmref + adding qualities).

Reification breadcrumb is a quality in a definition that has a keyword that tells "if modified" plus a value indicating the position in the blue tree.

A breadcrumb is an identifier for a part of the "blue" tree, that can be shared in many places in the tree.

MJK: allows for tracing a semantic tag back to its origin (because you can't look it up)

KL: Extrinsics vs intriniscs, ie also describe where things are installed, local context.

MJK: We've covered the intrinsics primarily. Bluetooth has e.g. Mesh Models that include extrinsic properties.

CB: extrinsics/interinsics are not different, depend on the perspective (example of washing machin power cord (ext) connected to a powe plug (intrinsic))

MJK: adding semantic reasoning allows for connecting intr/ext, very important to enable abstraction (in sense of moving from "turn on lightbulbs A & B " to "turn on lights in room"). One possible way for ext is to use FOI Feature of Interest.

KL: Identity of objects, how do we distinguish one instance from another? Is that included in this model?

MJK: top level is SKUs, we're not really modelling instances, currently type descriptor.

KL: If we include security, there needs to be notion of identity

CB: No need to model identities, because that functionality is kind of orthogonal to the device properties...

CB/MJK/NW ...discussion if there are additional requirements on SDF coming from eg LwM2M Manaement objects, likely not. ...

CB: We need to define a processing model, to validate the blue tree (needs to be part of SDF). The assumption is that $ref and odmref aer all expanded, whhich results in the blue tree. The breadcrumbs preserve the source where the *refs were expanded from.

MJK: Basic processing starts with validating the specification against the JSON schema for specifications, not really processing yet. Ari has a linter, which goes beyond the schema validation.

AK: what about the ID mapping file, that is processing?

CB: Need to figure out what the maping files should be.

Processing model:

1. Input:
1. SDF Specs (standardized or specialized)
2. Mapping files (name spaces)
3. Preprocessing puts 1.1 and 1.2, resolves into the "blue tree" (whichi is subset of "big blue tree")
- Blue tree looks like an SDF specification, but all JSON pinters have been replaced by content plus the breadcrumb
- Breadcrumb is the canonical form of the JSON pointer
3. Apply to IoT Network
- Still don't have instantition
- To instantiate a product, find the ODMProductNode and instantiate it

Works until we get recursion, then everything becomes more complicated...

NOTE: We need to resolve the recursion problem (either disallow or describe how to handle)

Should every node have breadcrumb (and what are they? hashes are good except for versioning problem)

We prefer semantic tags over names, we probably need structural equivalence, need to know if what is being processed right now has been processed before (same-as), names are therefore not sufficient.

MJK: Products are described by specs, don't have to live in odm namespace (but is built from blue tree)

CB: Namespaces are not fully defined. basically URIs. JSONPointers can reach into Representation (namespace#JSONPointer)

MJK: Namespace use is based on JSON-LD, should work the same way

Example: #/odmObject/foo is the same as http://example.com/#odmObject/foo. (assume namespace is http://example.com/#odmObject)

CB: use CURIEs <https://www.w3.org/TR/curie/>. We can probably get rid of relative pointers if we can define CURIes instead.

MJK: Not sure of value of relative pointers, blue tree not that deep. Alternative to curies is full URIs

CB, MJK: ... Discussion on JSON, other formats, machine vs human readability

NOTE Need a pretty printer

Tooling: https://github.com/interagent/prmd generates .md from JSON schema (perhaps no longer maintained)

NOTE: insert picture 2

The use of JSON pointers creates a weird dependency on the layout of concepts into files. We tend to think in terms of rolled-up files therefore, using a process that puts concepts into their right frame. We might as well make that a feature and stop thinking in terms of file. Bye-bye JSON pointer.

KH: Definitions of reusable Actions, Properties, Events, Data, and Objects should be placed (logically) into output namespaces and (physically) into input files. Input Files and output namespaces should be orthogonal: Definitions placed into the same output namespace can be spread over multiple input files; definitions placed into the same input file can be spread over multiple output namespaces. (Referencing a definition involves specifying the namespace, class name?, and definition identifier. Resolving references requires building an index of all the definitions across all namespaces.)

We ingest all the JSON files, index the definitions there. How does a key with an entry in the index look like? Can still use JSON pointer with classname/identifier.

*with CURIEs:*

{
  "odmInfo": {
    "copyright": "Copyright © Klaus 2020"
  },
  "odmCurie": {
    "z": "http://zcl.example.com/zcl",
    "c": "http://odm.example.com/common"
  },
  "odmNamespace": {
    "z:": {
      "odmObject": {
        "foobar": {
          "odmAction": {
            "startTheDay": {
              "odmRef": "c:#/odmAction/reset"
            }
          }
        }
      }
    },
    "c:": {
      "odmAction": {
        "reset": ...
      }
    }
  }
}

*without CURIEs:*

{
  "odmInfo": {
    "copyright": "Copyright © Klaus 2020"
  },
  "odmNamespace": {
    "http://zcl.example.com/zcl": {
      "odmObject": {
        "foobar": {
          "odmAction": {
            "startTheDay": {
              "odmRef": "http://odm.example.com/common#/odmAction/reset" 
            }
          }
        }
      }
    },
    "http://odm.example.com/common": {
      "odmAction": {
        "reset": ...
      }
    }
  }
}

*to placate people with vertical screens:*

{
  "odmInfo": {
    "copyright": "Copyright © Klaus 2020"
  },
  "odmCurie": {
    "z": "http://zcl.example.com/zcl",
    "c": "http://odm.example.com/common"
  },
  "odmNamespace": "z:",
  "odmObject": {
    "foobar": {
      "odmAction": {
        "startTheDay": {
          "odmRef": "c:#/odmAction/reset"
        }
      }
    }
  }
}

Resolve CURIEs during ingestion.

reconvene at 16:30

Compare Swagger DefaultResURI

Block 9: Intelligent Services

MJK: Processing loop, between Implementation, Atomic Service, Input, Output, Data Tensor.
Configure pipeline?

MJK: SDF construct for input/output, could be an action; CB: but with an action we would expect a physical result; MJK: So add a "procedure".

# Next steps

AP Chairs: Take unprocessed blocks above and make them a subject of a WISHI call.

AP MJK: For the blocks we did process today, come up with a number of items and create issues in the ODM github repo.

- Remove relative JSON pointers.
- Document the odmCurie "keyword".
- (info ➔ odmInfo?)
- Make examples that use CURIEs and RFC 6901 (absolute) JSON pointers
- Continue to use JSON pointers, but clean up namespaces
- Document the odmNamespace "keyword".
- Describe the processing model; rolling up of the files.

Need new prefix instead of ODM; SDF is about right except that things never stay simple. MDF (Model definition format)?

- every new version of sdf needs to come with a tool that converts from old sdf to new sdf.