Skip to content

Field types

A field is declared once, as name:Type after the -- of generar scaffold or generar dominio, and Puerto carries its type through every layer. The decision for each type is made in one place in the generator, generators/types.rs (ADR-0011).

CLI Rust Postgres TypeScript Form control
titulo:String String TEXT NOT NULL string text input, required
cantidad:i64 i64 BIGINT NOT NULL number number input
valoracion:f64 f64 DOUBLE PRECISION NOT NULL number number input, step=any
activo:bool bool BOOLEAN NOT NULL boolean checkbox
id_externo:Uuid Uuid UUID NOT NULL string text input, required
vence_en:DateTime DateTime<Utc> TIMESTAMPTZ NOT NULL string (ISO 8601) datetime-local
meta:map HashMap<String, String> JSONB NOT NULL DEFAULT '{}' Record<string, string> textarea, key=value per line

DateTime and map are shorthands: the manifest stores DateTime<Utc> and HashMap<String, String>.

CLI Rust Postgres TypeScript
nota:opt:String Option<String> TEXT (nullable) string | null
stock:opt:i64 Option<i64> BIGINT number | null
puntuacion:opt:f64 Option<f64> DOUBLE PRECISION number | null
hecho:opt:bool Option<bool> BOOLEAN boolean | null
visto_en:opt:DateTime Option<DateTime<Utc>> TIMESTAMPTZ string | null
etiquetas:vec:String Vec<String> TEXT[] NOT NULL DEFAULT '{}' string[]
cantidades:vec:i64 Vec<i64> BIGINT[] NOT NULL DEFAULT '{}' number[]

An optional field is not required in the form, and an empty input is sent as null. A vector is a comma-separated text input.

A value object wraps a primitive in a type of its own, so the domain can validate it once and nothing can pass a raw string where an Email goes. See Value objects.

CLI Rust (domain) On the wire
email:Email:String Email(String) string
importe:Importe:f64 Importe(f64) number
apodo:Apodo:opt:String Option<Apodo> string | null
etiquetas:Etiqueta:vec:String Vec<Etiqueta> string[]
estado:Estado:enum:Borrador/Pagado enum Estado { Borrador, Pagado } "Borrador" | "Pagado" (a <select>)
email:Email the shared Email its inner type

The last row uses a shared value object, declared once with puerto generar objeto-valor Email String and reused by any entity.

A field can hold another entity’s id (ADR-0022): an Pedido (order) that belongs to a Cliente (customer) keeps the customer’s id, never the customer.

CLI Rust (domain) Postgres On the wire Form control
cliente_id:ref:Cliente IdCliente UUID NOT NULL REFERENCES clientes (id) string (uuid) <select> of customers
revisor_id:ref:opt:Cliente Option<IdCliente> UUID REFERENCES clientes (id) string | null <select> with an empty option
  • The target must be a CRUD entity already scaffolded, and not the entity itself. ! (one-to-one) is allowed on ref:, not on ref:opt:.
  • The domain holds the target’s id type, so an IdProducto cannot go where an IdCliente is expected, and dominio_pedido depends on dominio_cliente. Rows and DTOs hold a Uuid. Two contexts that reference each other would be a cycle between crates, so scaffold refuses the reference that closes one.
  • In --db projects the foreign key checks that the target exists: a write naming a missing one is 422 with <entidad>.validacion.cliente_id_no_encontrado, shown under the field. The use case does not look the customer up first. In-memory projects check nothing.
  • The list filters by each reference: GET /pedidos?clienteId=….
  • Deletes are soft, so an order keeps pointing at its deleted customer: refusing or cascading the delete is the project’s decision.

Not yet: a reference to the entity itself, many-to-many (vec:ref:), and ref:Usuario.

Append ! to any field: sku:String!, email:Email:String!. In Postgres it becomes a named partial unique index, so a soft-deleted row does not keep its value taken (ADR-0003):

CREATE UNIQUE INDEX productos_sku_key ON productos (sku) WHERE borrado = false;

A duplicate is 409 with <entidad>.duplicado, from Postgres and from the in-memory repository alike.

id (UUID PRIMARY KEY, the entity’s own Id<Entidad> in the domain), creado_en, actualizado_en, borrado and borrado_en. Deletes are soft: every generated query filters WHERE borrado = false.

Puerto refuses a name when it would not compile or not migrate, at the command that introduced it rather than at cargo build:

  • Field names that every entity already has (id, creado_en, actualizado_en, borrado, borrado_en) and Rust keywords (type, match…). Field names are snake_case.
  • In --db projects, PostgreSQL reserved words as field names (order, user, desc…). A project without a database may use them (ADR-0005).
  • Entity names that would collide with a type the generated code already uses (Error, String, Option, Uuid…) or with a context the project already has: Correo, the context of mails, and in auth projects Usuario, Me and Auth. Entity names are PascalCase.