Entities and their describing Schemas (Kinds of Data) are the heart of a data ecosystem.
# Schema
> Please record your issues and comments on this space in the [issue tracker](https://gitlab.opengroup.org/osdu/opendes-contribution-wiki/issues). Please label the issues as `OSDU/ODES Schema`. For list of open issues, please see [open issues](https://gitlab.opengroup.org/osdu/opendes-contribution-wiki/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=OSDU%2FODES%20Schema)
Schema is a structure, also defined in JSON, which provides data type information for the record fields. In other words, the schema defines whether a given field in the record is a string, or an integer, or a float, or a geopoint, etc.
It is important to note that only fields with schema information associated with are indexed by the Search Service. For this reason, the data ecosystem developer must create the respective schema for his/her records kind before start ingesting records into the Data Ecosystem.
# Definitions
Schemas and records are tied together by the **kind** attribute. On top of that, a given kind can have zero or exactly one schema associated with. Having that concept in mind, the DELFI developer can make use of two APIs for schema management provided by the Data Ecosystem Storage Service:
## Schema (or JSON Schema)
Detail documentation of how Schemas relate to entities via kinds can before found in the [**Storage Service**](/OSDU-\(C\)/Design-and-Implementation/API-Specifications/Documentation/core-services/StorageService) documentation.
Schema is a structure of the data, defined in JSON format and follows the spec https://json-schema.org/specification-links.html#draft-7. Each entity defined in the system is described exactly by one schema.
## Kind
kind: (mandatory) Kind of data being ingested. Must follow the naming convention: {Namespace}:{Source}:{Type}:{version}.
In addition to describing the data attributes of the entity, the schema also describes additional metadata such as legal tags, ACLs, common attributes are required to fully quality a entity in the OSDU system
**Namespace**: Allows for different interpretations of Schema
**Source**: Is the source of the schema
**Type**: Is the type of content described by the Schema
**Version**: Is the version of the Schema
## Kind
A unique identifier (or a tag) given to the schema, such that from the identifier it is relatively easy to infer the entity it describes. Such that kind `osdu:ihs:well:1.0.0` may relate to a schema defining well headers that are provided by IHS and defined (authored) by osdu data definition subcommittee. It is a recommended that there exists a service or web server that hosts the schema of all type and each type can be retrieved by specificing it's kind. Such as `https://osdu.opengroup.org/schema/osdu/osdu:ihs:well:1.0.0.json`
Thus:
- slb:witsml:wellbore:1.0.1 is Schlumberger's interpretation of a Wellbore described in the WITSML Standard.
- npd:las:well:1.0.0 is NPDs interpretation of how to describe a well in Las
- slb:wke:well:1.0.0 is Schlumberger's version of a well known entity (common query/discovery model) for a well.
Schema also plays an important role, as the information present in the schema definitions can serve as a index schema for search engines
## Entity
A record or instance of a data item that follows the schema of its `kind`.
In this example, the IHS Kind reflects the schema of a well as we receive it from IHS
## Well Known Schema (WKS)
Same as schema, except when there is an interest to map different schema from different sources, into a canonical model. Subsequently such a common model is promoted as the first class citizen to search and consume. WKS can be defined as needed for a given implementation, with OSDU providing the first set of such known schema for known types handled inside the OSDU Data Platform.
In this example, we have registered a Schema provided by OSDU to represent a standard.
## Well Known Entities (WKE)
Instances of WKS, just how the Entity is an instance of Kind. In addition to being on the common model, duplicates in data are also expected to be resolved by designating them as WKE. For example, a well data can be mastered/enriched from more than one sources of information and enriched to remove redundant & duplicate entries. Such a resulting set of data are known as Well Known Entities.
[**Well Known Schema (WKS) Kind**](/OSDU-\(C\)/Design-and-Implementation/Entity-and-Schemas/WKS-Kind)
In this example, we have defined a Schema that represents a community view of a domain type. It is a schema for discovery, exchange and default consumption. It is not a canonical schema as other community or standard schemas can be used to represent the same data.
# WKE, WKS and Enrichment - Explained
Links to other Well Known Schema can be found in the [**wke-schema repo**](https://dev.azure.com/slb-des-ext-collaboration/open-data-ecosystem/_git/wke-schema?path=%2Fdomains%2Fwell%2Fjson_schema&version=GBmaster).
Please refer to [Demystifying Well Known Schema, Well Known Entity and Enrichment Pipelines](/OSDU-(C)/Design-and-Implementation//Entity-and-Schemas/Demystifying-Well-Known-Schemas,-Well-Known-Entities,-Enrichment-Pipelines)
# Entities
An entity is an instance of data represented a schema (kind).
# Comparing OSDU and OpenDES Schema - Recommendations
## Examples
Please refer to [Comparing OSDU & OpenDES Schema Semantics](/OSDU-(C)/Design-and-Implementation//Entity-and-Schemas/Comparing-OSDU-&-OpenDES-Schema-Semantics) on guidance of how the two models can be mapped as one going forward.
[**Well Known Entity (WKE)**](/OSDU-\(C\)/Design-and-Implementation/Entity-and-Schemas/WKE)
A Well Known Entity is an entity which best represents a business object (E.g. WellBore) that is created by merging the most correct information from various sources and expressed through a Well Known Schema.
Examples of other Well Known Entities can be found in the [**wke-schema repo**](https://dev.azure.com/slb-des-ext-collaboration/open-data-ecosystem/_git/wke-schema?path=%2Fdomains%2Fwell%2Fjson_data&version=GBmaster).
