feat: add extended metadata fields for fields and metrics

core-spec/osi-schema.json

@@ -124,6 +124,101 @@
       ],
       "description": "Logical data type for fields and metrics, independent of role (e.g. dimension vs fact) and physical representation. `Decimal` is exact base-10 with unspecified precision and scale; `Float` is approximate. `DateTime` has no timezone or offset, while `DateTimeTz` identifies an instant using offset or timezone context but does not guarantee preservation of a named timezone. Omit `datatype` when unknown; use `Opaque` plus `custom_extensions` for a known type outside the portable vocabulary."
     },
+    "SemanticType": {
+      "description": "High-level semantic classification of a field or metric. Either a well-known token or a URI pointing to an external type system.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["categorical", "quantitative", "monetary", "temporal", "geographic", "ordinal", "identifier"],
+          "description": "Well-known semantic type token"
+        },
+        {
+          "type": "string",
+          "format": "uri",
+          "description": "URI pointing to an external type system (e.g., ISO 20022, FIBO, SKOS vocabulary)"
+        }
+      ]
+    },
+    "DesiredDirection": {
+      "type": "string",
+      "enum": ["higher_is_better", "lower_is_better", "neutral"],
+      "description": "KPI polarity indicating whether higher or lower values are preferred"
+    },
+    "DefaultAggregation": {
+      "type": "string",
+      "enum": ["sum", "avg", "min", "max", "count", "count_distinct"],
+      "description": "Default aggregation function to apply when this field is used as a measure"
+    },
+    "DefaultTimeGranularity": {
+      "type": "string",
+      "enum": ["day", "week", "month", "quarter", "year"],
+      "description": "Default time bucket for temporal fields"
+    },
+    "UnitSystem": {
+      "type": "string",
+      "enum": ["si", "imperial", "custom"],
+      "description": "Unit system classification"
+    },
+    "Measurement": {
+      "type": "object",
+      "description": "Describes what a numeric value represents (units and measurement)",
+      "properties": {
+        "quantity_kind": {
+          "type": "string",
+          "description": "The kind of quantity (e.g., currency, length, weight, temperature, percentage, duration)"
+        },
+        "unit": {
+          "type": "string",
+          "description": "Specific unit. For currency use ISO 4217 (e.g., usd, eur). For others use UCUM or descriptive strings."
+        },
+        "unit_system": {
+          "$ref": "#/$defs/UnitSystem"
+        }
+      },
+      "additionalProperties": false
+    },
+    "DefaultSort": {
+      "type": "object",
+      "description": "Default sorting behavior",
+      "properties": {
+        "direction": {
+          "type": "string",
+          "enum": ["asc", "desc"],
+          "description": "Sort direction"
+        },
+        "nulls": {
+          "type": "string",
+          "enum": ["first", "last"],
+          "description": "Null value positioning"
+        },
+        "by_field": {
+          "type": "string",
+          "description": "Sort by a different field (e.g., sort month names by month number)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "SemanticMapping": {
+      "type": "object",
+      "description": "Link to an external ontology or standard using a SKOS-based predicate. The predicate vocabulary is intentionally open to allow non-positive assertions (e.g. DISTINCT_FROM) via extensions.",
+      "properties": {
+        "target": {
+          "type": "string",
+          "format": "uri",
+          "description": "URI of the external concept (e.g., https://schema.org/MonetaryAmount, https://spec.edmcouncil.org/fibo/...)"
+        },
+        "predicate": {
+          "type": "string",
+          "description": "Relationship type. SKOS baseline: exactMatch, closeMatch, broadMatch, narrowMatch, relatedMatch. Defaults to exactMatch. Vocabulary is open — non-standard predicates (e.g., DISTINCT_FROM) are permitted."
+        },
+        "provenance": {
+          "type": "string",
+          "description": "Optional: origin of this mapping (e.g., 'manual', 'FIBO 4.1', a tool name)"
+        }
+      },
+      "required": ["target"],
+      "additionalProperties": false
+    },
     "Dimension": {
       "type": "object",
       "description": "Dimension metadata",
@@ -153,6 +248,10 @@
           "type": "string",
           "description": "Label for categorization"
         },
+        "display_label": {
+          "type": "string",
+          "description": "Human-readable display name for UI and AI interaction"
+        },
         "description": {
           "type": "string",
           "description": "Human-readable description"
@@ -163,6 +262,40 @@
         "ai_context": {
           "$ref": "#/$defs/AIContext"
         },
+        "semantic_type": {
+          "$ref": "#/$defs/SemanticType"
+        },
+        "measurement": {
+          "$ref": "#/$defs/Measurement"
+        },
+        "display_format": {
+          "type": "string",
+          "description": "Excel-compatible display format string (e.g., $#,##0.00, 0.0%, #,##0)"
+        },
+        "default_aggregation": {
+          "$ref": "#/$defs/DefaultAggregation"
+        },
+        "default_sort": {
+          "$ref": "#/$defs/DefaultSort"
+        },
+        "default_time_granularity": {
+          "$ref": "#/$defs/DefaultTimeGranularity"
+        },
+        "semantic_mappings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/SemanticMapping"
+          },
+          "description": "Links to external ontologies or standards"
+        },
+        "hidden": {
+          "type": "boolean",
+          "description": "Whether this field should be hidden from consumer UIs"
+        },
+        "group_label": {
+          "type": "string",
+          "description": "Organizational grouping label for UI presentation"
+        },
         "custom_extensions": {
           "type": "array",
           "items": {
@@ -291,6 +424,41 @@
         "ai_context": {
           "$ref": "#/$defs/AIContext"
         },
+        "display_label": {
+          "type": "string",
+          "description": "Human-readable display name for UI and AI interaction"
+        },
+        "semantic_type": {
+          "$ref": "#/$defs/SemanticType"
+        },
+        "measurement": {
+          "$ref": "#/$defs/Measurement"
+        },
+        "display_format": {
+          "type": "string",
+          "description": "Excel-compatible display format string (e.g., $#,##0.00, 0.0%, #,##0)"
+        },
+        "desired_direction": {
+          "$ref": "#/$defs/DesiredDirection"
+        },
+        "default_sort": {
+          "$ref": "#/$defs/DefaultSort"
+        },
+        "semantic_mappings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/SemanticMapping"
+          },
+          "description": "Links to external ontologies or standards"
+        },
+        "hidden": {
+          "type": "boolean",
+          "description": "Whether this metric should be hidden from consumer UIs"
+        },
+        "group_label": {
+          "type": "string",
+          "description": "Organizational grouping label for UI presentation"
+        },
         "custom_extensions": {
           "type": "array",
           "items": {