Create a first draft of the format specification

[adiherzog]

[adiherzog]

I am currently working on a first version based on https://github.com/scenarioo/scenarioo/wiki/Scenarioo-Writer-Documentation-Format.

and

https://github.com/scenarioo/scenarioo/tree/develop/scenarioo-docu-generation-example/src/test/resources/example/documentation/scenarioDocuExample/wikipedia-docu-example

[tobiaszuercher]

nice.

i've changed the field definition to a table layout in a PR. i don't have permissions to write directly to the repo. can you pls give me permissions?

[bruderol]

:+1: nice

[bruderol]

I started to describe the generic Scenarioo object model to be used in the new format, that we discussed last monday in the design meeting with @tobiaszuercher @felixmokross @dola - will post it soon here.

[bruderol]

@scenarioo/scenarioo-devs I documented an inital draft of the new "Scenarioo Object Model" for the new format here:

https://github.com/scenarioo/scenarioo-format/blob/master/scenarioo_object_model.md

Pleae review it and give your feedback here or by directly changing my documentation.

This draft of the model is based on the discussion we had last monday together with @tobiaszuercher @felixmokross and @dola

Thank you all for the very good meeting, I hope you like my proposal (should be more or less what we discussed, I only improved it a little bit)

[bruderol]

@scenarioo/scenarioo-devs I will present this initial design on wednesday at the meeting. If anybody has some feedback on this, please bring it up now. After we will start to plan implementing this new format.

[dola]

If I remember correctly, we discussed that the main difference between properties and items (apart from the latter being rendered as child nodes) is, that properties have a key and labels don't; i.e. they are a list of child elements rather than a key-value mapping of those. With the change to flatten the objects so that the labelKey is directly in the properties object, this difference is no longer transparent in the json files. I'm not sure if it makes sense for items to have a labelKey but in the old format they never do. (IIRC) However this is a small difference that we could easily adapt and discuss again. Thank you for the detailed specification and explanation of the new format draft. I think we came up with a viable and robust new format.

[bruderol]

@dola Yes, thank you for the feedback. But when I rethought about it, I found out, that it is not true, that items can not have a labelKey. The difference here is, that for items it is not required, but can also be helpful. See the picture with the comparison of our model to UML object models, as you can see there, also the relations to other objects (=items) can have a labelKey (see the dependency to the SQL database in the example).

You could also think of it as follows in tables of objects (one possible metaphor to explain our model, apart from the UML object model metaphor):

• properties of an object are the attributes that you would display as columns in a table, where a collection of objects is displayed (each object is a row, each property is a column, the labelKeys are the captions of the columns as well as the identifiers into which column an attribute belongs)
• items on the other hand are sub-items of an object (relations to more other objects, just like use cases that have scenarios as contained or related items), they could be displayed in a table as well, but here each item is a row on its own in this table, and the properties of this items are again the columns. So what is the labelKey of such items then, you might ask? And it is quite simple: it is just a special row identifier column in this items-table. So e.g. it could just be the row number (for items of an object that have a well defined order, e.g. as for service calls that are called in a well defined order), or it could be just used to name the relations of sub items, if you have different kind of sub items. Since the model is very generic here, the user is very free on how to use this labelKey on its items of an object, and it is very optional to use it for things like that.

Is that okay for you? Does that make sense?

[bruderol]

we reviewed this in the dev meeting, and I consider the Object Model as finalized https://github.com/scenarioo/scenarioo-format/blob/master/scenarioo_object_model.md

The rest of the format needs improvements concerning following open points:

• finalize documentation with missing fields
• format for identifiers and labels (I would recommend to disallow spaces as well! but it seems to be allowed for labels?? shouldnt this format be the same)
• document which names need to be used for directories
• define logic for libraries how they have to calculate the identifier fields (I propose to simply replace all unallowed characters by _ and to replace a row of multiple _ by only one). if there are identifier clashes, that is just the users bad luck, he should use better names/values for his things or defined ids explicitly.
• format for dates needs specification (probably just usual iso date-time)
• document everything more nicely (finalize documentation of all fields)
• make a new uml model graphic for the format
• decide whether we want to allow labelsalso everywhere (even on objects?).

[bruderol]

I started planning the format 3.0 a little bit more detailed.

See here: https://huboard.com/scenarioo/scenarioo#/?repo=%5B%22scenarioo-format%22%5D

• Important open points have become its own issue
• The ready issues are the ones that we should finalize on the first day of the Coding Days
• All issues are ordered by priority

I think that we should try to set the following goals for the coding days:

• day 1: format is clearly specified and documented and agreed upon, some prototype implementations to verify the technologies to use for the implementation are done
• day 2: the writer libraries are implemented and the server can read the new format
• day 3: the webapplication (frontend!) is adjusted to new format 3.0, all writer libraries are conveniently useable and documented, also migration guides and migration tool are finalized

[bruderol]

The initial proposal is considered finalized, There is a full example under example. Docu needs to be cleaned up, see #7