Apache Ossie JSON Schema详解osi-schema.json逐行解读新手完整指南【免费下载链接】ossieApache Ossie, industry wide specification effort to standardize how we exchange semantic metadata across analytics, AI and BI platforms, providing a vendor neutral, single source of truth for semantic data项目地址: https://gitcode.com/GitHub_Trending/osi1/ossie 刚接触Apache Ossie的朋友一定绕不开 core-spec/osi-schema.json 这个文件——它是整个 Apache Ossie语义模型交换的行业标准前身为 OSI的宪法。这个JSON Schema定义了语义模型Semantic Model的结构、类型与枚举是 AI 工具、BI 平台之间交换语义元数据的唯一官方合同。本文将逐行带你读懂它无需深厚编程背景。一、osi-schema.json 是做什么的一句话定位它是一个用于校验 Ossie 语义模型定义文件的 JSON Schema2020-12 草案对应文件头部的description字段JSON Schema for validating Apache Ossie semantic model definitions在 Ossie 的三层架构中osi-schema.json 规范的是逻辑层Logical Layer——即直接映射数据库的传统 BI 语义模型层图中标识了 Ossie 的三层模型Ontological Layer本体层、Logical Layer逻辑层即本 Schema 管辖区和 Physical物理层各数据库原生 SQL。二、顶层结构只有 2 个字段却条条必填 打开 osi-schema.json前 22 行定义了文件骨架逐行看行号字段作用第 2 行$schema声明遵循 JSON Schema 2020-12 规范校验器据此工作第 4 行title文件标题Apache Ossie Core Metadata Specification第 8-12 行version必填且必须等于0.2.0.dev0const硬校验写错即不通过第 13-19 行semantic_model必填语义模型定义数组一个文件可含多个模型第 21 行requiredversion和semantic_model缺一不可第 22 行additionalProperties: false禁止任何未定义字段——这是 Ossie 防方言漂移的关键设计 新手要点顶层只允许这两个字段想加别的不存在的。所有厂商定制需求都被赶到custom_extensions里后文详述。三、$defs 速览13 个定义分四大类 第 23 行开始进入$defs可复用的类型定义库按职责可分为四组1️⃣ 基础枚举Dialect 与 DataTypeDialect第 24 行表达式的方言枚举共 7 种ANSI_SQL、SNOWFLAKE、MDX、TABLEAU、DATABRICKS、MAQL、BIGQUERY。它让同一字段/指标可以携带多种方言的 SQL 写法实现跨平台移植。DataType第 111 行10 种逻辑数据类型——String、Integer、Decimal、Float、Boolean、Date、Time、DateTime、DateTimeTz、Opaque。注意DateTimeTz表示带时区上下文的时刻而Opaque是逃生通道遇到不可移植的类型用它加custom_extensions标记。2️⃣ 扩展机制AIContext 与 CustomExtensionAIContext第 34 行给 AI 工具的上下文oneOf二选一——直接写一段字符串或写对象含instructions使用指令、synonyms同义词、examples示例问题。这就是 Ossie 拥抱 AI/BI 场景的体现。CustomExtension第 66 行厂商自定义扩展结构固定为vendor_name任意字符串dataJSON 字符串两项均必填。各 BI 平台可在此夹带私货而不破坏核心兼容性。3️⃣ 核心实体一张表看懂必填项 ✅定义含义必填字段SemanticModel顶层容器一个完整语义模型name、datasets至少 1 个Dataset逻辑数据集事实/维度表name、source物理表如db.schema.table或查询Field行级属性用于分组/过滤name、expressionRelationship数据集间外键关系多对一/一对一name、from、to、from_columns、to_columnsMetric跨数据集的量化度量KPIname、expressionDimension维度元数据无仅含is_time布尔标记Expression/DialectExpression多方言表达式dialects至少 1 项/dialect、expression4️⃣ 表达式设计多方言是本 Schema 的杀手锏Expression要求dialects数组至少 1 项minItems: 1每项是dialectexpression的组合。一个指标可以这样同时给 Snowflake 和 BigQuery 各写一份 SQL下游工具按自己的方言取用——这就是厂商中立的具体落点。四、三个最容易踩坑的细节 ⚠️is_time有默认逻辑第 131 行不显式设置时datatype为Date/Time/DateTime/DateTimeTz的字段自动视为时间维度审计时间戳这类日期但不是时间维度的列需显式写is_time: false。所有实体都写了additionalProperties: false每个字段名都被锁死拼写错误会被校验直接拦下而不是静默忽略。from是多端、to是一端第 236-243 行from_columns与to_columns必须一一对应支持复合键。五、写完后如何一键校验 项目自带校验器 validation/validate.py它做四件事用本 Schema 校验结构、类型、枚举检查数据集/字段/指标/关系名称唯一检查关系引用的数据集是否存在用 sqlglot 按方言校验 SQL 表达式语法MDX、TABLEAU、MAQL 自动跳过。对示例文件运行python validation/validate.py examples/tpcds_semantic_model.yaml看到Validation PASSED就说明你的语义模型完全符合规范。完整示例可参考 examples/tpcds_semantic_model.yaml。六、延伸阅读 人类可读规范core-spec/spec.mdYAML 版字段说明注释极详尽core-spec/spec.yaml表达式语言规范core-spec/expression_language.md官方转换器dbt、GoodData、Snowflake 等converters/总结osi-schema.json 用约 350 行 JSON定义了版本锁 语义模型数组的顶层契约和 13 个核心类型配合禁扩展字段 厂商扩展区的双轨设计实现了严格、中立、可扩展三者的平衡。读懂它就拿到了整个 Ossie 生态的钥匙。【免费下载链接】ossieApache Ossie, industry wide specification effort to standardize how we exchange semantic metadata across analytics, AI and BI platforms, providing a vendor neutral, single source of truth for semantic data项目地址: https://gitcode.com/GitHub_Trending/osi1/ossie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Ossie JSON Schema详解：osi-schema.json逐行解读新手完整指南
Apache Ossie JSON Schema详解osi-schema.json逐行解读新手完整指南【免费下载链接】ossieApache Ossie, industry wide specification effort to standardize how we exchange semantic metadata across analytics, AI and BI platforms, providing a vendor neutral, single source of truth for semantic data项目地址: https://gitcode.com/GitHub_Trending/osi1/ossie 刚接触Apache Ossie的朋友一定绕不开 core-spec/osi-schema.json 这个文件——它是整个 Apache Ossie语义模型交换的行业标准前身为 OSI的宪法。这个JSON Schema定义了语义模型Semantic Model的结构、类型与枚举是 AI 工具、BI 平台之间交换语义元数据的唯一官方合同。本文将逐行带你读懂它无需深厚编程背景。一、osi-schema.json 是做什么的一句话定位它是一个用于校验 Ossie 语义模型定义文件的 JSON Schema2020-12 草案对应文件头部的description字段JSON Schema for validating Apache Ossie semantic model definitions在 Ossie 的三层架构中osi-schema.json 规范的是逻辑层Logical Layer——即直接映射数据库的传统 BI 语义模型层图中标识了 Ossie 的三层模型Ontological Layer本体层、Logical Layer逻辑层即本 Schema 管辖区和 Physical物理层各数据库原生 SQL。二、顶层结构只有 2 个字段却条条必填 打开 osi-schema.json前 22 行定义了文件骨架逐行看行号字段作用第 2 行$schema声明遵循 JSON Schema 2020-12 规范校验器据此工作第 4 行title文件标题Apache Ossie Core Metadata Specification第 8-12 行version必填且必须等于0.2.0.dev0const硬校验写错即不通过第 13-19 行semantic_model必填语义模型定义数组一个文件可含多个模型第 21 行requiredversion和semantic_model缺一不可第 22 行additionalProperties: false禁止任何未定义字段——这是 Ossie 防方言漂移的关键设计 新手要点顶层只允许这两个字段想加别的不存在的。所有厂商定制需求都被赶到custom_extensions里后文详述。三、$defs 速览13 个定义分四大类 第 23 行开始进入$defs可复用的类型定义库按职责可分为四组1️⃣ 基础枚举Dialect 与 DataTypeDialect第 24 行表达式的方言枚举共 7 种ANSI_SQL、SNOWFLAKE、MDX、TABLEAU、DATABRICKS、MAQL、BIGQUERY。它让同一字段/指标可以携带多种方言的 SQL 写法实现跨平台移植。DataType第 111 行10 种逻辑数据类型——String、Integer、Decimal、Float、Boolean、Date、Time、DateTime、DateTimeTz、Opaque。注意DateTimeTz表示带时区上下文的时刻而Opaque是逃生通道遇到不可移植的类型用它加custom_extensions标记。2️⃣ 扩展机制AIContext 与 CustomExtensionAIContext第 34 行给 AI 工具的上下文oneOf二选一——直接写一段字符串或写对象含instructions使用指令、synonyms同义词、examples示例问题。这就是 Ossie 拥抱 AI/BI 场景的体现。CustomExtension第 66 行厂商自定义扩展结构固定为vendor_name任意字符串dataJSON 字符串两项均必填。各 BI 平台可在此夹带私货而不破坏核心兼容性。3️⃣ 核心实体一张表看懂必填项 ✅定义含义必填字段SemanticModel顶层容器一个完整语义模型name、datasets至少 1 个Dataset逻辑数据集事实/维度表name、source物理表如db.schema.table或查询Field行级属性用于分组/过滤name、expressionRelationship数据集间外键关系多对一/一对一name、from、to、from_columns、to_columnsMetric跨数据集的量化度量KPIname、expressionDimension维度元数据无仅含is_time布尔标记Expression/DialectExpression多方言表达式dialects至少 1 项/dialect、expression4️⃣ 表达式设计多方言是本 Schema 的杀手锏Expression要求dialects数组至少 1 项minItems: 1每项是dialectexpression的组合。一个指标可以这样同时给 Snowflake 和 BigQuery 各写一份 SQL下游工具按自己的方言取用——这就是厂商中立的具体落点。四、三个最容易踩坑的细节 ⚠️is_time有默认逻辑第 131 行不显式设置时datatype为Date/Time/DateTime/DateTimeTz的字段自动视为时间维度审计时间戳这类日期但不是时间维度的列需显式写is_time: false。所有实体都写了additionalProperties: false每个字段名都被锁死拼写错误会被校验直接拦下而不是静默忽略。from是多端、to是一端第 236-243 行from_columns与to_columns必须一一对应支持复合键。五、写完后如何一键校验 项目自带校验器 validation/validate.py它做四件事用本 Schema 校验结构、类型、枚举检查数据集/字段/指标/关系名称唯一检查关系引用的数据集是否存在用 sqlglot 按方言校验 SQL 表达式语法MDX、TABLEAU、MAQL 自动跳过。对示例文件运行python validation/validate.py examples/tpcds_semantic_model.yaml看到Validation PASSED就说明你的语义模型完全符合规范。完整示例可参考 examples/tpcds_semantic_model.yaml。六、延伸阅读 人类可读规范core-spec/spec.mdYAML 版字段说明注释极详尽core-spec/spec.yaml表达式语言规范core-spec/expression_language.md官方转换器dbt、GoodData、Snowflake 等converters/总结osi-schema.json 用约 350 行 JSON定义了版本锁 语义模型数组的顶层契约和 13 个核心类型配合禁扩展字段 厂商扩展区的双轨设计实现了严格、中立、可扩展三者的平衡。读懂它就拿到了整个 Ossie 生态的钥匙。【免费下载链接】ossieApache Ossie, industry wide specification effort to standardize how we exchange semantic metadata across analytics, AI and BI platforms, providing a vendor neutral, single source of truth for semantic data项目地址: https://gitcode.com/GitHub_Trending/osi1/ossie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
