eclipse-tractusx / eclipse-tractusx/bpdm

Pool: Expand Admin Area Property in Legal Form Response

Open
#1,686 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.