Skip to content

Align Population Density Data with Commonalities 0.9.0 (r4.4) #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jgarciahospital merged 1 commit into from
Sep 22, 2026
Merged

Align Population Density Data with Commonalities 0.9.0 (r4.4) #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 67 additions & 65 deletions code/API_definitions/population-density-data.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
openapi: 3.0.3

Check notice on line 1 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

externalDocs.description must match the DG template 

[P-039] externalDocs.description in code/API_definitions/population-density-data.yaml is 'Product documentation at CAMARA.' — expected 'Product documentation at CAMARA' | Suggestion: Set externalDocs.description to exactly "Product documentation at CAMARA".

Check warning on line 1 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

CloudEvent type format is wrong 

[P-015] No event type enum values found in code/API_definitions/population-density-data.yaml — subscription APIs should define EventType schemas | Suggestion: Define a named event type schema (e.g. ApiEventType) that constrains the CloudEvent `type` value via allOf, rather than inlining the enum directly in CloudEvent.properties.type.enum. See the implicit-events API template in Commonalities artifacts/api-templates/ (tracked in camaraproject/Commonalities#608).
info:
title: Population Density Data
description: |
Expand Down Expand Up @@ -112,21 +112,31 @@
The standard behaviour of the API is synchronous, although for large
area requests the API may behave asynchronously. An API invoker can enforce
asynchronous behaviour by providing a callback URL (`sink`)
in the request, in this case the API sends a callback
in the request; in this case the API sends a callback
to the callback URL provided with the result of the request. If `sink` is
included, it is RECOMMENDED for the client to provide as well the `sinkCredential`
property to protect the notification endpoint. In the current version,`sinkCredential.credentialType`
MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided.


For requests with a combination of `area`, `precision`, `startTime` and `endTime`
properties involving an amount of processing that cannot be processed synchronously,
the API returns the error response `POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE`.
Three different `422` error responses distinguish why a request cannot be served. They are
mutually exclusive and are evaluated in this order:

- `POPULATION_DENSITY_DATA.UNSUPPORTED_ASYNC_RESPONSE`: the API consumer requested the
asynchronous behaviour by providing `sink`, but the API provider does not support asynchronous
processing at all. This error depends only on the capabilities of the implementation, never on
the size of the request: it is returned even for a request small enough to be served
synchronously. The API consumer can retry the same request without `sink` to obtain a
synchronous response.

For requests with a combination of `area`, `precision`, `startTime` and `endTime`
properties too big for both synchronous and asynchronous processing, the API
returns the error response `POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST`.
- `POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE`: the combination of `area`, `precision`,
`startTime` and `endTime` involves an amount of processing that cannot be handled synchronously,
and asynchronous processing is not enabled. Unlike the previous error, this one depends on the
size of the request, so a smaller request would succeed.

- `POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST`: the combination of `area`, `precision`,
`startTime` and `endTime` is too big to be processed **even asynchronously**. Retrying with
`sink` does not help; only a smaller request does.

If an error happens during the asynchronous processing of the request. The API callback
will have property `status` with value `OPERATION_NOT_COMPLETED` as an error cannot be returned in the callback.
Expand All @@ -143,6 +153,7 @@
density information in the specified area.

<!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->

# Authorization and authentication

The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.
Expand All @@ -156,16 +167,18 @@
Therefore, the access to Population Density Data API is defined as Client Credentials - 2-legged. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the latest detailed specification of this authentication/authorization flow.

<!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->

# Additional CAMARA error responses

The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.
Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version.

As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
<!-- CAMARA:MANDATORY:additional-error-responses:END -->

<!-- CAMARA:MANDATORY:request-body-strictness:BEGIN -->

# Request body strictness

This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response.
Expand All @@ -176,7 +189,7 @@
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: wip

x-camara-commonalities: wip
x-camara-commonalities: 0.9.0
externalDocs:
description: Product documentation at CAMARA.
url: https://github.com/camaraproject/PopulationDensityData
Expand All @@ -187,7 +200,7 @@
variables:
apiRoot:
default: http://localhost:9091
description: API root

Check notice on line 203 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

apiRoot description should match standard text 

[S-023] apiRoot description does not match the standard CAMARA text.
tags:
- name: Population Density Data
description: Operations to retrieve population density information.
Expand Down Expand Up @@ -243,7 +256,7 @@
- $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
requestBody:
description: Population density data result.
content:

Check warning on line 259 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Notification must use application/cloudevents+json 

[S-035] Notification callback content type must include 'application/cloudevents+json', found: application/json
application/json:
schema:
$ref: '#/components/schemas/PopulationDensityAsyncResponse'
Expand All @@ -263,15 +276,15 @@
x-correlator:
$ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
'400':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic400'
$ref: '../common/CAMARA_common.yaml#/components/responses/BadRequest400'
'401':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic401'
$ref: '../common/CAMARA_common.yaml#/components/responses/Unauthenticated401'
'403':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic403'
$ref: '../common/CAMARA_common.yaml#/components/responses/PermissionDenied403'
'410':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic410'
$ref: '../common/CAMARA_event_common.yaml#/components/responses/SinkGone410'
'429':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic429'
$ref: '../common/CAMARA_common.yaml#/components/responses/TooManyRequests429'
security:
- {}
- notificationsBearerAuth: []
Expand Down Expand Up @@ -305,15 +318,13 @@
'400':
$ref: '#/components/responses/RetrieveLocationBadRequest400'
'401':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic401'
$ref: '../common/CAMARA_common.yaml#/components/responses/Unauthenticated401'
'403':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic403'
'404':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic404'
$ref: '../common/CAMARA_common.yaml#/components/responses/PermissionDenied403'
'422':
$ref: '#/components/responses/RetrieveLocationUnprocessableContent422'
'429':
$ref: '../common/CAMARA_common.yaml#/components/responses/Generic429'
$ref: '../common/CAMARA_common.yaml#/components/responses/TooManyRequests429'
security:
- openId:
- population-density-data:read
Expand Down Expand Up @@ -350,12 +361,14 @@
maximum: 12
default: 7
sink:
type: string
format: uri
maxLength: 2048
description: The address where the API response will be asynchronously delivered, using the HTTP protocol.
pattern: ^https:\/\/.+$
example: 'https://endpoint.example.com/sink'
description: |
The address where the API response will be asynchronously delivered, using the HTTP protocol.
Providing `sink` enforces the asynchronous behaviour of the API. If the API provider does not
support asynchronous processing, the request MUST be rejected with the error response
`422 POPULATION_DENSITY_DATA.UNSUPPORTED_ASYNC_RESPONSE` and no callback is delivered.
The API consumer can then retry the request without `sink` to obtain a synchronous response.
allOf:
- $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Sink"
sinkCredential:
$ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential"
required:
Expand Down Expand Up @@ -440,7 +453,7 @@
maxItems: 168
status:
$ref: '#/components/schemas/ResponseStatus'
statusInfo:

Check notice on line 456 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 512
description: Information about the status, mandatory when property `status` is `OPERATION_NOT_COMPLETED` for adding extra information about the error.
Expand All @@ -466,7 +479,7 @@
$ref: '#/components/schemas/OperationId'
required:
- operationId
OperationId:

Check notice on line 482 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: The unique identifier of the asynchronous operation that is returned when the operation is initiated.
Expand All @@ -485,25 +498,19 @@
- PART_OF_AREA_NOT_SUPPORTED
- AREA_NOT_SUPPORTED
- OPERATION_NOT_COMPLETED
TimedPopulationDensityData:

Check warning on line 501 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "TimedPopulationDensityData.description" property must be truthy

Check warning on line 501 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Array items must have a description 

[S-031] Array items must have a description
type: object
properties:
startTime:

Check warning on line 504 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "startTime.description" property must be truthy
type: string
format: date-time
maxLength: 64
description: >-
Interval start time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
and must have time zone.
example: "2023-07-03T10:00:00Z"
allOf:
- $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime"
- description: Interval start time.
example: "2023-07-03T10:00:00Z"
endTime:

Check warning on line 509 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "endTime.description" property must be truthy
type: string
format: date-time
maxLength: 64
description: >-
Interval end time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
and must have time zone.
example: "2023-07-03T11:00:00Z"
allOf:
- $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime"
- description: Interval end time.
example: "2023-07-03T11:00:00Z"
cellPopulationDensityData:
$ref: '#/components/schemas/CellPopulationDensityDataArray'
required:
Expand All @@ -529,7 +536,7 @@
properties:
geohash:
$ref: '#/components/schemas/Geohash'
dataType:

Check warning on line 539 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "dataType.description" property must be truthy
type: string
enum:
- NO_DATA
Expand All @@ -544,13 +551,13 @@
NO_DATA: '#/components/schemas/NoData'
LOW_DENSITY: '#/components/schemas/LowDensity'
DENSITY_ESTIMATION: '#/components/schemas/DensityEstimation'
NoData:

Check warning on line 554 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "NoData.description" property must be truthy
allOf:
- $ref: '#/components/schemas/CellPopulationDensityData'
LowDensity:

Check warning on line 557 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "LowDensity.description" property must be truthy
allOf:
- $ref: '#/components/schemas/CellPopulationDensityData'
DensityEstimation:

Check warning on line 560 in code/API_definitions/population-density-data.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Schema property must have a description 

[S-011] Property description is missing or empty: "DensityEstimation.description" property must be truthy
allOf:
- $ref: '#/components/schemas/CellPopulationDensityData'
- type: object
Expand Down Expand Up @@ -588,7 +595,6 @@
- Indicated `endTime` is earlier than the `startTime` ("code": "POPULATION_DENSITY_DATA.INVALID_END_TIME", "message": "Indicated endTime is earlier than the startTime")
- Indicated time period is partially in the past and partially in the future ("code": "POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD", "message": "time period is partially in the past and partially in the future")
- Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime) ("code": "POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED", "message": "Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime)")
- `sinkCredential.credentialType` is set to `PRIVATE_KEY_JWT` but no JWK Set is configured for the API consumer ("code": "PRIVATE_KEY_JWT_NOT_CONFIGURED", "message": "No JWK Set configured for PRIVATE_KEY_JWT authentication.")
headers:
x-correlator:
$ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator'
Expand All @@ -614,30 +620,15 @@
- POPULATION_DENSITY_DATA.INVALID_END_TIME
- POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED
- POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD
- PRIVATE_KEY_JWT_NOT_CONFIGURED
examples:
GENERIC_400_INVALID_ARGUMENT:
value:
status: 400
code: INVALID_ARGUMENT
message: Invalid input
$ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_400_INVALID_ARGUMENT"
GENERIC_400_INVALID_CREDENTIAL:
description: Invalid sink credential type
value:
status: 400
code: INVALID_CREDENTIAL
message: Only Access token or Private key JWT are supported
$ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_400_INVALID_CREDENTIAL"
GENERIC_400_INVALID_TOKEN:
value:
status: 400
code: INVALID_TOKEN
message: "Only bearer token is supported"
$ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_400_INVALID_TOKEN"
GENERIC_400_INVALID_SINK:
description: Invalid sink value
value:
status: 400
code: INVALID_SINK
message: sink not valid for the specified protocol
$ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_400_INVALID_SINK"
POPULATION_DENSITY_DATA_400_INVALID_AREA:
value:
status: 400
Expand Down Expand Up @@ -677,10 +668,12 @@
RetrieveLocationUnprocessableContent422:
description: >-
Problem with the client request. The following scenarios may exist:
- Indicated combination of area, time interval and precision is too big ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST", "message": "Indicated combination of area, time interval and precision is too big")
- Indicated combination of area, time interval and precision is too big for both synchronous and asynchronous processing, so providing `sink` does not help ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST", "message": "Indicated combination of area, time interval and precision is too big")
- Indicated cell precision (Geohash level) is not supported ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION", "message": "Indicated cell precision (Geohash level) is not supported")
- Indicated combination of area, time interval and precision is too big for a sync response ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "Indicated combination of area, time interval and precision is too big for a sync response")
- Indicated combination of area, time interval and precision is too big for a sync response and asynchronous processing is not enabled ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "Indicated combination of area, time interval and precision is too big for a sync response")
- `sink` is provided but the API provider does not support asynchronous processing at all, whatever the size of the request ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_ASYNC_RESPONSE", "message": "The API provider does not support the asynchronous processing")
- The requested `areaType` is not supported by the MNO ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE", "message": "The requested areaType is not supported by the MNO")
- `sinkCredential.credentialType` is set to `PRIVATE_KEY_JWT` but no JWK Set is configured for the API consumer ("code": "PRIVATE_KEY_JWT_NOT_CONFIGURED", "message": "No JWK Set configured for PRIVATE_KEY_JWT authentication.")
headers:
x-correlator:
$ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator'
Expand All @@ -700,9 +693,13 @@
- POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION
- POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE
- POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE
- POPULATION_DENSITY_DATA.UNSUPPORTED_ASYNC_RESPONSE
- PRIVATE_KEY_JWT_NOT_CONFIGURED
examples:
POPULATION_DENSITY_DATA_422_UNSUPPORTED_REQUEST:
description: >-
The request is too big to be processed even asynchronously, so retrying it with sink does not
help. Only a smaller request does
value:
status: 422
code: POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST
Expand All @@ -725,12 +722,17 @@
status: 422
code: POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE
message: The requested areaType is not supported by the MNO
GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED:
description: Private key JWT sink credential type is used but no configuration was pre-shared
POPULATION_DENSITY_DATA_422_UNSUPPORTED_ASYNC_RESPONSE:
description: >-
The API consumer requested the asynchronous behaviour by providing sink, but the API provider
does not support asynchronous processing. Unlike UNSUPPORTED_REQUEST, this error does not depend
on the size of the request
value:
status: 422
code: PRIVATE_KEY_JWT_NOT_CONFIGURED
message: No JWK Set configured for PRIVATE_KEY_JWT authentication.
code: POPULATION_DENSITY_DATA.UNSUPPORTED_ASYNC_RESPONSE
message: The API provider does not support the asynchronous processing
GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED:
$ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED"
examples:
PopulationDensitySupportedAreaResponseExample:
description: Population density supported area response example
Expand Down
Loading
Loading