Contributing

Help more practitioners own their records.

There are two ways in: adopt OSD natively in your software, or add a new source platform to the reference exporter. Both are open to anyone.

For software vendors: adopt OSD natively

The strongest form of support is built-in. Read the specification, then implement either side of it:

OSD Export — let your users download their records as a conforming bundle. You already have the data; the bundle is a zip with a manifest, canonical JSON records, and content-addressed assets.

OSD Import — accept a bundle and create the records in your system. The import guide describes the full algorithm; there is no vendor-specific code to write.

Once you conform, use the labels on your site so practitioners know what to expect. The standard is free to use, forever, with no license fee and no partnership agreement required.

For developers: add a platform to the reference exporter

The reference exporter (Open Spa Data Vault) is a Chrome extension that captures a practitioner's own records from their logged-in session and packs them into an OSD bundle. Vagaro, GlossGenius, and Square are live; each one is a self-contained adapter, and new platforms follow the same shape:

anatomy of an adapter
recon/<platform>-dom.md        DOM recon FIRST: selectors with sources,
                               URL routing, open questions
src/content/<platform>.ts      content script for the platform's domain
                               (same message contract as the others)
src/adapter/<platform>/
  selectors.ts                 every selector as a named constant
  discovery.ts                 how the client list is enumerated
  profile.ts, notes.ts, ...    one capture module per section
  index.ts                     per-client orchestration
src/osd/normalize/<platform>.ts  maps captured data to canonical
                               records at bundle-pack time

The bundle envelope and canonical record shapes never change per vendor. Your adapter captures what the platform shows and your normalizer maps it into the canonical shapes; the packer does the rest.

The capture rules (non-negotiable)

Every adapter must hold to the posture that keeps practitioners safe:

1. DOM-only — no undocumented API calls.
2. Foreground-only — no headless or background runs.
3. Human-paced — sequential, jittered delays, stop on 429.
4. No credential storage — use the existing logged-in session.
5. Own-tenant only — a merchant exports their own account.
6. Local export only — chrome.downloads to disk; no uploads.
7. Read-only — never write, modify, or delete anything.

Pull requests that violate any of these are rejected regardless of how well they work. The standard's credibility rests on the exporter being something a practitioner can trust completely.

What a pull request needs

PR checklist
[ ] recon/<platform>-dom.md — selectors documented with sources
[ ] selectors.ts — no inline selectors in capture code
[ ] discovery + per-section capture modules + orchestration
[ ] normalizer mapping to canonical records (client, note,
    treatment; service/product if the platform exposes them)
[ ] section names documented in the README scope section
[ ] npm run typecheck and npm run build pass
[ ] tested against a real account you own — include counts
    (clients / notes / assets) in the PR description, never
    real client data

Start with the recon doc and open a draft PR early — selector strategy is where reviews help most. The project lives on GitHub under github.com/SpaSphere/open-spa-data; open an issue there first if you want to claim a platform before building.

Proposing changes to the standard

The specification itself takes contributions too: new record kinds, new fields, or clarifications. Open an issue describing the real-world records the change would carry. Additive proposals (optional fields, new sections) are easy; anything that would break existing importers needs a schema version bump and a strong reason.