cda

type Address struct {
	Use     string   `json:"use,omitempty"`
	Lines   []string `json:"lines,omitempty"`
	City    string   `json:"city,omitempty"`
	State   string   `json:"state,omitempty"`
	Postal  string   `json:"postal,omitempty"`
	Country string   `json:"country,omitempty"`
}

type AgreementReport struct {
	Findings []Finding `json:"findings"`

	// Checked is how many sections were compared.
	Checked int `json:"checked"`
	// Skipped is how many were not, with Reasons saying why. A check that
	// silently examined half a document would be misleading.
	Skipped int      `json:"skipped"`
	Reasons []string `json:"reasons,omitempty"`

	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
}

type Author struct {
	Time         string `json:"time,omitempty"`
	Family       string `json:"family,omitempty"`
	Given        string `json:"given,omitempty"`
	ID           string `json:"id,omitempty"`
	Organisation string `json:"organisation,omitempty"`
}

type Document struct {
	// Title is the document's own title, which is what a clinician recognises it
	// by.
	Title string `json:"title,omitempty"`

	// TypeCode and TypeName come from the document's code element.
	TypeCode   string `json:"typeCode,omitempty"`
	TypeSystem string `json:"typeSystem,omitempty"`
	TypeName   string `json:"typeName,omitempty"`

	// TemplateIDs are the conformance claims the document makes. They are the
	// only reliable way to know which implementation guide applies.
	TemplateIDs []string `json:"templateIds,omitempty"`

	// DocumentType is the recognised kind, derived from the template IDs and the
	// code, in plain words.
	DocumentType string `json:"documentType,omitempty"`

	// ID and SetID identify the document and its revision series.
	ID    string `json:"id,omitempty"`
	SetID string `json:"setId,omitempty"`
	// Version is the revision number within the set.
	Version string `json:"version,omitempty"`

	EffectiveTime   string `json:"effectiveTime,omitempty"`
	Confidentiality string `json:"confidentiality,omitempty"`
	LanguageCode    string `json:"languageCode,omitempty"`

	Patient   Patient    `json:"patient"`
	Authors   []Author   `json:"authors,omitempty"`
	Custodian string     `json:"custodian,omitempty"`
	Encounter *Encounter `json:"encounter,omitempty"`

	Sections []Section `json:"sections"`

	// Transport is what the HL7 v2 message carrying this document said about it,
	// when it arrived that way.
	Transport *DocumentInfo `json:"transport,omitempty"`

	// Notes record anything about the document worth telling somebody, including
	// parts that were present but not understood.
	Notes []Note `json:"notes,omitempty"`

	// Tree is the parsed XML, kept so the viewer can show anything this struct
	// does not model.
	Tree *xtree.Node `json:"-"`
}

type DocumentInfo struct {
	// Type is TXA-2, the document type code.
	Type string
	// UniqueID is TXA-12, the document identifier the sending system uses. It is
	// the key for detecting a replacement later.
	UniqueID string
	// Status is TXA-17: "AU" authenticated, "IN" incomplete, "DO" documented.
	Status string
	// Availability is TXA-19.
	Availability string
	// ActivityDate is TXA-4.
	ActivityDate string
	// ParentID is TXA-13, set when this document replaces another.
	ParentID string
	// Author is TXA-9.
	Author string
}

type Embedded struct {
	// Segment is which OBX the document came from, 1-based, so a message
	// carrying several attachments can be described precisely.
	Segment int

	// Encoding is what OBX-5.2 or OBX-5.3 declared: "Base64", "A" for ASCII, and
	// so on. It is reported even when the payload turned out to be something
	// else, because the disagreement is itself worth knowing.
	Encoding string

	// MimeType is from OBX-5.3 where present.
	MimeType string

	// Data is the decoded payload.
	Data []byte

	// Notes record anything surprising about the extraction.
	Notes []string
}

type Encounter struct {
	ID       string `json:"id,omitempty"`
	Code     string `json:"code,omitempty"`
	Start    string `json:"start,omitempty"`
	End      string `json:"end,omitempty"`
	Location string `json:"location,omitempty"`
}

type Entry struct {
	// Kind is the CDA class: "Observation", "SubstanceAdministration", "Act",
	// "Procedure", "Encounter", "Organizer".
	Kind string `json:"kind,omitempty"`

	Code       string `json:"code,omitempty"`
	CodeSystem string `json:"codeSystem,omitempty"`
	CodeName   string `json:"codeName,omitempty"`

	// Value is the observation result as text.
	Value string `json:"value,omitempty"`
	// ValueCode and ValueName are set when the result is itself coded.
	ValueCode string `json:"valueCode,omitempty"`
	ValueName string `json:"valueName,omitempty"`
	// ValueSystem is the value's own code system. It is often not the code's: an allergy observation's code is an
	// HL7 act code (ASSERTION) and its value a SNOMED CT concept, and reading the value with the code's system
	// named SNOMED concepts as HL7 act codes.
	ValueSystem string `json:"valueSystem,omitempty"`

	// The participant's code: what an allergy is to (participant/participantRole/playingEntity/code). An allergy
	// observation's value says what kind of reaction it is ("allergy to substance"); the substance is here.
	ParticipantCode   string `json:"participantCode,omitempty"`
	ParticipantSystem string `json:"participantSystem,omitempty"`
	ParticipantName   string `json:"participantName,omitempty"`
	Unit              string `json:"unit,omitempty"`

	// StatusCode is the entry's status, which decides whether it is current.
	StatusCode string `json:"statusCode,omitempty"`

	EffectiveTime string `json:"effectiveTime,omitempty"`
	Low           string `json:"low,omitempty"`
	High          string `json:"high,omitempty"`

	// NegationInd inverts the meaning of the entry. It is carried explicitly
	// because ignoring it turns "no penicillin allergy" into "penicillin
	// allergy", which is the most dangerous single mistake available here.
	NegationInd bool `json:"negationInd,omitempty"`

	// NilFlavor states why a value is absent.
	NilFlavor string `json:"nilFlavor,omitempty"`

	// Text is the narrative this entry points at, resolved through its reference.
	Text string `json:"text,omitempty"`

	// Children are nested entries, which is how a medication carries its dose or
	// an organiser groups results.
	Children []Entry `json:"children,omitempty"`
}

type FHIROptions struct {
	// Version is "R4", "R4B" or "R5".
	Version string

	// IdentifierSystems maps an OID root to a URI, so that an MRN becomes
	// namespaced. Without one the identifier is emitted with an OID-derived
	// system rather than being dropped, because losing the identifier makes the
	// patient unmatchable.
	IdentifierSystems map[string]string

	// Original is the document bytes, attached to the DocumentReference. When
	// absent the DocumentReference records only metadata and says so.
	Original []byte
}

type FHIRResult struct {
	// Bundle is a transaction bundle of conditional upserts, so re-sending the
	// same document updates rather than duplicating.
	Bundle map[string]any `json:"bundle"`

	// Counts is how many of each resource type were produced.
	Counts map[string]int `json:"counts"`

	// Notes explain every judgement the conversion made.
	Notes []Note `json:"notes"`
}

type Finding struct {
	// Severity is "error", "warning" or "info". Only a genuine contradiction is an
	// error; a term missing from one side is a warning, because it may be a
	// wording difference this check cannot see through.
	Severity string `json:"severity"`

	// Section is which section the finding is in.
	Section string `json:"section"`

	// Kind classifies it, so a recurring pattern can be recognised:
	// "entries-without-narrative", "narrative-without-entries",
	// "term-missing-from-entries", "term-missing-from-narrative",
	// "negation-mismatch", "count-mismatch", "unreferenced-entry".
	Kind string `json:"kind"`

	Message string `json:"message"`

	// Narrative and Coded are the two readings, so somebody can judge for
	// themselves rather than taking the finding's word for it.
	Narrative string `json:"narrative,omitempty"`
	Coded     string `json:"coded,omitempty"`
}

type GenerateOptions struct {
	// DocumentType selects the template and code claimed. Only "CCD" is supported; anything else
	// is refused rather than guessed at, because a document claiming a template it does not satisfy
	// is worse than one claiming none.
	DocumentType string

	// CustodianName is the organisation responsible for the document. C-CDA requires a custodian,
	// so generation fails without one rather than emitting a document a receiver will reject.
	CustodianName string

	// Title overrides the default title for the document type.
	Title string

	// Indent writes the document with newlines and indentation. Off by default: the wire form is
	// what gets sent, and whitespace inside a narrative element is significant.
	Indent bool
}

type Identifier struct {
	// Root is the OID or UUID that namespaces the value. Without it an MRN is
	// ambiguous between facilities, which is the single most common cause of
	// unmatchable patients downstream.
	Root      string `json:"root,omitempty"`
	Extension string `json:"extension,omitempty"`
	// Assigner is a human-readable name for the root when one is recognised.
	Assigner string `json:"assigner,omitempty"`
}

type MedChange struct {
	// Kind is "added", "removed", "unchanged" or "changed".
	Kind       string `json:"kind"`
	Medication string `json:"medication"`
	Code       string `json:"code,omitempty"`
	CodeSystem string `json:"codeSystem,omitempty"`

	// Before is nil for an addition, After is nil for a removal. Both are carried so a reader can see the entries
	// the judgement was made from rather than taking the summary on trust.
	Before *Entry `json:"before,omitempty"`
	After  *Entry `json:"after,omitempty"`

	// Detail says what changed, for "changed".
	Detail string `json:"detail,omitempty"`
}

type Note struct {
	// Severity is "error", "warning" or "info".
	Severity string `json:"severity"`
	// Path locates the problem in the document.
	Path string `json:"path,omitempty"`
	// Message is written for a person, not a machine.
	Message string `json:"message"`
	// Rule names the check, so a recurring note can be looked up.
	Rule string `json:"rule,omitempty"`
}

type Patient struct {
	Identifiers []Identifier `json:"identifiers,omitempty"`
	Family      string       `json:"family,omitempty"`
	Given       []string     `json:"given,omitempty"`
	Prefix      string       `json:"prefix,omitempty"`
	Suffix      string       `json:"suffix,omitempty"`
	Gender      string       `json:"gender,omitempty"`
	GenderName  string       `json:"genderName,omitempty"`
	BirthTime   string       `json:"birthTime,omitempty"`
	Address     *Address     `json:"address,omitempty"`
	Phone       string       `json:"phone,omitempty"`
}

type ReconcileReport struct {
	Added     []MedChange `json:"added"`
	Removed   []MedChange `json:"removed"`
	Changed   []MedChange `json:"changed"`
	Unchanged []MedChange `json:"unchanged"`

	// Conflicts flags a medication that appears active in one document and completed or discontinued in the other.
	// This is the clinically dangerous case and the reason to run this at all: the two documents disagree about
	// whether the patient is currently taking something, and whichever the receiving clinician happens to read
	// decides what they believe.
	Conflicts []MedChange `json:"conflicts"`
}

type RenderOptions struct {
	// Footer is appended to the provenance note, for a site that has to record where a document came from.
	Footer string

	// IncludeCodes prints the code and code system beside each entry in the tables.
	//
	// Off by default. A printout for a clinician wants drug names; a printout for somebody debugging an exchange
	// wants the codes, and putting them in front of a clinician who does not need them is how a page of
	// medications becomes unreadable.
	IncludeCodes bool
}

type RepairAction struct {
	Kind RepairKind `json:"kind"`

	// Section is the section title, empty for document-level repairs.
	Section string `json:"section,omitempty"`

	// What was wrong, in terms of what a person would have seen.
	Problem string `json:"problem"`

	// Consequence is what would have happened if it were left alone. Separate from Problem because the problem
	// is technical and the consequence is clinical, and only one of them makes anybody act.
	Consequence string `json:"consequence"`

	// Action is what was done about it, or why nothing was.
	Action string `json:"action"`

	// Fixed distinguishes a repair from a report.
	Fixed bool `json:"fixed"`

	// Recovered is the narrative text that was reconstructed, so somebody can check it before trusting it. A
	// repair nobody can inspect is a repair nobody should accept.
	Recovered string `json:"recovered,omitempty"`
}

type RepairKind string

type RepairOptions struct {
	// CustodianName is used when the document has no custodian. C-CDA requires one and Generate refuses without
	// it, so a repair of a document missing its custodian needs the caller to say who is taking responsibility -
	// which is the correct place for that decision, since it is an assertion about an organisation.
	CustodianName string

	// Indent writes the result readably. Off for anything going on a wire.
	Indent bool
}

type RepairReport struct {
	Repairs []RepairAction `json:"repairs"`

	// Fixed and Reported are counted separately because they lead to different actions: one means the document is
	// now usable, the other means somebody has to go back to the sender.
	Fixed    int `json:"fixed"`
	Reported int `json:"reported"`

	// InvisibleEntries is the count of coded facts that no reader would have seen. This is the number that matters
	// and the reason to run this at all.
	InvisibleEntries int `json:"invisibleEntries"`

	// Document is the repaired XML, empty when nothing could be repaired.
	Document string `json:"document,omitempty"`
}

type Section struct {
	// Title is the section heading as written.
	Title string `json:"title,omitempty"`

	Code       string `json:"code,omitempty"`
	CodeSystem string `json:"codeSystem,omitempty"`
	CodeName   string `json:"codeName,omitempty"`

	// TemplateIDs are the section's conformance claims.
	TemplateIDs []string `json:"templateIds,omitempty"`

	// Kind is the recognised section type in plain words, empty when the section
	// is not one this package knows.
	Kind string `json:"kind,omitempty"`

	// NarrativeText is the human-readable content with markup removed. This is
	// what a clinician actually reads, and half of what the narrative check
	// compares.
	NarrativeText string `json:"narrativeText,omitempty"`

	// NarrativeHTML is the narrative converted to safe HTML for display, with
	// the table structure preserved because CDA narrative is mostly tables and
	// flattening them makes a result list unreadable.
	NarrativeHTML string `json:"narrativeHtml,omitempty"`

	// Entries are the coded, machine-readable observations.
	Entries []Entry `json:"entries,omitempty"`

	// Empty reports a section with neither narrative nor entries, which usually
	// means the sending system had nothing to say rather than that the patient
	// has nothing.
	Empty bool `json:"empty,omitempty"`

	// NilFlavor carries an explicit statement of absence, such as "no known
	// allergies". It is important to keep distinct from an empty section: one
	// says there is nothing, the other says nobody looked.
	NilFlavor string `json:"nilFlavor,omitempty"`
	// contains filtered or unexported fields
}

type Summary struct {
	Title        string `json:"title"`
	DocumentType string `json:"documentType"`
	Patient      string `json:"patient"`
	Effective    string `json:"effective"`
	Sections     int    `json:"sections"`
	Entries      int    `json:"entries"`
	Warnings     int    `json:"warnings"`
	Errors       int    `json:"errors"`
}

type TOCOptions struct {
	// IdentifierSystems maps an OID root to a URI, as for ToFHIR.
	IdentifierSystems map[string]string

	// Language is the document's language when the source does not say (BCP 47). Default en-US.
	Language string
}

type ValidationReport struct {
	// Profile is which IG was checked, e.g. "C-CDA R2.1 Continuity of Care Document".
	Profile string `json:"profile"`

	// Findings reuse the existing Note type so they integrate with the rest of
	// the package without conversion.
	Findings []Note `json:"findings"`

	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
	Infos    int `json:"infos"`
}