CDA-103 adr for handling location kind - #1755
Conversation
rma-bryson
changed the title
|
Met with @rma-bryson regarding this ADR. Guidance as follows:
|
a60af6a to
3a1a7ef
Compare
rma-bryson
changed the title
| Terminology | ||
| =========== | ||
|
|
||
| Location Kind Hierarchy |
There was a problem hiding this comment.
Qualify what this represents, is this the required fields for the current (not proposed)?
There was a problem hiding this comment.
There might also be a way to show the allowed relations in this table
|
|
||
| Marker | ||
| ------ | ||
| A location is "marked" as a specific Kind in the ``AT_PHYSICAL_LOCATION`` table, but does not have the corresponding metadata rows in specialized tables yet. The Kind in ``AT_PHYSICAL_LOCATION`` serves as the primary functional role indicator. It is no longer considered a marker-kind once the specialized kind-metadata is added to the corresponding kind table. |
There was a problem hiding this comment.
A term/name should be added for locations with the kind-specific metadata.
There was a problem hiding this comment.
Realized kind can be used here.
| ├── GATE | ||
| └── OVERFLOW | ||
|
|
||
| Marker |
There was a problem hiding this comment.
An alternative term that could be used instead of Marker is Declared.
| Behavioral Rules | ||
| ================ | ||
|
|
||
| Kind Transitions |
There was a problem hiding this comment.
It should be stated that transitions follow the allowed location kind relationships or are following the relationships
There was a problem hiding this comment.
"Based on the allowed relationships between location kinds, a location may transition from one kind to another as follows:"
| 1. **Current Behavior (New Rows Required)**: Currently, changing a Location's Kind in ``AT_PHYSICAL_LOCATION`` requires the creation of a new row in the corresponding ``AT_<KIND>`` table if it doesn't already exist. | ||
| 2. **Proposed Marker Support**: Under the proposed Marker system, the Kind in ``AT_PHYSICAL_LOCATION`` can be updated independently. If no specialized metadata row exists, the location is considered a "Marker" of that Kind. | ||
| 3. **Preservation of Existing Data**: Storing a new Kind marker should not automatically delete existing metadata from other kind-specific tables. A location that was a ``STREAM_GAGE`` and is now marked as a ``PROJECT`` should retain its gage metadata unless explicitly removed. Likewise, if transitioned to a ``SITE``, the specialized metadata rows for other Kinds should remain intact. | ||
|
|
There was a problem hiding this comment.
Overall, your listing of location kind transitions aren't actual transitions. This section should be revised to cover actual transitions if that is what you intend it to be. Don't remove the content you here as it is also valuable, you just aren't covering transitions. We want define the lifecycle of a location kind.
The ADR should define explicit invariants for valid location states. Can a location have one declared kind and multiple realized kinds? Should every realized kind be identified or does the marker identify only the primary kind? Which combinations are invalid? Which CDA database API enforces this? Transition should cover both successful transitions and rejected operations.
Cover what locations start as (Site or realized kind).
- start as Site
- start as realized kind
- can you start as marked?
Then cover transitions from a created location to marker and realized kinds.
- Cover the transition to be marked could a Site or realized kind that is being marked.
- Cover transition from marked as a kind to realized in that kind.
Then cover removals:
- Cover transition from marked to no longer being marked as a given kind. This could expose a realized location kind.
- Cover transition from realized to marked (if possible) or realized to no longer being that kind. Include row removals. This is a kind transition given it could be a rollback to Site or another set of marked/realized kinds. Can a location transition from realized to marker? Am I allowed to transition the kind to Site if I am realized as a Project? What portion of the API would prevent this transition? Certainly it would have to be the location portion? That also means the location portion of the API would have to know about the kind-specific sub-types in order to check if a location is realized or marked. Realized -> Site requires a deletion of the kind-specific row. Marker -> Site doesnt. This is further complicated given a location cane be marked as one type and realized as additional other types.
Lastly, conflicts or lacking functionality that is needed:
-
Add an item that identifies the need to catalog kinds given declared/marked kinds and realized kinds co-exist and currently all of the kinds that a location is marked/realized as are not obvious.
-
Add an item or discuss the conflict that covers at_physical_location currently only allowing a location to be declared/marked as one kind. Multiple markers are currently not supported. Is there value in being able to be marked as multiple kinds? Should we propose this feature?
|
|
||
| API Endpoint Expectations | ||
| ------------------------- | ||
| 1. **Filtering by Kind**: The general Location endpoint (getAll) should filter based on the Kind marker in ``AT_PHYSICAL_LOCATION``. This will not query against any at_<KIND> tables (This should be handled by kind-specified endpoints). |
There was a problem hiding this comment.
This expectation states that you can only filter to the marked kind (where you can only be marked as one kind) and you cannot filter as the realized kind. A marker can conceal a realized kind and a realized kind I would say has equal or more importance than designation as a marked kind given it defines metadata for the realized kind. Is this a reasonable decision to recommend?
| ------------------------- | ||
| 1. **Filtering by Kind**: The general Location endpoint (getAll) should filter based on the Kind marker in ``AT_PHYSICAL_LOCATION``. This will not query against any at_<KIND> tables (This should be handled by kind-specified endpoints). | ||
| 2. **Specialized Endpoints**: Kind-specific endpoints (e.g., ``/projects``, ``/streams``) must decide whether to return "marker-only" locations. | ||
| - *Proposed*: Marker-only locations should not be returned by specialized endpoints as they lack the required metadata. Specialized endpoints should only return locations with corresponding metadata rows in their respective tables. If a client needs to retrieve marker-only locations, a catalog endpoint could be introduced to allow for this behavior. |
There was a problem hiding this comment.
Can this catalog be elaborated on? Would it capture both marked and realized kinds for a location? If not - then how would that be accomplished? How would I query CDA to know all of the kinds (marked and realized) that define the location.
|
|
||
| Risks | ||
| ======================= | ||
| 1. **Data Integrity**: Allowing Kinds to exist without corresponding metadata rows may lead to confusion or misuse if not properly documented and handled in the API. |
There was a problem hiding this comment.
An additional concern is the singular relationship (1:1) when marked vs multiplicity (1:many) when realized.
2 participants
Summary
ADR for discussing handling of "marker" kinds
Related Issue
Relates to #1573
Checklist