Add slugify safe builtin for identifier-shaped expressions

[amc-corey-cox]

Motivation

Trans-specs that emit identifier-shaped slots from human-authored source labels routinely need to sanitize names: replace whitespace and punctuation, fold case, ensure leading-character validity. Concrete driver: schema-automator's EML importer (linkml/schema-automator#208), where EML <entityName> and <attributeName> fields contain spaces, punctuation, and mixed case but the target LinkML class_definition.name / slot_definition.name requires valid identifiers.

The current eval helpers (replace, lower, etc., from 0f803b6) can approximate slugify via 6-10 chained calls, but the chain is fragile and obscures intent. Regex was deliberately kept out for ReDoS reasons; slugify is bounded-time string manipulation and doesn't open that surface.

Proposed direction

Add slugify(s, separator='_') to the safe builtin set in eval_utils.py. Default behavior:

• ASCII-fold (Unicode → ASCII transliteration)
• Lowercase
• Collapse non-alphanumeric runs to the separator
• Strip leading and trailing separators
• Ensure leading character is non-digit (prepend separator if needed)

Optionally include sibling helpers in the same bounded-time class: to_snake(s), to_camel(s), to_pascal(s). Often needed in tandem when trans-specs target schemas with different naming conventions per location.

Return semantics: None on no-extractable-content

slugify returns None when the input has no extractable identifier content — empty string, all-whitespace, all-punctuation, or input that collapses to empty after sanitization. This matches linkml-map's existing expression-layer convention: None is the SQL-style "doesn't apply" signal, propagates through case() arms, and composes with or for fallback chains:

range: { expr: "slugify(attributeName) or slugify(attributeLabel) or 'anonymous'" }

If slugify raised on empty input, the raise would short-circuit the trans-spec rather than letting the or chain do its job. Returning None keeps slugify composable with the rest of linkml-map's expression vocabulary.

Enforcement of "this slot can't be None" lives at the schema layer

Schemas that require non-empty identifiers — class names, slot names, dictionary keys — enforce that requirement at the schema-derivation layer, not inside slugify. Reporting "this source instance has unusable data for required slot X" with full source provenance is the job of transform-time target validation (#241). slugify stays a simple, total string function; structural requirements live where they belong.

Implementation location

slugify could land in linkml-runtime's utility set if there's a reasonable home there, with linkml-map re-exporting it for the eval namespace. Same normalization is useful in schemasheets, schema-automator, and other tooling that today re-roll variants. If linkml-runtime has no obvious home, ship in linkml-map as a standalone module with a clear path to upstream later.

Open questions

• Separator default. _ vs -. LinkML identifier conventions skew snake-case → _ default. Configurable per-call.
• Unicode policy. ASCII-fold by default (predictable, identifier-safe) with slugify(s, allow_unicode=True) opt-in for cases where Unicode identifiers are wanted.
• Sibling helpers. Bundle to_snake / to_camel / to_pascal here, or scope this tight to slugify and follow up separately?

References / contrasts

• 0f803b6 — safe builtin registry that this extends
• Transform-time validation against target schema constraints #241 — handles "must-not-be-None" enforcement at the schema layer
• schema-automator's EML importer (EML (Ecological Metadata Language) importer schema-automator#208) — concrete consumer

[github-actions]

Summary

What this issue proposes: Add a slugify(s, separator='_') function to the safe built-in set in eval_utils.py, so trans-specs can cleanly convert human-authored labels (with spaces, punctuation, mixed case) into valid LinkML identifier-shaped strings.

---

Problem

Trans-specs that emit class_definition.name / slot_definition.name from human-readable source labels need a reliable sanitization step. The concrete driver is the schema-automator EML importer (schema-automator#208), where EML <entityName> and <attributeName> fields contain spaces, punctuation, and mixed case that are illegal in LinkML slot/class names.

The current safe built-ins in eval_utils.py:223-252 — replace, lower, strip, split, etc. — can approximate slugify via 6–10 chained calls, but the chain is fragile and obscures intent. Regex was deliberately excluded from the evaluator for ReDoS safety; slugify is bounded-time and doesn't open that surface.

---

Proposed implementation

Add slugify to _SCALAR_FUNCTIONS in eval_utils.py (gets the _distributing wrapper automatically, so it propagates None and distributes over lists for free). Default behavior:

1. ASCII-fold (Unicode → ASCII transliteration)
2. Lowercase
3. Collapse non-alphanumeric runs to separator
4. Strip leading/trailing separators
5. If leading character is a digit, prepend separator

Return None on no-extractable-content (empty string, all-whitespace, all-punctuation, or result that collapses to empty after sanitization). This matches the existing SQL-style null convention and composes cleanly with or-chain fallbacks:

range: { expr: "slugify(attributeName) or slugify(attributeLabel) or 'anonymous'" }

---

Relationship to related issues

• #241 — Transform-time validation: The "this slot can't be None" enforcement lives there, not inside slugify. Separating concerns: slugify stays a simple total string function; schema-layer enforcement (with full source provenance in error messages) is Transform-time validation against target schema constraints #241's job. The two compose: slugify returns None → or-chain picks a fallback or produces None → Transform-time validation against target schema constraints #241's validator reports the missing required slot with source-row context.

• schema-automator#208 — EML importer: The concrete consumer. Each <dataTable>/<attribute> produces a LinkML class/slot name. EML's <entityName> and <attributeName> are human-readable prose; slugify is the missing step between source label and valid identifier.

---

Open questions

Question	Options	Current lean
Separator default	_ vs -	_ (LinkML convention is snake_case)
Unicode policy	ASCII-fold by default; opt-in allow_unicode=True	ASCII-fold default
Sibling helpers	Bundle to_snake / to_camel / to_pascal here or separate follow-up?	Scope tight to slugify first
Landing location	linkml-map's eval_utils.py vs. upstream into linkml-runtime utilities	Ship in linkml-map; path to upstream clear since same normalization is useful in schemasheets, schema-automator, etc.

---

Implementation sketch

The existing _SCALAR_FUNCTIONS dict is the right landing spot. A minimal implementation using only stdlib (unicodedata, re) would look like:

import re
import unicodedata

def _slugify(s: str, separator: str = "_") -> str | None:
    # ASCII-fold
    s = unicodedata.normalize("NFKD", s).encode("ascii", "ignore").decode("ascii")
    s = s.lower()
    # Collapse non-alphanumeric runs
    s = re.sub(r"[^a-z0-9]+", separator, s).strip(separator)
    if not s:
        return None
    # Ensure first char is not a digit
    if s[0].isdigit():
        s = separator + s
    return s

Then add "slugify": _slugify to _SCALAR_FUNCTIONS (which gets _distributing applied automatically in the FUNCTIONS assembly at line 309).

---

Notes

• This is a low-risk, narrow addition: bounded-time, no new dependencies, fits cleanly into the existing _SCALAR_FUNCTIONS → _distributing wrapper pattern.
• @dragon-ai-agent please implement slugifyas described in issue #242 — add it to_SCALAR_FUNCTIONSinsrc/linkml_map/utils/eval_utils.pywith the behavior andNone-return semantics described, include doctests, and add a parametrized pytest test in the existing eval_utils test suite.