diff --git a/docs/README.md b/docs/README.md index 5a32e243cbb..c8eec94989d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ Data is an important asset of an organization and metadata is the key to unlock Poorly organized metadata is preventing organizations from realizing the full potential of data. Metadata is incorrect, inconsistent, stale, often missing, and fragmented in silos across various disconnected tools in proprietary formats obscuring a holistic picture of data. -**OpenMetadata is an Open standard for metadata with a centralized metadata store that unifies all the data assets and metadata end-to-end to power data discovery, user collaboration, and tool interoperability.** +## **OpenMetadata is an Open standard for metadata with a centralized metadata store that unifies all the data assets and metadata end-to-end to power data discovery, user collaboration, and tool interoperability.** ![](.gitbook/assets/openmetadata-overview.png) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0e01c390025..b5e5e285292 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -6,7 +6,8 @@ ## OpenMetadata APIs * [Schemas](openmetadata-apis/schemas/README.md) - * [Overview](openmetadata-apis/schemas/overview.md) + * [Schema Language](openmetadata-apis/schemas/schema-language.md) + * [Schema Concepts](openmetadata-apis/schemas/overview.md) * [OpenMetadata Types](openmetadata-apis/schemas/types/README.md) * [Basic](openmetadata-apis/schemas/types/basic.md) * [Audit Log](openmetadata-apis/schemas/types/audit-log.md) diff --git a/docs/openmetadata-apis/schemas/README.md b/docs/openmetadata-apis/schemas/README.md index bed7df6dace..e53622a52ed 100644 --- a/docs/openmetadata-apis/schemas/README.md +++ b/docs/openmetadata-apis/schemas/README.md @@ -2,19 +2,7 @@ ## Schema Modeling -OpenMetadata takes the **schema-first** approach to model metadata as a Single Source of Truth with clear vocabulary for the system. First, the Entities, Types, and relationships between the entities in the system are identified and schemas are defined for them. Code is then generated from these schemas for implementation. We use [JSON schema](https://json-schema.org/) as the Schema Definition Language as it offers several advantages: - -* Easy to describe the structure and semantics of metadata models with readable documentation that is both human and machine consumable. -* Common types can be developed once and can be reused as building blocks in other schemas and become the basis of vocabulary development. -* Models can include structural validation, such as required/optional fields, default values, allowed values, regex that not only serve as automated testing and validation but also as documentation of API contract. -* A rich set of tools are available that supports JSON schema support for generating code and validation from JSON schema in various languages, reducing the manual boilerplate coding. -* Supports rich formats to convert schema types into native standard types during code generation, such as URI, date, and time. - -## Reference - -1. [JSON schema](https://json-schema.org/) specification version [Draft-07 to 2019-099](https://json-schema.org/draft/2019-09/release-notes.html) -2. [JSON schema 2 POJO](https://www.jsonschema2pojo.org/) tool used for Java code generation from JSON schema -3. [Data model code generator](https://github.com/koxudaxi/datamodel-code-generator) for generating python code from JSON schema +OpenMetadata takes the **schema-first** approach to model metadata as a Single Source of Truth with clear vocabulary for the system. First, the Entities, Types, and relationships between the entities in the system are identified and schemas are defined for them. Code is then generated from these schemas for implementation. ## Schemas @@ -22,7 +10,5 @@ OpenMetadata takes the **schema-first** approach to model metadata as a Single S {% page-ref page="types/" %} -## Version Note -The schemas linked above follow the JSON Schema Spec version: [http://json-schema.org/draft-07/schema\#](http://json-schema.org/draft-07/schema#) diff --git a/docs/openmetadata-apis/schemas/overview.md b/docs/openmetadata-apis/schemas/overview.md index 5cc7db53802..80bd9a07e06 100644 --- a/docs/openmetadata-apis/schemas/overview.md +++ b/docs/openmetadata-apis/schemas/overview.md @@ -1,4 +1,4 @@ -# Overview +# Schema Concepts ## Types diff --git a/docs/openmetadata-apis/schemas/schema-language.md b/docs/openmetadata-apis/schemas/schema-language.md new file mode 100644 index 00000000000..76d46537801 --- /dev/null +++ b/docs/openmetadata-apis/schemas/schema-language.md @@ -0,0 +1,18 @@ +# Schema Language + +We use [JSON schema](https://json-schema.org/) as the Schema Definition Language as it offers several advantages: + +* Easy to describe the structure and semantics of metadata models with readable documentation that is both human and machine consumable. +* Common types can be developed once and can be reused as building blocks in other schemas and become the basis of vocabulary development. +* Models can include structural validation, such as required/optional fields, default values, allowed values, regex that not only serve as automated testing and validation but also as documentation of API contract. +* A rich set of tools are available that supports JSON schema support for generating code and validation from JSON schema in various languages, reducing the manual boilerplate coding. +* Supports rich formats to convert schema types into native standard types during code generation, such as URI, date, and time. + +## Reference + +1. [JSON schema](https://json-schema.org/) specification version [Draft-07 to 2019-099](https://json-schema.org/draft/2019-09/release-notes.html) +2. [JSON schema 2 POJO](https://www.jsonschema2pojo.org/) tool used for Java code generation from JSON schema +3. [Data model code generator](https://github.com/koxudaxi/datamodel-code-generator) for generating python code from JSON schema + +## +