Parser standard output

[sculpt0r]

Hi :)

Since we talk about some standardized output from parsers, i thought it would be nice to have some place to talk about it.

[sculpt0r]

I thought it would be nice to keep somewhere in this 'P3-format' information about source file (and line) where certain tags/markers where found during parsing. It will be easier to debug or even use it as source links in the output 'view'.

Not sure if that is sth we want right at the beginning or rather it can wait?

WDYT?

[koksyn]

IMO, the soon the discussion about it will start probably the better, even if we did not start implementation of it yet.

I agree with you to keep the source information in the metadata, indeed this can help in debugging and navigating in the visualization tools (e.g. in the IDE)

[technites-pl]

My initial idea was to treat language structures (classes, methods, etc.) as model elements. This kind of elements can have link to certain place in the source code (as a property). Other elements e.g. domain model building blocks can have relation to language structures (relation is implemented by) and thus we can find related places in the source code.

[technites-pl]

Debugging info (e.g. where certain annotation was found) is another thing. It's also important but I'm not sure if it should be placed in the standardized model.

[sculpt0r]

Does it mean, you want to auto-collect information about classes and methods, even when they are not tagged? And they will be used as some 'low-level' elements?

[technites-pl]

Yes, because classes and methods are important elements in technical perspective.

Of course they are not the main purpose of creating documentation because most often if we need such low level information we look directly into the code. However sometimes visual representation is better, e.g. graph of calls between classes for some use case. It may be especially useful for legacy code.

I think we should collect information about code structures even if we can't link it with domain model (because of lack of proper metadata). It can be also useful to visualize misalignment between domain and technical perspective.

[koksyn]

Here: https://github.com/P3-model/P3-model we have described meta-models, their attributes, etc. in Markdown text description format, so maybe this repository is also the right place to store the schema for standardized output 'P3-format' for parsers as well?

[technites-pl]

Yes, everything that is not platform / language specific should be placed in the main repository.

I've started describing meta model here: https://github.com/P3-model/P3-model/blob/main/MetaModel.md

I've also started to describe elements on separate branch: https://github.com/P3-model/P3-model/blob/feature/elements/Elements/Elements.md Now it's only draft of description structure but I'll be back to work on this soon.

[koksyn]

The second thing we should also consider is a notation for the schema of the output 'P3-format'.

I would propose using JSONSchema (https://json-schema.org/) to describe the schema, which will be used to validate an output model in JSON. I used this approach in practice in another project and it covered all its needs, maybe it will work here too.
Of course, there might be another solution out there (for Yaml, XML, and so on), feel free to propose yours ;)

[sculpt0r]

IMO: creating XML from code is always PITA... I would also use JSON.

C# and JS should be fine with this format. Not sure how about Java?

[koksyn]

In Java environment, the JSON notation is also widely used in plenty of serializers

[technites-pl]

For me JSON is also the best solution.
Creating schema for automatic validation will be a great option. We can develop this schema alongside the meta model and elements' descriptions.

[technites-pl]

I've prepared first version of standard json output.
I think it should be as simple as possible. P3 Model can be of course represented as graph but I think that standard output shouldn't be based on any graph notation. Converting P3 Model to graph should be on visualization tool side.

In P3 we have three main abstractions: elements, relations and traits (see: https://github.com/P3-model/P3-model/blob/main/MetaModel.md). Thus we need three arrays in root json object:
{ "Elements": [], "Relations": [], "Traits": [] }

Elements, Relations and Traits can be of many different types (e.g. Elements: DomainModule, DeployableUnit; Relations: DomainModule.ContainsBuildingBlock, DomainModule.IsDeployedInDeployableUnit, etc.). Each type can have its own set of properties. Thus we need $type property for each json object.
{ "$type": "DddAggregate" "Name": "Order", ... }

Each Relation represents single connection between two Elements (source and destination). We do not need to duplicate Elements' data in Relations so only $id + $ref properties are needed.
{ "$id": "1" "Name": "Order", ... }
{ "$id": "136", "Source": { "$ref": "1" }, "Destination": { "$ref": "7" }, ... }

What do you think about that?

[technites-pl]

Sample output file for DDD starter repository: model.txt
I don't know why GH doesn't support json so it's txt.