German Practice Management Shared Semantics (R4)
0.102.3 - release Germany

German Practice Management Shared Semantics (R4) - Downloaded Version null See the Directory of published versions

Migration Contract

Migration to the minimal contract

The machine-readable complete migration manifest gives all 529 audited artifacts one disposition. Each entry records the retired canonical, its disposition, the public target when one exists, and the semantic migration rule. Private implementation evidence and adapter details are deliberately outside the public IG.

The smaller Billing compatibility index points Billing-owned removals to that manifest. Historical Praxis packages remain available for validating resources that declare older canonicals.

Resource profiles and examples

All earlier Praxis resource profiles are retired from the active package. The only active resource profile is ti-transmission-task, defined new for TI transmissions (see TI transmissions). Remove a retired profile's Praxis meta.profile canonical and retain every native R4 element. If a retired profile inherited another Praxis profile, continue to the first standard or imported profile. Fixed codes that carry business meaning remain ordinary coded data; cardinality narrowing and Must Support flags do not create replacement facts.

Examples and test profiles from earlier releases are not normative definitions and are not republished by this package.

Retained definitions

Retained definition Required fact Why native R4 or an installed dependency is insufficient
billing-practitioner-role Exact role whose identifier is used for billing, including a prophylaxis or practice assistant whose services are attributed to and billed by the assigned dentist or physician Training supervision and ordinary participants do not establish billing attribution.
questionnaire-item-clinical-alert Assertion that an answer needs heightened clinical attention The item code describes clinical meaning and SDC rendering definitions describe presentation; neither carries this assertion.
dauerdiagnose A patient-level diagnosis is a Dauerdiagnose carried forward into following quarters Condition.category = problem-list-item alone cannot separate a Dauerdiagnose from other problem-list entries, and an active clinical status is a different assertion. KBV AW and WeST Dauerdiagnose extensions are exchange-format mappings only.
sitz-anteil, stunden-pro-woche, and arzt-sitz-status with the arzt-status CodeSystem and arzt-status-vs ValueSet Seat share, agreed weekly hours, and seat-assignment status of a practitioner role R4 PractitionerRole has no seat share or agreed workload, and PractitionerRole.code already carries the functional role.
vision-coverage and vision-supporting-information Coverage and supporting finding of a vision prescription R4 VisionPrescription has neither an insurance nor a supportingInfo element.
khe-belegarzt A hospital admission request is an admission by an attending office-based physician ServiceRequest.priority, reasonCode, and performerType do not carry this admission kind.
authorization-instrument, genehmigung-leistungsbereich, and ermaechtigung-art CodeSystems Exact authorization categories, issuer-defined service-area identifiers, and statutory authorization types No checked installed terminology preserves these distinct meanings. genehmigung-leistungsbereich remains reference-only and republishes no issuer code list.
wb-rolle CodeSystem Exact postgraduate training roles Native role fields do not supply these role distinctions.
wb-assignment-lifecycle CodeSystem Exact assignment stage Native Task.status preserves generic progress, while Task.businessStatus retains the requested, approved, active, or ended business state.
wb-parameter CodeSystem Meanings for trainer authorization, approved weekly hours, and maximum authorized duration R4 supplies native Task and Contract containers but no codes for these parameters.
organization-relationship CodeSystem Exact KV practice site, UEBAG, and operating-company membership meanings R4 OrganizationAffiliation has no equivalent standard relationship codes.
organization-type CodeSystem An organization is the KV practice (BMV-Ä §1a no. 18) under which the KV bills R4 Organization.type and the installed German terminologies have no code that separates this practice from its operating sites.
presence-event#physical-presence-confirmed Positive assertion that physical presence was authoritatively confirmed Encounter lifecycle and participation-mode codes do not state that this evidence event occurred.
ti-transmission-task with the ti-application, ti-transmission-status, and ti-transmission-output CodeSystems and their ValueSets The TI application a transmission serves, its business status together with the Task.status values each status may accompany, the kinds of evidence and answers it references, and the rules that bind them on one Task Native Task.status preserves only generic progress, and no installed terminology names the TI applications, the TI transmission stages, or the output kinds across all of them. Base R4 Task cannot require the application code, restrict the status pairing, or forbid the AccessCode on a revocation Task without a profile.

The active surface contains exactly one Profile, nine Extensions, thirteen CodeSystems, and four ValueSets.

Authorization, training, and organization

Authorization records migrate to base R4 Contract. Preserve stable identity in Contract.identifier, authorization kind in type and repeatable subType, the validity interval in applies, the authorized party in subject, the applicable site in site, and the issuing body in authority. Map lifecycle states to the closest exact R4 Contract.status and reject states without an established mapping. Preserve separate revoke and regrant records as separate Contracts.

Genehmigung scope

A Genehmigung uses native Contract.subject, Contract.site, and Contract.authority to carry its authorization restrictions and issuer. Every subject is an authorized party: all subjects must match (AND).

  • A personal (kopfbezogene) grant is physician-bound and MVZ-independent. Its subject contains the Practitioner only.
  • A Betriebsstaetten-bound grant has both the Practitioner and the operating site's Organization as subjects. The Organization restricts the grant even when site is absent.
  • Contract.site, when present, references a Location and further restricts where the grant applies, in addition to all subject restrictions.
  • For a personal grant, omit an Organization or Location that is mere context from Contract.subject and Contract.site; do not move it elsewhere.
  • Contract.authority is the issuing body, for example the KV. It never restricts the authorized party or site.

These rules are structural and need no genehmigung-typ CodeSystem or source-specific Contract.scope coding. These illustrative base R4 Contracts use synthetic references and are guidance, not package instances. They show scope only; established identity, validity and service-area facts are retained as described above.

Personal grant: physician A is the only subject, independently of the MVZ. A contextual Organization or Location is omitted from subject and site, without moving it elsewhere. The issuing KV remains the authority.

{
  "resourceType": "Contract",
  "id": "personal-authorization",
  "status": "executed",
  "type": {
    "coding": [
      {
        "system": "https://fhir.cognovis.de/praxis/CodeSystem/authorization-instrument",
        "code": "kv-service-authorization"
      }
    ]
  },
  "subject": [
    { "reference": "Practitioner/physician-a" }
  ],
  "authority": [
    { "reference": "Organization/issuing-kv" }
  ]
}

Betriebsstaetten-bound grant without a Location: physician A and operating-site Organization X must match. It does not authorize physician A at Organization Y, even though site is absent.

{
  "resourceType": "Contract",
  "id": "operating-site-authorization",
  "status": "executed",
  "type": {
    "coding": [
      {
        "system": "https://fhir.cognovis.de/praxis/CodeSystem/authorization-instrument",
        "code": "kv-service-authorization"
      }
    ]
  },
  "subject": [
    { "reference": "Practitioner/physician-a" },
    { "reference": "Organization/operating-site-x" }
  ],
  "authority": [
    { "reference": "Organization/issuing-kv" }
  ]
}

Betriebsstaetten-bound grant with a Location: physician A and operating-site Organization X must match, and the grant additionally applies only at treatment Location X.

{
  "resourceType": "Contract",
  "id": "operating-site-location-authorization",
  "status": "executed",
  "type": {
    "coding": [
      {
        "system": "https://fhir.cognovis.de/praxis/CodeSystem/authorization-instrument",
        "code": "kv-service-authorization"
      }
    ]
  },
  "subject": [
    { "reference": "Practitioner/physician-a" },
    { "reference": "Organization/operating-site-x" }
  ],
  "authority": [
    { "reference": "Organization/issuing-kv" }
  ],
  "site": [
    { "reference": "Location/treatment-site-x" }
  ]
}

Training and organization

A postgraduate trainer is represented by a PractitionerRole plus its exact authorization Contract. The role carries practitioner, organization, location, specialty, period, and wb-rolle#weiterbildungsbefugter. The Contract references the exact role, repeats the validity interval, and preserves authorization identity and lifecycle. Maximum authorized duration uses Contract.term.offer.type = wb-parameter#maximum-authorized-training-duration and Contract.term.offer.answer.valueQuantity with UCUM mo. Preserve explicit zero and omit the term when the value is absent.

When a legacy trainer record carries an explicit active flag, PractitionerRole.active preserves that authoritative value exactly. It is not derived from Contract.status, the role period, or the current date. Status and period remain separate facts and may be validated for consistency without silently overwriting the active flag.

A postgraduate assignment uses PractitionerRole plus Task. The role carries the assigned practitioner, organization, specialty, validity period, exact active flag, and wb-rolle#wb-assistent. The Task references the role as focus, the practitioner as for, uses intent = order, records generic progress in status, and records the exact business stage in businessStatus. Its typed inputs reference the exact trainer-authorization Contract and carry approved weekly hours as a UCUM h/wk Quantity. Explicit zero remains distinct from an absent input.

Training supervision never establishes billing attribution. Populate billing-practitioner-role only from an authoritative billing assignment. The same extension records that a prophylaxis or practice assistant's performed services are attributed to and billed by the assigned dentist's or physician's role; that attribution also drives the practice's per-practitioner revenue statistics.

Use Organization.partOf for the selected primary parent. If a second, independently established membership must also be retained, use OrganizationAffiliation with the applicable organization-relationship code. Do not duplicate the primary edge or infer authorization effects from the affiliation alone.

The KV practice is the Arztpraxis within the meaning of BMV-Ä §1a no. 18 under which the Kassenärztliche Vereinigung bills: a single practice, a BAG or ÜBAG, or an MVZ. It is its own Organization with type = organization-type#kv-arztpraxis and the BSNR under which the KV bills it, also when it has only one operating site. It has no Location, no PractitionerRole, and no partOf edge. When it shares the BSNR of its main operating site, the two remain separate organizations and are never merged by BSNR. Each operating site's membership is an OrganizationAffiliation with organization = the KV practice, participatingOrganization = the site, code = organization-relationship#kv-arztpraxis-membership, and period = the interval in which the membership applies. On one day an operating site belongs to at most one KV practice.

uebag-membership stays as a specialization of kv-arztpraxis-membership: the organization-relationship CodeSystem declares is-a hierarchy meaning, and uebag-membership is a child concept of kv-arztpraxis-membership. A producer writes kv-arztpraxis-membership for every KV practice kind. A reader that resolves the KV practice of a site also accepts uebag-membership.

Free text moves to the imported HL7 note extension only when its purpose and access boundary remain valid. Provenance records the actual source occurrence and import recording times when those facts are available; it must not invent source activity.

TI transmissions

A transmission to a Telematikinfrastruktur (TI) recipient is one Task that conforms to ti-transmission-task. The transmitted domain resource keeps its own KBV or gematik profile; the Task carries the transmission.

  • Task.code carries exactly one TI application from ti-application.
  • Task.businessStatus carries exactly one transmission stage from ti-transmission-status. Native Task.status keeps the generic progress and is draft, requested, in-progress, completed, failed, or cancelled. Each ti-transmission-status concept names the Task.status values it may accompany in its allowed-task-status property, and the profile rejects every other pair.
  • Task.intent is order. Task.for is the Patient. Task.requester is a literal copy of the focus resource's requester when it has one; otherwise it is the PractitionerRole, or the Practitioner when no single role is known, on whose behalf the practice transmits. Task.owner is the software Device of the adapter that serves the Task.
  • Task.focus is the transmitted domain resource or document Bundle, and is absent for retrievals (vsdm, eml).
  • Task.output.type comes from ti-transmission-output: signed-original references the byte-exact signed original as a Binary, receipt a receipt from the recipient side, response the business answer, and error-report the recipient's or Konnektor's error report.

completed, failed, and cancelled are terminal: status never changes after them. A retry is a new Task. The only later write to a terminal Task is a late recipient error on a completed Task: businessStatus changes to fehler, statusReason is set, and an error-report output is appended; otherwise only output is appended. storniert withdraws a Task before transmission. A revocation after transmission is its own Task with the same code and for as the original and focus referencing the original Task; it carries its own identifiers and never the AccessCode, and the original stays unchanged.

The attempt key of a Task is (code, for, focus), or (code, for) without a focus. At most one draft, requested, or in-progress Task exists per attempt key. The profile checks one Task; the terminal-state rule and the attempt-key rule span Task versions and Tasks, so writers enforce them.

Task.identifier carries external identifiers, at most one per system:

System Meaning and value format Applications
https://gematik.de/fhir/erp/NamingSystem/GEM_ERP_NS_PrescriptionId gematik E-Rezept-ID, for example 160.000.000.000.000.01. The Fachdienst Task id equals it. Defined by gematik. erp, evdga
https://gematik.de/fhir/erp/NamingSystem/GEM_ERP_NS_AccessCode gematik AccessCode, 64 hexadecimal characters issued by the Fachdienst. It is a bearer secret: never search by it, and carry it only on the original transmission Task. Defined by gematik. erp, evdga
urn:ietf:rfc:3986 with type = IHE.MHD.MHDIdentifierType#uniqueId Copy of the XDS uniqueId of the uploaded document as urn:oid:<oid>. The DocumentReference stays authoritative. epa-doc, epa-mio
https://fhir.cognovis.de/praxis/sid/kim-message-id Message-ID of the KIM message: the RFC 5322 msg-id without the angle brackets, for example 20261001092041.4f2a9c@kim.example.org. Defined by this package because no gematik system for KIM Message-IDs exists. eau, eab, eeb, ebz, kim
https://fhir.cognovis.de/praxis/sid/ebz-antragsnummer The element Antragsnummer of the GKV-SV EBZ XML schema, newly assigned for every first or corrected EBZ submission. Defined by this package because no FHIR system exists. ebz

Archive documents

Use base DocumentReference. Store the immutable archive handle as masterIdentifier and the archive revision as a separate identifier. A rendition-specific authenticated URL belongs on content.attachment.url.

DocumentReference.content may carry multiple Attachment representations of the same clinical document. An unchanged OCR representation uses its own text/plain attachment, while the original PDF or image remains a separate attachment. Consumers select representations by media type rather than a fixed array position. DocumentReference.subject records the patient association when one is established; absence may represent an unmatched document.

Represent original and stored renditions as separate DocumentReference resources linked with relatesTo.code = transforms. Apply the imported HL7 alternate-hash extension to the attachment whose bytes were hashed. This preserves algorithm, digest, and rendition association without the former local archive extensions.

Derived-document lineage uses base R4 Provenance. Target the resulting DocumentReference, identify the exact source DocumentReference version with an entity whose role is source, use the v3 DataOperation CREATE activity, and identify the producing service as assembler and the initiating actor as enterer when those actors are established. The enterer is not thereby the document author. A later patient reassignment does not silently retarget already accepted derived resources or their lineage.

Other standard mappings

  • A confirmed physical-presence event is an Observation with status = final, code = presence-event#physical-presence-confirmed, valueBoolean = true, the patient as subject, and the associated Encounter in encounter. Use effectiveDateTime, performer, and Provenance only for facts that are actually established. Encounter lifecycle alone is not proof of presence.
  • Nursing-home residence is a social-history Observation with the patient as subject, the residence Location as focus, and the interval as effectivePeriod.
  • A treatment-start date belongs on EpisodeOfCare.period.start.
  • A Flag remark uses the imported HL7 note extension with valueAnnotation.
  • questionnaire-item-clinical-alert records the clinical assertion that an affirmative answer requires heightened attention. Item codes and rendering extensions do not carry the same assertion.
  • Practitioner specialty certification uses Practitioner.qualification with code, identifier, period, and issuer.
  • An assessment conclusion represented as an Observation links its source response through Observation.derivedFrom. A conclusion represented as a Condition uses Provenance because R4 Condition has no derivedFrom path.
  • A waiting-room call may use base Task with focus on the Encounter and for the same Patient. Task lifecycle and timing must be represented with native R4 fields; an Encounter status alone does not assert that a call occurred.
  • A pre-signature electronic-prescription route may use base Task focused on the exact MedicationRequest. The official Task-context PrescriptionType extension carries an established Flowtype. This preparatory Task does not assert that the official workflow Task or a signed prescription already exists.
  • An asserted referral accident uses KBV_CS_FOR_Ursache_Type|1.3.1#1 in ServiceRequest.reasonCode. An asserted historic federal-treatment cause uses the versioned KBV_CS_FOR_Ursache_Type|1.0.2#3. False or unknown assertions emit neither code. Proprietary referral fields and exact round-trip state remain private to their owning adapters and are outside this public IG contract.
  • eAU certificate kind uses the official KBV_CS_EAU_AU_Type code in DocumentReference.category. An asserted accident belongs on the referenced eAU Condition through the standard condition-dueTo extension and official cause code. R4 Attachment.hash contains SHA-1; SHA-256 uses the imported HL7 alternate-hash extension on the same Attachment.
  • A hospital admission emergency sets ServiceRequest.priority = stat; an admission accident uses the same official accident reason code as a referral accident. False or unknown assertions emit nothing.
  • A patient link to a RelatedPerson describing the same person uses Patient.link with type = seealso.
  • Assessment evidence and conclusions use Provenance.entity with role source, targeting the assessment or conclusion.
  • An imaging appointment carries its modality in Appointment.serviceType and its device as a participant.actor.
  • Radiation dose is an Observation with partOf the exposing Procedure and one component per recorded quantity (DAP, effective dose, tube voltage, and tube current-time product) in the source UCUM unit. Tube current and exposure time are preserved separately when the product is not recorded; no value is derived.
  • The radiation-protection qualification of the performer is a Practitioner.qualification. A justified-indication attestation is an Observation referenced from Procedure.reasonReference, with Provenance for the assessor. Neither asserts legal sufficiency by itself.
  • Report distribution is a Communication (medium, recipient, sent); a report substatus is Task.businessStatus on a Task focused on the report. Device maintenance status is Device.statusReason, and a questionnaire category is Questionnaire.useContext.

Historical-only and Billing-owned facts

Definitions without an authorized new-write target remain valid only through the historical package version that defined them. Migration is review-only and must not delete, mutate, or reinterpret stored values.

Billing wrappers and fields leave this package. The accepted Billing migration contract records 107 typed mappings with their exact public target and value path. The four medication Money extensions festbetrag, zuzahlung, mehrkosten, and gesamtzuzahlung are historical-only: they have no new-write target, retain their original canonical and Extension.valueMoney unchanged, and remain blocked from automated migration.

Rows whose former target was a Billing resource profile that Billing replaced by a base or official profile now name that replacement and the Billing successor row in migration/authored-ig-migration.json of Billing 0.3.4. Fourteen financial leaves have a typed Billing successor with the same target, value path, and transformation in both contracts, for example the GOÄ factor in ChargeItem.factorOverride, the catalog category as a focus use context on ChargeItemDefinition, and home-visit travel in the Billing billing-home-visit-travel extension. A catalog version label is dropped only when it names the same quarter as ChargeItemDefinition.version; otherwise migration blocks.

Three canonicals that consumers used without a published Praxis definition, coverage-entitlement-status, hvg-mandant-approval-date, and hvg-mandant-written-confirmation, also have one migration entry each with their Billing successor row. A suspended statutory entitlement uses the official German GKV extension and requires source evidence for its kind and start date; migration blocks otherwise.