Extend nodes with a description item

[oalt]

Extend the data structure for nodes with a description item. All other data types have such a description:

"description": {
            "type": "string"
}

I had missed that also in ReqIF, because when you implement tools and you have to verify that the generated data is correct, you have no possibility to store helpful information for human readers in the nodes. So the information in a nodes description item is not at first for a tool for display this information, but more for usage for testing and debugging purposes. Of course you can also use it to place helpful internal information for a different purpose at all.

[odungern]

@oalt : The idea of a node is not to carry any information payload, but to be a hook for ordering the resources which carry the information. In principle, nodes should not have a 'title' either. The only reason to provide a 'title' attribute is to allow showing a tree without looking-up every single resource. It is redundant, though.

Now, what is your intent for a 'description' attribute?

Perhaps, we should even remove the 'title' (as it is redundant) and copy it from the referenced resource on import, if the particular system needs it. In fact, this is what I propose.

[odungern]

@oalt : I had a look at the schema for nodes (in the context of removing the hierarchyClasses). The nodes neither have a title nor a description (even though I am using the titles all the time for performance reasons). But there is no restriction to add additional properties. Thus I suggest to keep the schema clean from redundant information, i.e. not to add title and description. If an implementation prefers to use a title to avoid looking up the titles from the referenced resources it is free to do it, but must manage the redundancy.

[odungern]

Rationale to add title and description everywhere is as follows:

• For example it makes sense to add a title to a node when storing a hierarchy in a database, because then a tree can be built without retrieving every single referenced object to look up their title.
• When creating a SpecIF file, it would be better to omit the title of nodes to avoid redundancy.
• In case of resources and statements title and description can be used in simple applications. Only if more elaborated properties are needed, the dataTypes and propertyTypes are declared and used for the instances.

Have a look at SpecIF schema v0.10.8 And have a look at SpecIF schema v0.11.8

[odungern]

'description' has been added to a node, see schema v0.10.8 and v0.11.8, but is not required.