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).
Primitives
Section titled “Primitives”| 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>.
Optional and repeated
Section titled “Optional and repeated”| 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.
Value objects
Section titled “Value objects”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.
References
Section titled “References”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 onref:, not onref:opt:. - The domain holds the target’s id type, so an
IdProductocannot go where anIdClienteis expected, anddominio_pedidodepends ondominio_cliente. Rows and DTOs hold aUuid. Two contexts that reference each other would be a cycle between crates, soscaffoldrefuses the reference that closes one. - In
--dbprojects the foreign key checks that the target exists: a write naming a missing one is422with<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.
Unique
Section titled “Unique”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.
Columns every entity has
Section titled “Columns every entity has”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.
Names that are refused
Section titled “Names that are refused”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
--dbprojects, 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 projectsUsuario,MeandAuth. Entity names are PascalCase.