1// Package semconv is the registry of Atlas's semantic conventions: the2// attribute keys that carry display and geometry meaning through a bundle as3// a shared language, the way OpenTelemetry's semantic conventions carry4// meaning between systems that never met.5//6// The conventions are Atlas's own, so the format is beholden to no upstream's7// habits. Every rule that would otherwise be an unspoken promotion inside one8// tool is a named key any producer can write and any reader can act on.9//10// The contract has two sides, deliberately asymmetric:11//12// - Producers are strict. An attribute in the atlas namespace that the13// registry does not know, or a value outside its vocabulary, or a key14// attached to the wrong entity, fails the build. [Validate] is that gate.15// - Readers are lenient. An unknown key is ignored, never refused, so a16// bundle written by a newer pipeline still opens in an older reader.17// [EntityOf] reporting false is a reader's cue to skip, not to fail.18//19// New keys arrive with [Experimental] stability and earn [Stable]. Only a20// breaking change to an existing key's meaning moves [Version].21//22// The package depends on the Go standard library alone and knows nothing of23// Atlas the application.24//25// The vocabulary has one machine-readable source, spec/registry.yaml, from26// which three artifacts are cut: registry_gen.go here, the TypeScript lanes'27// key constants, and docs/semconv/REGISTRY.md, the document a reader learns28// the conventions from. Edit the spec, not the artifacts.29package semconv3031//go:generate go run ../../spec/gen3233// Entity is what an attribute attaches to. A key registered against one34// entity is a producer error on any other, which is what keeps a collection's35// vocabulary from drifting onto its features.36// The entities themselves are in registry_gen.go: which entities exist is37// vocabulary, and vocabulary comes from the spec.38type Entity string3940// Stability says how settled a key is. Experimental keys may still change41// spelling or vocabulary; stable keys only break with a [Version] move. The42// tiers, like the entities, are generated.43type Stability string