DomainResource
Model DomainResource (zasób domenowy) jest podstawą obiektów platformy wymiany danych dla systemów klasy ERP (księgowość, majątek, CRM, magazyn, kadry). Należy do standardu Kamsoft.FAIR (Fast Adaptive Interoperable Resources). Wzorowany na FHIR DomainResource, w uproszczonej postaci w tym przewodniku.
1. Zakres i zastosowanie
DomainResource to typ bazowy zasobu — nie występuje samodzielnie w API; specjalizują go zasoby domenowe opisane w tym przewodniku. Wspólny rdzeń (w JSON przyjęta jest konwencja camelCase):
- id — identyfikator logiczny,
- resourceType — nazwa typu zasobu,
- meta — metadane (np. lastModified); Meta. profile deklaruje profile, na które zasób się powołuje — lista adresów kanonicznych,
- owner — lista Reference(Party) (właściciele zasobu),
- comment — komentarz,
- category — klasyfikacje (CodeableConcept),
- status — status zasobu,
- type — typ zasobu (CodeableConcept),
- contained — zasoby osadzone w payloadzie nadrzędnym; reguły w §3,
- attribute — Attribute (cechy rozszerzające).
Zasoby pochodne dodają własne pola specyficzne dla domeny. identifier (Identifier) nie należy do rdzenia — deklarują go zasoby, które mają identyfikatory biznesowe (np. Party, Location, DocumentReference); zasoby bez własnego identifier (PartyRelationship, GrantAssignment, Notification) wyszukuje się po polach referencyjnych.
2. Zawartość (struktura)
| Nazwa | Kard. | Typ | Opis |
|---|---|---|---|
| id | 0..1 | string | Identyfikator logiczny zasobu |
| resourceType | 0..1 | string | Nazwa typu zasobu w payloadzie API (konwencja FAIR/REST) |
| meta | 0..1 | Meta | Metadane; meta.profile deklaruje profile zasobu adresami kanonicznymi (Meta) |
| owner | 0..* | Reference(Party) | Właściciele zasobu — podmiot będący właścicielem danych (w praktyce firma identyfikowana NIP-em); poszczególne zasoby/profile mogą czynić owner wymaganym (np. PostingInstruction) |
| comment | 0..1 | string | Komentarz |
| category | 0..* | CodeableConcept | Kategorie |
| status | 0..1 | CodeableConcept | Status — CodeableConcept wiązany ze słownikiem statusów per zasób (https://api-erp.kamsoft.pl/vs/.../<zasób>-status); rejestr słowników: code-systems |
| type | 0..1 | CodeableConcept | Typ zasobu — CodeableConcept wiązany ze słownikiem typów per zasób (https://api-erp.kamsoft.pl/vs/.../<zasób>-type); rejestr słowników: code-systems |
| contained | 0..* | object | Zasoby osadzone w payloadzie nadrzędnym — patrz §3 |
| attribute | 0..* | Attribute | Atrybuty rozszerzające |
Pola status i type są wiązane ze słownikami definiowanymi per zasób — zgodnie z konwencją URL https://api-erp.kamsoft.pl/vs/<dziedzina>/<zasób>-status oraz https://api-erp.kamsoft.pl/vs/<dziedzina>/<zasób>-type (segment <dziedzina>: finance, warehouse, assets, hr, retail; słowniki wspólne bez segmentu). Rejestr słowników: code-systems.
3. Zasoby osadzone (contained)
Pole contained przenosi zasoby w kontekście nadrzędnym, gdy nie występują jako samodzielna wiadomość w wymianie. Wzorzec jak w FHIR contained resources.
Kiedy używać
| Sytuacja | Opis |
|---|---|
| Dane towarzyszą nadrzędnemu zasobowi | Elementy przesyłane w jednym payloadzie wraz z zasobem głównym (np. BankAccount w Party) |
| Referencja lokalna zamiast osobnego GET | Reference z reference: "#<id>" wskazuje element w tablicy contained |
Dozwolone typy osadzonych zasobów i ewentualne ograniczenia pól określa profil zasobu nadrzędnego (dokumentacja konkretnego typu).
Reguły elementu w contained
| Element | Wymaganie |
|---|---|
| resourceType | Tak — typ zasobu zgodny z profilem nadrzędnym |
| id | Tak — identyfikator lokalny w ramach nadrzędnego zasobu (do referencji #id) |
| identifier | Nie — identyfikatory biznesowe należą do zasobu nadrzędnego |
| meta.versionId / meta.lastModified | Nie — brak niezależnej wersji (Meta) |
| Pola wiązania z nadrzędnym | Nie — kontekst wynika z zasobu rodzica; pola referencyjne do rodzica nie występują w elemencie osadzonym |
Referencja do osadzonego zasobu: Reference z reference = #<id> (np. #embedded-1).