Apply term ownership to NLDI, NGWMN, and WQP prose
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 68/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- python
- Domain
- documentation
Research direction
Start with ADR 0013 and the official NLDI, NGWMN, and WQP documentation linked in the issue. Search adapter prose, test comments, and the shared glossary for the affected terms, then run the offline adapter tests, lint, and architecture checks. Done means terminology changes match each service while public names, parameters, URLs, return shapes, and runtime behavior remain unchanged.
Written by the indexing model from the issue text.
Description
Parent
#406
Ownership rule
ADR 0013 separates package-owned core vocabulary from service-owned domain vocabulary:
getteris a dataretrieval core term. It applies only to public functions returning(DataFrame, metadata)and binds package prose and tests.collectionis a domain concept. Adapter prose should accurately translate the service's own vocabulary, while public parameters and wire spellings remain native to that service.
Primary sources settle the three adapters differently:
- NLDI's official documentation calls its operations navigation functions. The Python adapter returns GeoDataFrames or JSON directly, without a metadata tuple, so calling these functions getters is a package vocabulary defect.
- NGWMN's live OGC collections document publishes
sites,providers,waterLevelObs, and the other record sets as collections. Prose calling those collection identifiers services is upstream-inaccurate; NGWMN itself remains the service. - WQP's official Web Services Guide calls these endpoints the Station Web Service, Result Service, and profile services.
dataProfileis a separate request parameter. WQP's publicservicevocabulary is therefore native domain language and must not be normalized away.
What to build
Apply those ownership decisions consistently without changing public behavior:
- Describe NLDI's direct-return operations as navigation functions rather than getters, including package and test prose.
- Describe NGWMN OGC collection identifiers as collections in prose and comments, while continuing to call the external NGWMN system a service.
- Correct the shared glossary so it distinguishes WQP's Result/Station/Activity services from the separate
dataProfilevalues. - Preserve WQP's public
serviceparameters, URL-builder documentation, exported names, wire paths, and other service-oriented public prose.
Acceptance criteria
- NLDI prose and test comments no longer call direct GeoDataFrame or dictionary-returning functions getters.
- NLDI is described as navigation functions, matching both its return contract and official API documentation.
- NGWMN prose and comments use collection for identifiers exposed by its OGC
/collectionsdocument. - References to the external NGWMN system continue to use service.
- The glossary accurately records that WQP exposes Result, Station, and Activity services and treats
dataProfileas a separate concept. - WQP's public
serviceterminology and service-oriented URL-builder documentation remain unchanged. - Deprecated NWIS vocabulary, Samples resource/code-service terms, the deprecated CQL keyword, and permanent aliases remain unchanged.
- No public name, signature, return shape, exported value, wire parameter, URL, or runtime behavior changes.
- Documentation, offline adapter tests, lint, and architecture checks pass.
Blocked by
None — can start immediately.
- Dominant language
- Python
- Stars
- 266
- Forks
- 63
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 19
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from DOI-USGS/dataretrieval-python
-
Difficulty 4/5 3-5 days Newbie friendliness 48/100
DOI-USGS/dataretrieval-python#421 · 1 reaction ·
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
DOI-USGS/dataretrieval-python#415 · 1 comment · 1 reaction ·
-
ready-for-agent
Difficulty 4/5 3-5 days Newbie friendliness 42/100
DOI-USGS/dataretrieval-python#413 ·
-
ready-for-agent
Difficulty 3/5 1-2 days Newbie friendliness 68/100
DOI-USGS/dataretrieval-python#410 ·
-
ready-for-agent
Difficulty 3/5 1-2 days Newbie friendliness 72/100
DOI-USGS/dataretrieval-python#412 ·
All issues in DOI-USGS/dataretrieval-python
Similar issues
-
documentation help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
simonw/sqlite-utils#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100