The schema · v1.1 · frozen 2026-05-05

Six entities. One direction of links. Per-attribute provenance.

This page is the canonical reference. Every entity is reachable as a URL. Every attribute on every entity carries a SourceProvenance citation. The schema is published as JSON-LD; cite it.

Cardinalities

ProcessUnit       --[many-to-one]-->  Refinery
Refinery          --[many-to-one]-->  Operator
Operator          --[many-to-one]-->  ParentCompany
IncidentReport    --[many-to-one]-->  Refinery
IncidentReport    --[many-to-one]-->  ProcessUnit  (nullable)
*                 --[has-many   ]-->  SourceProvenance

Strategic shape

Every attribute scores along three axes: Difficulty (T1 simple, T2 paid, T3 ultrathink), Modify (raw, derived, synthesized), and Relevance (1 trivia, 5 trade-decision-driver). The pricing tiers are a projection of those axes onto willingness-to-pay; they are not a marketing decision. Full taxonomy at /DIFFICULTY-TAXONOMY.md.

Refinery Intelligence data difficulty matrix: 54 attributes plotted on a three-by-three grid of difficulty by relevance, color-coded by access tier.
v1.1 ontology, 54 attributes, recomputed against the live dataset 2026-05-05.

Entities

EntityJSON-LD classAttrsVersion
Refinery
A petroleum plant. Stable across operator and parent changes.		bf:Refinery18v1.1
Operator
The legal entity that runs a refinery. Contracting party in regulator filings.		bf:RefineryOperator7v1.1
ParentCompany
Ticker, exchange, country of incorporation. Globally deduplicated.		bf:ParentCompany8v1.1
ProcessUnit
CDU, FCC, hydrocracker, coker, reformer, alkylation. Capacity at the unit.		bf:ProcessUnit6v1.1
IncidentReport
Outages, turnarounds, fires, force majeure. Triggers the wire.		bf:IncidentReport11v1.1
SourceProvenance
A citation. Attached to an attribute, not a row. The bibliography model.		bf:SourceProvenance7v1.1

JSON-LD specimen

Every row in the public dataset can be fetched as JSON-LD with its provenance attached. A buyer who wants to fork the model into a private deployment can do so without reverse-engineering it.

{
  "@context": "https://refineryintelligence.com/refinery-ontology.jsonld",
  "@type":    "bf:Refinery",
  "@id":      "https://refineryintelligence.com/r/phillips-66-bayway-linden-nj",
  "slug":     "phillips-66-bayway-linden-nj",
  "name":     "Bayway Refinery",
  "city":     "Linden",
  "state":    "NJ",
  "countryCode": "US",
  "padd":     1,
  "geo": {
    "@type":     "schema:GeoCoordinates",
    "latitude":  40.6359,
    "longitude": -74.2237,
    "hasProvenance": {
      "@type":          "bf:SourceProvenance",
      "attribute":      "geo",
      "sourceClass":    "gazetteer",
      "sourceCitation": "OSM Nominatim, Bayway Refinery, Linden NJ 07202",
      "retrievedAt":    "2026-04-28T00:00:00Z",
      "confidence":     "high"
    }
  },
  "ratedCapacity": {
    "@type": "qudt:QuantityValue",
    "value": 258500,
    "unit":  "unit:BBL-PER-DAY",
    "hasProvenance": {
      "@type":          "bf:SourceProvenance",
      "attribute":      "ratedCapacity.value",
      "sourceClass":    "primary-regulator",
      "sourceUrl":      "https://www.eia.gov/petroleum/refinerycapacity/refcapacity.csv",
      "sourceCitation": "EIA Form 820, 2025 vintage",
      "retrievedAt":    "2026-04-15T00:00:00Z",
      "confidence":     "primary"
    }
  },
  "nelsonComplexity": {
    "@type":            "bf:NelsonComplexity",
    "value":            13.6,
    "estimationMethod": "operator-disclosed",
    "confidence":       "primary"
  },
  "operator": {
    "@type": "bf:RefineryOperator",
    "@id":   "https://refineryintelligence.com/op/phillips-66",
    "name":  "Phillips 66",
    "parentCompany": {
      "@type":   "bf:ParentCompany",
      "@id":     "https://refineryintelligence.com/pc/phillips-66",
      "name":    "Phillips 66",
      "ticker":  "NYSE:PSX"
    }
  },
  "status": "operating"
}

Versioning

The current schema is v1.1, frozen 2026-05-05. v1.0 (frozen 2026-04-27) is archived at /refinery-ontology-v1.0.jsonld. Schema changes ship as additive minor versions (v1.2, v1.3) when no existing query breaks, and as major versions (v2.0) when an entity or attribute is removed or its semantics change. The JSON-LD at /refinery-ontology.jsonld always serves the current major version. Aspirational entities (Pipeline, TankFarm, Tanker, CrackSpread, Turnaround, Outage, CrudeGrade) are described in roadmap.v2.0 of the JSON-LD, not in v1.1, because the dataset has zero rows for them today.