Cumuluz Translate Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Validate

Validate

Main Endpoint

POST /fhir/r4/$validate

This endpoint validates an R4 resource against a requested target profile and returns a FHIR OperationOutcome.

The service validates on the R4 side only. It does not expose source-side STU3 validation as part of the public contract.

That separation keeps the public contract simple: translation produces the target resource, and validation checks that resource against the requested target family and terminology set.

Accepted Request Shapes

The validation surface accepts either:

• a FHIR Parameters request with resource and profile
• a direct R4 resource request where the profile is carried in meta.profile

The Parameters form is the clearest and is the preferred form for clients.

If clients want to validate before they translate, they can do that explicitly as a separate step. The translator itself does not silently switch into source validation mode.

Parameters Request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "patient-validate-request",
        "text": {
          "status": "generated",
          "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Anja de Vries</div>"
        },
        "meta": {
          "profile": [
            "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
          ]
        },
        "active": true,
        "identifier": [
          {
            "system": "http://fhir.nl/fhir/NamingSystem/bsn",
            "value": "999998779"
          },
          {
            "system": "http://example.org/mrn",
            "value": "MRN-12345"
          }
        ],
        "name": [
          {
            "use": "usual",
            "family": "de Vries",
            "given": [
              "Anja"
            ]
          }
        ],
        "gender": "female",
        "birthDate": "1964-05-12",
        "address": [
          {
            "line": [
              "Laan van Europa 10"
            ],
            "city": "Amsterdam",
            "postalCode": "1000AA",
            "country": "NL"
          }
        ],
        "generalPractitioner": [
          {
            "reference": "Practitioner/gp-1"
          }
        ]
      }
    },
    {
      "name": "profile",
      "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
    }
  ]
}

That request validates the Patient against nl-core-Patient.

Type-Level Validation Endpoints

The service also exposes type-level validation routes for currently supported R4 resource types:

• POST /fhir/r4/Patient/$validate
• POST /fhir/r4/Condition/$validate
• POST /fhir/r4/Procedure/$validate
• POST /fhir/r4/Observation/$validate
• POST /fhir/r4/AllergyIntolerance/$validate
• POST /fhir/r4/Encounter/$validate
• POST /fhir/r4/CareTeam/$validate
• POST /fhir/r4/Appointment/$validate
• POST /fhir/r4/MedicationRequest/$validate
• POST /fhir/r4/MedicationStatement/$validate
• POST /fhir/r4/MedicationDispense/$validate
• POST /fhir/r4/Provenance/$validate
• POST /fhir/r4/Consent/$validate
• POST /fhir/r4/RelatedPerson/$validate
• POST /fhir/r4/Practitioner/$validate
• POST /fhir/r4/PractitionerRole/$validate
• POST /fhir/r4/CommunicationRequest/$validate
• POST /fhir/r4/Device/$validate
• POST /fhir/r4/DeviceUseStatement/$validate
• POST /fhir/r4/Goal/$validate

These routes reject mismatched resource types.

For example, POST /fhir/r4/Procedure/$validate rejects a Patient body with an OperationOutcome.

PZP target resources can be validated through the generic POST /fhir/r4/$validate endpoint or through the matching type-level endpoint with the requested PZP 2020 profile.

R4 QuestionnaireResponses for https://api.iknl.nl/docs/pzp/r4/Questionnaire/ACP-zib2020 can also be validated through the generic endpoint. Extraction from supported QuestionnaireResponses is a separate operation described in QuestionnaireResponse.

Response Behavior

The validation response is always a FHIR OperationOutcome.

Current HTTP behavior is:

• 200 when the outcome contains only information or warning
• 400 when the outcome contains error or fatal

That means clients should inspect both:

• the HTTP status
• the issues in the returned OperationOutcome

Success Response

When validation succeeds, the service returns HTTP 200 with an OperationOutcome that may contain informational notes.

{
  "resourceType": "OperationOutcome",
  "id": "patient-validate-response",
  "extension": [
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-issue-count-error",
      "valueInteger": 0
    },
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-issue-count-warning",
      "valueInteger": 0
    },
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-issue-count-information",
      "valueInteger": 1
    },
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-relaxed-issue-count",
      "valueInteger": 0
    }
  ],
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "No issues detected during validation"
    }
  ]
}

Failure Response

When validation fails, the service returns HTTP 400 with an OperationOutcome containing at least one error or fatal issue.

{
  "resourceType": "OperationOutcome",
  "id": "patient-validate-response-fail",
  "extension": [
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-issue-count-error",
      "valueInteger": 1
    },
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-issue-count-warning",
      "valueInteger": 0
    },
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-issue-count-information",
      "valueInteger": 0
    },
    {
      "url": "http://cumuluz/fhir/StructureDefinition/validation-relaxed-issue-count",
      "valueInteger": 0
    }
  ],
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Resource does not conform to http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient"
    }
  ]
}

Practical Interpretation

The validator is intentionally useful for target-side quality checks, but not every warning means the translation failed.

Current known behavior includes:

• informative or warning-level messages for some offline package or slice-resolution cases
• non-blocking warnings where the output is still structurally acceptable for the intended route

In practice, a warning may point to package availability, slice matching, or terminology resolution rather than to a bad translation.

Example Files

• ig/input/examples/patient-validate-request.json
• ig/input/examples/patient-validate-response.json
• ig/input/examples/patient-validate-response-fail.json

Clients that need a strict go/no-go decision should treat error and fatal as blocking and review warnings according to their own policy.

Target Families

Validation follows the same target families as translation.

• validate against nl-core 2020 when the translated output is meant to fit the Dutch profile family
• validate against eu-base when the translated output is meant to fit the European profile family
• validate against EPS when the translated output is meant to fit the European Patient Summary profile or document Bundle
• validate against PZP 2020 ACP profiles for supported PZP profile-pair translation output

For background on the target families themselves, see Target Profiles.

Validation Metadata

GET /fhir/r4/metadata returns a FHIR CapabilityStatement describing the R4-facing validation surface and the supported target profiles per resource type.