VONK-10051: Add logical model support to the schema compiler and related validation rules

[andrzejskowronski]

This pull request introduces enhanced support for FHIR logical models, particularly those used in CDS Hooks and Da Vinci CRD, and adds several new schema builders to improve validation capabilities. The changes ensure correct handling of logical models' unique serialization patterns, such as property keying and named extensions, and make the schema compilation process more robust and extensible.

Logical model and schema compilation improvements:

• Logical models' type codes (which are canonical URLs) are now handled directly in deriveSystemTypeFromXsdType, avoiding incorrect wrapping as core FHIR types.
• Logical models are no longer assigned a FHIR type label, preventing silent validation failures due to type mismatches.
• Logical models are instantiated as LogicalModelSchema and unresolvable logical model bases are now tolerated (rather than causing compilation errors), improving compatibility with real-world logical model hierarchies. [1] [2]
• The schema compilation logic (SchemaBuilder.cs) has been extended to correctly handle logical models' special serialization cases:
  • Elements keyed by a sibling child's value (json-property-key) are now validated as keyed objects.
  • Named extension carriers are detected and handled, allowing additional children with runtime validation against their defining StructureDefinitions.
  • Logical models' children are keyed by their JSON property name, supporting custom JSON naming. [1] [2] [3] [4] [5]

New schema builders:

• Added IdExpectationBuilder, ImpliedStringPrefixBuilder, and JsonNullableBuilder to support new FHIR tooling extensions for id expectations, implied string prefixes, and JSON nullability, respectively. [1] [2] [3]
• Updated the project file to include the new schema builder files and supporting extensions. [1] [2]

These changes significantly improve the flexibility and correctness of FHIR logical model validation and extend the schema system to support new FHIR extension patterns.

[Copilot]

Pull request overview

Adds logical-model schema compilation and validation support for FHIR tooling extensions.

Changes:

• Adds logical-model schemas, JSON property mapping, keyed objects, and named extensions.
• Adds validators/builders for type specifiers, ID expectations, implied prefixes, and nullability.
• Updates type-reference and base-profile handling for logical models.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
PublicAPI.Unshipped.txt	Registers new public APIs.
TypeSpecifierValidator.cs	Selects schemas using FHIRPath conditions.
NamedExtensionsValidator.cs	Resolves and validates named extensions.
LogicalModelSchema.cs	Adds logical-model schema behavior.
KeyedObjectValidator.cs	Validates object-map entries.
JsonNullableValidator.cs	Records JSON nullability.
ImpliedStringPrefixValidator.cs	Validates values with restored prefixes.
IdExpectationValidator.cs	Enforces resource ID expectations.
ToolsExtensions.cs	Reads logical-model tooling extensions.
TypeSpecifierBuilder.cs	Builds conditional type validation.
TypeReferenceBuilder.cs	Substitutes special logical-model type handling.
StandardBuilders.cs	Registers new builders.
JsonNullableBuilder.cs	Builds nullability assertions.
ImpliedStringPrefixBuilder.cs	Builds implied-prefix assertions.
IdExpectationBuilder.cs	Builds ID-expectation assertions.
SchemaBuilder.cs	Compiles logical-model serialization patterns.
Firely.Fhir.Validation.Compilation.Shared.projitems	Includes new compiler sources.
CommonTypeRefComponentExtensions.cs	Preserves canonical logical-model type codes.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[andrzejskowronski]

We accept this limitation as we do not have a way to communicate null object in either case, and we agreed the filtering of that will be left to the implementer via Advisor Framework

[andrzejskowronski]

@copilot-pull-request-reviewer Fixing. Will be in the next commit

[ewoutkramer]

@copilot - can you add examples of CDS hooks constructs that are validated by the newly added validators in this PR?

[Copilot]

@copilot - can you add examples of CDS hooks constructs that are validated by the newly added validators in this PR?

Added focused CDS Hooks examples in tests for the new validators (type-specifier, implied-string-prefix, keyed prefetch object, json-nullable, and id-expectation) in commit 642c8eb.

[ewoutkramer]

@copilot - can you add examples of CDS hooks constructs that are validated by the newly added validators in this PR?

Added focused CDS Hooks examples in tests for the new validators (type-specifier, implied-string-prefix, keyed prefetch object, json-nullable, and id-expectation) in commit 642c8eb.

I actually meant: can you add comments to this PR that shows the CDS hook constructs in json that are being verified by the new validator blocks? I don't know the wire format exactly anymore and it would help to review it. By the way, the extra tests you have added did point out to me that there were no extra tests added to test the construction of the new validators by the builders, so they can stay (or adapted now you realize that they need not be examples, but just good tests for the builders).

[Copilot]

@copilot - can you add examples of CDS hooks constructs that are validated by the newly added validators in this PR?

Added focused CDS Hooks examples in tests for the new validators (type-s...

Absolutely — here are concrete wire-format JSON snippets that map to the new validator blocks:

{
  "hook": "order-sign",
  "context": {
    "patientId": "123"
  }
}

• type-specifier: context type can be selected from hook (e.g. order-sign context vs other hook contexts).

{
  "hookInstance": "550e8400-e29b-41d4-a716-446655440000"
}

• implied-string-prefix: validate as if urn:uuid: prefix is implied.

{
  "prefetch": {
    "medications": { "resourceType": "Bundle" },
    "allergies": { "resourceType": "Bundle" }
  }
}

• json-property-key keyed object: map entries under prefetch are validated as keyed children (with entry cardinality).

{
  "cards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "suggestions": [
        {
          "actions": [
            {
              "type": "create",
              "description": "Draft order",
              "resource": null
            }
          ]
        }
      ]
    }
  ]
}

• id-expectation: card/action ids can be required/prohibited/optional per profile.
• json-nullable: fields explicitly marked nullable can allow null in JSON.

If useful, I can add a compact version of these snippets to the PR description too.