Choosing A Table Shape⚓︎

The first design choice is not which parser to use. It is how the table should be read.

Some tables read naturally across rows. Others read better as vertical cards. Both shapes are valid. The better one is the shape that makes the feature file less tiring to scan.

Row-shaped tables⚓︎

Use a row-shaped table when every record has only a few fields and the reader will compare many records at once.

Given the users exist
  | name  | role   | active |
  | Asha  | admin  | yes    |
  | Bruno | editor | no     |

This shape feels like a spreadsheet. It is compact, familiar, and good for lists of users, roles, permissions, simple products, or short payments.

See how that shape becomes a schema in Define the Row Contract.

Column-shaped tables⚓︎

Use a column-shaped table when each item has many fields, or when readers think of each item as a card.

Given the content exists
  | IDs      | article-1        | poll-1        |
  | Type     | Article          | Poll          |
  | Headline | Release notes    | Choose a plan |
  | Status   | draft            | published     |

Here, article-1 and poll-1 are the records. Each row describes one field of those records. This is often easier for CMS content, configuration, page sections, or objects with many optional fields.

See the corresponding implementation in Define the Column Contract.

from talika import ColumnTable, field, id_field


class ContentTable(ColumnTable):
    id = id_field("IDs")
    content_type = field("Type", required=True)
    headline = field("Headline", required=True)
    status = field("Status", required=True)

The wide-table smell⚓︎

A row-shaped table can become hard to read when each record has too many fields:

Given the content exists
  | id        | type    | headline      | body       | options       | status    |
  | article-1 | Article | Release notes | Many words |               | draft     |
  | poll-1    | Poll    | Choose a plan |            | Basic, Pro    | published |

This table is still valid, but the reader has to work harder. Long text, optional fields, and variant-specific columns often push a table toward the column shape.