diff --git a/Docs/2_OED_Overview.rst b/Docs/2_OED_Overview.rst deleted file mode 100644 index b1612670..00000000 --- a/Docs/2_OED_Overview.rst +++ /dev/null @@ -1,86 +0,0 @@ -Overview of OED -=============== - -The OED comprises of four input files which are designed to allow the user to enter data in a manageable way without needing to populate and understand the relationship between a large number of tables. This does mean that there are areas of inefficiency and duplication in the input tables: this is inevitable when trying to balance between practicality and efficiency. - -The four input files are described in the Input Format {enter link to that .rst here} - -Hierarchy ---------- - -OED follows an organisational and financial structure hierarchy that most users of catastrophe models will be familiar with. Specifically: - - - -Coverage -######## - -A **coverage** type represents the lowest structure within the OED hierarchy and constitutes the specific type of coverage within an insurance policy. Within OED this is defined as: - -• Buildings -• Other (e.g. outbuildings – ‘appurtenant’ structures or motor) -• Contents -• Business Interruption (BI) or time element coverage - -Primary financial structures such as limits and deductibles can be attached at coverage level as well as across property damage (PD = Buildings +Other Buildings + Contents) and across all coverages. - - - -Location -######## - -A **location**, or site, comprises a group of coverages at one particular location. Primary financial structures, such as limits or deductibles can be applied at location level. Reinsurance financial structures, such as facultative reinsurance, can also be attached at location level. - -Sometimes an individual location record will actually represent a number of buildings (but perhaps because of poor data quality only the main location is known). This can be represented using the **NumberOfBuildings** field. Occasionally an insurer will have details about a number of individual locations that they wish to link in some way, for example a number of buildings on a university campus or on an industrial site. This can be achieved using the **LocGroup** field. - - - -Policy -######## - -A **policy** is a specific type of financial structure that applies to a set of locations. The unique aspect of a policy is that multiple policies can exist under the same account and can apply to the same set of locations. An example of this is an insurance layer, where several layers can apply to the same underlying set of locations. Reinsurance can also apply at policy level. - -Within a policy there is a hierarchy of financial terms as follows: - -• A **special condition** is a type of policy level financial structure where financial conditions (such as sub-limits and sub-deductibles) apply to a subset of locations. -• **Standard policy level** financial structures apply after special conditions but before layers. -• **Layers** apply after special conditions and standard policy level financial structures. - -Since multiple policies can apply to the same set of locations care must be taken when summing exposure or ground-up loss at policy level to avoid overcounting these metrics. - - - -Account -######## - -An **account** comprises a group of policies and locations (both are needed: you cannot have a policy without a location or a location without a policy). Primary and reinsurance financial structures can apply at account level. - -An **account group** can also be specified (using the AccGroup field) which provides a means of grouping accounts together for reporting purposes. Financial structures cannot apply at account group level. - - - -Portfolio -########## - -A **portfolio** comprises a number of accounts. Primary financial structures cannot apply at portfolio level, however reinsurance structures can. -  -The table below shows the different hierarchical levels in OED and what financial terms are applicable: - -.. csv-table:: - :widths: 25,50,20,20 - :header: "Hierarchy", "Description", "Primary Financial Terms?", "Reinsurance Financial Terms?" - - "Location coverage", "Building, contents, business interruption (BI), other", "Yes", "No" - "Location", "Defined through the **LocNumber** field; location level financial field names start with ‘Loc’", "Yes", "Yes" - "Location group", "Defined through the **LocGroup** field", "No", "Yes" - "Policy", "Defined through the **PolNumber** field; within the policy level there is a hierarchy of financial terms: - - Special conditions apply first; field names start with *‘Cond’*. - - Standard policy conditions apply after special conditions; field start with *‘Pol’*. - - Layers apply after special conditions; field names start with *‘Layer’*.", "Yes", "Yes" - "Account", "Defined through the **AccNumber** field; account level financial term field names all start with *‘Acc’*", "Yes", "Yes" - "Account group", "Defined through the **AccGroup** field", "No", "No" - "Portfolio", "Defined by the **PortNumber** field", "No", "Yes" - diff --git a/Docs/Cyber/ReadMe.md b/Docs/Cyber/ReadMe.md deleted file mode 100644 index 479b396a..00000000 --- a/Docs/Cyber/ReadMe.md +++ /dev/null @@ -1,69 +0,0 @@ - - - -# OED Cyber - -### Introduction - -Growing demand over the past five years led to the release of the first cyber exposure data schema in 2022 as part of the Open Exposure Data standard. It soon became clear that a single, unified OED schema for multiple business classes would be more efficient than separate schemas. - -OED v4.0.0 is the first version which brings together the data standards for multiple exposure classes; property, cyber, liability and marine cargo, into a single integrated specification. It incorporates all fields from the original cyber schema, with some field names updated for better alignment with property and the main schema. - -Please refer to the release notes for OED v4 that includes all updates (https://github.com/OasisLMF/ODS_OpenExposureData/releases). - -More general information can also be found on the ODS webpage (https://oasislmf.org/open-data-standards). - -### Contributors - -The cyber data standard v1 was developed through the collaboration of a working group throughout 2022, made up of participants from the following companies. Their time and effort is hugely appreciated. - -* Allianz -* Aon -* Axis Capital -* CyberAcuView -* Gallagher Re -* Guidewire Cyence -* Guy Carpenter -* KOVRR -* Oasis LMF (ODS curator/secretariat) -* RenaissanceRe -* Richard DeKorte (Cyber Security Independent) -* Moody's RMS -* Sompo International -* Swiss Re -* Waratah Analytics -* Zurich Insurance - -  - -### Rationale - -The initial data schema was primarily intended to ensure a degree of consistency in policy-level data capture and to enable efficient sharing of select data fields across the industry. Other than the benefit of reduced frictional cost, wide-spread adoption of the schema should enable portfolio managers to implement granular, accurate and robust exposure management procedures. This can, in turn, enable sophisticated risk accumulation and/or cyber modelling use cases. - -The cyber specific data fields are highlighted in the 'Cyber Fields Status' column in the 'OEDInputsFields.csv' where the fields can be filtered on 'R' for 'required fields', 'O' for 'optional' and 'CR' for 'conditionally required'. - -The cyber specific coverage codes are included in the 'CoverageValues.csv' and prefixed by 'PolDed' for sub-deductibles and 'PolLimit' for sub-limits. - -### Considerations - -1. The aim of this schema is to promote consistency and efficiency of the transfer of cyber data around the marketplace. As the focus of this schema is to accommodate key requirements for multiple uses, this is not considered exhaustive and it is expected to develop and evolve over time. The user is not expected to populate all fields and should be treated as a guide. - -2. ODS encourages the capture of company identifier information but does not endorse any one provider of this data. It is the responsibility of the user to ensure that no contractual agreements with third parties are breached in the use of this schema or the transfer of licensed data such as DUNS or LEI company identifies. - -3. TECHNOGRAPHIC DATA: Opinions around the capture of technographic data were mixed during the development of the original schema. Most suggested they should be considered "aspirational" at this stage and should be the focus for further developments. The main reason for that thinking is that capturing this data accurately to reflect how and where these providers are used in a complex business is not trivial. Questions to consider for example are, "is the cloud/email provider the same for all servers and systems within a company?" or "do all devices/systems use the same OS?". -However, reinsurers consider that even capturing the basic data would provide value, especially for accumulation analytics. Therefore, it was decided that some basic fields should be included but populated at the discretion of the user. -They should consider the vendors of their 'primary' or 'main' systems/servers as included in the 'OSVendor' (operating system), 'CloudVendor' (cloud provider), 'CRMVendor' (customer relationship management provider), 'PatchPolicy' (cadence of patches for the main systems) and 'BackUpFreq' (cadence of backups for the main systems) fields. - -4. The user is responsible for populating the data fields in this schema. No fields will be linked to any external database (i.e. for industry scheme or code). - -5. All cyber exposure fields are captured in the acc (account) file. There is no need for a location file as the data standard does not currently require the capture of physical asset data with geographical locators, although there is nothing to preclude this from being developed going forward. - -Any feedback or suggestions should be sent as an issue in the GitHub repo: https://github.com/OasisLMF/ODS_OpenExposureData/issues - -  - - -### Governance - -A cyber steering committee (CSC) will be set up one enough market adoption has occurred and developments to this need 'steering'. This will act as a "sub-committee" and a member of this CSC will report into the main ODS Steer Co. - diff --git a/Docs/Liability/ReadMe.md b/Docs/Liability/ReadMe.md deleted file mode 100644 index 57e79e8e..00000000 --- a/Docs/Liability/ReadMe.md +++ /dev/null @@ -1,50 +0,0 @@ - - - -# OED Liability - -### Introduction - -The first version of the OED schema for liability data was released in April 2022 following the efforts of a small market working group. The release video can be found on the Oasis You Tube channel (https://youtu.be/WW9N4mlNtb8). This was the first data schema available to the market to promote the use of standardised liability data for the re/insurance industry. - -OED v4.0.0 is the first major release which brings together the data standards for multiple exposure classes; property, cyber, liability and marine cargo, into a single integrated specification. It incorporates all fields from the original liability schema (v1), with some field names updated for better alignment with property and the main schema. - -  - -### Rationale - -This data standard is primarily intended to ensure a degree of consistency in policy-level data capture and to enable efficient sharing of select data fields across the industry. Other than the benefit of reduced frictional cost, wide-spread adoption of the schema should enable portfolio managers to implement granular, accurate and robust exposure management procedures. This can, in turn, enable sophisticated risk accumulation and/or liability modelling use cases. - -The approach for the original schema was to make it as succinct and prescriptive as possible to ensure consistency of the data formats and to keep any ambiguity to a minimum. - -The original taxonomy created for the liability data standard below is still intended to be internationally applicable and implemented across UK, European and US markets. Increased market adoption of this schema will heavily rely on it being used by the key players in the data transfer process, specifically the brokers and reinsurers. - -At a high level, the approach taken has aligned to the EIOPA definition of liability classes (classes 10-13 in their non-life risk classification convention), with some subdivision of the broad Other category. The benefit of linking the scope to the EIOPA definition is primarily to ensure exhaustiveness. - -*Motor Liability*, *Aviation Liability*, *Marine Liability* and *Personal Liability* are all excluded from the data standard. This is partly motivated by concerns around the sharing of personal information, but also the idea that liability exposure accumulation analysis often starts at company or industry-level. Accident & Health, which is not considered a liability class under the EIOPA convention, could be omitted for similar reasons, with a possible fringe case for inclusion being the Workers’ Compensation class of business. - -It’s worth noting that in designing the taxonomy, it was decided to consider attributes of the insured, such as industry/trade/profession, separately from class/coverage. For example, medical practitioners, financial institutions, architects, engineers and lawyers can all be considered as insured attributes to be captured for the *Professional Liability* coverage class. This should lend itself to a more concise and consistent data schema. - -  - -### Taxonomy - -Below is the proposed class-based taxonomy, for the purpose of identifying the insurance policy coverages that should be in or out of scope of the first version of the standard. -  - - - -**Note:** What is considered 'Other', EIOPA has termed ‘general liability’. To avoid confusion, its intended to avoid this term as far as possible. In the US, general liability is better described as either Commercial or Personal Liability whereas in the UK it’s referred to as either Public or Employers Liability. - -  - -### Next Steps - -As interest and adoption increases, the likely next steps for this standard will be to develop the schema to include more required data fields specific to each sub-class through collaboration and on-going feedback. This work will also include expanding the scope of the taxonomy to those classes currently not supported and driven by demand, such as motor and aviation. - -Any feedback and suggestions for updates should be submitted via the 'issues' here (https://github.com/OasisLMF/OpenDataStandards/issues) which will then be reviewed by the Technical Working Group (TWG). - - - - - diff --git a/Docs/index.rst b/Docs/index.rst deleted file mode 100644 index baf9a143..00000000 --- a/Docs/index.rst +++ /dev/null @@ -1,17 +0,0 @@ - -Open Exposure Data (OED) -======================== - -.. toctree:: - :numbered: -.. include:: 1_OED_Rationale_and_Abbreviations.rst -.. include:: 2_OED_Overview.rst -.. include:: 3_OED_Import_Format.rst -.. include:: 4_OED_Asset_Related_Details.rst -.. include:: 5_OED_Geography_and_Perils.rst -.. include:: 6_OED_Financial_Details_Primary.rst -.. include:: 7_OED_Financial_Details_Policy_Conditions.rst -.. include:: 8_OED_Reinsurance.rst - - - diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..b22a55e9 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,6 @@ +build/ +source/reference/_generated/ +**/__pycache__/ +.jupyter_cache/ +jupyter_execute/ +.DS_Store diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..11797053 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,13 @@ +# Minimal Sphinx makefile for the ORD reference site +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/_ext/gen_oed_reference.py b/docs/source/_ext/gen_oed_reference.py new file mode 100644 index 00000000..9c0a6141 --- /dev/null +++ b/docs/source/_ext/gen_oed_reference.py @@ -0,0 +1,198 @@ +"""Generate OED reference pages from ``oed.json`` (single source of truth). + +The OED standard is defined by ``oed.json`` at the repo root — the same machine-readable +spec that ods-tools consumes. Rather than hand-maintain reference tables, this extension +reads ``oed.json`` at build time and writes MyST Markdown into ``reference/_generated/`` +which the reference pages include. Edit ``oed.json`` (and its source CSVs), not the +generated Markdown. + +Runs on the Sphinx ``config-inited`` event; also runnable standalone for quick checks. +""" +import csv +import json +import os + +HERE = os.path.dirname(os.path.abspath(__file__)) +REPO_ROOT = os.path.abspath(os.path.join(HERE, os.pardir, os.pardir, os.pardir)) +OED_JSON = os.path.join(REPO_ROOT, "oed.json") +AREA_CSV = os.path.join(REPO_ROOT, "OpenExposureData", "AreaCodeValues.csv") +OUT_DIR = os.path.join(HERE, os.pardir, "reference", "_generated") + +# input-file groups, in exposure-modelling order +FILE_ORDER = [("Loc", "Location"), ("Acc", "Account"), + ("ReinsInfo", "Reinsurance Info"), ("ReinsScope", "Reinsurance Scope")] + +# A field's status varies by line of business, so all four columns are rendered: for the great +# majority of fields they do not agree, and a single column cannot say which one it is showing. +# Column names are those of OpenExposureData/OEDInputFields.csv. +STATUS_COLUMNS = [("Property", "Property field status"), + ("Cyber", "Cyber field status"), + ("Liability", "Liability field status"), + ("Marine Cargo", "Marine Cargo field status")] + + +def _cell(text): + return str(text).replace("|", "\\|").replace("\n", " ").replace("\r", " ").strip() + + +def _pipe_table(columns, rows): + out = ["| " + " | ".join(columns) + " |", + "| " + " | ".join(["---"] * len(columns)) + " |"] + for row in rows: + out.append("| " + " | ".join(_cell(c) for c in row) + " |") + return "\n".join(out) + + +def _write(name, text): + os.makedirs(OUT_DIR, exist_ok=True) + with open(os.path.join(OUT_DIR, name), "w", encoding="utf-8") as fh: + fh.write(text + "\n") + + +def generate_fields(oed): + """input_fields -> field reference, grouped by input file, with a status per line of business.""" + fields = oed.get("input_fields") + if not fields: + raise ValueError( + f"{OED_JSON} has no 'input_fields' — it is incomplete or was written by an " + "incompatible utils/gen-json.py. Delete it and rebuild." + ) + parts = [""] + total = 0 + for key, title in FILE_ORDER: + recs = fields.get(key) + if not recs: + continue + parts.append(f"\n## {title} (`{key}`)\n") + rows = [] + for rec in recs.values(): + rows.append([ + rec.get("Input Field Name", ""), + rec.get("Type & Description", ""), + rec.get("Data Type", ""), + *(rec.get(col, "") for _, col in STATUS_COLUMNS), + rec.get("Default", ""), + ]) + total += 1 + parts.append(_pipe_table( + ["Field", "Description", "Data type", + *(head for head, _ in STATUS_COLUMNS), "Default"], rows)) + _write("oed_fields.md", "\n".join(parts)) + return total + + +def generate_values(oed): + """Coded value lists -> code reference tables.""" + parts = [""] + total = 0 + + # perils: nested under 'info' + perils = oed.get("perils", {}).get("info", {}) + if perils: + parts.append("\n## Perils\n") + rows = [[code, r.get("DB table PerilCode", ""), r.get("Peril Description", ""), + r.get("Grouped PerilCode", "")] for code, r in perils.items()] + parts.append(_pipe_table(["Code", "PerilCode", "Description", "Grouped"], rows)) + total += len(rows) + + def simple(key, title, cols): + nonlocal total + v = oed.get(key) + if not isinstance(v, dict): + return + parts.append(f"\n## {title}\n") + rows = [[code] + [rec.get(c, "") for _, c in cols] for code, rec in v.items()] + parts.append(_pipe_table(["Code"] + [h for h, _ in cols], rows)) + total += len(rows) + + simple("occupancy", "Occupancy codes", + [("Name", "Name"), ("Description", "Description"), ("Broad Category", "Broad Category")]) + simple("construction", "Construction codes", + [("Name", "Name"), ("Description", "Description"), ("Broad Category", "Broad Category")]) + simple("country", "Country codes", [("Name", "Name")]) + simple("CoverageValues", "Coverage types", + [("CoverageID", "CoverageID"), ("Description", "Description"), ("Type", "Type")]) + _write("oed_values.md", "\n".join(parts)) + return total + + +def generate_areas(oed): + """AreaCodeValues.csv -> one collapsible table of area codes per country. + + Read from the CSV rather than ``oed.json``: the JSON's ``area`` entry keeps only the codes + (``{"AT": ["101", "102", ...]}``) and drops the area names and resolutions, which are the + part a reader actually needs. There are ~1500 codes across 48 countries, far too many for a + flat table, so each country gets a collapsed ``dropdown``. + + Args: + oed (dict): The parsed spec, used only to label countries with their names. + + Returns: + int: Number of area codes written. + """ + with open(AREA_CSV, encoding="utf-8-sig", newline="") as fh: + rows = list(csv.DictReader(fh)) + + country_names = {code: rec.get("Name", "") for code, rec in (oed.get("country") or {}).items()} + by_country = {} + for r in rows: + by_country.setdefault(r["CountryCode"], []).append(r) + + parts = [""] + total = 0 + for code in sorted(by_country): + recs = by_country[code] + name = country_names.get(code, "") + label = f"{code} — {name}" if name else code + parts.append(f"\n:::{{dropdown}} {label} ({len(recs)} codes)\n") + parts.append(_pipe_table( + ["AreaCode", "AreaName", "Resolution"], + [[r["AreaCode"], r["AreaName"], r["Resolution"]] for r in recs])) + parts.append("\n:::\n") + total += len(recs) + _write("oed_areas.md", "\n".join(parts)) + return total + + +def _build_oed_json(): + """Rebuild ``oed.json`` from the spec CSVs. + + ``oed.json`` is a generated artifact (``utils/gen-json.py`` builds it from + ``OpenExposureData/*.csv``) and is not committed, so the docs build has to produce it to be + self-sufficient in CI. It is rebuilt on every build rather than only when missing: skipping + the rebuild would serve the tables from whatever ``oed.json`` happened to be lying around, + so editing a field description and rebuilding locally would silently show the old text. The + generator takes well under a second, which is not worth a staleness check. + + Raises: + subprocess.CalledProcessError: If the spec CSVs cannot be converted. + """ + import subprocess + import sys + gen = os.path.join(REPO_ROOT, "utils", "gen-json.py") + subprocess.run([sys.executable, gen, "--output-path", OED_JSON], cwd=REPO_ROOT, check=True) + + +def run(app=None, config=None): + _build_oed_json() + with open(OED_JSON, encoding="utf-8") as fh: + oed = json.load(fh) + n_fields = generate_fields(oed) + n_values = generate_values(oed) + n_areas = generate_areas(oed) + msg = (f"[gen_oed_reference] wrote {n_fields} fields, {n_values} coded values, " + f"{n_areas} area codes -> reference/_generated/") + if app is not None: + from sphinx.util import logging + logging.getLogger(__name__).info(msg) + else: + print(msg) + + +def setup(app): + app.connect("config-inited", run) + return {"parallel_read_safe": True, "parallel_write_safe": True} + + +if __name__ == "__main__": + run() diff --git a/docs/source/_static/OASIS_LMF_COLOUR.png b/docs/source/_static/OASIS_LMF_COLOUR.png new file mode 100644 index 00000000..eac8dc49 Binary files /dev/null and b/docs/source/_static/OASIS_LMF_COLOUR.png differ diff --git a/docs/source/_static/OASIS_LMF_WHITE.png b/docs/source/_static/OASIS_LMF_WHITE.png new file mode 100644 index 00000000..8aec5a7a Binary files /dev/null and b/docs/source/_static/OASIS_LMF_WHITE.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..71525338 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,77 @@ +"""Sphinx configuration for the Open Exposure Data (OED) standard reference site. + +The field and coded-value reference is generated at build time from ``oed.json`` by the +local ``gen_oed_reference`` extension (single source of truth). Theme and MyST setup mirror +the other OasisLMF documentation sites for a consistent aggregated site. +""" +import datetime +import os +import sys + +sys.path.insert(0, os.path.abspath("_ext")) + +project = "Open Exposure Data (OED)" +author = "Oasis LMF" +copyright = f"{datetime.date.today().year} Oasis LMF" + +extensions = [ + "myst_parser", + "sphinx_design", + "sphinx_copybutton", + "gen_oed_reference", # build-time reference generation from oed.json +] + +source_suffix = {".rst": "restructuredtext", ".md": "markdown"} +master_doc = "index" +language = "en" +# _generated/*.md are include-only fragments, not standalone documents +exclude_patterns = ["reference/_generated/**"] + +myst_enable_extensions = ["colon_fence", "deflist", "substitution", "tasklist"] +myst_heading_anchors = 6 + +html_theme = "furo" +html_title = "Open Exposure Data (OED)" +html_static_path = ["_static"] if os.path.isdir(os.path.join(os.path.dirname(__file__), "_static")) else [] + + +# -- Cross-component links (intersphinx, aggregated site) -------------------- +# The GenerateDocs orchestrator sets OASIS_INTERSPHINX_MAP (JSON) to point cross-references at +# the other components' built inventories; standalone builds add nothing. Use explicit roles, +# e.g. {external+ord:doc}`reference/tables` or :external+oed:ref:`some-label`. +import json as _ix_json +import os as _ix_os +if "sphinx.ext.intersphinx" not in extensions: + extensions = list(extensions) + ["sphinx.ext.intersphinx"] +try: + intersphinx_mapping +except NameError: + intersphinx_mapping = {} +intersphinx_mapping.update({ + _k: (_v[0], _v[1]) + for _k, _v in _ix_json.loads(_ix_os.environ.get("OASIS_INTERSPHINX_MAP") or "{}").items() +}) +# -- Oasis shared branding (logo, palette, GitHub footer) ------------------- +if globals().get("html_theme") == "furo": + if "_static" not in (globals().get("html_static_path") or []): + html_static_path = list(globals().get("html_static_path") or []) + ["_static"] + try: + html_theme_options + except NameError: + html_theme_options = {} + html_theme_options.setdefault("light_logo", "OASIS_LMF_COLOUR.png") + html_theme_options.setdefault("dark_logo", "OASIS_LMF_WHITE.png") + _lcv = html_theme_options.setdefault("light_css_variables", {}) + _lcv.setdefault("color-brand-primary", "#862633") + _lcv.setdefault("color-brand-content", "#d22630") + _lcv.setdefault("font-stack", "Raleway, sans-serif") + _dcv = html_theme_options.setdefault("dark_css_variables", {}) + _dcv.setdefault("color-brand-primary", "#e2919b") + _dcv.setdefault("color-brand-content", "#ef8b93") + # GitHub link — Furo's conventional spot is the footer icons (bottom of every page) + html_theme_options.setdefault("footer_icons", [{ + "name": "GitHub", "url": "https://github.com/OasisLMF", "class": "", + "html": '', + }]) + if "https://fonts.googleapis.com/css?family=Raleway" not in (globals().get("html_css_files") or []): + html_css_files = list(globals().get("html_css_files") or []) + ["https://fonts.googleapis.com/css?family=Raleway"] diff --git a/Docs/4_OED_Asset_Related_Details.rst b/docs/source/explanation/asset-details.rst similarity index 100% rename from Docs/4_OED_Asset_Related_Details.rst rename to docs/source/explanation/asset-details.rst diff --git a/docs/source/explanation/classes-of-business.md b/docs/source/explanation/classes-of-business.md new file mode 100644 index 00000000..89b77488 --- /dev/null +++ b/docs/source/explanation/classes-of-business.md @@ -0,0 +1,33 @@ +# Classes of business + +OED began as a property standard. Since **v4.0.0** it is a single integrated specification +covering four classes of business, rather than separate schemas per class: + +Property +: The original and most fully developed class. The chapters in this section — import format, + asset details, geography and perils, financial terms and reinsurance — describe property + business unless they say otherwise. + +Cyber +: Released as a separate schema in February 2023 and folded into the main schema at v4.0.0. + See {doc}`cyber`. + +Liability +: Released as a separate schema in April 2022 and folded into the main schema at v4.0.0. + See {doc}`liability`. + +Marine Cargo +: Integrated into the main schema at v4.0.0. It follows the same four-file structure as + property. There is no separate background document for marine cargo. + +A field's requirement level differs by class, and the {doc}`field reference <../reference/fields>` +gives all four statuses per field — a field required for property may be `n/a` for cyber, and +vice versa. + +```{toctree} +:maxdepth: 1 +:hidden: + +cyber +liability +``` diff --git a/docs/source/explanation/cyber.md b/docs/source/explanation/cyber.md new file mode 100644 index 00000000..c02dbdfc --- /dev/null +++ b/docs/source/explanation/cyber.md @@ -0,0 +1,101 @@ +# OED Cyber + +## Introduction + +Growing demand over the past five years led to the release of the first cyber exposure data +schema in 2022 as part of the Open Exposure Data standard. It soon became clear that a single, +unified OED schema for multiple business classes would be more efficient than separate schemas. + +OED v4.0.0 is the first version which brings together the data standards for multiple exposure +classes — property, cyber, liability and marine cargo — into a single integrated specification. +It incorporates all fields from the original cyber schema, with some field names updated for +better alignment with property and the main schema. + +Please refer to the +[release notes for OED v4](https://github.com/OasisLMF/ODS_OpenExposureData/releases), which +include all updates. More general information can also be found on the +[ODS webpage](https://oasislmf.org/open-data-standards). + +## Contributors + +The cyber data standard v1 was developed through the collaboration of a working group throughout +2022, made up of participants from the following companies. Their time and effort is hugely +appreciated. + +- Allianz +- Aon +- Axis Capital +- CyberAcuView +- Gallagher Re +- Guidewire Cyence +- Guy Carpenter +- KOVRR +- Oasis LMF (ODS curator/secretariat) +- RenaissanceRe +- Richard DeKorte (Cyber Security Independent) +- Moody's RMS +- Sompo International +- Swiss Re +- Waratah Analytics +- Zurich Insurance + +## Rationale + +The initial data schema was primarily intended to ensure a degree of consistency in policy-level +data capture and to enable efficient sharing of select data fields across the industry. Other +than the benefit of reduced frictional cost, wide-spread adoption of the schema should enable +portfolio managers to implement granular, accurate and robust exposure management procedures. +This can, in turn, enable sophisticated risk accumulation and/or cyber modelling use cases. + +The cyber specific data fields are highlighted in the `Cyber field status` column of +`OEDInputFields.csv`, where the fields can be filtered on `R` for required fields, `O` for +optional and `CR` for conditionally required. That column is rendered per field in the +{doc}`field reference <../reference/fields>`. + +The cyber specific coverage codes are included in `CoverageValues.csv` and prefixed by `PolDed` +for sub-deductibles and `PolLimit` for sub-limits. + +## Considerations + +1. The aim of this schema is to promote consistency and efficiency of the transfer of cyber data + around the marketplace. As the focus of this schema is to accommodate key requirements for + multiple uses, this is not considered exhaustive and it is expected to develop and evolve over + time. The user is not expected to populate all fields and it should be treated as a guide. + +2. ODS encourages the capture of company identifier information but does not endorse any one + provider of this data. It is the responsibility of the user to ensure that no contractual + agreements with third parties are breached in the use of this schema or the transfer of + licensed data such as DUNS or LEI company identifiers. + +3. **Technographic data.** Opinions around the capture of technographic data were mixed during + the development of the original schema. Most suggested they should be considered + "aspirational" at this stage and should be the focus for further developments. The main reason + for that thinking is that capturing this data accurately to reflect how and where these + providers are used in a complex business is not trivial. Questions to consider, for example, + are "is the cloud/email provider the same for all servers and systems within a company?" or + "do all devices/systems use the same OS?". + + However, reinsurers consider that even capturing the basic data would provide value, + especially for accumulation analytics. Therefore, it was decided that some basic fields should + be included but populated at the discretion of the user. Users should consider the vendors of + their primary or main systems and servers, as captured in `OSVendor` (operating system), + `CloudVendor` (cloud provider), `CRMVendor` (customer relationship management provider), + `PatchPolicy` (cadence of patches for the main systems) and `BackUpFreq` (cadence of backups + for the main systems). + +4. The user is responsible for populating the data fields in this schema. No fields will be + linked to any external database (for example for an industry scheme or code). + +5. All cyber exposure fields are captured in the account (`acc`) file. There is no need for a + location file, as the data standard does not currently require the capture of physical asset + data with geographical locators — although there is nothing to preclude this from being + developed going forward. + +Any feedback or suggestions should be sent as an issue in the +[GitHub repository](https://github.com/OasisLMF/ODS_OpenExposureData/issues). + +## Governance + +A cyber steering committee (CSC) will be set up once enough market adoption has occurred and +developments to this need steering. This will act as a sub-committee, and a member of this CSC +will report into the main ODS Steer Co. diff --git a/Docs/7_OED_Financial_Details_Policy_Conditions.rst b/docs/source/explanation/financial-policy-conditions.rst similarity index 100% rename from Docs/7_OED_Financial_Details_Policy_Conditions.rst rename to docs/source/explanation/financial-policy-conditions.rst diff --git a/Docs/6_OED_Financial_Details_Primary.rst b/docs/source/explanation/financial-primary.rst similarity index 100% rename from Docs/6_OED_Financial_Details_Primary.rst rename to docs/source/explanation/financial-primary.rst diff --git a/Docs/5_OED_Geography_and_Perils.rst b/docs/source/explanation/geography-perils.rst similarity index 97% rename from Docs/5_OED_Geography_and_Perils.rst rename to docs/source/explanation/geography-perils.rst index 7fe2a217..9ca7c758 100644 --- a/Docs/5_OED_Geography_and_Perils.rst +++ b/docs/source/explanation/geography-perils.rst @@ -55,7 +55,7 @@ The OED format caters for a wide variety of models from different model develope For example, a model developer may want to split each country up into four equal areas ‘A’, ‘B’, ‘C’, ‘D’. In this case they would define a new GeogScheme code e.g. ‘QUAD’. They would communicate to users of their model that they must specify GeogName values ‘A’, ‘B’, ‘C’ or ‘D’ for their new ‘QUAD’ GeogScheme. The model user would then populate one of the GeogScheme / GeogName pairs with ‘QUAD’ and ‘A’, ‘B’, ‘C’ or ‘D’ respectively. This provides a large amount of flexibility to cope with different user and model developer requirements. -GeogScheme codes are up to five characters (no special characters). The latest codes can be found in the Open Exposure Data Spec spreadsheet on the OED GitHub repository in https://github.com/OasisLMF/OpenDataStandards/tree/master/OpenExposureData/Docs +GeogScheme codes are up to five characters (no special characters). The current coded values are listed in the :doc:`coded values reference <../reference/values>`, including the per-country area codes. Users can also specify their own schemes (e.g. for reporting purposes). The only requirement here is that any user defined scheme codes **must start with ‘X’** in order to avoid a potential code clash with future model developer schemes. diff --git a/docs/source/explanation/images/Hierarchy.png b/docs/source/explanation/images/Hierarchy.png new file mode 100644 index 00000000..61dd4663 Binary files /dev/null and b/docs/source/explanation/images/Hierarchy.png differ diff --git a/docs/source/explanation/images/ODS_Liability_Taxonomy_v1.png b/docs/source/explanation/images/ODS_Liability_Taxonomy_v1.png new file mode 100644 index 00000000..9d125fb5 Binary files /dev/null and b/docs/source/explanation/images/ODS_Liability_Taxonomy_v1.png differ diff --git a/Docs/3_OED_Import_Format.rst b/docs/source/explanation/import-format.rst similarity index 97% rename from Docs/3_OED_Import_Format.rst rename to docs/source/explanation/import-format.rst index 684495ec..9bf43b06 100644 --- a/Docs/3_OED_Import_Format.rst +++ b/docs/source/explanation/import-format.rst @@ -8,9 +8,9 @@ The import format for OED is defined by four .csv files: • Reinsurance info (RIinfo) • Reinsurance scope (RIscope) -The fields in each file and their corresponding data type are described in the ‘OED Input Fields’ tab in the OED Data Spec spreadsheet found here: - -https://github.com/OasisLMF/OpenDataStandards/tree/master/OpenExposureData/Docs +The fields in each file, their data types, defaults and requirement level per line of business +are listed in the :doc:`field reference <../reference/fields>`, generated from the specification +itself. Location ('loc') Import File diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md new file mode 100644 index 00000000..43f42f63 --- /dev/null +++ b/docs/source/explanation/index.md @@ -0,0 +1,90 @@ +# Explanation + +Background on the OED standard — what it is, its file structure and the exposure hierarchy. +Detailed chapters (import format, asset details, geography & perils, financial terms and +reinsurance) are migrated from the standard's specification documents. + +## The four input files + +OED comprises four input files, designed to let users enter data in a manageable way without +having to understand the relationships between many underlying tables: + +- **Location (`Loc`)** — the exposed locations and their coverages, characteristics and + primary financial terms. +- **Account (`Acc`)** — accounts and policies, including policy-level financial terms and + special conditions. +- **Reinsurance Info (`ReinsInfo`)** — the reinsurance programme definitions. +- **Reinsurance Scope (`ReinsScope`)** — what each reinsurance contract applies to. + +This trades some duplication for practicality. The full field lists are in the +{doc}`field reference <../reference/fields>`. + +## The exposure hierarchy + +OED follows an organisational and financial hierarchy familiar to catastrophe-model users: + +Coverage +: The lowest level — the specific type of cover: **Buildings**, **Other** (e.g. appurtenant + structures or motor), **Contents**, and **Business Interruption** (time element). Primary + financial terms can attach at coverage level, across property damage (PD = Buildings + + Other + Contents), or across all coverages. + +Location +: A site — a group of coverages at one place. Primary financial terms and facultative + reinsurance can attach here. A single location record can represent several buildings + (`NumberOfBuildings`), and related locations can be linked (`LocGroup`). + +Policy +: A financial structure applying to a set of locations. Multiple policies can exist under + the same account and apply to the same locations (e.g. insurance layers). Within a policy, + a **special condition** applies sub-limits/sub-deductibles to a subset of locations. + Reinsurance can attach at policy level. + +Account +: Groups policies and locations — you cannot have a policy without a location, or a location + without a policy. Primary and reinsurance terms can attach here. + +Account group +: A grouping of accounts for reporting purposes, defined through `AccGroup` (for example, a + binder). No financial structures attach at this level. + +Portfolio +: A number of accounts, defined through `PortNumber`. Primary terms cannot attach at portfolio + level, but reinsurance structures can. + +Which levels financial terms attach to: + +| Hierarchy level | Defined by | Primary terms? | Reinsurance terms? | +| --- | --- | --- | --- | +| Location coverage | Buildings, contents, business interruption, other | Yes | No | +| Location | `LocNumber`; field names start with `Loc` | Yes | Yes | +| Location group | `LocGroup` | No | Yes | +| Policy | `PolNumber`; within it, special conditions (`Cond`) apply first, then standard policy conditions (`Pol`), then layers (`Layer`) | Yes | Yes | +| Account | `AccNumber`; field names start with `Acc` | Yes | Yes | +| Account group | `AccGroup` | No | No | +| Portfolio | `PortNumber` | No | Yes | + +Because multiple policies can apply to the same locations, take care when summing exposure or +ground-up loss at policy level, to avoid overcounting. + +## Coded values + +Many OED fields draw on controlled vocabularies (perils, occupancy, construction, country, +coverage). Those allowed values are in the {doc}`coded values reference <../reference/values>`. + +## Detailed chapters + +The full specification narrative, migrated from the OED standard documents: + +```{toctree} +:maxdepth: 1 + +classes-of-business +rationale +import-format +asset-details +geography-perils +financial-primary +financial-policy-conditions +reinsurance +``` diff --git a/docs/source/explanation/liability.md b/docs/source/explanation/liability.md new file mode 100644 index 00000000..c473eb49 --- /dev/null +++ b/docs/source/explanation/liability.md @@ -0,0 +1,76 @@ +# OED Liability + +## Introduction + +The first version of the OED schema for liability data was released in April 2022 following the +efforts of a small market working group. The +[release video](https://youtu.be/WW9N4mlNtb8) can be found on the Oasis YouTube channel. This +was the first data schema available to the market to promote the use of standardised liability +data for the re/insurance industry. + +OED v4.0.0 is the first major release which brings together the data standards for multiple +exposure classes — property, cyber, liability and marine cargo — into a single integrated +specification. It incorporates all fields from the original liability schema (v1), with some +field names updated for better alignment with property and the main schema. + +## Rationale + +This data standard is primarily intended to ensure a degree of consistency in policy-level data +capture and to enable efficient sharing of select data fields across the industry. Other than the +benefit of reduced frictional cost, wide-spread adoption of the schema should enable portfolio +managers to implement granular, accurate and robust exposure management procedures. This can, in +turn, enable sophisticated risk accumulation and/or liability modelling use cases. + +The approach for the original schema was to make it as succinct and prescriptive as possible, to +ensure consistency of the data formats and to keep any ambiguity to a minimum. + +The original taxonomy created for the liability data standard, below, is still intended to be +internationally applicable and implemented across UK, European and US markets. Increased market +adoption of this schema will heavily rely on it being used by the key players in the data +transfer process, specifically the brokers and reinsurers. + +At a high level, the approach taken has aligned to the EIOPA definition of liability classes +(classes 10–13 in their non-life risk classification convention), with some subdivision of the +broad Other category. The benefit of linking the scope to the EIOPA definition is primarily to +ensure exhaustiveness. + +*Motor Liability*, *Aviation Liability*, *Marine Liability* and *Personal Liability* are all +excluded from the data standard. This is partly motivated by concerns around the sharing of +personal information, but also the idea that liability exposure accumulation analysis often +starts at company or industry level. Accident & Health, which is not considered a liability class +under the EIOPA convention, could be omitted for similar reasons, with a possible fringe case for +inclusion being the Workers' Compensation class of business. + +It is worth noting that in designing the taxonomy, it was decided to consider attributes of the +insured, such as industry/trade/profession, separately from class/coverage. For example, medical +practitioners, financial institutions, architects, engineers and lawyers can all be considered as +insured attributes to be captured for the *Professional Liability* coverage class. This should +lend itself to a more concise and consistent data schema. + +## Taxonomy + +Below is the proposed class-based taxonomy, for the purpose of identifying the insurance policy +coverages that should be in or out of scope of the first version of the standard. + +```{image} images/ODS_Liability_Taxonomy_v1.png +:alt: ODS liability taxonomy, version 1 +:width: 100% +``` + +```{note} +What is considered 'Other', EIOPA has termed 'general liability'. To avoid confusion, it is +intended to avoid this term as far as possible. In the US, general liability is better described +as either Commercial or Personal Liability, whereas in the UK it is referred to as either Public +or Employers Liability. +``` + +## Next steps + +As interest and adoption increases, the likely next steps for this standard will be to develop +the schema to include more required data fields specific to each sub-class, through collaboration +and ongoing feedback. This work will also include expanding the scope of the taxonomy to those +classes currently not supported and driven by demand, such as motor and aviation. + +Any feedback and suggestions for updates should be submitted via the +[issues here](https://github.com/OasisLMF/OpenDataStandards/issues), which will then be reviewed +by the Technical Working Group (TWG). diff --git a/Docs/1_OED_Rationale_and_Abbreviations.rst b/docs/source/explanation/rationale.rst similarity index 100% rename from Docs/1_OED_Rationale_and_Abbreviations.rst rename to docs/source/explanation/rationale.rst diff --git a/Docs/8_OED_Reinsurance.rst b/docs/source/explanation/reinsurance.rst similarity index 100% rename from Docs/8_OED_Reinsurance.rst rename to docs/source/explanation/reinsurance.rst diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..c4674125 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,39 @@ +# Open Exposure Data (OED) + +**OED** is the open standard for catastrophe-model **exposure data** — a common format for +describing locations, accounts, policy terms and reinsurance, so that exposure can be moved +between models and tools without bespoke conversion. It is the exposure counterpart to +[ORD](https://github.com/OasisLMF/ODS_OpenResultsData) (results data), together forming the +Open Data Standards (ODS) maintained by the ODS Steering Committee. + +This site is the reference for the standard. The field and coded-value definitions are +generated directly from the authoritative `oed.json` in this repository, so they always match +the released specification. + +::::{grid} 1 1 2 2 +:gutter: 3 + +:::{grid-item-card} 📖 Explanation +:link: explanation/index +:link-type: doc + +What OED is, the file structure (Location / Account / Reinsurance), the exposure hierarchy, +and how financial terms and perils are represented. +::: + +:::{grid-item-card} 📋 Reference +:link: reference/index +:link-type: doc + +The generated field reference for every input file, plus the coded value lists (perils, +occupancy, construction, country, coverage). +::: +:::: + +```{toctree} +:hidden: +:maxdepth: 2 + +explanation/index +reference/index +``` diff --git a/docs/source/reference/fields.md b/docs/source/reference/fields.md new file mode 100644 index 00000000..aa571a1e --- /dev/null +++ b/docs/source/reference/fields.md @@ -0,0 +1,22 @@ +# OED fields + +The input fields for each OED file, grouped by file. A field's requirement level depends on the +line of business, so there is one status column per line — **Property**, **Cyber**, +**Liability** and **Marine Cargo** — each taking one of: + +```{list-table} +:header-rows: 0 +:widths: 10 90 + +* - `R` + - Required +* - `O` + - Optional +* - `CR` + - Conditionally required (required in certain circumstances — see the field description) +* - `n/a` + - Not applicable to this file / line of business +``` + +```{include} _generated/oed_fields.md +``` diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md new file mode 100644 index 00000000..49c7e17a --- /dev/null +++ b/docs/source/reference/index.md @@ -0,0 +1,11 @@ +# Reference + +The authoritative OED schema. These pages are generated at build time from `oed.json` in +this repository — edit the spec (and its source CSVs), not the generated tables. + +```{toctree} +:maxdepth: 2 + +fields +values +``` diff --git a/docs/source/reference/values.md b/docs/source/reference/values.md new file mode 100644 index 00000000..a13d057b --- /dev/null +++ b/docs/source/reference/values.md @@ -0,0 +1,17 @@ +# Coded values + +The controlled vocabularies used by OED coded fields — perils, occupancy, construction, +country, coverage and area. These are the allowed values for the corresponding fields in the +{doc}`field reference `. + +```{include} _generated/oed_values.md +``` + +## Area codes + +The values for `AreaCode` — typically the largest sub-division within a country, such as a state +or province. Around 1,500 codes span 48 countries, so each country is collapsed; open one to see +its codes, names and the resolution they represent. + +```{include} _generated/oed_areas.md +```