fd-open-data-protocol 0.2.0__tar.gz → 0.3.0__tar.gz

{fd_open_data_protocol-0.2.0 → fd_open_data_protocol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fd-open-data-protocol
-Version: 0.2.0
+Version: 0.3.0
 Summary: The open-data datasource protocol: a manifest contract a datasource exposes to be ingested by fd-open-data-mcp (or any consumer).
 Author: FindDataOfficial
 License: MIT
@@ -99,7 +99,7 @@ my-source = "my_pkg.catalog:CATALOG"
 - **`DatasourceManifest`**: name, label, source_url, scanner_mode, ranking_seed, functions[], concepts[], entities[], entity_definitions[], relationships[], fetch.
 - **`FunctionSpec`**: command, category, description, parameters[], columns[], frequency, verified.
 - **`ColumnSpec`**: name, type, description, meaning, semantic_type, `frequency` + `datasource` (column-level).
-- **`ConceptHint`**: column, concept, `entity_type`, `measure`, unit, frequency, confidence.
+- **`ConceptHint`**: column, concept, `entity_type`, `measure`, unit, frequency, confidence, `concept_family` (optional).
 - **`EntitySpec`**: entity_type, coverage ("universe"|"explicit"), codes[] (for explicit coverage).
 - **`Entity`**: entity_type, code, name_en, name_zh, metadata{}, relationships[].
 - **`EntityRelationship`**: target_entity_type, target_code, relation_type, confidence, metadata{}.
@@ -149,9 +149,33 @@ entity_definitions:
 
 When included, entities are registered in the ontology database during `register_datasource()`.
 
+#### Reserved metadata key: `external_ids`
+
+An entity definition may anchor itself in an external entity graph under the
+reserved metadata key `external_ids`. Registration persists each entry as a
+per-source identifier, so consumers can resolve the external id back to the
+local entity.
+
+```yaml
+entity_definitions:
+  - entity_type: country
+    code: CN
+    name_en: China
+    metadata:
+      external_ids:
+        wikidata: Q148          # Wikidata QID (Q followed by digits)
+        datacommons: country/CHN  # Data Commons DCID
+```
+
+Supported anchor sources are `wikidata` (QID, validated as `Q<digits>`) and
+`datacommons` (non-empty DCID). A malformed or unknown anchor is logged and
+skipped — it never fails registration.
+
 ### Canonical Entity Types
 
-All `entity_type` values must be from this vocabulary:
+The entity-type vocabulary is defined by
+[`fd_open_data_protocol/vocabulary/entity_types.yaml`](fd_open_data_protocol/vocabulary/entity_types.yaml)
+(14 types) and is the authority for manifest validation:
 
 | Type | Description | Example IDs |
 |------|-------------|-------------|
@@ -165,7 +189,69 @@ All `entity_type` values must be from this vocabulary:
 | `crypto` | Cryptocurrencies | btc, eth |
 | `organization` | General orgs | org_code |
 | `industry` | Classifications | shenwan_1_01, gics_10 |
+| `exchange` | Exchanges / venues | XNYS, XNAS, SSE |
 | `company` | Public companies | AAPL, TSLA |
+| `commodity` | Raw goods | steel, oil, grain |
+| `person` | Humans (fund managers) | person_code |
+
+## Semantic vocabulary
+
+The protocol ships the publishable semantic core of FindData as versioned YAML
+under [`fd_open_data_protocol/vocabulary/`](fd_open_data_protocol/vocabulary/):
+
+| File | Registry |
+|------|----------|
+| `entity_types.yaml` | entity types (the manifest vocabulary above) |
+| `concepts.yaml` | concept families + their seeded Variables |
+| `qualifiers.yaml` | qualifiers (nominal_current, real_constant, ppp, per_capita, growth, ...) |
+| `units.yaml` | units of measure (UN/CEFACT codes + ISO 4217 currencies) |
+| `relation_types.yaml` | entity relationship types |
+| `event_types.yaml` | event types (empty in this release) |
+| `crosswalks/*.yaml` | Variable ↔ external-vocabulary assertions |
+
+The vocabulary files ship as package data (`0.3.0`+), so `load_vocabulary()`
+works from an installed wheel with no checkout on disk.
+
+```python
+from fd_open_data_protocol.vocabulary import load_vocabulary, validate_vocabulary
+
+vocab = load_vocabulary()                    # shipped files
+vocab = load_vocabulary("/path/to/dir")      # or an explicit directory
+vocab.version                                # release version of the file set
+vocab.get("concept", "GDP").uri              # https://schema.finddata.tech/concept/GDP
+vocab.entity_type_ids()                      # the manifest entity-type vocabulary
+vocab.seeded_variables()                     # Variables a family declares
+errors = validate_vocabulary()               # [] when the file set is valid
+```
+
+Every entry carries a stable URI of the form
+`https://schema.finddata.tech/<kind>/<Id>`, where `<kind>` is one of
+`entity-type`, `concept`, `qualifier`, `unit`, `relation-type`, `event-type`.
+
+**Stability rules.** A URI is never reassigned to a different meaning and
+entries are never deleted. Retirement is expressed with a `superseded_by`
+pointer to the successor entry, which keeps the URI resolvable. The file set
+carries one release `version`, and the loader rejects a file set whose files
+disagree.
+
+## Concept families and Variables
+
+Concepts are two-level. A **concept family** (`fd:GDP`, `fd:Population`) is the
+small curated vocabulary from `concepts.yaml`; a **Variable** is the qualified
+combination `(code, entity_type, measure, unit, frequency)` — the identity a
+datasource actually binds columns to.
+
+A manifest concept hint may point at its family with the optional
+`concept_family` field, which the loader validates against `concepts.yaml`:
+
+```yaml
+concepts:
+  - {column: close, concept: price.close, entity_type: stock, unit: currency,
+     frequency: daily, concept_family: PriceClose}
+```
+
+Omitting it preserves the previous behaviour — no family validation occurs, and
+the consumer derives a family from the concept code.
 
 ## Manifest Declaration Requirement
 

{fd_open_data_protocol-0.2.0 → fd_open_data_protocol-0.3.0}/README.md

@@ -86,7 +86,7 @@ my-source = "my_pkg.catalog:CATALOG"
 - **`DatasourceManifest`**: name, label, source_url, scanner_mode, ranking_seed, functions[], concepts[], entities[], entity_definitions[], relationships[], fetch.
 - **`FunctionSpec`**: command, category, description, parameters[], columns[], frequency, verified.
 - **`ColumnSpec`**: name, type, description, meaning, semantic_type, `frequency` + `datasource` (column-level).
-- **`ConceptHint`**: column, concept, `entity_type`, `measure`, unit, frequency, confidence.
+- **`ConceptHint`**: column, concept, `entity_type`, `measure`, unit, frequency, confidence, `concept_family` (optional).
 - **`EntitySpec`**: entity_type, coverage ("universe"|"explicit"), codes[] (for explicit coverage).
 - **`Entity`**: entity_type, code, name_en, name_zh, metadata{}, relationships[].
 - **`EntityRelationship`**: target_entity_type, target_code, relation_type, confidence, metadata{}.
@@ -136,9 +136,33 @@ entity_definitions:
 
 When included, entities are registered in the ontology database during `register_datasource()`.
 
+#### Reserved metadata key: `external_ids`
+
+An entity definition may anchor itself in an external entity graph under the
+reserved metadata key `external_ids`. Registration persists each entry as a
+per-source identifier, so consumers can resolve the external id back to the
+local entity.
+
+```yaml
+entity_definitions:
+  - entity_type: country
+    code: CN
+    name_en: China
+    metadata:
+      external_ids:
+        wikidata: Q148          # Wikidata QID (Q followed by digits)
+        datacommons: country/CHN  # Data Commons DCID
+```
+
+Supported anchor sources are `wikidata` (QID, validated as `Q<digits>`) and
+`datacommons` (non-empty DCID). A malformed or unknown anchor is logged and
+skipped — it never fails registration.
+
 ### Canonical Entity Types
 
-All `entity_type` values must be from this vocabulary:
+The entity-type vocabulary is defined by
+[`fd_open_data_protocol/vocabulary/entity_types.yaml`](fd_open_data_protocol/vocabulary/entity_types.yaml)
+(14 types) and is the authority for manifest validation:
 
 | Type | Description | Example IDs |
 |------|-------------|-------------|
@@ -152,7 +176,69 @@ All `entity_type` values must be from this vocabulary:
 | `crypto` | Cryptocurrencies | btc, eth |
 | `organization` | General orgs | org_code |
 | `industry` | Classifications | shenwan_1_01, gics_10 |
+| `exchange` | Exchanges / venues | XNYS, XNAS, SSE |
 | `company` | Public companies | AAPL, TSLA |
+| `commodity` | Raw goods | steel, oil, grain |
+| `person` | Humans (fund managers) | person_code |
+
+## Semantic vocabulary
+
+The protocol ships the publishable semantic core of FindData as versioned YAML
+under [`fd_open_data_protocol/vocabulary/`](fd_open_data_protocol/vocabulary/):
+
+| File | Registry |
+|------|----------|
+| `entity_types.yaml` | entity types (the manifest vocabulary above) |
+| `concepts.yaml` | concept families + their seeded Variables |
+| `qualifiers.yaml` | qualifiers (nominal_current, real_constant, ppp, per_capita, growth, ...) |
+| `units.yaml` | units of measure (UN/CEFACT codes + ISO 4217 currencies) |
+| `relation_types.yaml` | entity relationship types |
+| `event_types.yaml` | event types (empty in this release) |
+| `crosswalks/*.yaml` | Variable ↔ external-vocabulary assertions |
+
+The vocabulary files ship as package data (`0.3.0`+), so `load_vocabulary()`
+works from an installed wheel with no checkout on disk.
+
+```python
+from fd_open_data_protocol.vocabulary import load_vocabulary, validate_vocabulary
+
+vocab = load_vocabulary()                    # shipped files
+vocab = load_vocabulary("/path/to/dir")      # or an explicit directory
+vocab.version                                # release version of the file set
+vocab.get("concept", "GDP").uri              # https://schema.finddata.tech/concept/GDP
+vocab.entity_type_ids()                      # the manifest entity-type vocabulary
+vocab.seeded_variables()                     # Variables a family declares
+errors = validate_vocabulary()               # [] when the file set is valid
+```
+
+Every entry carries a stable URI of the form
+`https://schema.finddata.tech/<kind>/<Id>`, where `<kind>` is one of
+`entity-type`, `concept`, `qualifier`, `unit`, `relation-type`, `event-type`.
+
+**Stability rules.** A URI is never reassigned to a different meaning and
+entries are never deleted. Retirement is expressed with a `superseded_by`
+pointer to the successor entry, which keeps the URI resolvable. The file set
+carries one release `version`, and the loader rejects a file set whose files
+disagree.
+
+## Concept families and Variables
+
+Concepts are two-level. A **concept family** (`fd:GDP`, `fd:Population`) is the
+small curated vocabulary from `concepts.yaml`; a **Variable** is the qualified
+combination `(code, entity_type, measure, unit, frequency)` — the identity a
+datasource actually binds columns to.
+
+A manifest concept hint may point at its family with the optional
+`concept_family` field, which the loader validates against `concepts.yaml`:
+
+```yaml
+concepts:
+  - {column: close, concept: price.close, entity_type: stock, unit: currency,
+     frequency: daily, concept_family: PriceClose}
+```
+
+Omitting it preserves the previous behaviour — no family validation occurs, and
+the consumer derives a family from the concept code.
 
 ## Manifest Declaration Requirement
 

{fd_open_data_protocol-0.2.0 → fd_open_data_protocol-0.3.0}/fd_open_data_protocol/__init__.py

@@ -5,4 +5,4 @@ concept hints + fetch reference) so that fd-open-data-mcp - or any consumer -
 can ingest it via ``register_datasource``. Ship one manifest file -> the
 datasource is added; no consumer-side wiring.
 """
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{fd_open_data_protocol-0.2.0 → fd_open_data_protocol-0.3.0}/fd_open_data_protocol/schema.py

@@ -10,26 +10,70 @@ entity metadata (names, attributes, relationships) in the ontology database.
 """
 from __future__ import annotations
 
-from typing import Any, Optional
+from functools import lru_cache
+from typing import Any, Iterable, Optional
 
 from pydantic import BaseModel, Field, field_validator
 
 
-# Canonical entity type vocabulary - all entity_type values must be in this set
-ENTITY_TYPE_VOCABULARY: tuple[str, ...] = (
-    "country",           # ISO codes (CN, US, JP)
-    "city",              # Municipalities (beijing, shanghai)
-    "stock",             # A-shares (600000.SH, 000001.SZ)
-    "fund",              # ETFs/funds (etf_code, fund_code)
-    "bond",              # Bonds (bond_code)
-    "index",             # Indices (SH000001, SZ399001)
-    "future",            # Futures (cu2412, rb2401)
-    "crypto",            # Cryptocurrencies (btc, eth)
-    "organization",      # General organizations
-    "industry",          # Industry classifications (shenwan_1_01, gics_10)
-    "exchange",          # Securities exchanges / market venues (XNYS, XNAS, XASE)
-    "company",           # Public companies with sector (AAPL, TSLA)
-)
+@lru_cache(maxsize=1)
+def _concept_family_ids() -> frozenset[str]:
+    """Concept family ids from the shipped vocabulary (loaded once per process)."""
+    from fd_open_data_protocol.vocabulary import load_vocabulary
+
+    return frozenset(load_vocabulary().ids("concept"))
+
+
+class _EntityTypeVocabulary:
+    """Lazy, file-sourced view of ``vocabulary/entity_types.yaml``.
+
+    Replaces the hardcoded tuple of entity types while keeping the public name
+    and the operations callers use (membership, iteration, ``len``, ``join``).
+    The file is read on first use, not at import time. An override can be
+    pinned for tests via :func:`set_entity_type_vocabulary`.
+    """
+
+    def __init__(self) -> None:
+        self._override: Optional[tuple[str, ...]] = None
+        self._cache: Optional[tuple[str, ...]] = None
+
+    def _values(self) -> tuple[str, ...]:
+        if self._override is not None:
+            return self._override
+        if self._cache is None:
+            from fd_open_data_protocol.vocabulary import load_vocabulary
+
+            self._cache = load_vocabulary().entity_type_ids()
+        return self._cache
+
+    def set(self, values: Optional[Iterable[str]] = None) -> None:
+        """Pin the vocabulary to ``values``, or reset to file-sourced when None."""
+        self._override = tuple(values) if values is not None else None
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._values()
+
+    def __iter__(self):
+        return iter(self._values())
+
+    def __len__(self) -> int:
+        return len(self._values())
+
+    def __getitem__(self, index):
+        return self._values()[index]
+
+    def __repr__(self) -> str:
+        return repr(self._values())
+
+
+# Canonical entity type vocabulary - all entity_type values must be in this set.
+# Sourced from the shipped vocabulary file; see fd_open_data_protocol.vocabulary.
+ENTITY_TYPE_VOCABULARY = _EntityTypeVocabulary()
+
+
+def set_entity_type_vocabulary(values: Optional[Iterable[str]] = None) -> None:
+    """Test escape hatch: pin the entity-type vocabulary, or reset to file-sourced."""
+    ENTITY_TYPE_VOCABULARY.set(values)
 
 
 class EntityRelationship(BaseModel):
@@ -156,6 +200,9 @@ class ConceptHint(BaseModel):
     unit: Optional[str] = None
     frequency: Optional[str] = None
     confidence: float = 0.9
+    # Optional reference to a concept family in vocabulary/concepts.yaml, tying
+    # this concept to the two-level semantic model. Omitted = no family check.
+    concept_family: Optional[str] = None
 
     @field_validator("entity_type")
     @classmethod
@@ -166,6 +213,18 @@ class ConceptHint(BaseModel):
             )
         return v
 
+    @field_validator("concept_family")
+    @classmethod
+    def validate_concept_family(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        if v not in _concept_family_ids():
+            raise ValueError(
+                f"Unknown concept family '{v}'. Must be one of: "
+                f"{', '.join(sorted(_concept_family_ids()))}"
+            )
+        return v
+
 
 class FetchRef(BaseModel):
     runner: Optional[str] = None   # built-in runner name
@@ -183,6 +242,15 @@ class EntitySpec(BaseModel):
     coverage: str = "universe"  # "universe" or "explicit"
     codes: Optional[list[str]] = None  # required if coverage="explicit"
 
+    @field_validator("entity_type")
+    @classmethod
+    def validate_entity_type(cls, v: str) -> str:
+        if v not in ENTITY_TYPE_VOCABULARY:
+            raise ValueError(
+                f"Invalid entity_type '{v}'. Must be one of: {', '.join(ENTITY_TYPE_VOCABULARY)}"
+            )
+        return v
+
 
 class RelationshipSpec(BaseModel):
     """Relationship resolution declaration.

fd_open_data_protocol-0.3.0/fd_open_data_protocol/vocabulary/concepts.yaml

@@ -0,0 +1,230 @@
+# FindData vocabulary — concept families.
+#
+# The first level of the two-level concept model. A *Concept family* is the
+# small, curated semantic vocabulary (`fd:GDP`, `fd:Population`, ...); a
+# *Variable* is the qualified five-tuple identity that lives in the MCP
+# ontology store `concepts` table and carries `concept_code` pointing back here.
+#
+# URIs: https://schema.finddata.tech/concept/<id>
+#
+# `variables:` blocks are the initial seed content — the five-tuple identities
+# `consume-concepts` materializes for that family. Families without a
+# `variables:` block are declarative only (derivation links to them by code).
+#
+# Entries are never deleted — retirement is expressed with `superseded_by`.
+version: "2026.09"
+kind: concept
+entries:
+  - id: GDP
+    label_en: Gross Domestic Product
+    label_zh: 国内生产总值
+    description: >-
+      The market value of all final goods and services produced within a
+      country's borders in a period. The qualified variants (nominal, real,
+      PPP, per-capita, growth) are distinct Variables of this family.
+    value_type: currency
+    unit_type: currency
+    dimensions: [nominal_current, real_constant, ppp, per_capita, per_capita_ppp, growth]
+    variables:
+      - {code: gdp, entity_type: country, measure: nominal_current,  unit: usd,           frequency: yearly}
+      - {code: gdp, entity_type: country, measure: real_constant,    unit: usd,           frequency: yearly}
+      - {code: gdp, entity_type: country, measure: growth,           unit: "%",           frequency: yearly}
+      - {code: gdp, entity_type: country, measure: per_capita,       unit: usd,           frequency: yearly}
+      - {code: gdp, entity_type: country, measure: per_capita_ppp,   unit: international, frequency: yearly}
+
+  - id: Population
+    label_en: Population
+    label_zh: 人口
+    description: >-
+      Total resident population of an entity at a point in time. Aligns with
+      Data Commons Count_Person and World Bank SP.POP.TOTL.
+    value_type: count
+    unit_type: count
+    dimensions: []
+    variables:
+      - {code: population.total, entity_type: country, measure: "", unit: persons, frequency: yearly}
+
+  - id: PriceClose
+    label_en: Closing Price
+    label_zh: 收盘价
+    description: >-
+      Price of the last trade in a session — the canonical closing quote for a
+      listed instrument.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: price.close, entity_type: stock, measure: "", unit: currency, frequency: daily}
+
+  - id: PriceOpen
+    label_en: Opening Price
+    label_zh: 开盘价
+    description: Price of the first trade in a session.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: price.open, entity_type: stock, measure: "", unit: currency, frequency: daily}
+
+  - id: PriceHigh
+    label_en: Session High Price
+    label_zh: 最高价
+    description: Highest traded price during a session.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: price.high, entity_type: stock, measure: "", unit: currency, frequency: daily}
+
+  - id: PriceLow
+    label_en: Session Low Price
+    label_zh: 最低价
+    description: Lowest traded price during a session.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: price.low, entity_type: stock, measure: "", unit: currency, frequency: daily}
+
+  - id: PriceVolume
+    label_en: Traded Volume
+    label_zh: 成交量
+    description: Number of units traded during a session.
+    value_type: count
+    unit_type: count
+    dimensions: []
+    variables:
+      - {code: price.volume, entity_type: stock, measure: "", unit: shares, frequency: daily}
+
+  - id: PriceAmount
+    label_en: Traded Turnover
+    label_zh: 成交额
+    description: Monetary value traded during a session.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: price.amount, entity_type: stock, measure: "", unit: currency, frequency: daily}
+
+  - id: NavUnit
+    label_en: Net Asset Value per Unit
+    label_zh: 单位净值
+    description: >-
+      Net asset value of one fund unit — the canonical daily price series for
+      funds and ETFs.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: nav.unit, entity_type: fund, measure: "", unit: currency, frequency: daily}
+
+  - id: Revenue
+    label_en: Revenue
+    label_zh: 营业收入
+    description: Operating revenue recognized in a reporting period.
+    value_type: currency
+    unit_type: currency
+    dimensions: [growth]
+    variables:
+      - {code: financials.revenue, entity_type: stock, measure: "", unit: currency, frequency: yearly}
+
+  - id: NetProfit
+    label_en: Net Profit
+    label_zh: 净利润
+    description: Profit attributable to the reporting entity after tax.
+    value_type: currency
+    unit_type: currency
+    dimensions: [growth]
+    variables:
+      - {code: financials.net_profit, entity_type: stock, measure: "", unit: currency, frequency: yearly}
+
+  - id: TotalAssets
+    label_en: Total Assets
+    label_zh: 资产总计
+    description: Carrying amount of all assets at the reporting date.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: financials.total_assets, entity_type: stock, measure: "", unit: currency, frequency: yearly}
+
+  - id: TotalLiabilities
+    label_en: Total Liabilities
+    label_zh: 负债合计
+    description: Carrying amount of all liabilities at the reporting date.
+    value_type: currency
+    unit_type: currency
+    dimensions: []
+    variables:
+      - {code: financials.total_liabilities, entity_type: stock, measure: "", unit: currency, frequency: yearly}
+
+  - id: Inflation
+    label_en: Inflation Rate
+    label_zh: 通货膨胀率
+    description: >-
+      Rate of change of a general price level, typically consumer prices.
+      Aligns with World Bank FP.CPI.TOTL.ZG.
+    value_type: ratio
+    unit_type: percent
+    dimensions: []
+    variables: []
+
+  - id: Unemployment
+    label_en: Unemployment Rate
+    label_zh: 失业率
+    description: >-
+      Share of the labour force that is without work and seeking it. Aligns
+      with World Bank SL.UEM.TOTL.ZS.
+    value_type: ratio
+    unit_type: percent
+    dimensions: []
+    variables: []
+
+  - id: LifeExpectancy
+    label_en: Life Expectancy
+    label_zh: 预期寿命
+    description: >-
+      Expected years of life at birth for a given population. Aligns with
+      World Bank SP.DYN.LE00.IN.
+    value_type: duration
+    unit_type: count
+    dimensions: []
+    variables: []
+
+  - id: CO2Emissions
+    label_en: CO2 Emissions
+    label_zh: 二氧化碳排放
+    description: >-
+      Carbon dioxide emissions from fuel combustion, total or per capita.
+      Aligns with World Bank EN.ATM.CO2E.KT and EN.ATM.CO2E.PC.
+    value_type: count
+    unit_type: count
+    dimensions: [per_capita]
+    variables: []
+
+  - id: DocTitle
+    label_en: Document Title
+    label_zh: 文档标题
+    description: Title of a published document (notice, report, filing).
+    value_type: text
+    unit_type: none
+    dimensions: []
+    variables: []
+
+  - id: DocDate
+    label_en: Document Date
+    label_zh: 文档日期
+    description: Publication or effective date of a document.
+    value_type: date
+    unit_type: none
+    dimensions: []
+    variables: []
+
+  - id: DocUrl
+    label_en: Document URL
+    label_zh: 文档链接
+    description: Canonical web address of a published document.
+    value_type: text
+    unit_type: none
+    dimensions: []
+    variables: []

fd_open_data_protocol-0.3.0/fd_open_data_protocol/vocabulary/crosswalks/datacommons-worldbank.yaml

@@ -0,0 +1,51 @@
+# FindData vocabulary — crosswalk assertions (Data Commons + World Bank).
+#
+# Each mapping asserts that a FindData Variable (identified by its five-field
+# identity tuple) corresponds to a term in an external vocabulary, with a
+# SKOS-style relation and a confidence. `import-crosswalks` ingests these into
+# the MCP `concept_mappings` table with provenance `registry`.
+#
+# Relation types: exact | close | broader | narrower | related
+# (skos:exactMatch / closeMatch / broadMatch / narrowMatch / relatedMatch).
+#
+# URIs for the mapped Variables themselves are Phase 4; this release carries
+# only family URIs.
+version: "2026.09"
+kind: crosswalk
+mappings:
+  # --- Population -------------------------------------------------------------
+  - code: population.total
+    entity_type: country
+    measure: ""
+    unit: persons
+    frequency: yearly
+    vocabulary: datacommons
+    term: Count_Person
+    relation: exact
+    confidence: 1.0
+    note: Data Commons' generic population StatisticalVariable.
+
+  - code: population.total
+    entity_type: country
+    measure: ""
+    unit: persons
+    frequency: yearly
+    vocabulary: worldbank
+    term: SP.POP.TOTL
+    relation: exact
+    confidence: 1.0
+    note: World Bank "Population, total".
+
+  # --- GDP --------------------------------------------------------------------
+  - code: gdp
+    entity_type: country
+    measure: nominal_current
+    unit: usd
+    frequency: yearly
+    vocabulary: worldbank
+    term: NY.GDP.MKTP.CD
+    relation: exact
+    confidence: 1.0
+    note: World Bank "GDP (current US$)" — the nominal current-USD variable only;
+      the real/PPP/per-capita variants are separate Variables with their own
+      external terms (NY.GDP.MKTP.KD, NY.GDP.PCAP.CD, NY.GDP.PCAP.PP.CD).