add the concept of flexibility zone which is required for the Portuguese demo

[cdmNSIDE]

• A flexibility zone must contain:
  • an id
  • a sensitivity
  • a flexibility need
  • a list of portfolios
• Creation of new endpoints to create / get / update / delete the flexibility zones (should be only accessible to the DSO)
• Creation of a new endpoint to get only some information about the flexibility zone (i.e. the list of portfolios), because it's the only information that is visible to the aggregator
• Creation of a new endpoint to create a trade (so that the aggregator can create the trade of the disaggregated orders)
• Expected workflow:
  1. During the registration phase, the FSP will create portfolios for the different assets and indicate in which physical grid zone those assets are located, and post those portfolios on the market platform
  2. The DSO will get those portfolios
  3. The DSO will create several flexibility zones, i.e. groups of portfolios with different sensitivities and flexibility needs. Those flexibility zones do not correspond to a physical zone of the network (that's why we can't use the concept of grid node). The DSO will post those flexibility zones on the market platform
  4. The aggregator will get the list of portfolios in each flexibility zone
  5. The aggregator will build an aggregated order for each zone, and post this order on the market platform (the order is associated to a flexibilityZoneId, no gridNodeId, no portfolioId)
  6. The market platform will launch the clearing
  7. The aggregator will get the trades of the aggregated order
  8. The aggregator will create the trades of the disaggregated orders and post them on the market platform
  9. The DSO will get the get the trades of the disaggregated orders

[narve]

Hi,

first of all: This is functionality that NODES will not support, and we don't have very strong opinions on these endpoints. In our server they will simply throw a suitable error (FlexilibityZonesNotSupported or something like that).

Further comments below:

[narve]

Nested/hiearchical endpoints, in this case /FlexibilityZones/portfolios: I generally don't recommend them. In real life they usually turn out to become messy, as most data models can be accessed through multiple "paths". If we were to use them, they should be more fully "pathified", e.g. /FlexibilityZones/{flexibilityzoneId}/portfolios.

So far we've used a flatter hiearchy for all other data models. I would therefore prefer something like /FlexilibityZonePartialSearchResult?flexibilityZoneId=xxx. This would make our URL structure more consistent.

[narve]

Partial search results: This is also a somewhat contended / problematic area. There are already cases were information will be partially hidden from the search results. We've chosen to not add separate "limited" datatypes for all these cases, as this will lead to an explosion in the number of data models. Instead, we hide fields by setting them to NULL in cases were the recipient is not allowed to see them. This already applies to Orders and to Trades.

I propose that you use the same methodology for the flexibility zones. Then you can reuse the same data model (FlexibilityZone) and endpoint (/FlexibilityZones), and you can just add in the description field that not all fields will be visible to all recipients.

Again, we are not going to implement it so it does not really matter to us, but it makes the OpenAPI spec longer and harder to read (and to implement, even if it is just to throw correct exceptions). Also it makes it inconsistent.

If you decide to keep it, I suggest a more generic term and enpoint as well - maybe just a /PortfolioList?flexibilityZoneId=xxx (possibly other query params?) returning either just a string[] of portfolio-ids, or (better) a PortfolioListSearchResult containing an Items which is a string[] of ids.

[cdmNSIDE]

Thanks for your comments Narve! I will check with my colleagues what are the changes we want to apply and will post the modification here

[cdmNSIDE]

Hello @narve , What do you think of the new version ?

• I removed the resource called ListFlexibilityZones and added instead a field called equivalentPerimeterId in the resource called FlexibilityZone
• I prefer to keep 2 different endpoints to retrieve FlexibilityZones and PartialFlexibilityZones, but I made some modification to avoid nested endpoints.

[narve]

I am sorry my review is a bit delayed, I wanted to discuss this in the meetings but the topic never came up.

First of all: This PR also introduces the "Clearing" type, which is new to me. I would suggest adding at least a description of what a clearing is, and also consider renaming it.

Furthermore, the difference between FlexibilityZone and PartialFlexibilityZone is, as far as I can see, only that the property "flexibilityNeed" is not included?

If so, I strongly suggest merging these two objects. There are several other places / data types where not all requests will return and/or require all properties of all data. This could be due to several reasons, security restrictions being one of them.

If we were to create separate types for each of these cases that would cause an explosion in the number of schemas.

Consider e.g. the POST operation - when you create a new object, e.g. Order, you don't typically specify the "id" property. But we choose not to add a separate "CreateOrder" or "OrderCreation" model for this case.

For consistency, I recommend the same approach here.

[narve]

However, if you do need to have them as separate object types, I suggest using the OpenAPI operators allOf.

Using allOf, one can make one model (FlexibilityZone) "extend" another (PartialFlexibilityZone, or preferrable a more descriptive name like e.g. "PublicFlexibilityZone" - partial does not say much). This means that FlexibilityZone should contain all properties of PartialFlexibilityZone, in addition to its own properties (flexibilityNeed in this case).

This will reduce the code duplication and ensure consistency.

[narve]

Using this approach one can also modify the endpoints to specify what they return, using oneOf:

One can say that the /FlexibilityZones endpoint returns an array of either FlexibilityZone or PartialFlexibilityZone. This removes the need for extra endpoints.

We could use this approach for various other endpoints as well... but we don't time to make things perfect :)

In addition, the code generator tools will typically generate more code, usually quite bloated, so I don't recommend this approach in all cases.

[cdmNSIDE]

Hello @narve I have removed the notion of Clearing because we finally don't need it. I still need to work on your other comment ;)

[cdmNSIDE]

Hello @narve. The PartialFlexibilityZone has been removed. We will indeed work with the authorization stuff to handle the specific case where the FSP can not have access to the flexibility need. I did not write anything about that in the UMEI as it is too specific.

This PR is ready for a final review

[cdmNSIDE]

Hi Narve, This PR can be merged and then closed :)