citation-evidence/wiki/AttributeValueTypes-proposal.md

# Proposal: Attribute Value Type Canon (consumer + InfoTechCanon)

**Status:** accepted defaults (2026-07-30) — CE MVP frozen  
**Consumers:** citation-evidence Capture attributes  
**Producer candidate:** info-tech-canon (Data Model extension)  
**Related:** CE-WP-0012, ITC-WP-0013 (proposed)

### Accepted defaults (operator 2026-07-30)

1. **Owner:** InfoTechCanon Data Model (long-term); CE ships interim catalog.
2. **Amount wire form:** structured JSON `{"value":"…","currency":"EUR"}`.
3. **textarea:** accept on load; normalize to `text-long` on write.
4. **boolean / integer / number / uri / identifier:** reserved, not implemented yet.
5. **one-of UI:** native `<select>` (not radio list) for MVP.

---

## 1. Problem

citation-evidence Capture attributes currently support only:

| Type id | UI | Value shape |
|---------|-----|-------------|
| `text` | single-line input | string |
| `textarea` | multi-line | string |
| `date` | HTML date | ISO calendar date string |

Real evidence-backed capture (legal, finance, admin) needs richer types:
**time**, **datetime**, **amount** (money), **one-of** (single choice),
**some-of** (multi choice), without inventing an ad-hoc enum only for this app.

---

## 2. What InfoTechCanon already has

### 2.1 Present (seed)

`InfoTechCanonDataModel` (ITC-DATA) already names structure/semantic concepts:

| Concept | Role |
|---------|------|
| **Field** | Named structural component of a schema/record |
| **Attribute** | Property of a data object / conceptual entity (semantic) |
| **DataElement** | Unit of data with meaning + representation (ISO 11179–aligned) |
| **Representation** | How a data element is represented (*examples*: string, integer, decimal, boolean, date, timestamp, code, identifier, URI) |
| **DataType** | “Technical or logical type of a field or data element” — **stub only** |
| **CodeList** | Controlled permitted values (country, currency, status…) |
| **Constraint** | required, unique, min/max, regex, enum, format, cardinality |

### 2.2 Missing

There is **no closed, versioned catalog** of:

- application-facing **value types** (what control to render, how to validate),
- **storage encoding** conventions (JSON/string wire form),
- **cardinality** for choices (`one-of` vs `some-of`),
- **quantity + unit/currency** for amounts.

So the user’s intuition is correct: Attribute/Field exist as *entity kinds*,
but not as a **canonical collection of attribute value types**.

---

## 3. Recommended split of concerns

```text
InfoTechCanon (producer)
  └── AttributeValueType catalog (closed enum + encoding rules)
        owns: type id, meaning, wire encoding, constraints hooks
        does NOT own: React widgets, PDF viewer, evidence links

citation-evidence (consumer)
  └── Capture Attribute schema + UI adapters
        owns: FormFieldSchema, editors, filters, evidence links
        maps: AttributeValueType → widget + validation
```

citation-evidence should **not** be the long-term owner of the type list;
it may ship a consumer profile that imports the catalog once ITC lands.

---

## 4. Proposed AttributeValueType catalog (v0)

Ids are stable machine tokens (kebab-case). Display labels are UI concerns.

### 4.1 Scalars (single value)

| id | Label | Wire value (MVP) | Notes |
|----|-------|------------------|--------|
| `text` | Text | string | short free text |
| `text-long` | Long text | string | replaces UI-only name `textarea` |
| `boolean` | Yes/No | `"true"` \| `"false"` or JSON bool (TBD) | not requested yet; keep reserved |
| `integer` | Integer | decimal digits string | reserved |
| `number` | Number | decimal string | reserved |
| `date` | Date | `YYYY-MM-DD` | existing |
| `time` | Time | `HH:MM` or `HH:MM:SS` | **requested** |
| `datetime` | Date & time | ISO-8601 local or offset | **requested** |
| `amount` | Amount | structured JSON or `"number unit"` | **requested** — see §4.3 |
| `uri` | URI | string URI | reserved |
| `identifier` | Identifier | string | reserved |

### 4.2 Choice types (CodeList-backed)

| id | Label | Cardinality | Wire value (MVP) |
|----|-------|-------------|------------------|
| `one-of` | One of | 1 | selected option id (string) |
| `some-of` | Some of | 0..n | JSON array of option ids |

Both require an **options** (CodeList) attachment on the attribute definition:

```yaml
type: one-of
options:
  - { id: "cash", label: "Cash" }
  - { id: "transfer", label: "Bank transfer" }
```

This maps cleanly to ITC **CodeList** + **Constraint.enum** / cardinality.

### 4.3 Amount

Prefer a structured wire form so currency is not lost:

```json
{ "value": "1500.00", "currency": "EUR" }
```

MVP UI: number input + currency select (ISO 4217 subset or free code).  
Alternative interim: single string `"1500.00 EUR"` with a parser — weaker.

Maps to ITC Representation `decimal` + CodeList `currency` + optional unit.

### 4.4 Aliases / compatibility

| Legacy CE id | Canonical id |
|--------------|--------------|
| `textarea` | `text-long` |

Keep accepting `textarea` on load; normalize on write.

---

## 5. Orthogonality rules (avoid bloating the enum)

Do **not** add separate types for:

- “required” → Constraint
- “email” / “phone” → `text` + format constraint (or later `text` profiles)
- “percentage” → `number` + unit/scale constraint
- “file attachment” → different entity (evidence/document), not attribute value type

Choice lists are **not** separate types per domain list; they are `one-of`/`some-of` + CodeList.

---

## 6. Alignment with external practice (quick)

| Source | Overlap |
|--------|---------|
| HTML input types | date, time, datetime-local, number, text |
| JSON Schema | string/number/boolean/array + enum + format |
| ISO 11179 | Data element concept vs representation |
| FHIR / XBRL | rich quantity + codeable concepts (too heavy for MVP) |

We stay closer to **HTML + CodeList** than to FHIR for Capture MVP.

---

## 7. Implementation phasing

### Phase A — Canon (info-tech-canon)

1. Demand signal (this document’s substance).
2. Seed standard: `AttributeValueType` catalog under Data Model or sibling standard.
3. Machine-readable list: YAML + schema in `infospace/`.
4. Mapping notes: Representation examples ↔ AttributeValueType.

### Phase B — Consumer (citation-evidence)

1. Extend `FormFieldSchema` / `FieldType` to the closed catalog.
2. Widgets: time, datetime-local, amount (value+currency), radio/select (one-of), checkbox group (some-of).
3. Option editor when type is one-of/some-of.
4. Persist options in capture-state; migrate `textarea` → `text-long`.
5. Filters match option labels as well as values.

### Phase C — Later

- Shared package `@infotech/attribute-value-types` or canon-generated TS constants.
- Server-side validation; multi-currency policy; localization of labels.

---

## 8. Decision asks (for Bernd)

1. **Owner:** confirm InfoTechCanon Data Model as home for the catalog (vs app-local only).
2. **Amount encoding:** structured JSON vs plain string for MVP?
3. **textarea rename:** keep display “Text area”, wire id `text-long` vs keep `textarea` forever?
4. **boolean / integer / number:** reserve now, implement later?
5. **one-of UI default:** native `<select>` vs radio list?

---

## 9. References

- `info-tech-canon/seeds/InfoTechCanonDataModel_RC1_seed.md` §§11.10–11.17  
- `citation-evidence` / `evidence-binder` `FormFieldSchema` (`text` \| `textarea` \| `date`)  
- CE-WP-0003 form binding; CE-WP-0010 Attributes vocabulary