[interfaces] Geo-Awareness: Observation API

[barroco]

This PR adds to the Geo-Awareness automated testing interfaces the observation endpoint. The interface is defined to be as close as possible to the ED-269 interfaces.

[BenjaminPelletier]

I think this endpoint will probably warrant some moderate additional discussion. I'd suggest we should avoid simple regurgitation tests -- USSPs will usually have wide latitude to use data in ways they consider appropriate and may, for instance, not retain all the information necessary to populate the full UASZoneVersion data structure, nor is there a requirement that I'm aware of that a USSP must be able to recite information they receive verbatim. We want to make sure not to impose any additional requirements on USSPs whenever possible since doing so would prompt USSPs to write custom code to satisfy those additional requirements -- in this case, they would presumably store the verbatim received data in a separate place than they store their comprehended version of that data, which is the opposite of what we want them to do in order to verify they obtained and comprehended the data correctly.

I think our geoawareness checks should be based on what USSPs are required to do with the geoawareness data they obtain. When we perform checks on the responses USSPs under tests provide, we should be able to quote the requirement the USSP necessarily doesn't satisfy when the check fails. I don't know of any requirement we could cite if a USSP was unable to repeat back the full original data format. For instance, if a USSP stored all geographic data as S2 data, it would process a circle into a large array of 64-bit values and wouldn't be able to reconstruct the fact that a group of those values are semantically a circle -- that seems like a reasonable implementation and we wouldn't want to penalize it.

My expectation is that USSPs will have requirements to do (or not do) certain things on the basis of geoawareness data, and that is the level at which we should test. So, for instance, if there is a requirement not to grant flight authorisations that enter restricted areas (my understanding is that this actually isn't currently a U-space requirement, but we can assume it is for the purpose of this explanation), then the real test should be whether a flight authorisation that intersects the restricted area is granted. To verify the requirement that USSPs interpret circle types correctly, I would expect the test to be something like "inject geoawareness data with just a circle, attempt to make flight authorisation that goes near the circle but not in, verify success; attempt to make flight authorisation that barely enters the circle, verify failure".

Based on this, I would expect the query to be something more like: "If I (the test directory, acting like a normal client operator) were to try to obtain a flight authorisation with this precise geometry, what would you (the USSP under test) do?" with the possible answers being things like "Don't grant the flight authorisation", "advise that the flight authorisation intersects a restriction", etc. The possible answers would be based on what the USSP was required to do by regulatory bodies. I don't think we would use the SCD "attempt to create a flight authorisation" endpoint because that is too heavyweight and too general -- instead, we could essentially assume that all other aspects of the flight authorisation have been satisfied and we know the flight occupies a particular set of volumes. That would isolate the influencing factors on the answer to the question to just geoawareness, and make this new endpoint specific to geoawareness.

If geoawareness requires the USSP to do something that doesn't relate to flight authorisations, we would want to capture that too. For instance, if a USSP were required to notify all its users when a certain geoawareness condition were satisfied, then we would want to add an endpoint where the USSP under test would report what notifications were dispatched to the virtual test director user.

[barroco]

@BenjaminPelletier, thank you very much for the input. I tried to dive into the requirements, please let me know what you think.

My expectation is that USSPs will have requirements to do (or not do) certain things on the basis of geoawareness data, and that is the level at which we should test.

I see three main sources of requirements:

• [1] U-Space regulation
• [2] NPA / Future AMC / GM
• [3] ED-269

Taking into account the following set of requirements (See below for excerpt):

1. U-Space regulation, Article 9
2. GM1 Article 9 Geo-awareness service (b)
3. GM1 Article 9 Geo-awareness service (c)
4. ED-269 - Data Model

Do you think the following scenario would be at the expected level of details?

UAS Operator requests geo-awareness information to the USSP for 
a geographical zone and time. The USSP returns a checklist of applicable 
airspace constraints, temporary restrictions and related operational conditions.

The detailed test coverage is described in this document .

In terms of interface, the following changes could be made to only require the minimal information:

1. Rename /geozones/query to /checklist
2. Properties of the request payload :
   1. airspaceVolume
   2. region
   3. startDateTime
   4. endDateTime
3. Properties of the reply payload
   1. array of zones with properties:
      1. identifier
      2. country
      3. name
      4. type
      5. restriction (U-Space Regulation Article 9 (a) )
      6. restrictionConditions
      7. region
      8. reason
      9. otherReasonInfo
      10. regulationExemption
      11. uSpaceClass (U-Space Regulation Article 9 (b) )
      12. message
      13. zoneAuthority
      14. applicability (U-Space Regulation Article 9 (c) )
      15. geometry (U-Space Regulation Article 9 (b) )
      16. extendedProperties
          Note that OpenAPI objects will have to be renamed to distinguish ED-269 Objects with this subset.

For reference:

U-Space regulation requirements for geo-awareness
Article 9 : A geo-awareness service consisting of the following geo-awareness information shall be provided to UAS operators:
(a) information on the applicable operational conditions and airspace constraints within the U-space airspace;
(b) UAS geographical zones, relevant to the U-space airspace;
(c) temporary restrictions applicable to airspace use within the U-space airspace.

GM1 Article 9 Geo-awareness service (b)
This service aims at supporting UAS operators to fulfil their obligations, as it provides the
information on applicable operational conditions and airspace constraints with the level of
accuracy and other performance requirements for which it has been certified.

GM1 Article 9 Geo-awareness service (c)
The geo-awareness service is used by the UAS flight authorisation service as a source of data to
inform UAS operators of relevant operational constraints and changes both prior to and during
the flight.

[barroco]

@BenjaminPelletier, apologies for my reply above. I just realized that this solution is still mostly regurgitating the geo-awareness dataset and it would deserve a bit of clarification.

I tried to start from the regulatory requirements to build the minimal test which would satisfy Article 9. My understanding of the three references mentioned above is that decisions based on geo-awareness are left to the operator and not the USSP (Please let me know if I misunderstood it). Then, I am expecting that the USSP should be able to return at least some information to the Operator and therefore, store it. In that case, the minimal response would look like the one of the previous reply.

One scenario could be with your wording :

If I (the test directory, acting like a normal client operator) were to request a briefing checklist with this precise geometry, what would you (the USSP under test) return ?

Now, to address GM1 Article 9 Geo-awareness service (c), "... changes both prior to and during
the flight." requirement, would it be sufficient in your opinion to test the ability of the USSP to handle and expose updates ? In that case, I would expect that it could be addressed by the test driver (TD) and the geozone_sources endpoint:

1. TD instructs the USSP under test to load dataset 1
2. TD queries /checklist endpoint of USSP under test and check prior flight checklist.
3. TD instructs the USSP under test to load dataset 2 with expected update.
4. TD queries /checklist endpoint of USSP under test and check that the checklist has been updated.

I hope it clarifies my thoughts.

[BenjaminPelletier]

My understanding of the three references mentioned above is that decisions based on geo-awareness are left to the operator and not the USSP (Please let me know if I misunderstood it)

Yes, agreed -- geo-awareness does not prescribe any decisions IIUC.

I am expecting that the USSP should be able to return at least some information to the Operator [...]

Yes, I think this is the core purpose of geo-awareness.

[...] and therefore, store it.

I think that's probably fair generally (in that the USSP is able to respond to the test director as if they were a user), but I don't think there is a requirement for the a USSP to store or communicate geo-awareness information in the original format that it was received, which is what I think may be implied here.

In that case, the minimal response would look like the one of the previous reply.

I think this is the main question. According to the regulation, it is clear that the geo-awareness service must provide certain geospatial information to the operator. But, it doesn't say this information has to be provided in a particular format, and for good reason: the original format is text with JSON encoding which would be borderline unreadable to a human. Instead of providing the information in the original format, most applications designed to serve human operators will likely render that information as colored pixels and provide the geospatial information to a human in the form of colored pixels. Automated operators may need the information rendered within a native planning grid, like S2 or H3 cells that are similar to what are usually slippy tiles displayed to a human. I don't think we can say that all USSPs which successfully provide geospatial information to the operator per the regulation necessarily retain the original form of that data after ingestion, which means they may not be able to populate the minimal-information data model 2 comments up.

So, how can we tell if a USSP successfully "provided" geospatial information to the operator? My suggestion is that 1) every operator, human or automated, must always have some concept related to the idea of what geospatial information is applicable to a particular operator for a particular geospatial point. For a human using a GUI, the geospatial point would map to a pixel which would have to be colored/annotated a certain way based on the geospatial information to effectively "provide" that information to the operator. I then suggest that 2) every operator, human or automated, must be able to answer whether there is applicable/relevant geospatial information present in a particular viewport regardless of representational format. I suggest that these two assumptions are sufficient to test all the requirements to provide applicable/relevant geospatial information to the operator with appropriate test data sets. The general idea would be:

A. Many test points should be chosen to be inside and outside the geospatial test data features, and the checks would be that a feature is indicated when the point is inside an applicable/relevant feature and not indicated when the point is outside the applicable/relevant feature
B. Multiple operator/operation configurations should be chosen to trigger operator/operation-based applicability of features, and the checks would be that a feature is indicated when the feature is applicable/relevant to the operator/operation and a feature is not indicated when the feature is not applicable/relevant to the operator/operation

This probably suggests an update from my previous summary: "If I (the test director, acting like a normal client operator) were to request information at this specific point, would you (the USSP under test) indicate that there are any applicable operational conditions or airspace constraints, relevant UAS geographical zones, or applicable temporary restrictions?" The expected answer would simply be "yes" or "no". From a practical perspective, we'd probably want to batch a bunch of these questions into one /checklist (or whatever we name the endpoint) HTTP call.

[changes both prior to and during the flight requirement:] would it be sufficient in your opinion to test the ability of the USSP to handle and expose updates ?

Your sequence looks good to me.

[barroco]

Thank you for the clarification regarding the various ways of storing geoawareness information.

I suggest that these two assumptions are sufficient to test all the requirements to provide applicable/relevant geospatial information to the operator with appropriate test data sets.

Ok, makes sense and I agree with the general idea (A and B).

"If I (the test director, acting like a normal client operator) were to request information at this specific point, would you (the USSP under test) indicate that there are any applicable operational conditions or airspace constraints, relevant UAS geographical zones, or applicable temporary restrictions?"

Sounds good.

Based on your suggestions, I would propose the following changes to the interface supporting batch queries:

1. Rename /geozones/query to /geozones/check
2. Properties of the request payload :
   1. airspaceVolume
   2. uSpaceClass
   4. acceptableRestrictions*: PROHIBITED, REQ_AUTHORISATION, CONDITIONAL and/or NO_RESTRICTION
   5. startDateTime
   6. endDateTime
3. Properties of the reply payload :
   1. applicableUASZone: boolean
   2. errorMessage: in case of error, human-readable message

A batch version of the endpoint would wrap requests and replies in sorted arrays.

[barroco]

As discussed, airspaceVolume will be replaced by a 3d position to simplify checks. This may be changed in the future if the need for checking volumes is required by test scenarios.