You publish a listing for a three-bedroom home. The JSON-LD block on that page looks identical to the one on your rental site, right down to the @type value. It’s a common shortcut: copy the RealEstateListing schema for a sale and paste it onto a lease page without changing a single character. The problem is that a sale and a lease are fundamentally different transactions, and search engines need to know the difference to categorize your property listing markup correctly.
The authoritative type for this is RealEstateListing, a Schema.org definition designed specifically for web pages that present real-estate offers. Unlike generic property types that describe the physical structure, RealEstateListing describes the commercial intent behind the page. It sits in the “new” area of Schema.org, making it a precise tool for sites that want to distinguish between a property being sold and one being leased out. Ignoring this distinction means your real estate schema fails to convey whether a potential buyer is looking at an acquisition opportunity or a tenancy agreement.
How RealEstateListing works in the schema hierarchy
Real estate schema begins with the RealEstateListing type, which is defined as a WebPage that describes one or more real-estate Offers. In the Schema.org hierarchy, this type sits specifically under WebPage, following the path: Thing > CreativeWork > WebPage > RealEstateListing. This placement is critical because it tells search engines that you are not marking up the physical building itself, but rather the digital page that advertises it.
The WebPage vs. Offer distinction
Understanding this hierarchy prevents a common error in property listing markup. The RealEstateListing entity represents the manifestation of the offer on your site. It contains metadata about the page, such as the datePosted or the primaryImageOfPage. The actual transaction details, however, live in a nested Offer object. This separation allows you to describe the webpage experience while distinctly specifying the commercial intent within it.
Why this specific type matters
RealEstateListing resides in the “new” area of Schema.org. While this means the definition is still evolving, it offers a more precise choice than generic page types. By using this specific real estate schema type, you signal to crawlers that the page contains structured data relevant to property transactions. This specificity helps AI engines distinguish your listing from standard articles or product pages, ensuring your content is understood in the context of real-estate commerce rather than general web information.
Deciding between businessFunction sell and lease
The businessFunction property inside the nested Offer object is the primary switch that defines the nature of the transaction. In property listing markup, this field tells the crawler whether the user is expected to buy the asset or rent it out. It is the single most critical attribute for distinguishing between a sale and a lease.
The ‘sell’ function for sales
When the goal is a permanent transfer of ownership, the businessFunction must be set to sell. This is the standard value for residential property listings where the intent is a definitive purchase. The markup signals that the offer is for a sale, not a temporary arrangement. This distinction is vital for the property listing markup to be interpreted correctly by search engines.
The ‘lease’ function for rentals
Conversely, when the goal is a long-term tenancy, the businessFunction is set to lease. This is the core of the residential rental schema. It indicates that the property is being let out for a specific duration, often tied to the leaseLength property. For a residential rental schema, this value ensures the listing is categorized under rentals, not sales, in search results and AI-generated summaries.
The cost of choosing the wrong function
Choosing the wrong businessFunction miscommunicates the intent of the listing to both search engines and AI engines. If a rental is marked as a sale, users may click with the expectation of buying, only to find a lease agreement. This mismatch hurts user experience and can lower the credibility of the real estate schema in the eyes of automated systems. Accurate tagging ensures that the JSON-LD real estate data aligns with the actual business intent, helping AI engines distinguish between active sales and available rentals with precision.
Applying the leaseLength property for residential rentals
When structuring residential rental schema, the leaseLength property is the key differentiator that tells search engines exactly how long a tenancy lasts. This attribute is specific to offers where the businessFunction is lease, making it a critical component of accurate real estate schema for rental listings.
The valid data types for this field are Duration or QuantitativeValue. This flexibility allows you to specify the term in a way that matches your data source. You might use an ISO 8601 P-time string, such as P1Y for one year, or a more granular value if you support month-to-month agreements. For a standard one-year contract, a Duration value is often the most semantically clear choice.
This requirement stands in sharp contrast to sale property listing markup. When the businessFunction is sell, the concept of a lease term does not exist. Including leaseLength in a sale listing creates a logical conflict that can confuse parsers and reduce the trustworthiness of your structured data. In sale scenarios, this property should be omitted entirely to maintain clean, consistent property listing markup.
Practical JSON-LD Example
To visualize this, consider a practical example of how to structure a JSON-LD snippet for a one-year residential lease. The snippet below demonstrates how leaseLength sits within the Offer object, nested under the RealEstateListing type.
{
"@context": "https://schema.org",
"@type": "RealEstateListing",
"name": "Two-Bedroom Apartment in Downtown",
"url": "https://example.com/rentals/123",
"offers": {
"@type": "Offer",
"businessFunction": "lease",
"price": "1500",
"priceCurrency": "EUR",
"leaseLength": "P1Y"
}
}
In this structure, the P1Y string clearly defines the one-year term. Note that if you were marking up a sale instead, you would remove the leaseLength line and change businessFunction to sell. This distinction ensures that the residential rental schema accurately reflects the nature of the transaction, providing clear signals for both search engines and users looking for specific lease terms.
Frequently asked questions about property listing markup
Does the schema require a specific property type?
No, RealEstateListing is a page-level type in the schema hierarchy, meaning it describes the web page itself rather than the physical structure. It does not require you to nest a specific House or Apartment type inside it. Instead, the nested Offer object describes the transaction intent. You can specify the property’s characteristics within the Offer’s itemOffered, but the listing type remains a WebPage derivative, keeping the markup flexible for various property classes.
Can one page handle both sale and rental?
Generally, no. A single RealEstateListing page should represent one specific transaction intent. If a property is available for both sale and long-term lease, these are distinct commercial offers. Combining them in a single Offer object confuses search engines and AI engines, as the businessFunction cannot be both sell and lease simultaneously for the same line item. Create separate listing pages or separate structured data blocks for each distinct commercial scenario to ensure clarity in the index.
How does local business schema interact?
local business schema, such as RealEstateAgent or Organization, defines the entity offering the property, while RealEstateListing defines the offer itself. They work in tandem: the listing page references the agent or broker through properties like author or publisher. This separation ensures that the property data and the business entity data are both accurately parsed, allowing AI engines to attribute the listing to a specific, verified source without conflating the physical asset with the service provider.
Is JSON-LD the only option?
While microdata is technically an acceptable alternative for valid markup, JSON-LD is the preferred standard for JSON-LD real estate implementations. It is easier to maintain, less likely to break page layouts, and directly supported by major search engines and AI crawlers. For most property management teams, JSON-LD offers a cleaner separation of concerns, allowing you to update the structured data without touching the HTML presentation layer, which reduces the risk of rendering errors.
Conclusion
Property listing markup is not a single static block but a decision framework that hinges on the businessFunction of the offer. A practical final check is to ensure the nested Offer object accurately mirrors the actual intent of the page, whether that is a sale or a lease. This consistency allows AI engines to reliably distinguish between active sales and available rentals, reinforcing the accuracy of the structured data.
