logicsrc/docs/openproperty.md

OpenProperty

The property profile of OpenListing. It adds one key, subject.property, describing a house, an apartment, a room, a plot of land or a commercial unit. Everything else — the offer, the price, the location, the media, the provenance — is the parent specification and is not restated here.

Status: 0.1 draft, alongside the parent.

Slug: openproperty

When this profile applies

When subject.type is "property". A reader that does not know this profile still reads the whole listing correctly; it simply does not know how many bedrooms the thing has.

subject.property

"subject": {
  "type": "property",
  "title": "Two-bedroom flat on Elm Street",
  "property": {
    "kind": "apartment",
    "bedrooms": 2,
    "bathrooms": 1.5,
    "floor_area": { "value": 780, "unit": "sqft" },
    "lot_area": { "value": 0.12, "unit": "acre" },
    "year_built": 1974,
    "floors": 1,
    "floor": 3,
    "parking": { "spaces": 1, "kind": "street" },
    "furnished": "unfurnished",
    "heating": "gas",
    "pets": "cats-only",
    "features": ["balcony", "dishwasher"],
    "energy": { "rating": "C", "scheme": "EPC" }
  }
}

kind

house, apartment, condo, townhouse, room, land, commercial, parking, storage, other.

room is a room within a dwelling let separately, which is a different thing from a one-bedroom apartment and is routinely mislabelled as one. land carries lot_area and usually no floor_area.

Fields

Field	Notes
bedrooms	An integer. A studio is 0, not absent — this is the one place absent and zero genuinely differ and the difference matters.
bathrooms	A number, because half-baths are real and 1.5 is the ordinary way to write one.
floor_area	value + unit (sqft, sqm). Internal area.
lot_area	value + unit (sqft, sqm, acre, hectare).
year_built	Four-digit year.
floors	How many storeys the dwelling has.
floor	Which storey it is on. Distinct from floors, and confusing them is the commonest error in property data. Ground floor is 0 in the UK sense and 1 in the US sense, so a publisher SHOULD also set floor_scheme to uk or us when it sets floor.
parking	spaces and kind (garage, driveway, street, permit, none).
furnished	furnished, part-furnished, unfurnished.
heating	Free text; no controlled vocabulary, because national ones disagree.
pets	allowed, none, cats-only, dogs-only, ask.
accessibility	step_free, lift, wet_room and similar, as a list.
features	Free-text list. Deliberately unconstrained: this is where everything a controlled vocabulary would lose goes.
energy	rating and scheme (EPC, HES, NABERS). The scheme is required alongside the rating, because a bare "C" means nothing without it.

All are optional. Absent means unstated, exactly as in the parent, with bedrooms: 0 noted above as the meaningful exception.

Tenure

For a sale, subject.property.tenure MAY be freehold, leasehold, commonhold, share-of-freehold or other, with lease_years_remaining where it applies. A leasehold with eighty years left is a materially different asset from the same flat freehold, and a listing that omits this is omitting the thing a buyer most needs.

What this profile does not do

• No valuation. A listing says the asking price. What the thing is worth is somebody else's claim, and OpenOntology is where a claim with a source belongs.
• No condition or survey. "Needs work" is description text, not a field, because every attempt to enumerate condition ends up either useless or misleading.
• No floorplan geometry. A floorplan is media with kind: "floorplan". Describing rooms as geometry is a different specification and a much larger one.
• No address normalisation. The parent's location carries what the seller stated, at the precision the seller chose. Normalising it is a consumer's job.

Market context is not a listing

Aggregate market data — median sale price for a ZIP, days on market, inventory — is not an OpenListing document and MUST NOT be published as one. It describes a market, not a thing on offer, and it has no offer and no seller. Directories that carry both keep them apart.