From d4327b6be6adbe3ac38eeb70710b3846f8f54264 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 30 Jul 2026 20:58:25 +0200 Subject: [PATCH] Propose AttributeValueType catalog research and CE-WP-0012. Document gap vs InfoTechCanon Data Model stubs; plan consumer types time/datetime/amount/one-of/some-of aligned with a future ITC catalog. --- docs/mvp-workplans-index.md | 6 +- wiki/AttributeValueTypes-proposal.md | 200 ++++++++++++++++++ workplans/CE-WP-0012-attribute-value-types.md | 184 ++++++++++++++++ 3 files changed, 388 insertions(+), 2 deletions(-) create mode 100644 wiki/AttributeValueTypes-proposal.md create mode 100644 workplans/CE-WP-0012-attribute-value-types.md diff --git a/docs/mvp-workplans-index.md b/docs/mvp-workplans-index.md index 63a510d..38bc92e 100644 --- a/docs/mvp-workplans-index.md +++ b/docs/mvp-workplans-index.md @@ -33,11 +33,13 @@ publish tasks wait on ADR-0002 resolution. |----------|-------|--------| | `CE-WP-0010` | Annotate & Attributes UX — labels, filters, layout, evidence connectors | finished | | `CE-WP-0011` | Attributes guide n:m lines, title migration, Add attribute placement | finished | +| `CE-WP-0012` | Attribute value types — time, datetime, amount, one-of, some-of | proposed | User-facing polish after manual document review: rename Review→Annotate, keep Evidence column in Capture with Attributes on the right, list filters, and -card→citation connector lines. CE-WP-0011 adds n:m attribute↔evidence guides, -legacy title migration, and Add attribute below the list. +card→citation connector lines. CE-WP-0011 adds n:m attribute↔evidence guides. +CE-WP-0012 extends attribute types; canon ownership tracked as ITC-WP-0013 +(see `wiki/AttributeValueTypes-proposal.md`). ## Order diff --git a/wiki/AttributeValueTypes-proposal.md b/wiki/AttributeValueTypes-proposal.md new file mode 100644 index 0000000..8396caf --- /dev/null +++ b/wiki/AttributeValueTypes-proposal.md @@ -0,0 +1,200 @@ +# Proposal: Attribute Value Type Canon (consumer + InfoTechCanon) + +**Status:** research draft (2026-07-30) +**Consumers:** citation-evidence Capture attributes +**Producer candidate:** info-tech-canon (Data Model extension) +**Related:** CE-WP-0012, ITC-WP-0013 (proposed) + +--- + +## 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 `