Format Version History

The version history of the Positive Experience Format, the JSON that P.E.A. exports and imports. The format itself is described at archive.green/format.

exportSchemaVersion is 4 since October 2026 (build 96); it was 3 from June 2026, and every v3 file still imports. The point releases below added optional fields and changed nothing for files that don't have them. The build numbers are TestFlight builds.

• v4.1: When an experience reached the archive. (November 2026, in every build since 97.)

  • Per-entry archivedAt: when the archive received the experience, next to createdAt, when it happened. A file without it imports as before. An experience without it keeps it empty, because no earlier build recorded that moment. Optional. exportSchemaVersion stays 4.

  • appVersion tells a backup from a conversion. P.E.A. writes its own version number (“1.0”). A converter writes its name and version (“swarm-to-pea/1.2.1”), and P.E.A. then dates each entry’s arrival to the import.

  • In the same build, P.E.A. moved your archive into encrypted iCloud storage. Nothing in this format changed for it: the keys are the same, and a backup is the same plain JSON file it always was.

• Page revision, October 23, 2026. No format change. The page is half its length: this version history, the spreadsheet template (archive.green/import-template) and the Swarm mapping (archive.green/swarm-to-pea) are pages of their own, and one import prompt replaces two. The season row now says how a converter writes the southern hemisphere’s season (corrected November 1, 2026: this line said P.E.A. itself reads the hemisphere since build 96; no build does yet, and P.E.A. keeps using the northern table for what it captures).

• v4: Topic suggestions, and the place's category. (October 2026, in every build since 96.)

  • A new top-level topicAssociations array (see Topic Suggestions Schema at archive.green/format): what P.E.A. remembers about suggesting topics at a place, for a kind of place or an activity, and the suggestions you turned off. The rule always (a topic a place adds by itself) came a few days later without a version change. A build that doesn’t know it lists those objects as skipped in its import report, with the reason, and leaves them alone when they arrive through iCloud. A new top-level collection is why exportSchemaVersion went from 3 to 4. A build before 96 refuses a v4 file with a “please update” message, and every v3 file imports into build 96 as before.

  • Per-place category: the kind of place in Apple's words ("Cafe"), the same word entries already have as placeCategory. It lets a place suggest topics by its kind, even when P.E.A. picked the place for you. Optional. P.E.A. fills it in after import where it can.

• Page revision, October 8, 2026. No format change. Concepts are called Topics in the app since September 27, 2026; the keys (concepts, conceptUUIDs, conceptCount) stay as they are. Every "not shipped yet" note below is gone, because everything shipped. New on the page: the short prompt for Siri and Apple Intelligence, and the hour bands for timeOfDay and the months for season in the Time table. The spreadsheet template's concepts column is now topics, it gained locationAdministrativeArea, and its watch row says watch.

• v3.6: Region, neighbourhood, county and postal code on entries, and the listing on places. (September 2026, in every build since 91.)

  • Per-entry locationAdministrativeArea: the state or region, exactly as the map data gives it: "WA" in one country, "Bavaria" in another. P.E.A. shows it next to the town ("Seattle, WA") and falls back to the two-letter country code when there is no region. There is no table that expands or shortens these, so copy your source's spelling. Leave it out when you don't know it, and P.E.A. looks it up from the coordinates after import, like the city and the country.

  • Per-entry locationSubLocality, locationSubAdministrativeArea and locationPostalCode: the neighbourhood ("Ballard"), the county or its local equivalent ("King County") and the postal code ("98117"). Same rules as the region. Nothing in the app shows these three yet. They are kept so an archive written today already has them.

  • Per-place websiteURL, phoneNumber, street, locality, administrativeArea, postalCode and country: the place's own listing, so the place card can show an address, a website and a phone number without going online. detail is unchanged and still the short "City, Country" line. Write these if your source knows the venue's address. If it only knows a coordinate, leave them out and P.E.A. looks the place up after import. Once recorded, P.E.A. doesn't overwrite them.

  • All eleven are optional. exportSchemaVersion stays 3, older files import unchanged, older builds ignore the fields.

• v3.5: Place association and role. (August 2026, in every build since 70.)

  • Per-place associationState: whether the place may associate itself with new experiences automatically ("notLicensed" / "disabled" / "enabled"). Absent means something: the place was saved before the field existed and behaves as enabled. Keep it absent when you convert a file.

  • Per-place role ("home" / "work" / "other") and roleUpdatedAt (ISO 8601): the place's role in your life and when you last set it. There is at most one home and one work. The timestamp is there so a sync conflict can be settled by a person. Imports copy it as is.

  • All three are optional. exportSchemaVersion stays 3.

• v3.4: Motto active state. (August 2026, in every build since 70.)

  • Per-motto inactive: true keeps a motto in the archive but stops showing it, on every device. Left out when the motto is active. Not part of the motto's identity, so the merge still matches by uuid or by the three lines. Optional. exportSchemaVersion stays 3.

• v3.3: Place identity. (July 2026, in every build since 70. See Place identity at archive.green/format.)

  • Per-entry placeIdentityKey: which place an experience belongs to, as a stable key. apple: for a place backed by an Apple Maps Place ID, local: for one P.E.A. created. The key, not the name, says "these two experiences happened at the same place", which is why one archive can hold several places called "Home".

  • Per-place identityKey, providerName, radiusMeters, symbol: the same key on the saved place, what Apple Maps called the place when you linked it (not refreshed), how far the place reaches in meters, and the SF Symbol you picked. No radiusMeters means the app's default. No symbol means the app picks one by category.

  • Identity keys are opaque. Don't parse one, don't make one up, don't copy one onto another place. Leave them out and P.E.A. works out identity itself.

  • All five are optional. exportSchemaVersion stays 3.

• v3.2: Time zone. (July 2026, in every build since 70.)

  • Per-entry timeZoneID: the IANA time zone the experience happened in ("Asia/Tokyo"), set at creation. When it's there, timeOfDay and dayOfWeek are read on that clock, so an experience archived in another zone keeps its wall clock instead of drifting with the device. Converters write it only when the source really records a zone (Day One's timeZone, for example), never from a bare UTC offset. Optional. exportSchemaVersion stays 3.

• v3.1: Place category. (July 2026, in every build since 70.)

  • Per-entry placeCategory: the Apple Maps point-of-interest category of an assigned place, human-readable ("Cafe", "Amusement Park"). Set when a place is picked from Apple Maps search. Plain addresses and custom places have none. Optional. exportSchemaVersion stays 3.

• v3: Concepts, which are Topics now. (June 2026.)

  • concepts top-level collection + conceptCount. A word or two that says what an experience was about ("soccer", "made", "noticed"), created and associated in the entry editor. Native rows are stamped source: "pea" with no sourceID. The app renamed them Topics in September 2026; the keys didn't change.

  • Per-entry conceptUUIDs array, linking each entry to its topics. Many-to-many, same shape as peopleUUIDs.

  • On Add data to P.E.A. (merge), topics match by uuid or (source, sourceID). Native topics (no sourceID) match by uuid only.

  • People reached the editor. People came in at v2 as a round trip only. From v3 you create and associate them in the entry editor's People field. The wire format is unchanged.

  • Both additions are optional, so a v1 or v2 archive imports unchanged on a v3 build. An older build refuses a v3 archive with a "please update" message rather than dropping the topics.

• v2: Add data + Unset + People (schema only). (May 2026.)

  • people top-level collection + peopleCount. People round-trip through export and import. The in-app surfaces came with v3.

  • Per-entry peopleUUIDs array linking each entry to people in the top-level people array.

  • Per-entry sourceID: a stable identifier from the originating system. With source, it's the merge key for "Add data to P.E.A.". The same createdAt and text also mark a duplicate.

  • Per-entry importPayload: the original record as a string. P.E.A. doesn't read it. It's there so a future import can reach back into fields P.E.A. didn't model the first time.

  • Per-entry sourceURL: a link back to the original record (Swarm check-in, Day One entry, tweet). Shows as a tappable "View external experience" row. Native captures have none.

  • Per-entry isIntensityUnset: true on rows that came in through merge from another source and haven't been rated. Shows as a solid light-gray dot at the smallest size (the dashed gray dot is Neutralized, a different thing). Never on native entries.

  • All five are optional, so a v1 archive imports unchanged on a v2 build.

• v1: The first public schema. (May 2026.)

  • One JSON file, no zip.

  • Top-level entries, places, mottos.

  • A stable uuid on every row, for round trips.

  • A permanent archiveNumber on every entry (the "P.E. #X").

  • A readme field, so a person can read the file.

  • Place fields on the entry next to the top-level places array, so an entry is self-describing without cross-references.

  • Per-entry source: "pea" for native captures, the service name for converted imports. Optional. A file without it is treated as all native.

The format version is independent of the P.E.A. app version. It's a plain integer that only changes when the archive's shape changes. P.E.A. always reads older versions. Newer files are refused with a clear message until you update the app.