Rentiful Open Data v1 Schemas

stable production Version: v1 Generated: 2026-03-03T07:30:00.696Z

This document contains the complete JSON Schema definitions for all entities and list responses in the Rentiful Open Data v1 contract.

Place

Entity Type: Place
Description: Rentiful Open Data v1 contract schema for Place. This is a public contract derived from the current data model, not a complete internal domain dump.
Required Fields: 3 fields
Entity Schema List Schema OpenAPI Reference
Fields (9)
Field Required? Type Description
canonicalUrl optional string Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/places/{handle}. Requires handle and countryCode. Mutable, may change if handle changes. May be omitted if handle or countryCode is not available.
countryCode optional string ISO 3166-1 alpha-2 country code for this Place (e.g., 'gb', 'ae'). Used for region-scoped marketing URLs. Optional.
dataUrl optional string Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.
handle optional string Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical placeId.
idUrl optional string Immutable, ID-based identity URL for this entity. Uses the Place ID token in the path (eg /places/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.
name required string The branded name of this Place (e.g., 'Wembley Park', 'East Village').
operatorId required string The current managing brand for this Place. This may change over time and is not part of the Place's identity.
placeId required string Canonical public identifier for this Place. Opaque, human-friendly key.
url optional string Public URL for this Place, if available.

Required Fields

  • placeId
  • operatorId
  • name

Collection

Entity Type: Collection
Description: Rentiful Open Data v1 contract schema for Collection. This is a public contract derived from the current data model, not a complete internal domain dump.
Required Fields: 4 fields
Entity Schema List Schema OpenAPI Reference
Fields (8)
Field Required? Type Description
canonicalUrl optional string Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/places/{placeHandle}/collections/{handle}. Requires handle, placeHandle, and countryCode. Mutable, may change if handle changes. May be omitted if handle, placeHandle, or countryCode is not available.
collectionId required string Canonical public identifier for this Collection. Opaque, human-friendly key.
dataUrl optional string Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.
handle optional string Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical collectionId.
idUrl optional string Immutable, ID-based identity URL for this entity. Uses the Collection ID token in the path (eg /collections/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.
name required string The name of this Collection (e.g., 'Ferrum', 'Portlands Place', 'Luna').
operatorId required string The current managing brand for this Collection. This may change over time and is not part of the Collection's identity.
placeId required string The Place this Collection belongs to. A Collection always belongs to a Place.

Required Fields

  • collectionId
  • placeId
  • operatorId
  • name

Building

Entity Type: Building
Description: Rentiful Open Data v1 contract schema for Building. This is a public contract derived from the current data model, not a complete internal domain dump.
Required Fields: 4 fields
Entity Schema List Schema OpenAPI Reference
Fields (15)
Field Required? Type Description
buildingId required string Canonical public identifier for this Building. Opaque, human-friendly key.
canonicalUrl optional string Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/places/{placeHandle}/buildings/{handle}. Requires handle, placeHandle, and countryCode. Mutable, may change if handle changes. May be omitted if handle, placeHandle, or countryCode is not available.
city optional string City where this Building is located.
collectionId optional string The Collection this Building belongs to, if any. A Building may belong to a Collection.
dataUrl optional string Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.
handle optional string Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical buildingId.
idUrl optional string Immutable, ID-based identity URL for this entity. Uses the Building ID token in the path (eg /buildings/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.
lat optional number Latitude coordinate for this Building.
lng optional number Longitude coordinate for this Building.
name required string The name of this Building (e.g., 'Sky Point', 'Landsby East').
operatorId required string The current managing brand for this Building. This may change over time and is not part of the Building's identity.
placeId required string The Place this Building belongs to. A Building always belongs to a Place.
postcode optional string Postal code for this Building.
streetAddress optional string Street address for this Building.
url optional string Public URL for this Building, if available.

Required Fields

  • buildingId
  • placeId
  • operatorId
  • name

Unit

Entity Type: Unit
Description: Rentiful Open Data v1 contract schema for Unit. This is a public contract derived from the current data model, not a complete internal domain dump. Unit represents the publicly presented rentable home. In co-living or student housing this may be an individual bedroom within a shared flat, rather than a self-contained apartment.
Required Fields: 7 fields
Entity Schema List Schema OpenAPI Reference
Fields (24)
Field Required? Type Description
availableFrom optional string Date from which this Unit is available. Format: YYYY-MM-DD.
bathrooms optional integer Number of bathrooms in this Unit.
bedrooms optional integer Number of bedrooms in this Unit.
buildingId required string The Building this Unit belongs to (authoritative parent). A Unit always belongs to a Building.
canonicalUrl optional string Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/property/{idToken}. Uses the Unit ID token in the path (never handle). Uses countryCode if available, otherwise equals idUrl. Mutable, may change if countryCode changes.
collectionId optional string The Collection this Unit belongs to, if any (derived/read-only). Derived from the Unit's Building.
dataUrl optional string Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.
floor optional integer Floor number for this Unit (integer).
handle optional string Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical unitId.
idUrl optional string Immutable, ID-based identity URL for this entity. Uses the Unit ID token in the path (eg /property/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.
isActive required boolean Whether this Unit is currently active. false for retired/superseded units.
lastVerifiedDate required string Date when this Unit's information was last verified. Format: YYYY-MM-DD.
layoutType optional string Standardized layout classification for cross-operator comparison and filtering. Derived from bedrooms and structure. Consistency: layoutType = 'studio' implies bedrooms = 0.
marketSegment optional string The market segment this Unit belongs to.
name optional string The name or identifier of this Unit (e.g., 'Apartment 101', 'Flat 12A').
operatorId required string The current managing brand for this Unit. This may change over time and is not part of the Unit's identity.
placeId required string The Place this Unit belongs to (derived/read-only, required). Derived from the Unit's Building.
sqm optional number Size of this Unit in square meters.
status required string Current availability status of this Unit. Availability is derived, not contractual. Lease/tenancy is never exposed.
structureType optional string The physical dwelling form of this Unit (standardized).
supersededByUnitId optional array Array of Unit IDs that supersede this Unit (for split/merge history). Empty array if none.
supersedesUnitId optional array Array of Unit IDs that this Unit supersedes (for split/merge history). Empty array if none.
unitId required string Canonical public identifier for this Unit. Opaque, human-friendly key.
unitType optional string Operator-specific unit taxonomy. Not standardized or comparable across operators. Examples: operator codes or labels (e.g., '1B-Type-04', 'A1', 'FP-C'), not generic values like 'studio'.

Required Fields

  • unitId
  • buildingId
  • placeId
  • operatorId
  • status
  • lastVerifiedDate
  • isActive

Listing

Entity Type: Listing
Description: Rentiful Open Data v1 contract schema for Listing. This is a public contract derived from the current data model, not a complete internal domain dump.
Required Fields: 4 fields
Entity Schema List Schema OpenAPI Reference
Fields (17)
Field Required? Type Description
availableFrom optional string Date from which this Listing is available. Format: YYYY-MM-DD.
canonicalUrl optional string Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/property/{handle}. Requires handle and countryCode. Mutable, may change if handle changes. May be omitted if handle or countryCode is not available.
currency optional string ISO 4217 currency code for rent amounts.
dataUrl optional string Direct JSON endpoint on the Property Service open data domain.
depositWeeks optional string Deposit amount expressed as weeks of rent.
firstPublishedAt optional string When this Listing was first published. Format: ISO 8601 date-time.
furnished optional string Furnishing status of this Listing.
idUrl optional string Immutable, ID-based identity URL for this entity. Uses the Listing ID token in the path.
lastUpdatedAt optional string When this Listing was last updated. Format: ISO 8601 date-time.
listingId required string Canonical public identifier for this Listing. Opaque, human-friendly key.
maxTenancyMonths optional string Maximum tenancy length in months, if applicable.
minTenancyMonths optional string Minimum tenancy length in months.
operatorId required string The current managing brand for this Listing.
petsAllowed optional string Whether pets are allowed in this Listing.
rentPcm optional string Monthly rent in pence (GBP) or smallest currency unit.
status required string Current availability status of this Listing.
unitId required string The Unit this Listing is for. A Listing always belongs to a Unit.

Required Fields

  • listingId
  • unitId
  • operatorId
  • status

Operator

Entity Type: Operator
Description: Rentiful Open Data v1 contract schema for Operator. This is a public contract derived from the current data model, not a complete internal domain dump.
Required Fields: 2 fields
Entity Schema List Schema OpenAPI Reference
Fields (7)
Field Required? Type Description
canonicalUrl optional string Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/operators/{handle}. Requires handle. No country prefix for operators. Mutable, may change if handle changes. May be omitted if handle is not available.
dataUrl optional string Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.
handle optional string Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical operatorId.
idUrl optional string Immutable, ID-based identity URL for this entity. Uses the Operator ID token in the path (eg /operators/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.
name required string The name of this Operator (e.g., 'Get Living', 'Quintain Living', 'Vertus').
operatorId required string Canonical public identifier for this Operator. Opaque, human-friendly key.
url optional string Public URL for this Operator, if available.

Required Fields

  • operatorId
  • name

Entity Relationships

Place → Contains Collection (optional) and Building

Collection → Groups Buildings (optional, marketing grouping)

Building → Contains Unit

Unit → Belongs to Building (required), Collection (optional, derived), Place (required, derived)

Unit → Has many Listings (rental offerings over time)

Listing → Temporal rental offering for a Unit (price, availability, terms)

Operator → Manages all entities (current managing brand, may change over time)

Note: Unit ancestry fields (placeId, collectionId) are derived/read-only convenience fields. Building and Collection placeId fields represent canonical relationships.

Contract Rules

ID Patterns

All properties ending in Id must match these patterns:

Required Fields by Entity

Name Requirements

All renter-native entities (Place, Residence, Building, Operator) require name with minLength: 1.

Unit name is optional.

URL Fields

All entities include idUrl field (format: uri) - immutable, ID-based identity URL on rentiful.ai, dereferenceable via content negotiation (HTML by default, JSON with Accept: application/json).

All entities include dataUrl field (format: uri) - direct JSON endpoint on the Property Service open data domain (same domain family as schemas and OpenAPI).

All entities include optional canonicalUrl field (format: uri) - SEO canonical URL for sharing and marketing on rentiful.ai.

External links remain under the url field.

List Response Schemas

All entity types have corresponding list response schemas (e.g., place.list.schema.json, operator.list.schema.json).

List responses use the standard envelope format: { "schemaUrl": "...", "items": [...], "nextCursor": "..." | null }.

Each list schema references its entity schema via $ref. The items array contains entities conforming to the entity schema.

Additional Properties

All schemas enforce additionalProperties: false. Only explicitly allowlisted fields are exposed.

Unit Entity Notes

Unit represents the publicly presented rentable home. In co-living or student housing this may be an individual bedroom within a shared flat, rather than a self-contained apartment.