eclipse-tractusx / eclipse-tractusx/bpdm
Pool: Expand Admin Area Property in Legal Form Response
- Dominant language
- Kotlin
- Stars
- 12
- Forks
- 28
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 41
Description
### Description
**As** a consumer of the Pool API,
**I want** the `administrativeAreaLevel1` field of a Legal Form to be returned as a structured object containing both a name and an ISO 3166-2 code,
**so that** it matches the data model defined in CX-0012 §1.5.2.5 and is consistent with how administrative area level 1 is represented everywhere else in the API.
CX-0012 §1.5.2.5 defines the Legal Form entity with an `Administrative Area Level 1` attribute of type **Administrative Area (Level 1)**, which is a structured object with two fields:
| Attribute | Type |
|-----------|--------|
| Name | String |
| Code | String (ISO 3166-2) |
The current implementation in `LegalFormDto` represents this as a plain `String?`:
```kotlin
// bpdm-pool-api/.../model/LegalFormDto.kt
val administrativeAreaLevel1: String?,
```
This flattens the structured object to a single string, losing either the name or the code depending on which value is stored. For comparison, `PhysicalPostalAddressVerboseDto` and `AlternativePostalAddressVerboseDto` correctly use `RegionDto` (which has `regionCode`, `regionName`, and `countryCode`) for their `administrativeAreaLevel1` field. `LegalFormDto` is inconsistent with both the standard and its sibling DTOs.
### Acceptance Criteria
- [ ] `LegalFormDto.administrativeAreaLevel1` is changed from `String?` to a structured type that exposes at minimum an ISO 3166-2 `code` (String) and a `name` (String), consistent with `CountrySubdivisionDto` or `RegionDto` already in the model
- [ ] The `LegalFormRequest` (used for `POST /legal-forms`) is updated accordingly so that the administrative area level 1 can be set with both code and name
- [ ] The database mapping / persistence layer for Legal Form is updated to store and retrieve the structured administrative area
- [ ] Existing legal forms with a plain string administrative area are migrated or the API documents backward-compatibility behaviour
- [ ] The generated OpenAPI specification reflects the structured type for `LegalFormDto.administrativeAreaLevel1`
### Additional Information
Reference: CX-0012 §1.5.2.5 Legal Form; §1.5.2.8 Administrative Area (Level 1).
The `CountrySubdivisionDto` (returned by `GET /administrative-areas-level1`) already models this as `{ countryCode, code, name }` and could be reused or referenced as the type for the Legal Form's administrative area field.
Contributor guide
Research direction
Start with bpdm-pool-api/.../model/LegalFormDto.kt and compare its field with CountrySubdivisionDto and RegionDto. Trace LegalFormRequest and the Legal Form database mapping, then inspect the generated OpenAPI output. Done means requests, persistence, responses, and API documentation expose the structured administrative area while addressing existing plain-string data.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- api, backend-api-design, database
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100