Causal Schema

Open-source semantic extensions to schema.org for encoding causal reasoning across industries. This vocabulary enables precise representation of causal mechanisms, temporal progressions, multi-factorial conditions, and conditional recommendations that standard schema.org cannot capture.

Why CausalSchema?

Schema.org excels at describing what things are but falls short when expressing why things happen or how to reason about them:

Multi-Step Mechanisms

Content often explains how something works through multiple steps. Schema.org cannot capture multi-step mechanistic chains—only simple direct relationships.

Solution: CausalPathway and CausalStep types model step-by-step mechanistic explanations with evidence levels for each transition.

Time-Based Progressions

Conditions and situations evolve through distinct stages with different characteristics and recommended actions at each phase. Standard schema.org has no way to represent this temporal structure.

Solution: Progression and Stage types capture stage-based timelines with rich contextual information.

Multi-Factorial Causation

Real-world conditions result from multiple interacting factors, not single causes. Schema.org can list factors but cannot describe how they interact or their relative importance.

Solution: ContributingFactor and FactorInteraction types model complex causation patterns.

Conditional Recommendations

Recommendations often depend on multiple criteria with AND/OR logic, risk stratification, and specific characteristics. Schema.org cannot express complex decision trees.

Solution: ConditionalRecommendation, Criteria, and RiskAssessment enable precise conditional guidance.

Domain-Agnostic Design

CausalSchema provides core reasoning types that work across any industry:

Healthcare: Disease mechanisms, treatment progressions, drug interactions
Construction: Building defects, deterioration timelines, remediation decisions
Automotive: Failure mechanisms, maintenance schedules, diagnostic pathways
Agriculture: Crop diseases, growth stages, treatment recommendations
Infrastructure: Asset degradation, risk assessment, intervention planning

Domain-specific extensions (like construction.causalschema.org) add specialised types while sharing the same namespace and core vocabulary.

Design Principles

Extension, not replacement — These types augment schema.org's existing vocabulary rather than replacing it. Use standard schema.org types wherever possible.
LLM-optimised — Designed to enable large language models to truly understand causal content, not just keyword match.
Evidence-based — Properties include evidence levels and citations to support claims.
Single namespace — All types (core and extensions) use the cs: prefix and share the https://causalschema.org/ namespace.
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

How to Use This Vocabulary

1. Declare the Context

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

JSON-LD

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

Or declare the namespace explicitly:

JSON-LD

{
  "@context": [
    "https://schema.org",
    {
      "cs": "https://causalschema.org/",
      "CausalPathway": "cs:CausalPathway",
      "Progression": "cs:Progression"
    }
  ]
}

2. Use Custom Types Alongside Schema.org

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

JSON-LD

{
  "@context": [
    "https://schema.org",
    "https://causalschema.org/context.jsonld"
  ],
  "@graph": [
    {
      "@type": "Article",
      "headline": "Understanding Rising Damp",
      "about": {
        "@type": "Thing",
        "name": "Rising damp"
      }
    },
    {
      "@type": "CausalPathway",
      "name": "Rising damp mechanism",
      "initialCause": "Ground moisture contact",
      "pathwaySteps": [ ... ],
      "finalOutcome": "Wall damage and decay"
    }
  ]
}

3. Validate Your Markup

Important Note on Validation

Standard schema.org validators will not recognise these custom types and may report them as errors. This is expected behaviour. These extensions are designed for:

Enhanced understanding by large language models
Knowledge graph enrichment
Semantic relationship modelling

Search engines will process standard schema.org properties normally and ignore custom extensions they don't understand.

Architecture: Core + Extensions

CausalSchema uses a single namespace with domain-specific documentation entry points:

Architecture

causalschema.org (core)
│
├── Domain-agnostic causal reasoning types
│   ├── CausalPathway, CausalStep
│   ├── Progression, Stage  
│   ├── ContributingFactor, FactorInteraction
│   └── ConditionalRecommendation, Criteria, RiskAssessment
│
└── Extensions (domain-specific)
    │
    ├── construction.causalschema.org
    │   └── BuildingDefect, RemediationProcedure...
    │
    └── Future: automotive, agriculture, infrastructure...

All types share the cs: prefix and https://causalschema.org/ namespace. Extension contexts import the core context and add domain-specific terms.

Technical Resources

JSON-LD Context Definition — Machine-readable context for all types and properties

Contact & Feedback

Causal Schema is an open-source project developed initially by Creative Touch and refined through real-world content markup.

For questions, suggestions, or to contribute:

Website: causalschema.org
Email: contact@causalschema.org
Original implementation: Creative Touch

Version Information

Current Version: 0.1 (December 2025)

Namespace URI: https://causalschema.org/

License: Creative Commons Attribution 4.0 International (CC BY 4.0)