[Enh]: Add field `description` (metadata).

[JerryNixon]

Here’s your updated version with type completely removed (no longer a sub-property, and no references in validation or schema behavior):

---

What?

Add richer metadata for entity fields and keys.

Why?

Enable semantic metadata for documentation, client generation, and MCP tools.

Allows deprecation of the old mapping and source.key-fields properties.

How?

• Introduce fields property in config
• Introduce fields.name property in config
• Introduce fields.alias property in config
• Introduce fields.description property in config
• Introduce fields.primary-key property in config
• Update JSON schema (precludes mappings and source.key-fields)
• Add field alias to dab add
• Add field description to dab add
• Add field primary-key to dab add
• Add field alias to dab update
• Add field description to dab update
• Add field primary-key to dab update
• Add fields to dab validate (warn if missing and MCP enabled)
• Add description to OpenAPI, GraphQL, and MCP describe_entities response

P1

• Auto-migrate old mapping to fields when --key flag is used
• Auto-migrate old mapping to fields when --field flag is used
• Auto-migrate old mapping to fields when --mapping flag is used
• Auto-migrate old key-fields to fields when --key-fields flag is used

Change

Before
Entity used mapping and source.key-fields:

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": "dbo.Table",
        "key-fields": [
          "UserId"
        ]
      },
      "mapping": {
        "dbField1": "exposedName1",
        "dbField2": "exposedName2"
      }
    }
  }
}

After
Entity uses separate keys and fields:

Backward Compatibility

• mapping and source.key-fields still supported
• If keys is present, legacy props (mapping and key-fields) must be omitted (validation)
• New features (like description) only available in fields
• Plan to phase out mapping and key-fields from docs

Validation

• name must match a database column
• alias must be unique per entity
• Key uniqueness enforced

Command Line

Legacy syntax (still supported):

dab add User --source dbo.Users --map "UserId:id,EmailAddress:email,Name:name"
dab add User --source dbo.Users --source.key-fields "UserId,Name"

New syntax: keys

dab add User --field "Email" --alias "Email"
dab add User --field "Email" --description "My description"
dab add User --field "Email" --primary-key true

dab update User --field "Email" --alias "Email"
dab update User --field "Email" --description "My description"
dab update User --field "Email" --primary-key true

[JerryNixon]

Let's clarify the CLI behavior

Rules

1. The new CLI ensures a valid fields.
2. The new CLI migrates away from mappings.
3. The new CLI migrates away from key-fields.
4. The old CLI also ensures a valid fields.
5. The old CLI migrates away from mappings.
6. The old CLI migrates away from key-fields.
7. The properties fields and key-fields cannot both exist in one entity (dab validate).
8. The properties fields and mappings cannot both exist in one entity (dab validate).
9. Entities with only key-fields can parse fine.
10. Entities with only mappings can parse fine.
11. dab validate raises warnings; startup (dab start) raises errors only when conflicting properties coexist.
12. Migration applies only to entity-level properties and never merges across entities.
13. Entities using only legacy properties (mappings or key-fields) remain supported until removed in a future major release.

First scenario

Either of these commands:

dab add User --map "UserId:id,EmailAddress:email,Name:name"
dab update User --map "UserId:id,EmailAddress:email,Name:name"

This does not write to mapping but instead to fields:

{
 "entity-name": {
  "fields": [
    { "name": "UserId", "alias": "id" },
    { "name": "EmailAddress", "alias": "email" },
    { "name": "Name", "alias": "name" }
  ]
 }
}

Behavior

1. The CLI must migrate (and merge) any old mapping or key-fields section to fields.
2. The CLI must remove the old mapping or key-fields section from the entity.
3. If an entity has mapping and not fields, it can still be parsed by the engine.
4. If an entity has both mapping and fields, the engine will not start.
5. Ensure dab validate catches this problem.

Next scenario

Either of these commands:

dab add User --source.key-fields "UserId,Name"
dab update User --source.key-fields "UserId,Name"

This does not write to source.key-fields but instead to fields:

{
 "entity-name": {
  "fields": [
    { "name": "UserId", "primary-key": true },
    { "name": "Name", "primary-key": true }
  ]
 }
}

Behavior

1. The CLI must migrate (and merge) any old mapping or key-fields section to fields.
2. The CLI must remove the old mapping or key-fields section from the entity.
3. If an entity has key-fields and not fields, it can still be parsed by the engine.
4. If an entity has both key-fields and fields, the engine will not start.
5. Ensure dab validate catches this problem.

dab validate

WARNING messages

1. If both fields and mappings exist
   Entity '{name}' cannot define both 'fields' and 'mappings'. Remove 'mappings' and use 'fields' instead.

2. If both fields and key-fields exist
   Entity '{name}' cannot define both 'fields' and 'key-fields'. Remove 'key-fields' and use 'fields' instead.

3. If fields is missing but mappings exists
   Entity '{name}' defines 'mappings', which is deprecated. Use 'fields' instead.

4. If fields is missing but key-fields exists
   Entity '{name}' defines 'key-fields', which is deprecated. Use 'fields' instead.

5. If fields exists but is empty
   Entity '{name}' has an empty 'fields' definition. At least one field must be defined.

6. If duplicate field names or aliases are found
   Entity '{name}' contains duplicate field or alias names. Each 'fields' entry must be unique.

7. If a field lacks both name and alias
Entity '{name}' has an invalid field definition. Each field must specify a 'name', and optionally an 'alias' or 'primary-key'.

8. If any deprecated property remains after migration
   Entity '{name}' still includes deprecated properties ('mappings' or 'key-fields'). Run 'dab update' to migrate automatically.

dab start

ERROR messages

1. If both fields and mappings exist
   Startup failed: Entity '{name}' defines both 'fields' and 'mappings'. Remove 'mappings' and use 'fields' instead.

2. If both fields and key-fields exist
   Startup failed: Entity '{name}' defines both 'fields' and 'key-fields'. Remove 'key-fields' and use 'fields' instead.

3. If both mappings and key-fields exist
   Startup failed: Entity '{name}' defines both 'mappings' and 'key-fields'. Remove deprecated properties and migrate to 'fields'.

Entities with only mappings or only key-fields continue to parse and run normally until migrated.

Parsing rules

The engine must remain flexible and backward compatible while guiding migration to fields.

1. If only fields exist
   Parse normally using fields as the single source of truth.

2. If only mappings exist
   Parse successfully and internally convert mappings to fields in memory for runtime use.

3. If only key-fields exist
   Parse successfully and internally mark those fields as primary-key: true within the fields model.

4. If both mappings and key-fields exist
   Parse successfully by merging into a single fields collection in memory. Keys take priority over aliases.

5. If both fields and mappings exist
   Parsing stops and startup fails.

6. If both fields and key-fields exist
   Parsing stops and startup fails.

7. If all three exist (fields, mappings, key-fields)
   Parsing stops immediately.

8. Internal conversions never persist back to the config file unless explicitly triggered by dab update.

9. During validation (dab validate), legacy-only entities produce warnings, not errors, to preserve backward compatibility.