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.
This commit is contained in:
parent
154e48cdd2
commit
d4327b6be6
3 changed files with 388 additions and 2 deletions
200
wiki/AttributeValueTypes-proposal.md
Normal file
200
wiki/AttributeValueTypes-proposal.md
Normal file
|
|
@ -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 `<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
|
||||
Loading…
Add table
Add a link
Reference in a new issue