# Parameter schemas and configuration

> Implementation status: see [Parameter workspace and application delivery](27-parameter-workspace.md). This chapter is the broader design baseline; not every acceptance criterion is implemented.

## Design objective

A visual schema designer lets authorized bank staff define parameter forms without writing application code. The same published schema drives device parameter editing, server validation, template application and terminal payload generation. The implementation belongs entirely to this solution: Razor views plus a focused JavaScript/TypeScript editor module, MVC endpoints and gRPC use cases.

The reference editor was inspected for interaction concepts: catalog/tree navigation, field properties, preview contexts, row/column/span layout, typed fields and import comparison. Its framework, service model and destructive overwrite behavior are not adopted. No external project references or branded components are required.

## Designer workspace

| Region | Contents | Behavior |
| --- | --- | --- |
| Header | Customer, application, schema version, Draft/Published badge | Persistent ownership context; published version read-only |
| Left: structure | Catalog tables, root node, child/repeatable nodes, fields | Add, rename, reorder; stable IDs survive label changes |
| Center: canvas | Form layout with sections, rows, columns and fields | Move/resize fields; keyboard alternatives; design/preview toggle |
| Right: properties | Type, key, label, help, required/default, constraints, reference | Immediate local feedback; authoritative server validation |
| Bottom: validation | Errors, warnings, compatibility and version diff | Click error to select field/node; no publish while invalid |
| Action bar | Save draft, preview, compare, import/export, publish | Publish requires impact summary and permission |

Preview uses the same renderer as the device parameter form. Responsive preview includes wide and narrow layouts. A schema is a declarative document; it cannot contain executable JavaScript, arbitrary HTML, SQL or remote code references.

## Definition format

Use a versioned UIC TMS schema DSL, with `formatVersion` distinct from published schema version. It is not implicitly a standards-compliant JSON Schema document. Support text, textarea, integer/decimal, boolean, enum, date, hex, port, catalog reference, secret reference and controlled file reference. Field IDs and node IDs are immutable; labels and translated help text may change.

Validation includes required, requiredOnApply, length/range, enum membership, hex format, reference cardinality and safe regular expressions with timeout/complexity limits. Bound tree depth, repeat counts, total fields and document size. Stable record keys distinguish repeated acquirers/issuers; disallow duplicate keys. Published schemas identify compatible application versions, terminal platforms and serializer version.

```json
{
  "formatVersion": 1,
  "applicationKey": "bank-payment",
  "schemaVersion": 1,
  "catalogs": [{
    "id": "hosts",
    "label": {"en": "Connection profiles", "es": "Perfiles de conexión"},
    "fields": [
      {"id": "host", "type": "text", "required": true},
      {"id": "port", "type": "port", "default": 443}
    ]
  }],
  "root": {
    "id": "terminal",
    "fields": [
      {"id": "terminalId", "type": "text", "requiredOnApply": true,
       "layout": {"row": 1, "column": 1, "span": 6}},
      {"id": "hostProfile", "type": "reference", "catalogId": "hosts",
       "required": true, "layout": {"row": 1, "column": 7, "span": 6}}
    ],
    "children": [{"id": "acquirers", "repeatable": true,
      "recordKey": "acquirerCode", "fields": [
        {"id": "acquirerCode", "type": "text", "required": true}
      ], "children": []}]
  }
}
```

The example is illustrative; validation rules and serializers must be specified and tested before implementation. Catalog references resolve only inside the same customer and pinned schema/catalog revision. Secret fields return a masked/set indicator; leaving them unchanged preserves the secret reference. Clear and replace are explicit actions with separate authorization.

## Version lifecycle

Draft → Validated → Published → Deprecated → Retired. Save drafts with optimistic concurrency and durable autosave. Published versions are immutable; edit by cloning to a new version. Deprecation prevents new use by default but does not invalidate working devices. Retirement is blocked while required references remain unless an approved migration handles them.

Publishing validates the definition server-side, computes a canonical hash, records author and timestamp, identifies affected applications/devices/templates, and stores an immutable version. It never automatically deploys parameters to devices.

Import is staged: parse bounded content → validate format → show diff and compatibility impact → create draft/new version. Export excludes secret values and customer-specific records unless explicitly requested and authorized. Imports cannot overwrite published versions or delete existing values silently.

## Editing and applying device parameters

1. Select customer, device and application; load current published schema plus draft/config revision and concurrency token.
2. Render catalog references and nested/repeatable records from the schema. Show defaults, current values, secret status and validation feedback.
3. A template copies values into a draft. `requiredOnApply` fields prompt for device-specific values; unresolved fields block publication.
4. Server validates types, unknown keys, reference ownership, compatibility and secrets. Save a draft without changing the terminal.
5. Publish a resolved immutable revision, pinning schema, catalogs, serializer and artifact hashes. Show a value diff with secrets redacted.
6. Push via a deployment; device downloads the authorized artifact, validates it, applies atomically and acknowledges revision/hash.
7. Portal distinguishes draft, desired published revision, delivered revision and device-reported applied revision. Drift is visible; successful transport is not successful application.

Proposed release-one precedence is schema defaults → explicitly applied template → explicit device values. The result is materialized into a device revision. Groups/subgroups and tags are targeting tools, not automatic parameter inheritance. Moving a terminal between groups never mutates its effective configuration. Optional future group inheritance would require a separate decision defining precedence, exceptions and conflict behavior.

## Schema evolution and rollback

Classify added optional fields/defaults as potentially compatible; removed fields, required fields without values, type changes, changed reference cardinality and renamed stable IDs require an explicit migration plan. Preview impact against saved configurations and templates; report per-device errors. Never purge old values just because a field disappears from the new schema.

Migrate into new draft revisions transactionally or through resumable batches, keeping the old published revisions intact. A rollback deploys a known revision after confirming application/agent compatibility. If the terminal cannot apply atomically, document the safe update procedure and expose partial/failed state rather than claiming rollback support.

## Acceptance criteria

- A designer creates catalogs and nested repeatable nodes, lays out fields and previews without source-code edits.
- Client and server agree on valid/invalid fixtures for every supported type and constraint.
- Two editors cannot overwrite each other's draft; published schemas cannot be edited in place.
- Foreign-customer references, unknown fields, hostile markup and unbounded patterns are rejected.
- Required-on-apply fields prevent incomplete pushes; secrets never appear in exports or audit diffs.
- Device acknowledgement pins both revision and hash; stale acknowledgements cannot mark a newer revision applied.
- Template application and group movement follow the explicitly documented behavior.