Project structure and package name

[relu91]

We have to decide:

• the npm root name and the subprojects.
• README already mentions a list of possible projects but what is the directory structure?
• Is gitsubmodules still an option? or npm workspaces?
• Understand dependencies between tools

[egekorkan]

• Unless we observe a lot of dependency between different tools, we do not need something like npm workspaces or something similar.
  • We should allow tools to even have different versions if there is no tight dependency between them.
• We do not need gitsubmodules since we want to copy everything here
• For the folder structure, I have a couple of ideas I can list below:
  1. We have a top level folder that has programming language in the name, e.g. node-packages, python-packages . We do not have multiple languages at the moment but it is good to have stable links for the future.
  2. Same as above but without programming language. Only after going into the tool folder, one understand the language. The end user never sees a difference if we distribute executables anyways.
  3. We categorize the tools based on their purpose, i.e. if there is one validator in Node.js and in Python, there can be a validators folder and then node and python folders within them.
• Dependencies between tools:
  • Playground
  • core (validation component) depends on node-wot thing model helpers (see here)
  • TD Default add/remove depends on core for tests so it is a dev dependency here
  • JSON Spell Checker: no dependencies.
  • TD to AsyncAPI: dependency to defaults so that the unknown fields are added before conversion. This can be left to the developer so the dependency can be removed.
  • TD to OpenAPI: no dependency but similar situation to above
  • node-wot td-tools:
  • aid tools: No dependency to others in this list, only dependency are some util-like tools under td-tools. When we move to td-tools, node-wot/td-tools can be a dependency.
  • thing-model-helpers: No dependency to others in this list but if better TM validation is needed, there might be dependencies to core/validator package of playground. When we move to td-tools, node-wot/td-tools can be a dependency.
  • In this case, we need to find a way to remove td-tools from node-wot as a package but keep the functionality in other places.

[egekorkan]

@danielpeintner will detail what the other scripts within node-wot/td-tools do

[danielpeintner]

Please find below a proposal how to restructure "td-tools" related code:

• eclipse-thingweb/node-wot
  • remove folder eclipse-thingweb/node-wot/packages/td-tools entirely
  • eclipse-thingweb/node-wot/packages/core should link to eclipse-thingweb/td-tools/node/foundation (see newly created package below)
• eclipse-thingweb/td-tools
  • create project eclipse-thingweb/td-tools/node/foundation (all open for a better name) with
  • thing-description.ts
  • td-parser.ts // maybe rename it since it is a serializer as well or split the functionality
  • resolver-interface.ts // not sure whether we actually need this interface used by helpers and thing-model
  • td-helpers.ts // has little functionality, maybe can be moved into node-wot/core
  • create project eclipse-thingweb/td-tools/node/thing-model with
  • thing-model-helpers.ts
  • create project eclipse-thingweb/td-tools/node/aid with
  • asset-interface-description.ts
  • create other projects w.r.t. validation etc from playground ...

Any opinions/suggestions?

[egekorkan]

I quite like the proposal. The main confusing part is how to explain what the "foundation" package offers to outsiders so I am not able to provide an alternative name :/

[egekorkan]

• npm packages variations:
  • @eclipse-thingweb/td-tools/thing-model-helpers
  • @thingweb/td-tools/thing-model-helpers -> may not be allowed
  • @thingweb/td-tools-thing-model-helpers
  • @thingweb/thing-model-helpers
  • @thingweb/tm-helpers
  • @thingweb/node-wot-binding-http
  • @thingweb/node-wot-contrib-binding-x
  • Note: @ is not governed or restricted but we should check

Decision on renaming: we will have @thingweb/TOOL_NAME

[sebastiankb]

When will the new structure be applied?

[egekorkan]

When will the new structure be applied?

• I can move playground tools in one PR with renaming before January. For node-wot "foundation" package we need more discussion.
• thing-model should be called tm-helpers, foundation can be td-helpers if we want to.
• The goal is having one package that does "parsing", i.e. canonicalization by adding all needed defaults. This needed before consuming. It is validation + adding defaults imo.
  • There is a refactoring need. In node-wot, there are multiple places where validation and defaults happen. (parser, init exposed thing, bindings for protocol defaults)

[egekorkan]

In the meantime, @relu91 or @danielpeintner, could you document here or in node-wot how the td-tools are used within it? I think we need better understanding before committing to a direction.

[danielpeintner]

I sketched how I "see" the best way forward in https://github.com/eclipse-thingweb/td-tools/issues/3#issuecomment-1816398949 We (I) can try to describe next year ;-) the relations and it current usage...

[egekorkan]

node-wot td parser: Consuming:

• It corrects user inputs (if readonly is not boolean, it is corrected to boolean)
• Fills defaults

For the future, the core package can do this, meaning td-parser is not necessary for an outsider as a tool

• At the same time, we should align the default addition mechanism to use ajv and share the library between playground web and node-wot
• We can have a common validation library used after https://github.com/eclipse-thingweb/node-wot/blob/8adf8406c395e01fcd9d38f20af59aae96220182/packages/core/src/helpers.ts#L59
  • That line is doing a partial TD validation so it is not same validation as TD or TM validation.
  • There can be other users of clenaup style validation -> Going towards linting maybe https://stoplight.io/open-source/spectral ?

[egekorkan]

The overall structure is now applied. I will open new issues for default handling and validation