EMR-Bear EHI Export Format

This document describes the format of the two export files produced by EMR-Bear to satisfy ONC/ASTP Health IT criterion 45 CFR § 170.315(b)(10):

• Single-patient EHI export — § 170.315(b)(10)(i)
• Patient-population EHI export — § 170.315(b)(10)(ii)

Both use the same package format. The population export is the general case; the single-patient export is the same format narrowed to one patient. Same filenames, same columns, same CSV conventions, same asset layout, same dictionary. Software that can read one can read the other, and the single key that tells them apart is export.spec in dictionary.json.

Under § 170.315(b)(10)(i)(E) and § 170.315(b)(10)(ii), the hyperlink to this document is included inside every export of either kind. Under § 170.315(b)(10)(iii), this document is kept up to date as the format changes.

01The two exports

Where the data comes from

Both exports draw from the same three stores:

How the exported set is decided

In both exports the set of tables is discovered at run time by reflecting over the live database schema. It is not a hand-maintained list, so a schema change that adds new storage is picked up automatically rather than silently omitted. What differs is the test for inclusion:

• Single  A table is included when its rows can be linked to the patient, by the mechanisms in § 6.
• Population  A table is included when it holds electronic health information, whether or not any given row can be attributed to an individual patient.

The single-patient rule is a patient-scoping algorithm; the population rule is not. This is why the population export reaches storage the single-patient export cannot, and why the two have different exclusion lists.

Which people are patients

EMR-Bear stores patients in a shared people table alongside non-patient persons such as staff. A person record is exported as a patient when it is marked as a client. The population export writes every client record to people.csv; the single-patient export writes one — or, where duplicate records have been merged or hidden, the small linked set described in § 8.

Where a patient’s record refers to another person, what that record holds about them is exported with the patient’s data. That person’s own record is not, being outside this patient’s designated record set.

02How an export is produced

Single-patient export Single

Export is limited to a specific set of identified users, satisfying § 170.315(b)(10)(i)(C)(1). A user must hold one of the following roles:

• sysadmin
• human resources
• biller manager
• report

Users without one of these roles are not shown the export controls and cannot invoke the export endpoint.

A permitted user starts an export from either of two places in the application, with no assistance from EMR-Bear staff or developers, satisfying § 170.315(b)(10)(i)(B):

1. Patient chart → Admin tab → “Export Client Data” — exports the patient whose chart is open.
2. Reports → “Client EHI Export (ONC)” — select a single patient by name.

The export runs as a background job. When it completes, the ZIP file is available for download from the Reports page. Exactly one patient must be selected: the export refuses to run with no patient selected, and refuses to run with more than one.

Population export Population

A population export is the entire organisation’s health information in one package. It is not a self-service function within the application. § 170.315(b)(10)(ii) carries neither the “without subsequent developer assistance” requirement of § 170.315(b)(10)(i)(B) nor the user-limiting requirement of § 170.315(b)(10)(i)(C), and EMR-Bear produces a population export as a coordinated process rather than an in-application report.

An organisation requests a population export through its usual EMR-Bear support channel. The request is verified as originating from the organisation whose data is being exported, and the export is then scheduled and produced offline. For a large organisation, production takes several hours.

The resulting package is encrypted at rest and delivered through a separate, expiring download. Requests and deliveries are recorded.

The dictionary.json inside the package describes the run that actually happened, including the window over which it read — see started_at and completed_at in § 5.

03Package structure

Each export is a single ZIP archive.

Single-patient package Single

ehi-export-client-{patient_id}-{YYYY-MM-DD}.zip

Population package Population

ehi-export-population-{org_id}-{YYYY-MM-DD}.zip

Rules that apply to both

• dictionary.json is the authoritative index. Read it first. It names every data file, where it came from, how it was linked to a patient, every column and its type, and how many rows were written. It also records what was excluded and why, and anything that failed.
• A CSV containing only a header row is normal and is not an error. It means EMR-Bear stores nothing in that table for the scope of this export. A file that is missing entirely while listed in dictionary.json is a defect.
• The mongo_ prefix distinguishes document-store collections from relational tables and prevents a collection name from colliding with a table name. The _index/ directory is prefixed for the same reason: it can never collide with a table named index.
• assets/ is absent when there are no stored documents. dictionary.json always reports the document count, so an absent directory is never ambiguous.
• Files are linked to their records by the id column of the corresponding CSV: a file at assets/documents/45231/scan.pdf belongs to the row with id 45231 in documents.csv. Because id is a primary key, this layout is unchanged between the two exports — the path is already unambiguous across the whole population.

Additional rules for the population package Population

• patients.csv is the roster. One row per exported patient, with columns client_id, person_id, mrn, row_count and asset_count. It deliberately carries no demographics — those are in people.csv — so it serves as a completeness checklist without duplicating patient information.
• Large files are split into parts. A table is written as <table>.part-0001.csv, <table>.part-0002.csv and so on once it would exceed 1 GB uncompressed or 5,000,000 rows, whichever comes first. Every part carries its own header row. Parts of one table are contiguous and ordered by primary key; concatenating them requires dropping the repeated headers. A table small enough not to be split has no part- suffix at all.
• _index/attribution/<table>.csv maps rows to patients for files where the link is not a column in the row itself. Columns: row_id, client_id. A row shared between patients appears once in the data file and several times in the map. Only files whose attribution is index have one — see § 6.
• The archive uses ZIP64. A population package routinely exceeds the 4 GB and 65,535-entry limits of the original ZIP format. Use a ZIP64-capable extractor; most modern tools are, but some older built-in utilities are not.

04CSV conventions

All CSV files in both exports follow RFC 4180 and the conventions below. No columns are added or removed between the two exports. A given table has the same columns, in the same order, whichever export it appears in — which is why patient attribution is carried in a separate index rather than as an extra column.

Value representation

Text handling

Clinical free text in a long-lived record can contain byte sequences that are not valid UTF-8, and NUL bytes. Because a corrupted CSV is worse than an absent one — it looks complete — the export normalises text rather than failing:

• Invalid UTF-8 byte sequences are removed.
• NUL bytes (0x00) are removed.
• Newlines inside a value are preserved and the field is quoted.

The [unrepresentable: …] sentinel

If a single stored value cannot be rendered at all, the cell is written as the literal marker:

[unrepresentable: Encoding::UndefinedConversionError]

This is a marker, not patient content. It exists so that one bad value cannot cost the rest of the table. It is rare; where you encounter one, the underlying value is still held in EMR-Bear and can be retrieved on request.

Document-collection (mongo_*.csv) specifics

A document store has no fixed schema, so:

• The header row is the union of the field names actually present across the documents in scope for that collection, in first-seen order. Fields no document uses do not appear.
• A document lacking a field that appears in the header has an empty cell for it.
• Nested objects and arrays are written as JSON.
• Column types are inferred from the data — the type of the first non-NULL value seen for that field — and are reported in dictionary.json as lower-cased runtime type names such as string, integer, time, bson::objectid. They are not declared SQL types.

05dictionary.json

The machine-readable description of the package. It is generated while the export is being written, so it describes what actually happened rather than reconstructing it afterwards. Both exports produce one, with the same top-level shape.

Top-level structure

{
  "export":   { … },   // object  — summary of this export
  "notes":    [ … ],   // strings — conventions and stated limits, in prose
  "files":    [ … ],   // objects — one per data file written
  "assets":   [ … ],   // objects — one per attachment type copied
  "excluded": [ … ],   // objects — what was deliberately not exported, and why
  "failures": [ … ]    // objects — what could not be read (empty in a clean export)
}

There is no patient roster in dictionary.json. In a population export the roster is patients.csv, so that a consumer does not have to parse a JSON array of every patient in the organisation to learn anything about the package.

export

files[] — one entry per CSV written, sorted by filename

assets[] — one entry per table and attachment kind

excluded[] and failures[]

Controlled vocabularies

source takes exactly one of:

tier takes exactly one of:

attribution Population takes exactly one of:

Worked example — single-patient Single

Abbreviated. All values are synthetic.

{
  "export": {
    "spec": "ONC 170.315(b)(10)(i)",
    "client_id": 100042,
    "generated_at": "2026-08-28T14:03:11Z",
    "file_count": 312,
    "row_count": 4871,
    "asset_count": 26,
    "assets_missing": 0
  },
  "notes": [
    "One CSV per table. A file with only a header row means nothing is stored for this
     client in that table; a table listed under \"failures\" was not exported at all."
  ],
  "files": [
    {
      "file": "encounters.csv",
      "source": "mysql",
      "table": "encounters",
      "tier": "2-client_id",
      "links": ["client_id"],
      "description": "Clinical encounters — a visit or contact that clinical
                      documentation hangs from.",
      "row_count": 143,
      "columns": [
        { "name": "id",         "type": "integer"  },
        { "name": "client_id",  "type": "integer"  },
        { "name": "start_time", "type": "datetime" },
        { "name": "note",       "type": "text"     }
      ]
    }
  ],
  "assets": [
    { "table": "documents", "attachment": "document",
      "files": 26, "bytes": 8134902, "missing": 0 }
  ],
  "excluded": [
    { "table": "hl7_endpoints",
      "reason": "Holds TLS certificates and private keys — must never be exported" }
  ],
  "failures": []
}

Worked example — population Population

The same package, widened. All values are synthetic.

{
  "export": {
    "spec": "ONC 170.315(b)(10)(ii)",
    "client_count": 24718,
    "generated_at": "2026-09-11T02:14:56Z",
    "started_at":   "2026-09-10T22:40:03Z",
    "completed_at": "2026-09-11T02:14:56Z",
    "consistency": "not-point-in-time",
    "file_count": 488,
    "row_count": 91344027,
    "asset_count": 412903,
    "assets_missing": 17
  },
  "notes": [
    "Rows span all patients. Use patients.csv as the roster and the file's
     \"attribution\" value to determine how to tie a row to a patient.",
    "This export is not a point-in-time snapshot. See the published format
     documentation, section 8."
  ],
  "files": [
    {
      "file": "encounters.part-0001.csv",
      "source": "mysql",
      "table": "encounters",
      "tier": "2-client_id",
      "links": ["client_id"],
      "attribution": "row",
      "description": "Clinical encounters — a visit or contact that clinical
                      documentation hangs from.",
      "row_count": 5000000,
      "part": 1,
      "part_count": 3,
      "columns": [
        { "name": "id",         "type": "integer"  },
        { "name": "client_id",  "type": "integer"  },
        { "name": "start_time", "type": "datetime" },
        { "name": "note",       "type": "text"     }
      ]
    },
    {
      "file": "crew_team_members.csv",
      "source": "mysql",
      "table": "crew_team_members",
      "tier": "4-second_hop",
      "links": ["through crew_teams"],
      "attribution": "index",
      "description": "Membership of a care team.",
      "row_count": 88214,
      "columns": [
        { "name": "id",            "type": "integer" },
        { "name": "crew_team_id",  "type": "integer" },
        { "name": "person_id",     "type": "integer" }
      ]
    }
  ],
  "assets": [
    { "table": "documents", "attachment": "document",
      "files": 412903, "bytes": 119338204471, "missing": 17 }
  ],
  "excluded": [
    { "table": "hl7_endpoints",
      "reason": "Holds TLS certificates and private keys — must never be exported" }
  ],
  "failures": []
}

06Linkage and attribution

How rows are selected

In a single-patient export, every row is tied to the patient by one of the mechanisms below, and the mechanism used for each file is reported in that file’s tier and links values. The same mechanisms describe how population rows relate to patients.

1. The patient’s own record. Matched by primary key in the shared people table and written to people.csv.
2. A direct identifier column. The table carries client_id, person_id or patient_id holding the patient’s identifier.
3. A polymorphic owner. The table carries an <owner>_id / <owner>_type pair.
4. A second hop. For tables with no direct patient column, rows are reached through an intermediate record.

Union of links Single

Where a table can be reached in more than one way — for example a table carrying both a client_id column and a polymorphic owner — the single-patient export takes the union of the direct links, so rows set by either mechanism are included. Indirect second-hop links are not unioned with direct ones, because some intermediate records are shared between patients and unioning them would pull in another patient’s rows.

This restriction does not exist in the population export, where there is no other patient to leak into. A population export takes every row of an included table.

Attribution Population

A single-patient package carries attribution implicitly: everything in it belongs to the one patient, including second-hop rows that have no patient column of their own. A population package cannot rely on that, so every file declares an attribution value in dictionary.json:

• row — filter the CSV on the column named in links. This covers the large majority of files.
• index — read _index/attribution/<table>.csv, a two-column map of row_id to client_id.
• none — the rows are health information not attributable to an individual.

A record shared between patients — a care team, say — is written once in the data file and appears once per patient in the attribution map. This is a deliberate difference from the single-patient exports of those same patients, where the shared record is duplicated into each package because each package stands alone.

Attachments are copied only for rows that were actually written, so a document can never ship without the record it belongs to.

07What is not included, and why

Everything else is exported. Each exclusion is listed with its reason in the excluded array of every export. The lists differ: some exclusions exist only because a single-patient export must be scoped to one patient, and those do not survive into the population export.

Nothing else is withheld from either export. In particular, soft-deleted rows, superseded rows and hidden duplicate patient records are included in both.

08Stated limits of the export

These are properties a recipient could not infer from the files themselves. They are repeated in the notes array of dictionary.json.

Both exports

• people.csv may contain more rows than you expect. Where duplicate records for the same person have been merged or hidden, the related rows are linked by hidden_active_client_id and all of them are exported. A single-patient export can therefore contain several people.csv rows for one patient.
• A document a record references may be unretrievable. Where a record names a stored file that could not be retrieved from object storage, the record still ships and the file is counted in assets[].missing and export.assets_missing. A non-zero value there means the package is short by that many files — declared, rather than silent.
• A table that could not be read is declared. It appears in failures[] with the error and is never silently omitted. failures[] is empty in a clean export.
• Row counts in dictionary.json are authoritative. If a file’s row count disagrees with the dictionary, treat the package as defective and request a fresh export.

Single-patient export only Single

• versions.csv is not a complete audit trail. Only rows whose item_type is Person are patient-scoped and exported. Change history for related records carries other item_type values and is not included.
• Records with no patient link are absent. Health information that cannot be attributed to the patient is out of scope for this export by construction. It is present in the population export.

Population export only Population

• This is not a point-in-time snapshot. A population export runs for hours and reads two independent stores. Rows written near the start and near the end reflect different states of the database, and there is no cross-store transactional boundary between MySQL and MongoDB. The window is declared in export.started_at and export.completed_at, and export.consistency is not-point-in-time. Where exact consistency matters, reconcile against the source system rather than inferring it from the package.
• versions.csv is complete — the single-patient restriction to item_type Person does not apply here. The full change history ships.
• Rows with attribution none cannot be tied to a patient. They are included because they are health information; no map exists to attribute them, and none can be constructed from the package.
• Split files repeat their header. Concatenating <table>.part-*.csv naively produces a header row in the middle of the data. Drop the first line of every part after the first.
• Document-collection headers are wider. A mongo_*.csv header in a population export is the union of fields across all patients, so it is generally wider than the same collection in a single-patient export and the column order may differ. Read by column name.

09Reading an export

Both packages are designed to be readable with ordinary tooling and no EMR-Bear software.

1. Unzip the archive. Use a ZIP64-capable extractor for a population package.
2. Open dictionary.json. Read export.spec to learn which export you have.
3. Use files[] to find the tables relevant to your purpose — each carries a plain-language description.
4. Load the CSVs with any RFC 4180 parser — spreadsheet software, pandas.read_csv, R’s readr, Ruby’s CSV. Parse them; do not count lines.
5. Where a file has part_count, load every part and drop the repeated header rows.
6. Join across files on the identifier columns, which retain EMR-Bear’s internal values consistently across the whole package.
7. Find a record’s documents at assets/<table>/<id>/, where <id> is the record’s id column value.
8. Decode any value beginning base64: by stripping that prefix and Base64-decoding the remainder.

Isolating one patient from a population export Population

1. Find the patient in patients.csv and take their client_id.
2. For each file in files[], branch on attribution:
   • row — filter the CSV on the column named in links.
   • index — read _index/attribution/<table>.csv, collect the row_id values for that client_id, and select those rows by id.
   • none — skip; these rows belong to no individual.
3. Collect the corresponding assets/<table>/<id>/ directories for the rows you selected.

The result is equivalent in content to that patient’s single-patient export, with two known differences: the population export also contains their versions history beyond item_type Person, and shared records appear once rather than duplicated.

10Format versioning and currency

This document describes format version 2.0.

Changes in 2.0

• Added the patient-population export, § 170.315(b)(10)(ii).
• Added patients.csv, _index/attribution/, and file splitting — population export only.
• Added export keys client_count, started_at, completed_at and consistency — population export only.
• Added files[] keys attribution, part and part_count — population export only.
• Added tier value 6-unscoped and the attribution vocabulary — population export only.
• Documented that non-client person records are not exported, in both exports. This describes existing behaviour; it is not a change to the export.

Currency

The format is generated directly by the export code rather than transcribed from it: the column lists, types, row counts and table descriptions in dictionary.json are produced from the live schema at export time. As a result, the dictionary.json inside any given package is always an accurate description of that package, even if this document has not yet caught up with a very recent schema change.

Per § 170.315(b)(10)(iii), this document is kept up to date for both export formats. It is maintained in the same repository as the export implementation and is reviewed whenever either export’s structure, conventions or exclusions change. Changes that would affect a consumer — a new or removed top-level dictionary.json key, a change to value encoding, a change to package layout, or a new source, tier or attribution value — increment the version above.

11Contact

Questions about this format, or a request for data that appears to be missing from an export, should be directed to EMR-Bear support through your organisation’s usual support channel.