# Field standards — smart-value-objects v3

Official constraints for catalog value objects. Use these limits in UI (`maxLength`, validation messages) and API handlers — never duplicate rules locally.

| Type | Primitive | minLength | maxLength | trim | pattern / notes | Gains |
|------|-----------|-----------|-----------|------|-----------------|-------|
| `Title` | `string` | 1 | 120 | yes | unicode allowed | G4 — project/WBS titles |
| `ShortLabel` | `string` | 1 | 80 | yes | short labels (v4 `PersonName` max) | G4 — compact labels |
| `PersonName` | `string` | 2 | 120 | yes | — | G4 — people names (Archsphere sales) |
| `EmailAddress` | `string` | 5 | 254 | yes + lowercase | pragmatic email regex | G1 — domain email type |
| `Uuid` | `string` | 36 | 36 | yes + lowercase | RFC 4122 variant 1–5; rejects nil UUID | G1 — typed identifiers |
| `KebabSlug` | `string` | 1 | 64 | yes + lowercase | `^[a-z0-9]+(?:-[a-z0-9]+)*$`; `sanitize()` for forms | G4 — artifact/MCP slugs |
| `CalendarDate` | `string` | — | 10 | yes | `YYYY-MM-DD`; real calendar validation | G4 — schedule/DORA dates |
| `Subject` | `string` | 3 | 200 | yes | feedback ticket subject | G4 — short text tier |
| `MessageBody` | `string` | 10 | 5000 | yes | preserves internal newlines | G4 — message tier |
| `OrganizationName` | `string` | 1 | 200 | yes | optional via `tryCreateOptional` | G4 — company field |
| `HttpUrl` | `string` | — | 2048 | yes | http/https only; adds `https://` when omitted | G4 — project links |

## Optional helpers

| Helper | Use when |
|--------|----------|
| `tryCreateOptionalUuid` | nullable FK UUID columns |
| `OrganizationName.tryCreateOptional` | optional company/name fields |
| `validateRecordToFieldError` | consumers with `{ ok: false, field }` UX |

## Accessing constraints in code

```typescript
import { Title, EmailAddress, MessageBody } from 'smart-value-objects';

const maxTitleLength = Title.constraints.maxLength; // 120
const emailPattern = EmailAddress.constraints.pattern;
```

## Rules for consumers

1. Import catalog types from `smart-value-objects` — never re-declare `string` for official fields.
2. Use `tryCreate` at boundaries; use `create` only when invalid input is impossible.
3. Bind UI limits from `X.constraints` — do not invent `maxLength` values.
4. Serialize with `getValue()` when persisting JSON or sending over the wire.
5. Use `validateRecordToFieldError` when the app returns the first invalid field name to the UI.