Platform · The standards position · in progress — draft for discussion

A first data standard for tick-borne illness

Tick-borne illness has no standard shape. What we built, and the places the existing vocabulary did not reach.

Tick-borne illness has no standard data representation. This is the element set we had to draft in order to build anything at all — class, element, definition, and exactly what a patient’s own export carries for it. The places no standard reaches are marked rather than filled.

What this page is, and is not

Nothing here has been submitted to, reviewed by, or endorsed by any standards body. This is a working draft written from the inside of one platform, offered for discussion. It has one qualification and one only: we had to build something, and these are the places the existing vocabulary did not reach.

classes
6
elements in the draft
18
marked as having no standard place
10
carried by your own export
10

01 · The problem

A field that does not exist cannot be studied

Standards for health data are lists of what is worth recording, and everything outside a list becomes free text, then a note, then nothing. For tick-borne illness that is most of the useful information: how long a tick was attached, which species it was, whether a rash appeared and on what skin, which markers a test actually showed and when the sample was drawn, whether a treatment was followed by any change.

None of that is exotic. It is the ordinary content of a clinical conversation about this illness, and almost none of it survives into a form that can be aggregated. So the research that could settle the arguments cannot be assembled — not because the data was never collected, but because it was collected into a shape nothing can read.

02 · What we built

5 things that work, and are worth generalising

Modelled, running on invented data, and load-bearing in the product.

  • A household sentinel signal

    An animal test result, the household it belongs to, and a location no finer than three digits of a postal code — enough to say where ticks are and nothing about whether a person is infected.

  • Consent scope, as data

    8 named, separately revocable choices, with every change appended to a history the database writes and no update or delete can touch.

  • An aggregation floor

    A minimum group size carried by the data itself rather than applied at the point of release, so a combination describing fewer than five people is never written down.

  • Where a record came from

    Whether a lab value was uploaded, entered, or arrived from a claims feed — modelled from the start, because provenance stops being recoverable the moment it is not recorded.

  • A treatment response window

    A treatment start date, the window either side of it, how much of that window was actually recorded, and a flag when something else started at the same time. Association, never attribution.

03 · Where we ran out

4 gaps we hit, and did not paper over

Parked deliberately rather than improvised — an invented field is worse than an absent one.

  • How long the tick was attached

    The single most clinically useful fact about a bite, and we have found no standard field for it. Recording it needs an agreed vocabulary for exposure events first, which is why it is parked rather than improvised.

  • Which species it was

    Different species carry different infections. With no coded field on this platform it would arrive as free text, which is the same as not arriving.

  • Skin tone, where a rash is being described

    A rash is identified by appearance, and appearance differs by skin tone. A Johns Hopkins study (JAMA Network Open, 12 December 2023) found that Black patients were less likely than white patients to be diagnosed while the rash was the only sign, and the researchers point partly to how the rash looks on darker skin (Johns Hopkins Medicine news release, December 2023, read 7 October 2026). A dataset that never records skin tone cannot notice the disparity it is producing.

  • Band-level serology, and when the sample was drawn

    A two-tier result reduces to positive or negative in every standard representation, which discards both the individual markers and the timing that decides what a negative means.

Why parking beats inventing

A field invented locally looks like data and aggregates like noise. Two platforms recording attachment duration in different vocabularies produce a number that cannot be pooled and cannot be trusted, and the fact that it exists stops anyone asking for the standard. So these stay absent and named rather than present and private.

04 · The element set

18 elements, each traced to an artifact

Every element below says exactly what a patient’s own export carries for it, or exactly why it carries nothing. An element with nowhere to go does not travel between systems.

The set is implemented, not aspirational: a signed-in patient can download their own record in exactly this shape from their account’s tools page. Where a FHIR R4 resource exists the export uses it; where none does, a LymeHQ extension carries the value under our own URL; and where the platform holds nothing, the element is absent from the file and named in a coverage statement inside it — documented, never defaulted. The same discipline as our claims import, pointed the other way.

Tick exposure

New class3 elements
Attachment durationno standard place foundattachment-duration

How long the tick was attached — the single most clinically useful fact about a bite, and no standard field exists for it.

Not held: The platform records attachment duration on a stated five-value vocabulary, but only in the anonymous clinician-read workflow (`tick_exposures`), which is keyed to a link rather than to an account and holds no patient reference — so nothing connects a recorded duration to the person whose export this is. Absent from the export and named in its coverage statement.

Species identifiedno standard place foundspecies-identified

Which tick species it was. Different species carry different infections; without a coded field this arrives as free text, which is the same as not arriving.

Not held: Parked with the exposure event it would belong to. A free-text species field would aggregate as noise, which is worse than absence.

Exposure countyno standard place foundexposure-county

Where the exposure happened, at county grain — where the tick was, which is not always where the person lives.

Not held: The anonymous clinician-read workflow records a place of exposure in the patient’s own words, but it is keyed to a link rather than to an account, so no exposure place can be joined to this record. The only geography held against a patient is the household ZIP3, which describes residence, not exposure.

Clinical picture

3 elements
EM rash presentem-rash-present

Whether an erythema migrans rash appeared — the one finding that can settle an early diagnosis on its own.

Not held: A standard shape exists (a coded condition), but the platform holds no structured rash field — a free-text diagnosis list is not a rash observation, and the export does not pretend one into being.

Skin tone recordedno standard place foundskin-tone-recorded

The skin tone a rash was assessed on. A rash is identified by appearance, appearance differs by skin tone, and a dataset that never records it cannot notice the disparity it is producing.

Not held: Deliberately not collected until the collection instrument has clinically-informed review — the same rule that holds the rash-identification imagery.

Symptom severityno standard place foundsymptom-severity

Patient-reported daily severity for six named symptoms, on a stated 0–10 scale — the raw material of any before/after picture. The gap claimed here is a code for these, as patient-reported dailies; severity in general is not the claim.

In the export: One FHIR Observation per recorded score — six named symptoms, integers on a 0–10 scale, coded in the LymeHQ code system because no standard code exists for these as patient-reported dailies. The patient’s own single word for the whole day is recorded and is deliberately NOT exported — a decision about who may read it, not a gap in any standard. Journal text never exports.

Laboratory

3 elements
Two-tier resultstwo-tier-results

The overall result of the standard two-tier serology protocol.

In the export: A FHIR DiagnosticReport per lab result, one Observation per value. A report you added and confirmed exports the values you typed, exactly as printed, with the laboratory’s own flag where it printed one; older results export as extracted from the document. No coded mapping is invented where the source stated none.

Band-level detailband-level-detail

Which individual immunoblot bands reacted — the detail behind a positive-or-negative two-tier result.

Not held: Extraction keeps analyte rows as the document stated them, not immunoblot bands as coded entities. That is this platform’s limit, not a statement about what a standard could carry. Absent from the export and named in its coverage statement.

Serology timingserology-timing

When the sample was drawn relative to exposure — the fact that decides what a negative means.

Not held: The sample date itself exports (DiagnosticReport.effectiveDateTime). The element is timing relative to exposure, and no exposure event exists to relate it to.

Household sentinel

New class3 elements
Animal test resultanimal-test-result

A household animal’s tick-borne antibody result — an early-warning signal about where ticks are, saying nothing about whether a person is infected.

In the export: The household animal as its own Patient resource carrying the standard patient-animal extension, with an Observation holding the C6 antibody result and its test date.

Household linkno standard place foundhousehold-link

That the animal and the person share a household — the link that makes the signal mean something, with no finer relationship claimed.

In the export: A LymeHQ extension on both Patient resources naming a shared household identifier — an internal id, same household, nothing else.

County onlyno standard place foundcounty-only

The geographic grain the signal travels at — coarse enough that it describes an area, never an address.

In the export: Exported at the platform’s own grain: three digits of ZIP code and a state, no street, no city. That is coarser than the county grain this draft names, and the divergence is stated here rather than rounded away.

Treatment

3 elements
Antimicrobial courseantimicrobial-course

What was taken and when — the anchor every response question hangs on.

In the export: A FHIR MedicationStatement per medication: the name as the patient recorded it, patient-reported dates, current or stopped. No drug code is invented for free text.

Response windowno standard place foundresponse-window

A treatment start date, the window either side of it, and how much of that window was actually recorded — association, never attribution.

In the export: A LymeHQ extension on each dated MedicationStatement: window length, days logged and days marked too unwell to record each side, and for each symptom the days per word before and after — counts, never an average or a direction, computed by the same arithmetic as every other surface, never re-derived here.

Confound flagno standard place foundconfound-flag

Whether something else started inside the window — the fact that keeps a before/after picture honest.

In the export: A LymeHQ extension naming any other treatment started inside the window, and any reported stop. Carried beside the figures, never resolved away.

Draft for discussion — not a submitted standard. Which elements an existing standard already covers is a judgement made here, not a survey anyone else has verified — an element that is wrong, missing, or already standard somewhere is the useful reply. There is no code-system column because this platform holds no code-system field: the export carries plain text, the FHIR resources it maps onto, and our own extension URLs, and it does not invent a code the source never stated.

Proposed element · outside the set above

Overall, how was today

Ordered categorical · five levels
  1. rank 1Rough
  2. rank 2Hard
  3. rank 3OK
  4. rank 4Good
  5. rank 5Clear
The value
The label is the value. The rank is carried beside it for ordering, and for nothing else.
No interval is assumed
No interval is assumed between levels: the step from Rough to Hard is not the step from OK to Good. The rank is never averaged, summed or differenced, and no figure is computed across a person’s days.
Missingness is part of the element
A day with no answer is part of the element. It is recorded as not answered — never imputed from other days or from the symptom scores, and never dropped from a count of days.
Precedent for the shape
CDC’s HRQOL-4 asks one general-health question on five ordered words — excellent, very good, good, fair, poor. It is the precedent for the shape, not the source: this question is about a day rather than health in general, and its five words are the tracker’s own. cdc.gov · HRQOL Healthy Days core module (opens in a new tab)
In the exports
Recorded, and not exported: neither the patient’s FHIR export nor the research dataset carries it. That is a consent decision about who may read a person’s own word for their day, not a gap in any standard.

05 · Conformance, and connections

There is nothing yet to conform to

TEFCA and USCDI+ are the two frameworks we are asked about by name, and neither has been assessed here. The reason is the whole subject of this page: no representation of tick-borne conditions exists in either of them, so conformance would be a statement about paperwork rather than about whether your illness can be recorded. That absence is either a gap or a contribution, and which one is not ours to decide — which is why the draft above is published in full, with the elements no standard reaches marked instead of filled. Where each named framework stands today, one by one, is on Standards fit.

The tables that let clinical and claims data arrive from outside — a connection record, a claims store, and a field on every lab result saying where it came from — are built, and so is the code for the first connection that uses them: the consent gate, the authorisation exchange and the redirect chain to CMS. What the code does and how far it actually reaches are two different questions, and only the first is decided in this repo — how far each one reaches is the word beside it below, and where it stops is decided by the insurer rather than here.

The element set and codebookWorking
The draft on this page, and the export that ships it: a signed-in patient downloads their own record as a FHIR R4 bundle carrying a coverage statement that names every element the file does not hold.
CMS Blue Button 2.0 — your own Medicare claimsBlocked upstream
An authorisation flow, an import that can be run again safely, and a switch that disconnects it and deletes the credentials. What an insurer paid would arrive as a claim, never as sharing.
Patient portal importDesigned, not built
Patient-directed, over FHIR, into your own record. An import is not sharing, and it moves in one direction only.

Each state above is the word the register gives that row, read at render. A row renamed or moved fails this page rather than leaving a claim behind.

Where credentials for such a connection would be held, the design is already settled and the code exists: the encryption key lives outside the database, so a copy of the database contains identifiers and no way to decrypt anything. Nothing is stored through it today, because nothing is connected.

06 · Versioning

A standard without a version number is a claim, not a standard

Interoperability only means something if the other side knows which version they are reading and what changed since the last one. This draft does not have that yet: the element set is published in full and dated only by the commit that changed it, and there is no version scheme, no supported-versions window and no dated changelog to read. That is a gap in the draft rather than a property of it, and naming it here is cheaper than a version number nothing enforces.

A dated changelog of what changed on the siteDesigned, not built
Until it exists, the commit history is the changelog — which is honest, and is not a substitute a reader outside this repo can use.

Where to go next

If you work on health data standards and any of this is wrong, or already solved, we would rather know than be right — standards@lymehq.com. The story behind the platform explains why a patient ended up writing a data model at all.