Go Types Conversion
Developmentgo-types-conversionGo Types Conversion is an Agent Skill for development published in the openmeterio/openmeter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Naming convention for type-translation files and functions. Use when creating or editing files that convert between domain, API, and DB types.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/openmeterio/openmeter/blob/HEAD/.agents/skills/go-types-conversion/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/go-types-conversion, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Type Translation Naming
Apply to new and touched code. Do not rename legacy symbols unsolicited.
File naming
| Path contains | File name | Purpose |
|---|---|---|
httpdriver/, httphandler/, api/v3/handlers/ | convert.go | API ↔ domain |
adapter/, repo/ | mapping.go | DB ↔ domain |
Split large files by entity: convert_plan.go, mapping_subscription.go.
mapper.go is forbidden. Rename it to convert.go or mapping.go (based on layer) when the file is touched.
Function naming
Shape: From<Qualifier><Thing> / To<Qualifier><Thing>
The qualifier is API or DB — no other qualifiers (Domain, Model, package-name infixes).
The suffix <Thing> is the non-domain type's unqualified name — the API type or DB type, not the domain type. This keeps it stable: a matched pair (FromAPI<Thing> / ToAPI<Thing>) always refers to the same non-domain type, regardless of direction.
FromAPI<Thing>— takes the API type<Thing>as input, returns the domain representation.ToAPI<Thing>— takes the domain type as input, returns the API type<Thing>.- Same for
FromDB<Thing>/ToDB<Thing>.
Examples
// API ↔ domain
FromAPIPlan(a api.Plan) (plan.Plan, error)
ToAPIPlan(p plan.Plan) api.Plan
// Suffix is the API type name, even when domain type differs
FromAPIPlanCreate(a api.PlanCreate) (plan.CreateInput, error)
ToAPIPlanCreate(p plan.CreateInput) api.PlanCreate
FromAPIProRatingConfig(a api.ProRatingConfig) (productcatalog.ProRatingConfig, error)
ToAPIProRatingConfig(p productcatalog.ProRatingConfig) *api.ProRatingConfig
// DB ↔ domain — suffix is the DB type name
FromDBSubscription(row *db.Subscription) (subscription.Subscription, error)
ToDBSubscription(s subscription.Subscription) *db.Subscription
FromDBChargeFlatFee(row *entdb.ChargeFlatFee) (flatfee.Charge, error)
ToDBChargeFlatFee(c flatfee.Charge) *entdb.ChargeFlatFee
Additional rules
- Exported functions always include the type suffix (
FromAPIPlanCreate, not bareFromAPI). - Unexported helpers in a single-type file may drop the suffix (
fromDB,toAPI). - Fallible (parse/validate) →
(T, error). Infallible (projection) →T. TypicallyFromAPI…/FromDB…is fallible; the reverse is not. - Batch helpers use the plural:
FromAPIPlans,ToDBSubscriptions. Same suffix rule — the plural of the non-domain type name.
Forbidden patterns
Map…,Convert…To…, primaryAs…<Source>To<Target>shape (e.g.APIToPlan)- Bare
FromAPI/ToDBwithout a type suffix - goverter or other codegen type mappers
Decision tree
Naming a function
- Pick the qualifier: API/HTTP/wire on one side →
API. DB/persistence on one side →DB. - Pick the suffix: the non-domain type's unqualified name (
Plan,PlanCreate,ChargeFlatFee). - Pick the return style: fallible →
(T, error), infallible →T. - Exported? Must include the type suffix. Unexported single-type helper may drop it.
Interacting with the user
- File is
mapper.go? Flag it — should beconvert.goormapping.gobased on layer. Offer to rename as part of the edit. Don't rename silently. - Adding new functions to a legacy file? Use the new convention for new functions. Don't rename old ones unless asked.
- Task is "clean up this file"? Rename, update call sites,
Grepfor the old name to catch misses, keep the rename in its own commit. // Code generatedheader? Off-limits regardless.
Suggestion phrasing
Lead with the specific rename and the reason. Keep it short.
MapChargeFlatFeeFromDB— useFromDBChargeFlatFee. Want me to rename and update callers?
Direction looks inverted —
FromAPI…returns a domain type, so this should beToAPIPlan. Drop the error return if it can't actually fail.
This file is
mapper.go— should beconvert.gosince it lives inhttphandler/. Want me to rename it?