Properties
Property entities represent real-estate assets, rentable sub-units, ownership and management roles, and time-dependent tax configuration.
properties
Purpose
Represents a real-estate asset. It must support Italian taxation data and several rental modes, including single-tenant rentals, multi-tenant rentals, and room-level rentals.
Suggested attributes
| Field | Description |
|---|---|
id | Primary identifier. |
name | Internal property name. |
property_type | APARTMENT, VILLA, ROOM, OFFICE, SHOP, BUILDING, or OTHER. |
rental_mode | SINGLE_TENANT, MULTI_TENANT, or ROOM_RENTAL. |
address | Street address. |
city | City. |
province | Italian province or equivalent local area. |
region | Region. |
country | Country. |
postal_code | Postal code. |
floor | Floor. |
surface_sqm | Surface in square meters. |
rooms | Number of rooms. |
bathrooms | Number of bathrooms. |
cadastral_municipality | Cadastral municipality. |
cadastral_section | Cadastral section. |
cadastral_sheet | Cadastral sheet. |
cadastral_parcel | Cadastral parcel. |
cadastral_subaltern | Cadastral subaltern. |
cadastral_category | Italian cadastral category. |
cadastral_class | Cadastral class. |
cadastral_income | Cadastral income. |
ownership_title | Ownership title or legal basis. |
purchase_date | Purchase date. |
purchase_price | Purchase price. |
main_residence_flag | Whether the asset is a main residence for tax purposes. |
tax_regime_default | Default tax regime for contracts on this property. |
imu_applicable | Whether IMU may apply. |
tari_applicable | Whether TARI may apply. |
cedolare_secca_eligible | Whether cedolare secca may be available. |
status | AVAILABLE, RENTED, INACTIVE, or UNDER_MAINTENANCE. |
notes | Free-form notes. |
created_at | Creation timestamp. |
updated_at | Last update timestamp. |
Relationships
| Relationship | Description |
|---|---|
properties to property_units | One property has many rentable units. |
properties to property_parties | One property has many role-based party links. |
properties to contracts | One property has many contracts over time. |
properties to property_services | One property has many utilities and services. |
properties to property_bank_accounts | One property may use several bank accounts. |
properties to bank_transactions | Bank transactions may be linked directly or indirectly through splits. |
properties to expected_expenses | One property has many expected expenses. |
properties to documents | Documents can be linked to properties. |
properties to maintenance_requests | One property has many maintenance requests. |
Notes and design rationale
Property tax fields can exist on properties for current/default values, but historical and time-dependent tax data belongs in property_tax_profiles.
property_units
Purpose
Represents rentable sub-units of a property. This supports whole-property rentals, individual room rentals, and separate parking or storage units.
Suggested attributes
| Field | Description |
|---|---|
id | Primary identifier. |
property_id | Parent property. |
unit_name | Human-readable unit name, for example Room A. |
unit_type | WHOLE_PROPERTY, ROOM, PARKING, STORAGE, or OTHER. |
surface_sqm | Surface in square meters. |
floor | Floor. |
private_bathroom_flag | Whether the unit has a private bathroom. |
furnished_flag | Whether the unit is furnished. |
status | AVAILABLE, RENTED, INACTIVE, or UNDER_MAINTENANCE. |
notes | Free-form notes. |
created_at | Creation timestamp. |
updated_at | Last update timestamp. |
Relationships
| Relationship | Description |
|---|---|
property_units.property_id to properties.id | Each unit belongs to one property. |
property_units to contract_units | Units can be covered by one or more contracts over time. |
property_units to property_services | A service may be specific to a room or unit. |
Notes and design rationale
Even whole-property contracts should be represented through contract_units when unit-level precision is needed. A property can have a WHOLE_PROPERTY unit plus room units if the business needs both views.
property_parties
Purpose
Role-based relationship between parties and properties.
Suggested attributes
| Field | Description |
|---|---|
id | Primary identifier. |
property_id | Linked property. |
party_id | Linked party. |
role | OWNER, CO_OWNER, TENANT, MANAGER, SERVICE_PROVIDER, ACCOUNTANT, AGENCY, or GUARANTOR. |
ownership_percentage | Ownership share when relevant. |
start_date | Role start date. |
end_date | Role end date. |
notes | Free-form notes. |
Relationships
| Relationship | Description |
|---|---|
property_parties.property_id to properties.id | Many roles can exist for one property. |
property_parties.party_id to parties.id | One party can have roles on many properties. |
Notes and design rationale
Do not store owner_id, tenant_id, or manager_id directly on properties. Ownership, tenancy, and management change over time and can involve multiple parties.
property_tax_profiles
Purpose
Stores tax-related property information over time.
Suggested attributes
| Field | Description |
|---|---|
id | Primary identifier. |
property_id | Linked property. |
valid_from | Start date of this tax profile. |
valid_to | End date of this tax profile. Nullable for current profile. |
tax_country | Tax country, initially IT. |
tax_regime | Applicable tax regime. |
cadastral_income | Cadastral income valid for the period. |
imu_applicable | Whether IMU applies. |
tari_applicable | Whether TARI applies. |
cedolare_secca_eligible | Whether cedolare secca is eligible. |
main_residence_flag | Main residence status for the period. |
notes | Tax notes. |
Relationships
| Relationship | Description |
|---|---|
property_tax_profiles.property_id to properties.id | One property can have many historical tax profiles. |
Notes and design rationale
Tax rules and fiscal classification can change. Keeping historical profiles allows yearly tax reporting without losing the context that was valid at the time.