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
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.
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 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 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.
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).
subject contains the Practitioner only.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.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" }
]
}
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.
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 |
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.
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.Observation with the patient as
subject, the residence Location as focus, and the interval as
effectivePeriod.EpisodeOfCare.period.start.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.qualification with
code, identifier, period, and issuer.Observation links its source
response through Observation.derivedFrom. A conclusion represented as a
Condition uses Provenance because R4 Condition has no derivedFrom path.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.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.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.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.ServiceRequest.priority = stat; an
admission accident uses the same official accident reason code as a referral
accident. False or unknown assertions emit nothing.Patient.link with type = seealso.Provenance.entity with role
source, targeting the assessment or conclusion.Appointment.serviceType and
its device as a participant.actor.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.Practitioner.qualification. A justified-indication attestation is an
Observation referenced from Procedure.reasonReference, with Provenance
for the assessor. Neither asserts legal sufficiency by itself.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.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.