Export & interchange format
One OpenPlan3D-compatible JSON file, read and written by every OpenLandscape3D app.
OpenLandscape3D doesn’t invent a new file type. Every export is an OpenPlan3D “prepared RoomPlan JSON” — the format OpenPlan3D’s iOS app writes and its web editor imports through Import JSON. Landscape data rides in one extra top-level block, openlandscape3d, which OpenPlan3D ignores today and keeps intact.
This page summarises version 1 of the contract shared by the web planner, the iPhone/iPad app and this website’s plant catalog.
Conventions
| Value | |
|---|---|
| File name | <Site-Name>-openplan3d.json |
| Units | metres everywhere |
| Plan axes | plan x → world X, plan y → world Z, Y up; on screen plan +y points down |
| North | site.north = unit vector in plan coordinates; default [0, -1] |
| Ids | lower-case UUID strings |
| Dates | ISO-8601; months are 1–12; calendars assume the northern hemisphere in v1 |
| Polygons | arrays of [x, y], not closed |
Top level
Standard OpenPlan3D arrays — walls, doors, windows, openings, sections, stories, floors, defaults — plus objects and the openlandscape3d block. When a site started from an OpenPlan3D file, the building arrays are kept verbatim and re-emitted, so OpenPlan3D → OpenLandscape3D → OpenPlan3D keeps the building geometry exactly. walls may be empty; OpenPlan3D imports objects alone.
Objects OpenPlan3D understands
Each plant, fence segment, gate, patio/deck, pool, raised bed, retaining-wall segment and site object becomes an objects[] entry whose category is an OpenPlan3D catalog id (for example tree_oak, bush_large, fence_planks, deck_patio, pergola), sized at the scenario year of the export. Groups export one object per plant. Each object carries openlandscape3dRole (existing, proposed, retain, remove), openlandscape3dKind and, for plants, plantId. See the mapping table.
Known gap: lawn, bed, mulch, gravel, path and driveway areas, terrain, the boundary and field observations have no OpenPlan3D equivalent yet and stay in the block.
The openlandscape3d block
| Field | Holds |
|---|---|
schema |
openlandscape3d/project@0.1 |
producer |
web or ios |
catalogVersion |
the plant catalog version, e.g. ol-plants@0.1 |
site |
optional coarse or precise location, regionId, hardiness zone, frost dates, north, default sun / moisture / soil, boundary, terrain (flat or spot-elevation points) |
scenario |
the view state: month, year after planting, hour |
areas |
lawn, bed, mulch, gravel, patio, path, deck, driveway, water polygons with material, elevation and optional sun / moisture overrides |
lines |
fences, retaining walls and edging with style, height and gates |
plants |
placed plants: plantId, position, status, planted year, install size and dimensions, group, condition and measured size for existing plants, a visual seed |
groups |
rows, masses and grids with species mix and spacing; resolved instances live in plants |
objects |
site objects by OpenPlan3D catalog id |
observations |
append-only field notes, photos, issues, measurements and inventory |
alternatives |
named snapshots of the design |
verification, overrides |
which measurements were checked; check results accepted with a note |
Producers preserve fields they don’t understand, so data from a newer client survives a round trip through an older one. An unknown plantId is shown as an “unknown plant” placeholder and kept on re-export.
Deterministic models
Web and iOS must compute identical results, so the rules are written down:
Growth. With install size s0, mature size sm (midpoint of the catalog range) and t years after planting:
k = { slow: 0.12, medium: 0.25, fast: 0.45 }[growthRate]
s(t) = sm − (sm − s0) · exp(−k · t)
applied separately to height and spread. Existing plants start from their measured size.
Seasons. Deciduous plants are leafless strictly after the first-fall-frost month or strictly before the last-spring-frost month. Fall colour shows in the first-frost month and the month before. Plants are in bloom in their bloom months.
Design checks. OL-HARDY, OL-INVASIVE, OL-ONHARD (errors); OL-SUN, OL-WATER, OL-OVERLAP, OL-CLEARANCE, OL-OUTSIDE (warnings); OL-BLOOMGAP, OL-UNVERIFIED (info). Mature overlap is flagged when r1 + r2 − d > 0.5 · min(r1, r2). Results are sorted by rule id and first subject; an override downgrades a result to info.
Schedules. Task rules are anchored to lastSpring and firstFall with day offsets and turned into dated windows from the site’s frost dates.
CSV outputs
Plant schedule: code,scientific_name,common_name,quantity,install_size,spacing_m,mature_height_m,mature_spread_m,native,notes — one row per plant and install size, sorted trees first; code is the first two letters of genus and species.
Task schedule: task,plant,scientific_name,quantity,start,end,recurrence,source,confidence.
Delivery paths
- File — import into OpenPlan3D with Import JSON, or open in either OpenLandscape3D app.
- OpenPlan3D link — the file is posted to OpenPlan3D’s handoff service and opened in its editor.
- Web ⇄ iOS transfer links — the design travels in the link itself (DEFLATE + base64url), with no server in between. Links never carry precise location, observation coordinates or photos; location is rounded to two decimals.
Versioning
The block’s schema changes only for breaking changes; additive fields don’t bump it. Plant ids are stable — renamed taxa keep their old id as an alias.