Why These Extensions?

Schema.org provides excellent coverage for basic medical entities and relationships, but falls short when representing:

Design Principles

• Extension, not replacement — These types augment schema.org's existing medical vocabulary rather than replacing it. Use standard schema.org types wherever possible.
• LLM-optimised — Designed to enable large language models to truly understand medical content, not just keyword match.
• Evidence-based — Properties include evidence levels and citations to support claims.
• Practical application — Developed through real-world use on medical and wellness content.
• Schema.org conventions — Follows schema.org's design patterns and naming conventions for easy adoption.
• Open source — Free to use under Creative Commons license. Community contributions welcome.

Type Reference

Causal Mechanisms

Temporal Progressions

Multi-Factorial Conditions

Conditional Recommendations

Supporting Types

How to Use This Vocabulary

1. Declare the Context

Include both schema.org and the Health Schema context in your JSON-LD:

{
  "@context": [
    "https://schema.org",
    "https://healthschema.org/context.jsonld"
  ]
}

Or declare the namespace explicitly (reduces reported errors on the schema.org validator):

{
  "@context": [
    "https://schema.org",
    {
      "hs": "https://healthschema.org/",
      "CausalPathway": "hs:CausalPathway",
      "TemporalProgression": "hs:TemporalProgression"
    }
  ]
}

2. Use Custom Types Alongside Schema.org

Combine standard schema.org markup with custom extensions using @graph:

{
  "@context": [
    "https://schema.org",
    "https://healthschema.org/context.jsonld"
  ],
  "@graph": [
    {
      "@type": "MedicalCondition",
      "name": "Telogen effluvium",
      "riskFactor": [
        {
          "@type": "MedicalRiskFactor",
          "name": "Rapid weight loss"
        }
      ]
    },
    {
      "@type": "CausalPathway",
      "name": "Weight loss → Hair loss mechanism",
      "initialCause": { "@type": "Drug", "name": "Mounjaro" },
      "pathwaySteps": [ ... ],
      "finalOutcome": { 
        "@type": "MedicalCondition", 
        "name": "Telogen effluvium" 
      }
    }
  ]
}

3. Validate Your Markup

4. Best Practices

• Use standard schema.org first — Only use custom types when schema.org cannot express the relationship.
• Maintain compatibility — Always include standard schema.org alongside custom extensions.
• Document thoroughly — Use description and rationale properties liberally.
• Be consistent — Use the same custom types for similar patterns across your content.
• Cite sources — Include citation and evidenceLevel properties to support claims.

Examples

See practical implementations in the examples section:

• Causal Pathway Example — Mounjaro → hair loss mechanism
• Temporal Progression Example — Hair loss and recovery timeline
• Multi-Factorial Condition Example — GLP-1-associated hair loss
• Conditional Recommendation Example — High-risk population protocol
• Complete Article Markup — Full implementation combining all types

Relationship to Schema.org

This vocabulary is designed to complement, not compete with, schema.org's medical vocabulary:

Technical Resources

• JSON-LD Context Definition — Machine-readable context for all types and properties
• Complete Examples — Real-world implementations

Contact & Feedback

Health Schema is an open-source project developed initially by Creative Touch, a UK aesthetics clinic, and refined through real-world medical content markup.

For questions, suggestions, or to contribute:

• Website: healthschema.org
• Email: contact@healthschema.org
• Original implementation: Creative Touch