Scuemata naming: last chance for different names

[sdboyer]

(This discussion was originally in grafana/grafana, and reflects the names of the original "scuemata" system. The terminal state of this naming discussion is the names that are now in use in Thema.)

Naming is hard!

We merged the initial scuemata PR about six months ago (Scuemata design doc - it's rough!). We've learned a lot since, and soon, it'll be time to move the generic scuemata system into its own, standalone repository (#38038). The move will be the last opportunity to discuss/bikeshed about names. I'd like to box all of that in here, in this discussion.

The scuemata system has five [planned] essential concepts/logical constructs - more detail on them here - and sorta-six names for them:

• Schema: a single, actual schema.
• Lineage: a sequence of schema, having the verified invariant that every schema in the sequence is backwards compatible with its predecessor, per CUE's built-in definition of backwards compatibility.
• Migration: a mapping from one lineage's final schema (A) to the next lineage's first (B), allowing us to take an artifact valid with respect to A, and transform it into an artifact valid with respect to B.
  • Note (necessary, but not yet implemented): an object, emitted by a migration, that indicates the resultant artifact contains what the user may consider to be a flaw due to a known, unavoidable imperfection in the migration logic. Multiple notes my be emitted by each migration.
• Family: a collection of lineages and migrations between them that collectively represent the history of all known schemas for a particular kind of object.
  • Scuemata: In practice, the term "family" is usually not used, and we instead say "scuemata" or "scuemata families." This was my intent when choosing the names (and i've personally reinforced it) - "scuemata" could colloquially refer to the system as a whole, or to families, because the ambiguity there often isn't important. When it is important, the more specific terms "scuemata family" or "scuemata system" may be used.

In general, i think these terms are adequate, and it would not be the end of the world if we went forward with all of them. But i know that some of these terms make people itchy, and i'm not perfectly content with them either. So, i'll list my concerns and possible alternatives here in the OP; other folks can weigh in on those ideas, or with their own independent comments/concerns/suggestions. (It is out of scope for this discussion to talk about introducing any new concepts or logic to the system.)

Schema

This one's not up for debate - it's the exact same concept as in the world outside scuemata, and using a different word for this previously-established, not-novel concept would be very confusing.

Lineage

Seems mostly fine to me. It's largely suggestive of what's going on, though the conventional meaning/other common uses of it (e.g. "data lineage") does not carry any connotation of the backwards compatibility that is an essential feature of the system. I also find saying "lineage version" slightly awkward. Still, i don't have enough concerns to make the

The only thing that's absolutely clear is that "major" has no business being here, because that would conflate with semver. Semver is aspirational and appropriate for Turing-complete problems; scuemata is verifiable and intended for clean, precise composition into Turing-complete problems.

Migration

This is the one i want to change most.

"Migration" connotes a mutation. It may be reversible, but that's not a guarantee. That's kinda consistent with the forward-only nature of the migration guarantees afforded by scuemata (though those may expand in the future). But migrations also imply something about the persistence of that mutation - you either have the before-form, or the migrated-form, but not both. That's not the case here: migrations take an input, and return a transformed version of the output. Whether that output is actually persisted anywhere is quite intentionally outside the scope of the scuemata system, as that decoupling makes it easy to imagine networks of programs, all with knowledge of a whole scuemata family, passing around objects and choosing to defer (or not) actually "committing" a migration until an appropriate moment.

Back in June, @annanay25 pointed out to me the overlaps between scuemata and Project Cambria, of which there are many. Really, they're kinda more the same than not. i think Cambria illustrates the viability of this entire schema-translation-at-the-boundaries approach, and that scuemata will only allow us to take those principles further.

I like how Cambria calls these translations "lenses". This word really implies exactly what's going on: you can choose to view a given artifact through a lens, or even a stack of lenses. You can even act on this intermediated view, as a translated artifact. The lenses may distort certain aspects of the original artifact, but they do not change the original artifact. So, "Lens" is a front-runner, here. My main misgiving is that it's hard to make a verb out of - "apply a lens"? - so maybe "Translation" is better.

Note

This has always been a handwavy placeholder name, and i'd really like to see it replaced.

"Warning" seems like the obvious candidate - an event indicating a suboptimal runtime behavior occurred, but that's not sufficient to actually stop the process. I didn't go with this in the first place, though, because there's baggage there which i think would misdirect people:

• Warnings frequently (though not always!) occupy an obnoxious liminal space between "everything is fine" and "there's an error, stop!" In such cases, it's kinda as though the programmer didn't have a strong enough sense of what it meant for their own program to be correct to actually make a firm decision either way, so..."hey, throw a warning instead." By contrast, it is an invariant of the scuemata design that migrations cannot fail, which seats them on a fundamentally different epistemic context (ok, problem) vs. warnings (ok, maybe-problem, problem).
• Warnings are usually just burped back to the user, who invariably drowns in a sea of them, and thus ignores them.
• Warnings are almost always just text, not structured data. Notes will absolutely be structured data (e.g., they may require an association with a field in the target schema) because...
• It is absolutely, absolutely the expectation that systems consuming scuemata could reasonably choose to convert certain types of notes into actual, program-halting errors.

If we switch to "Lens" or "Translation" for migrations we could extend the metaphor here and use e.g. "Flaw" or "Distortion". Front-runner for flourish and elitist Latinate whiff, though, would be "Lacuna".

Family

Decent enough. I'm not really motivated to change it, but i could be moved.

That human families are heterogeneous and branching makes it somewhat misleading - arguably, Family should be Lineage, and Lineage then becomes something else (Sequence?).

Scuemata

It's the name for the whole system. It's also probably the big one that bothers people the most. Maybe you're:

• Familiar with Catholicism and you dislike that it makes you think "stigmata"
• Annoyed that it is only plural with no feasible singular form (ain't nobody gonna ever say "scuema")
• Irked by the colloquial ambiguous usage of Scuemata in the place of Family, and delighted by precisiated disambiguation

I don't have any alternative ideas, but i could still be convinced to rename this whole thing. If we do, i'd strongly prefer that we deal with the colloquial ambiguity around families, though.

PS - yes, i had "stigmata" in mind originally. The original design doc was called "Confrigor and Scuemata." No, i'm not Catholic, but i am a word nerd and studied European medieval history in school, so it was close to hand.

Candidates

i'll keep this list up to date with the current name, and their candidate replacements. (Assuming anyone cares much at all 😜) Bolded candidates indicate a choice has been made/discussion is closed.

Current name	Candidates
Schema	Schema
Lineage	Lineage Sequence
Migration	Migration Lens Translation
Note	Note Warning Flaw Lacuna
Family	Family Lineage
Scuemata	Scuemata

Let the bikeshedding begin!

/cc @ryantxu @rgeyer @ying-jeanne @sh0rez @dsotirakis @pkolyvas @malcolmholmes

[malcolmholmes]

Most of these names seem fine to me. The one that does confuse a bit is "family" for which I imagine a room of peers with a few parents. That's not the linear model we have. I wonder if we could use names such as chain/lineage, lineage/links, sequence/lineage, succession/lineage, etc. There's plenty of words there that suggest one single thing comes after another single thing.

[sdboyer]

Indeed, i voiced similar concerns in OP. Make a specific proposal for what you think would be best, please :)

[cedricgc]

For Migration, I favor a change to something like Translation or Transform. It is subtle, but Translation conveys that it represents the execution that changes A to B, while Migration is more about the tracking a change itself (sometimes also interpreted to be one directional). Migration makes more sense if you want a concept that tracks a single instance of translation between Lineages A & B.

Warning makes more sense than Note if every instance emitted denotes some negative information. If there is some relevant, but not negative information that may be emitted in the future, Note makes more sense to me. You could also keep the top-level class neutral like Note and further annotate each Note with a sub-class. I could see this object becoming very broad in what it models (If it is more than just recording flaws) so it may make sense to keep it flexible.

[sdboyer]

while Migration is more about the tracking a change itself (sometimes also interpreted to be one directional)

This is an interesting distinction, and one of the problems i have with Lens - there's a difference between the noun (the mapping between schema versions, written by the scuemata author) and the verb (the act of translating a resource by moving it through the mappings). Lens has no obvious action form.

I could see this object becoming very broad in what it models (If it is more than just recording flaws) so it may make sense to keep it flexible.

This is a good point, and one that i don't have a firm sense of yet. It seems very likely, for example, that we'd want to emit these objects automatically - as in, create one in the supporting Go scuemata library, whether or not the scuemata author has explicitly written one. That's still got "possible problem here" connotations, though...

Mmm, well, another possible case would be if we abandon the linked-list-like qualities of scuemata, allowing for the possibility that migrations move forward or backwards through schema history. Then, we might want to record in an object the path that a series of migration steps have taken. But...meh, that feels like a different kind of thing than what's being covered here.

[cedricgc]

In general, I would want the logical pieces to be nouns, and the API could use the the verb complement for the actual action when performed. I think only Migration is the only verb focused term, so changing that would keep everything consistent on that front.

I also prefer to keep the terms simple unless there is a specific noun that truly captures the nuance. I get where Lens comes from, but I do not think it would be immediately clear to the average user, and from what I understand Scuemata does actually generate and store a new Schema to exist in a Lineage. To me Lens would imply a more dynamic system where you would compose a series of Lens to generate a new Schema on demand. Maybe a just me thing though.

[peterbourgon]

Is it pronounced "SKEW-mata"? If so, let me suggest: Skewmata? I understand and appreciate the Cue etymology, but it brings to mind the Oneders/Wonders dialectic from the 1996 comedy/drama That Thing You Do! — which, if you haven't seen the film, essentially suggests that you not spend a complexity token on the parsing and pronunciation of your thing's name 😜

edit: I see I have been preëmpted by Julius on this one, oops 😅

[sdboyer]

Hah! Indeed, we were just twittering about this :)

I would indeed prefer not to spend a complexity token in this way (solid reference, and well done taking me back to childhood, lol). My concern with "skewmata," though, is that "skew" itself carries connotations that i'm finding hard to see as anything but misleading. (Like - i don't know exactly what "skewing" is, but it sounds like something i don't want my schema system to do.) Also, if the overall name has "skew" in it, i think i'd be confused about why that doesn't apply to the part of the system where we're talking about change, where we're instead using words like "migrate" or "translate" or "lens". (Or "lacuna"!)

[sdboyer]

https://github.com/grafana/scuemata is now up. i'm considering one last name change now to scuemata itself, but everything else is decided:

• Schema: a single, actual schema.
• Sequence: an ordered list of schema, having the verified invariant that every schema in the sequence is backwards compatible with its predecessor, per CUE's built-in definition of backwards compatibility.
• Lens: a mapping from one sequence's final schema (A) to the next sequence's first (B), allowing us to take an artifact valid with respect to A, and transform it into an artifact valid with respect to B.
• Lacuna: an object, emitted by a lens, that indicates the resultant instance contains what the user may consider to be a flaw due to a known, unavoidable imperfection in the migration logic. Multiple lacunae my be emitted by each migration.
• Lineage: a series of sequences and lenses between them that collectively represent the history of all known schemas for a particular kind of object, and the path for traversing them.

[sdboyer]

And, i went for the rename. Scuemata - the name for the overall system - is now "Thema," and lives at https://github.com/grafana/thema. Closing this out, as all decisions are now final 😄

Grafana itself still needs to be moved over to the generic, standalone repository, which means the "scuemata" name (and all the other, old names in the OP here) will continue to exist in grafana/grafana until we migrate.