Add pre-deployment edge cloud zone viability discovery

[dimitrisgiannopoulos]

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Adds a planning-oriented Optimal Edge Discovery operation:

POST /retrieve-viable-edge-cloud-zones

The new operation lets API consumers evaluate which edge cloud zones are viable candidates for one or more target areas and an application profile before deployment, without requiring an active device or user session.

The API contract intentionally keeps the response at the public planning-abstraction level. It does not expose UPF, DNN, S-NSSAI, routing policy, topology, or other operator-internal details, and estimated metrics are documented as planning indicators rather than runtime guarantees.

This branch was prepared from the r1.2 tag.

Main additions:

• retrieveViableEdgeCloudZones operation
• PreDeploymentEdgeDiscoveryInfo request schema
• PreDeploymentEdgeDiscoveryResponse response schema
• EdgeCloudZoneViability candidate result schema
• target area, edge cloud zone criteria, network operator criteria, pricing tier, and latency estimate schemas
• request and response examples
• reusable EdgeCloudZoneStatus schema extracted from the existing inline status definition

Example request:

{
  "targetAreas": [
    { "areaId": "patras" },
    { "areaId": "athens" }
  ],
  "applicationProfileId": "2fa85f64-5717-4562-b3fc-2c963f66afa0",
  "edgeCloudZoneCriteria": {
    "edgeCloudRegion": "gr-west-1",
    "edgeCloudProviders": ["EdgeCo Neutral Host"]
  },
  "networkOperatorCriteria": {
    "pricingTiers": ["STANDARD", "PREMIUM"]
  },
  "maxResults": 4,
  "includeNonViableCandidates": false
}

Example response excerpt:

{
  "applicationProfileId": "2fa85f64-5717-4562-b3fc-2c963f66afa0",
  "validUntil": "2026-05-19T12:15:00Z",
  "areaResults": [
    {
      "targetArea": { "areaId": "patras" },
      "edgeCloudZoneViabilities": [
        {
          "edgeCloudZone": {
            "edgeCloudZoneId": "4f7b5555-6457-4890-9d4e-1dc79f44ab66",
            "edgeCloudZoneName": "GR West Zone A",
            "edgeCloudProvider": "EdgeCo Neutral Host",
            "edgeCloudRegion": "gr-west-1",
            "edgeCloudZoneStatus": "active"
          },
          "viability": "VIABLE",
          "networkOperatorCommercialInfo": {
            "pricingTiers": ["PREMIUM"]
          },
          "estimatedMetrics": {
            "latencyEstimate": {
              "p50LatencyMs": 8,
              "p95LatencyMs": 14
            }
          }
        }
      ]
    }
  ]
}

Which issue(s) this PR fixes:

Issue #35

Special notes for reviewers:

The repository does not currently include a local CAMARA Commonalities schema file, so Area is included as a local placeholder with a TODO to replace it with the Commonalities Area schema once imported.

Changelog input

release-note
Added pre-deployment edge cloud zone viability discovery operation for planning viable edge cloud zone candidates by target area and application profile.

Additional documentation

This PR updates the OpenAPI definition inline with operation and schema descriptions.

docs
OpenAPI examples added for the new pre-deployment viability operation.

[DLondonoD]

Thank you, @dimitrisgiannopoulos, for your contribution. I would like to raise the following point for your consideration and for the other contributors as well:

CAMARA recognizes that aggregators can expose CAMARA APIs directly, as well as their own enriched products built on top of CAMARA APIs. In its current form, this proposal appears to provide its greatest value when exposed by an aggregator, which makes me wonder whether it may be leaning toward the kind of functionality that would be better positioned as an aggregator-enriched product.