# CleanedWeb data contract and provenance

This guide explains the semantics around the global `property-profile-v2` contract. The JSON Schema
remains authoritative for structure. The machine-readable field catalog is
`https://cleanedweb.com/schemas/property-profile-field-catalog-v2.json`.

## Identity

- `property_entity_id` is the canonical upsert key.
- `sources[].listings[].listing_id` is local to one source advertisement and must not replace
  canonical identity.
- Preserve `sources` with the canonical record. It is the provenance boundary for
  source URLs, listing identifiers, advertiser details, and contact channels.
- Derive source and listing counts from the grouped `sources` collection when needed.
  Neither count is a completeness guarantee for the market.

CleanedWeb can improve entity resolution over time. Consumers must treat a previously
unknown identifier as a new canonical entity and must not merge two identifiers based
only on address text, title, coordinates, or an agent name.

## Missing, unknown, hidden, and placeholder values

Optional values are omitted when no delivery-safe value exists. Do not turn an omitted
field into an empty string, zero, `false`, or an inferred fact.

Use explicit enum values only where the schema defines them:

- `location.precision: "unknown"` means location granularity is not established.
- `sources[].listings[].pricing.quality: "known"` authorizes use of a delivered numeric price.
- `sources[].listings[].pricing.quality: "hidden"` means the advertiser withheld the price.
- `sources[].listings[].pricing.quality: "placeholder"` means an observed value was not a usable asking price.
- `sources[].listings[].pricing.quality: "missing"` means no delivery-safe price was retained.
- Advertiser `unknown` values are classifications, not permission to guess a type.

## Units and normalization

- `property.floor_area` and `property.land_area` are delivered in square metres.
- Latitude and longitude use WGS84 decimal degrees.
- Currency is an uppercase ISO 4217 code. CleanedWeb does not imply currency conversion.
- Dates and timestamps use the formats declared by JSON Schema.
- Room definitions, floor conventions, and advertised area definitions can vary by
  source market. Normalization does not erase that real-world boundary.

## Freshness

`snapshot.dataUpdatedAt` is the latest successful rebuild time of the maintained serving
projection. It is not the API request time and it does not promise that every source was
observed at that instant.

Listing `first_observed_at` and `observed_at` values describe retained CleanedWeb
observations. They are not construction, transaction, publication, or legal event dates.

## Property facts and source assertions

Recurring building facts such as construction year, condition, energy class, structure,
heating, parking, and orientation are canonical only when one retained current source
reports the value or all reporting sources agree. When current sources conflict, the
canonical field is omitted and the source-specific values can remain under
`sources[].listings[].unit`.

`property.amenities`, `property.features`, and `property.construction_materials` are
deduplicated unions of current source advertisements. They mean that at least one retained
source reported the value; they are not independent physical inspections. Structure and
construction material are separate concepts and are not silently converted into each other.

## Area context and marketplace observations

Property profiles can store an immutable `context.area_profile_ref`, not a copied area
profile. Each referenced area fact retains its source, vintage, measurement geography,
derivation status, confidence, and limitation. Missing area context leaves the property
result usable and does not alter its availability.

Marketplace advertisements are grouped as `sources[].listings[]`. Every distinct
listing keeps its source-local ID, links, deal type, status, asking price, discounts and
fees, unit facts, content, availability actions, metrics, attribution, and advertiser or
contact details. Source media remains internal and is not exposed in the customer profile.
Official identifiers and records are included only where an authoritative source and a
defensible link to the property entity are available.

## Contact and source data

Delivered agency, agent, phone, email, website, and contact-form values are observations
from source advertisements. Presence does not prove current reachability, ownership,
consent, licensing, or a legal basis for a downstream communication. Consumers remain
responsible for their use of contact data.

## Acceptance requirements

Before persisting a response, require:

1. `returned === results.length`.
2. Every result uses `property-profile-v2`.
3. Every `property_entity_id` is non-empty and unique within the response.
4. `snapshot.dataUpdatedAt` meets the consumer's declared freshness policy.
5. `has_more === false` after aggregating cursor pages, or one complete
   unbounded response, when the workflow requires a complete result.
6. Source provenance is retained beside the canonical entity.

Do not infer readiness, entitlement, availability, completeness, or cost from this static
guide. Read runtime capabilities and authenticated market metadata.