docs(ogc): add OGC layer naming conventions by likithabommasani21 · Pull Request #898 · DataIntegrationGroup/OcotilloAPI

likithabommasani21 · 2026-08-27T20:04:31Z

Title: BDMS-1167: Document standardized OGC layer naming conventions

Why

No documented standard exists for OGC layer naming, so naming decisions have drifted layer by layer over time — inconsistent abbreviations, word order, and prefixes across the catalog, with no single place to check before adding or renaming a layer.
A prior audit (OGC Feature Layer Audit Report) reviewed naming once, but as a point-in-time snapshot — 7 layers added since then were never checked against it.

How

Added docs/ogc_conventions.md: the standing naming convention for OGC layers.
Documents the governing standard (USGS NWIS site-type vocabulary), why it was chosen, and how to apply it.
Do/don't rules with concrete examples, plus a documented set of deviations where NWIS genuinely doesn't apply (analytic/summary layers, geothermal layers, actively_monitored_wells).
Change-level framework (Level 1 cosmetic / Level 2 grace-period rename / Level 3 hard rename) for handling any future rename consistently.
Full current-layer inventory across public and internal mounts, each row showing current vs. recommended ID/name, change level, and rationale — including the 7 post-audit layers, reviewed here for the first time.

Notes

This documents recommendations only — no layer IDs or titles are renamed in this PR. Each recommended rename still needs its own Level 1/2/3 decision before implementation.
Several recommendations (geothermal layers, well_water_column) are marked "needs review".
Doc includes a revision-history table and an explicit instruction to update both the layer and this doc together whenever a recommended rename is actually implemented, so it doesn't go stale.

github-actions · 2026-08-27T20:07:54Z

Coverage

✅ 79.30% total — gate is 75%.

ksmuczynski · 2026-08-27T21:05:31Z

+  site type. It's exempt from NWIS alignment by definition. It was widened to
+  cover all groups rather than renamed.
+
+## Change-level framework


Let's make this a two-level framework. We do not need to consider a Level 2 rename since there are no external consumers of our OGC service. Keep Level 1 and Level 3, but rename Level 3 as Level 2. Let me know if that doesn't make sense.

ksmuczynski · 2026-08-27T21:09:20Z

+Check any newly-added layer against the [do/don't rules](#do--dont-rules)
+**before** it merges, not retroactively.
+
+## Current layer inventory


I'd like to see the tables include current and proposed title/descriptions, since the change-level framework mentions it. Is that what the Layer Name column is referring to? If so, consider standardizing the use of these names across the document for consistency (i.e. on line 99, change "Update title/description" to "Update Layer Name (title/description)". Layer Name can remain as is in the tables.)

Yes, Layer Name is referring to Title.
fixed it

ksmuczynski · 2026-08-27T21:23:11Z

+| `meteorological_stations` | N/A | Meteorological Stations | N/A | N/A | Conforms (USGS `AT`) |
+| `outfalls_wastewater_return_flow` | `wastewater_outfalls` | Outfalls and Return Flow | N/A | 2 or 3 | ID reads as a description, not a name; title is already fine |
+| `perennial_streams` | N/A | Perennial Streams | N/A | N/A | Conforms |
+| `rock_sample_locations` | `rock_sample_sites` | Rock Sample Locations | Rock Sample Sites | 1 and 2/3 | USGS uses "site" consistently |


I'd use either "locations" or "sites", not mix them. If USGS uses "site" consistently, let's go with that.

Yes, recommendations includes only sites

ksmuczynski · 2026-08-27T21:23:40Z

+| `outfalls_wastewater_return_flow` | `wastewater_outfalls` | Outfalls and Return Flow | N/A | 2 or 3 | ID reads as a description, not a name; title is already fine |
+| `perennial_streams` | N/A | Perennial Streams | N/A | N/A | Conforms |
+| `rock_sample_locations` | `rock_sample_sites` | Rock Sample Locations | Rock Sample Sites | 1 and 2/3 | USGS uses "site" consistently |
+| `soil_gas_sample_locations` | `soil_gas_sample_sites` | Soil Gas Sample Locations | Soil Gas Sample Sites | 1 and 2/3 | USGS uses "site" consistently |


Same comment as above. I'd use either "locations" or "sites", not mix them. If USGS uses "site" consistently, let's go with that.

…entory columns

ksmuczynski · 2026-08-27T21:30:12Z

+| `depth_to_water_trend_wells` | N/A | Depth to Water Trend (Water Wells) | N/A | N/A | Conforms |
+| `water_elevation_wells` | N/A | Water Elevation (Water Wells) | N/A | N/A | Conforms |
+| `water_well_summary` | N/A | Water Well Summary | N/A | N/A | Conforms |
+| `well_water_column` | N/A | Well Water Column (Water Wells) | N/A | N/A | Conforms — plain English, matches its description (standing water column per well). ⚠️ *needs review*: doesn't follow the `water_well_` prefix direction |


Recommended ID = water_well_water_column, so it aligns with the water_well_ prefix direction.

Recommended Layer Name = Water Column (Water Wells). I think this reads easier.

Sure, will fix that

ksmuczynski · 2026-08-27T21:36:38Z

+| `minor_chemistry_wells` | `water_well_minor_chemistry` | Minor Chemistry (Water Wells) | N/A | 2 or 3 | Should mirror the recommended `water_well_major_chemistry` for its sibling layer |
+| `actively_monitored_wells` | N/A | Actively Monitored Wells | N/A | N/A | Not renamed — see [Deviations](#deviations-from-usgs-nwis-conventions) |
+| `project_areas` | N/A | Project Areas | N/A | N/A | Conforms |
+| `geothermal_wells_bht` | `geothermal_wells_bottom_hole_temperature` | Geothermal Wells — Bottom-Hole Temperature | N/A | 2 or 3 | ⚠️ *needs review*: `bht` abbreviation in the ID only; title already spells it out |


I'd suggest the following to mirror water well naming conventions:

Recommended Layer Name = `Bottom-Hole Temperature (Geothermal Wells)

ksmuczynski · 2026-08-27T21:37:26Z

+| `actively_monitored_wells` | N/A | Actively Monitored Wells | N/A | N/A | Not renamed — see [Deviations](#deviations-from-usgs-nwis-conventions) |
+| `project_areas` | N/A | Project Areas | N/A | N/A | Conforms |
+| `geothermal_wells_bht` | `geothermal_wells_bottom_hole_temperature` | Geothermal Wells — Bottom-Hole Temperature | N/A | 2 or 3 | ⚠️ *needs review*: `bht` abbreviation in the ID only; title already spells it out |
+| `geothermal_wells_temperature_profile` | N/A | Geothermal Wells — Temperature-Depth Profile | N/A | N/A | Conforms |


I'd suggest the following to mirror water well naming conventions:

Recommended Layer Name = `Temperature-Depth Profile (Geothermal Wells)

ksmuczynski · 2026-08-27T21:38:51Z

+
+
+
+## References


Thank you for including references!!

ksmuczynski

I left a few minor comments, otherwise looking good!

…ater well naming

docs(ogc): add OGC layer naming conventions

9f89d6a

likithabommasani21 requested review from jirhiker and ksmuczynski August 27, 2026 20:04

ksmuczynski reviewed Aug 27, 2026

View reviewed changes

docs(ogc): simplify change-level framework to two levels, clarify inv…

fe49b80

…entory columns

ksmuczynski reviewed Aug 27, 2026

View reviewed changes

Comment thread docs/ogc_conventions.md

## References

ksmuczynski Aug 27, 2026

Copy link
Copy Markdown

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for including references!!

ksmuczynski requested changes Aug 27, 2026

View reviewed changes

docs(ogc): update well_water_column and geothermal titles to mirror w…

f2b35e1

…ater well naming

likithabommasani21 requested a review from ksmuczynski August 27, 2026 21:51

ksmuczynski approved these changes Aug 28, 2026

View reviewed changes

likithabommasani21 merged commit f25653d into staging Aug 28, 2026
9 checks passed

likithabommasani21 deleted the BDMS-1167-define-and-document-standardized-naming-conventions-for-ogc-layers-to-prevent-layer-drift branch August 28, 2026 19:28

Uh oh!

Conversation

likithabommasani21 commented Aug 27, 2026

Title: BDMS-1167: Document standardized OGC layer naming conventions

Why

How

Notes

Uh oh!

github-actions Bot commented Aug 27, 2026

Coverage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ksmuczynski Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

likithabommasani21 Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ksmuczynski Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ksmuczynski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ksmuczynski Aug 27, 2026 •

edited

Loading

likithabommasani21 Aug 27, 2026 •

edited

Loading

ksmuczynski Aug 27, 2026 •

edited

Loading