ZapperMsgParser
ZapperMsgParser is a set of standalone Python parsers for common healthcare message formats. Each one returns the same result shape, so downstream systems and AI pipelines receive predictable, structured data.
- Python
Python parsers that turn HL7, FHIR, C-CDA and X12 healthcare messages into consistent, structured JSON using only the standard library.
- Python 3.9 or newer
- dataclasses
- Type hints
- HL7 v2.x
- FHIR R4
- C-CDA R2.1
- X12 005010
- Python standard library only
- xml.etree.ElementTree
- json
- re
The challenge
Healthcare data arrives in many formats. Hospital systems send pipe-delimited HL7 messages, modern APIs exchange FHIR resources, clinical documents travel as C-CDA XML, and payers use X12 claims. Each format has its own structure, codes and quirks, which makes every integration a separate project.
When this data feeds analytics, automation or AI, the format problem becomes a control problem. Teams need to know exactly which fields were read, what was missing, and what failed. Parsers that guess silently or raise unhandled errors make that hard to audit.
What it does
HL7 v2 parsing
Reads pipe-delimited HL7 v2.x messages such as admit, discharge and transfer, lab results, orders, scheduling, documents and acknowledgements, and returns patient, visit, diagnosis, allergy and insurance data.
FHIR R4 parsing
Accepts a JSON string or a Python dictionary and normalises resources such as Patient, Observation, Encounter, Condition and Bundle. A batch call parses a list of resources in one pass.
C-CDA documents
Reads C-CDA XML from a file or a string, detects the document type, and extracts patient, author, custodian and many clinical sections including medications, problems, allergies and results.
X12 claims and remittance
Parses X12 005010 transactions including professional, institutional and dental claims, remittance advice and claim acknowledgements, with envelope data, claim lines, payments and financial totals.
One result shape
Every parser returns a result object with a success flag, errors, warnings and a to_json method, so calling code handles all formats in the same way.
No external dependencies
Each parser is a single file that uses only the Python standard library, so it can be copied into a project and reviewed without a long dependency chain.
How it works
Choose the parser
Pick the parser that matches the message format: HL7, FHIR, C-CDA or X12. Each lives in its own Python file and can be used independently.
Pass in the message
Provide the raw message as text, a dictionary for FHIR, or a file path or XML string for C-CDA. X12 can be auto-detected or parsed by transaction type.
Receive a result object
The parser returns a result with a success flag, the detected message or document type, structured data, and lists of errors and warnings. It does not raise on bad input.
Use the structured output
Call convenience methods such as get_patient or get_all_medications, or export the whole result with to_json to feed storage, analytics or an AI pipeline.
Under the hood
- Language
- Python 3.9 or newer
- dataclasses
- Type hints
- Healthcare standards
- HL7 v2.x
- FHIR R4
- C-CDA R2.1
- X12 005010
- Libraries
- Python standard library only
- xml.etree.ElementTree
- json
- re
- Output
- Structured JSON
- Result objects
- Errors and warnings lists
Inside the harness
Data transfer
Parsing sits after secure transfer, turning received HL7, FHIR, C-CDA and X12 files into structured records that downstream steps can validate.
Guardrails
Parsed, typed fields give guardrails something concrete to check before healthcare data reaches a model or another system.
Security
The parsers read messages that contain patient data, so they should run inside the customer's own environment with access controls and data residency decisions applied around them.
Audit
Success flags, errors and warnings are returned with every parse, giving a record of what was read and what was not.
Business outcome
One integration pattern for four formats. Teams write one way of handling results instead of a separate approach for each healthcare message standard, which keeps integrations easier to maintain.
Predictable data for downstream use. Consistent JSON gives analytics, automation and AI steps the same structure to work with, whatever format the message arrived in.
Failures are visible, not silent. Errors and warnings are returned rather than raised, so a malformed message is reported clearly and does not stop a larger batch.
Easy to review and adapt. Standard library only and one file per format means security and engineering teams can read the code and adapt it to local profiles.
Where it is used
- Converting inbound HL7 admit, discharge and lab messages into structured records for a data platform.
- Normalising FHIR resources and bundles before loading them into a reporting store.
- Extracting medications, problems and allergies from C-CDA clinical documents for review.
- Reading X12 claims and remittance files to summarise billing and payment data.
Frequently asked questions
How do I use it?
Clone the repository and import the parser you need, for example HL7Parser or FHIRParser. There is no install step. Create the parser, call parse with your message, then read the result or call to_json.
What licence is it under?
The README states the MIT licence. The repository does not include a separate licence file, so confirm the terms with Zapper Edge before relying on it commercially.
Does it include AI or retrieval features?
No. The repository is a set of rule-based parsers for healthcare message formats. It does not call a model or build embeddings. Its output can feed AI pipelines as clean structured input.
Is it production-ready?
The repository does not make that claim. Treat it as a starting point to review and test against your own message profiles, sample data and compliance requirements before using it with real patient data.
Using this in a governed AI setup?
Talk to us about running it inside the harness, with policy, guardrails and audit around it.