Schema API (Open Data for Industries)

Manage schemas to define and enforce sets of attributes on functional data.

The Schema API provides mechanisms to define and enforce structure to the data that is managed by Open Data for Industries.

Schema

A schema is a structure, which is defined in JSON format.

It provides data type information for the data record fields.

In other words, the schema defines whether a field in the record is a string, integer, floating point, geopoint, or other data types.

Only fields that are associated with schema information are indexed by the Search API. Therefore, Open Data for Industries users must create the respective schema for their records before ingesting data into the system.

The API supports creation, full search, and filtered search of the schema resources in the Open Data for Industries service.

To use the API, see the Schema API reference.

Learn more

Data entity types
Schema structure
Running Schema API methods
Schema API endpoint permissions

Data entity types

The Schema API supports several subsurface data types. These data types are categorized in the following table:

Table 1. Subsurface data types
Data types	Description	Data Description
Wellbore	A hole in the ground that extends from a point at the earth's surface to the maximum point of penetration.	Data that depicts the position of a borehole or well path in three-dimensional space.
Well	The origin of a set of wellbores. A well has one or more wellbores.	Data that describes the set of wellbore entities.
Seismic	Subsurface structures and energy waves.	Data that provides a “time picture” of a subsurface structure.

Schema structure

Schemas are defined in JSON format. These definitions follow a structure to standardize the identification of the schemas in the Open Data for Industries service.

The following example shows the structure of the JSON file:

{
  "schemaInfo": {
    "schemaIdentity": {
      "authority": "osdu",
      "source": "wks",
      "entity": "work-product-component.WellLog",
      "schemaVersionMajor": 1,
      "schemaVersionMinor": 0,
      "schemaVersionPatch": 0,
      "id": "osdu:wks:work-product-component.WellLog:1.0.0"
    },
    "createdBy": "OSDU Data Definition Group",
    "scope": "SHARED",
    "status": "DEVELOPMENT"
  },
  "schema": {
    ...
  }
}

The schema property contains the full schema definition. The definition is omitted from the schema property in the preceding example.

The structure has various attributes that help to uniquely identify the schema definitions.

Table 2. Schema structure attributes
Attributes	Description
`authority`	Authority that accounts for the definition.
`source`	The functional source of the definition.
`entity`	The classification that is defined.
`schemaVersionMajor`	Major version for the definition.
`schemaVersionMinor`	Minor version for the definition.
`id`	A read-only system defined ID, which is used for referencing a schema.
`createdBy`	The user who created the schema. This value is taken from the API caller token.
`scope`	An array value [INTERNAL, SHARED], which is a system-defined attribute based on the `partition-id` that was passed.
`status`	An array value [PUBLISHED, OBSOLETE, DEVELOPMENT] to define the status of the schema definition.

Running Schema API methods

To use the Schema API, follow these steps:

Choose a partition:
The Open Data for Industries service publishes schema definitions for different tenants, depending on the different accounts on the system. A user may belong to many accounts, for example, to an owner account and a customer account. When you log in to the industry applications, you choose which account is active. To use the Schema API, specify the active account by using the data-partition-id parameter.
Create data groups:
Create data groups and assign users to these groups. Data groups use prefix data. For data access authorization purposes, the groups in the following example must exist already. Create groups by using the Entitlements API.
- service.schema-service.viewers
- service.schema-service.editors
- service.schema-service.admin
Use the Schema API methods to publish schema definitions on the storage layer of Open Data for Industries.

Table 3. Schema service endpoints
API endpoint	Description	API reference
`POST /api/schema/v1/schema`	Creates a schema to the schema repository.	Create schema
`PUT /api/schema/v1/schema`	Creates or updates a schema in development status.	Create or update schema
`GET /api/schema/v1/schema`	Gets all schema definitions under a `data-partition-id`.	Get all schemas
`GET /api/schema/v1/schema/{id}`	Gets the definition for an identified schema from the schema repository.	Get specific schema

Schema API endpoint permissions

The following table describes the Schema API endpoint permissions.

Table 4. API method permissions
Endpoint URL	Method	Minimum permissions required
`/api/schema/v1/schema`	POST	`service.schema-service.editors`
`/api/schema/v1/schema`	PUT	`service.schema-service.editors`
`/api/schema/v1/schema`	GET	`service.schema-service.viewers`
`/api/schema/v1/schema/{id}`	GET	`service.schema-service.viewers`