FHIR schema — the structure of resources and their extensions — has patterns that separate maintainable implementations from technical debt. Six best practices to adopt.
1. Version-pin profile references. Reference US Core profiles at specific versions. Prevents drift when profile updates change semantics.
2. Publish custom StructureDefinitions. Any custom extension needs a StructureDefinition. Publish at a stable canonical URL your team controls.
3. Use references, not contained. Resources needed elsewhere should be referenced; contained resources duplicate.
4. Bundle transaction for related writes. Related resources (Patient + Observation + Encounter for one visit) use type: transaction for atomicity.
5. $validate in write path. Every POST/PUT triggers $validate against target profile. Rejections at boundary, not downstream.
6. _lastUpdated monotonic. Never touch Meta.lastUpdated on unchanged resources. Broken monotonicity breaks incremental sync.
Common schema anti-patterns
1. Unversioned profile references. Drift over time. 2. Custom extensions without StructureDefinition. Non-conformant. 3. Contained resources for shared entities. Duplication. 4. Individual REST writes for related resources. Race conditions. 5. Skipping $validate. Data quality debt. 6. Touching _lastUpdated on unchanged. False sync.
Schema governance
1. Version control custom profiles. Git for StructureDefinitions. 2. Review process for schema changes. Cross-team review. 3. Deprecation policy. Version bumping and migration path. 4. Test coverage. $validate in CI.
Documentation to maintain
1. Canonical URLs for all custom extensions. 2. Version history of profile references. 3. Data model diagrams. 4. Terminology binding tables. 5. Reference type documentation.
Common schema mistakes discovered late
1. Cross-system schema drift → integration failures. 2. Missing profile validation → non-conformant data. 3. Extension URL collisions → semantic ambiguity. 4. Reference to wrong resource type → validation catches too late.
Tools
1. `$validate` — server-side validation. 2. Inferno — conformance testing. 3. FHIR Validator CLI — build-time validation. 4. Vendor SDK validators.
FHIR schema best practices compound over years. Sites adopting the six above ship maintainable systems; sites skipping them build technical debt.