Deferred: Tag Vocabulary Validation

[bsstahl]

Deferred: Tag Vocabulary Validation

Status

Deferred. This is deliberately outside the MVP.

Summary

Several SpeakerOps subdomains use a Tags field, but the fields do not currently share one domain model:

• LiquidVictor tags ContentItems used while building presentations.
• PPTail tags publishable site content and uses tags for discovery and tag-cloud generation.
• TalkFolio tags talk concepts for discovery, topical overlap, and CFP fit.
• TalkCircuit stores tags selected for a specific submission and models the vocabulary allowed by a particular CFP.

The shared requirement is validation, not shared ownership. Each subdomain should be able to maintain a validation list for the tags used by its own entities. An unknown tag should produce an error.

Decision

When this feature is implemented:

1. Each tag-bearing subdomain owns its own validation list.
2. Validation is performed within that subdomain's boundary and applies only to its own tag-bearing entities.
3. An unknown tag is an error, rather than a warning or an automatically accepted value.
4. The validation list is separate from the entity data and is explicitly maintained as part of that subdomain.
5. A shared validation library or file format may be introduced later, but it must not become a shared Tag bounded context or shared semantic model by accident.
6. Conference-specific tag vocabularies remain owned by TalkCircuit/CFP data. They are not interchangeable with TalkFolio's general-purpose tags.

This issue defines a future capability only. MVP schemas and workflows may continue to accept unvalidated tag strings.

Why This Is Not a Shared Tag Context

The same spelling can be useful across contexts without having the same meaning or lifecycle. For example, a TalkFolio topic tag describes a talk concept, while a LiquidVictor label may describe how a ContentItem is used in a deck. PPTail's tag behavior is editorial and publication-oriented. TalkCircuit's allowed tags are imposed by an external CFP.

A central Tag context would need to own identities, aliases, renames, merges, and lifecycle rules. None of those responsibilities is currently required. Extracting them prematurely would add synchronization and integration work while leaving the meaningful classification decisions in the owning subdomains.

Proposed Shape

The exact serialization format is intentionally left open. A validation list should be able to express at least a canonical value and, if needed later, lifecycle information:

Tags:
  - Name: rag
    Status: Active
  - Name: old-tag
    Status: Deprecated
    ReplacedBy: new-tag

The minimum MVP-after-MVP version may be only a list of canonical strings:

Tags:
  - rag
  - embeddings
  - retrieval

The richer form should not be adopted unless aliases, deprecation, or replacement guidance is needed. A validation list is not required to define a taxonomy, hierarchy, descriptions, or cross-context identity.

Context Responsibilities

LiquidVictor

Validate tags assigned to LiquidVictor-owned ContentItems, if ContentItem tag validation remains useful after the MVP. Production labels such as visual-illustrative may be valid here even when they have no meaning in TalkFolio.

PPTail and Site Data

Validate editorial tags for the site content store that PPTail compiles. The generator should consume the site vocabulary or receive already-validated content; PPTail should not impose TalkFolio's vocabulary on every site.

TalkFolio

Validate tags assigned to TalkFolio Talks. These remain topical labels for talk discovery, overlap, and CFP relevance. Category remains a separate concept. A TalkFolio tag should not be considered valid for a CFP merely because it is valid in TalkFolio.

TalkCircuit

Validate selected submission tags against the relevant CFP's allowed vocabulary and selection rules. This is a second validation step with different ownership: the CFP vocabulary comes from the conference, while any mapping from TalkFolio tags is a TalkCircuit concern.

Validation Behavior

Unknown values

An unknown tag must produce an error identifying:

• the subdomain and entity being validated;
• the invalid tag value;
• the validation list or vocabulary used;
• the source record, where available; and
• a useful remediation, such as adding the tag to the local list or correcting the spelling.

Validation must fail the relevant command, build, import, or CI check rather than silently dropping or rewriting the tag.

Normalization

Before implementation, each subdomain must specify whether comparison is:

• case-sensitive or case-insensitive;
• whitespace-trimmed;
• Unicode-normalized; and
• based on a canonical value, an alias, or both.

The first implementation should prefer a small, explicit rule set. It should not silently mutate persisted data while validating it.

Duplicate values

The validation list should reject duplicate canonical values, including duplicates that differ only by normalization rules. Duplicate tags on one entity should either be rejected or normalized by an explicitly documented local rule; this issue does not choose between those behaviors.

Deprecated values

If lifecycle fields are introduced, the subdomain must decide whether a deprecated tag is an error or a warning and whether ReplacedBy is advisory or automatically migrated. This decision is separate from the baseline rule for completely unknown values, which is always an error.

Non-Goals

• Creating a cross-context Tag service or universal tag registry.
• Making tags globally unique across SpeakerOps.
• Moving tag ownership out of LiquidVictor, PPTail/site data, TalkFolio, or TalkCircuit.
• Replacing TalkFolio's Category with tags.
• Treating PresentationFamily as a tag or taxonomy node.
• Automatically mapping every tag between contexts.
• Validating tags during the MVP.
• Automatically creating unknown tags from author input.

Migration Considerations

Before enabling validation in a subdomain:

1. Extract the currently used tag values from its authoritative data.
2. Decide canonical spelling, casing, whitespace, and delimiter rules.
3. Deduplicate equivalent values deliberately.
4. Classify values that are misspellings, obsolete labels, or local-only labels.
5. Add accepted values to that subdomain's validation list.
6. Update or remove invalid source records in a deliberate migration.
7. Enable validation in CI before making it blocking for authoring workflows.
8. Keep the validation list versioned with the subdomain that owns it.

Existing values must not be rejected merely because another subdomain does not recognize them.

Acceptance Criteria

• Each participating subdomain has a clearly identified owner and location for its validation list.
• A valid tag passes validation in the owning subdomain.
• An unknown tag fails validation with an actionable error.
• Validation is applied to every relevant tag-bearing entity and ingestion path in that subdomain.
• Case, whitespace, Unicode, alias, duplicate, and deprecated-value behavior is documented per subdomain.
• TalkCircuit validates CFP-selected tags against the specific CFP vocabulary and does not substitute the TalkFolio list.
• Validation lists are versioned, reviewable, and covered by focused tests.
• MVP behavior remains unchanged until this feature is explicitly enabled.

Open Questions

• Should each validation list be a flat string list initially, or should all contexts use one shared structural format?
• Should aliases be accepted at validation time, or should source data be migrated to canonical values first?
• Should deprecated tags block CI, warn, or be allowed temporarily?
• Should duplicate tags on an entity be an error in every context?
• Which command is the authoritative validation entry point for each repository?
• Should validation run on every build, only in CI, or both?

Related Domain Rule

CONTEXT.md records the current glossary rule: tag vocabulary validation is deferred beyond the MVP, each subdomain owns validation for its tag-bearing entities, and an unknown tag is an error once validation is implemented.