{
"openapi": "3.0.0",
"info": {
"description": "Schema Service enables schema management in the Data Platform and offers an\nimplementation of the schema standard.\n\nSchema Service handles schema life cycle to help with the development of schemas in the Ecosystem.\n\n```plain {% title=\"Client ID\" %}\n963f2cc6915e479fa0fcb73ec2ec90e7\n```\n\n## Schema States\n\nThis lifecycle consists of three states - \"DEVELOPMENT\", \"PUBLISHED\" and \"OBSOLETE\".\n\n* `DEVELOPMENT` - Denotes that a Schema is in draft or evolutionary phase. Schema in this state is mutable.\n\n* `PUBLISHED` - A Schema can directly be created in published state or moved from the DEVELOPMENT state to the PUBLISHED state. A Schema in published state is immutable.\n\n* `OBSOLETE` - Schema can be marked as obsolete once they are no more in use. You can change DEVELOPMENT state schemas to OBSOLETE state.\n\n## Schema Scopes\n\n* `INTERNAL` - A schema defined in a certain data partition and accessible to only the users of that data partition is said to have \"INTERNAL\" scope.\n\n* `SHARED` - The Managed Planning Data Foundation makes certain standard schema available out of the box to all OSDU data partitions. These schema will have scope as \"SHARED\" by default and it should be created using system endpoint.\n",
"version": "1.0.0",
"x-product-id": "OSDU-Schema-Service",
"title": "Schema APIs",
"contact": {
"name": "SLB Customer Support for Digital",
"url": "https://customersupport.digital.slb.com"
}
},
"servers": [
{
"url": "https://as5.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (SGP)"
},
{
"url": "https://br5.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB SaaS OSDU (BRS)"
},
{
"url": "https://eu5.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (WEU)"
},
{
"url": "https://eu6.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB SaaS OSDU (EUT)"
},
{
"url": "https://eu7.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (MDE)"
},
{
"url": "https://us5.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (PSC)"
},
{
"url": "https://us7.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (USC)"
},
{
"url": "https://us8.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (WUS)"
},
{
"url": "https://as6.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (SAS)"
},
{
"url": "https://eu8.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (SWC)"
},
{
"url": "https://as7.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (MYW)"
},
{
"url": "https://za1.api.enterprisedata.slb.com/api/schema-service/v1",
"description": "SLB Saas OSDU (ZAN)"
}
],
"tags": [
{
"name": "Schema",
"description": "Core Schema Service related methods"
},
{
"name": "Shared Schema",
"description": "Endpoint to create and update shared schemas"
},
{
"name": "Info",
"description": "Build and git information"
}
],
"security": [
{
"bearer": []
}
],
"paths": {
"/schemas/system": {
"put": {
"tags": [
"Shared Schema"
],
"summary": "Creates/Updates a SHARED schema in development status",
"description": "This endpoint allows user to a create schema with all possible states i.e. DEVELOPMENT,PUBLISHED or OBSOLETE but update can be used only on schemas that are in \"DEVELOPMENT\" state. A schema status can also be changed from `DEVELOPMENT` to `PUBLISHED` or `OBSOLETE` while updating schema content or by providing the same schema content.
**Note:** The schema may refer to other schema definitions in `DEVELOPMENT` state. If those schemas are updated, it is the schema owner's responsibility to PUT the dependent schemas again in order to refresh the schema definitions. By default scope for a schema created through this endpoint will be SHARED. Service principal authorization is required to call thi API. There is no need to provide a data-partition-id in the header.",
"operationId": "Update System Schema",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaRequest"
}
}
},
"description": "SchemaRequest",
"required": true
},
"responses": {
"200": {
"description": "Schema updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaInfo"
}
}
}
},
"201": {
"description": "Schema created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaInfo"
}
}
}
},
"400": {
"description": "Bad user input. Mandatory fields missing or unacceptable value passed to API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"401": {
"description": "Unknown or invalid user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"403": {
"description": "User not authorised to access the API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"deprecated": false
}
},
"/schema": {
"post": {
"tags": [
"Schema"
],
"summary": "Adds a schema to the schema repository with status INTERNAL.",
"description": "Adds a schema to the schema repository. The schemaIdentity must be unique. The `authority`, `source` and `entityType` will be registered if not present. If lower minor versions are registered the service validates the new schema against breaking changes; if breaking changes are discovered the request fails.
**Note:** The schema must not reference other schemas with status `DEVELOPMENT`. By default scope to a schema will be set as `INTERNAL`
**Required roles** 'users.datalake.editors' or 'users.datalake.admins' groups to create schema.",
"operationId": "Create Schema",
"parameters": [
{
"$ref": "#/components/parameters/data-partition-id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaRequest"
}
}
},
"description": "Schema description and schema to add",
"required": true
},
"responses": {
"201": {
"description": "Schema created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaInfo"
}
}
}
},
"400": {
"description": "Bad user input. Mandatory fields missing or unacceptable value passed to API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"401": {
"description": "Unknown or invalid user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"403": {
"description": "User not authorised to access the API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"deprecated": false
},
"put": {
"tags": [
"Schema"
],
"summary": "Updates/Creates a schema in DEVELOPMENT status with INTERNAL scope",
"description": "Creates a new schema or updates an already existing schema with status `DEVELOPMENT` in the schema repository. If a user tries to create/update a schema with status other then `DEVELOPMENT`, API will throw an exception. Any schema instance with the same schemaIdentity is replaced (in contrast to the immutability of `PUBLISHED` or `OBSOLETE` schemas). A schema state can also be changed from `DEVELOPMENT` to `PUBLISHED` or `OBSOLETE` while updating schema content or by providing the same schema content.
**Note:** The schema may refer to other schema definitions in `DEVELOPMENT` state. If those schemas are updated themselves, it is the schema owner's responsibility to PUT the dependent schemas again to update the schemas. Scope for a schema can't be updated, its a system defined value. Required roles 'users.datalake.editors' or 'users.datalake.admins' groups to update schema.",
"operationId": "Update Schema",
"parameters": [
{
"$ref": "#/components/parameters/data-partition-id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaRequest"
}
}
},
"description": "SchemaRequest",
"required": true
},
"responses": {
"200": {
"description": "Schema updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaInfo"
}
}
}
},
"201": {
"description": "Schema created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaInfo"
}
}
}
},
"400": {
"description": "Bad user input. Mandatory fields missing or unacceptable value passed to API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"401": {
"description": "Unknown or invalid user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"403": {
"description": "User not authorised to access the API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"deprecated": false
},
"get": {
"tags": [
"Schema"
],
"summary": "Get identity information for all available schema",
"description": "The API returns a list of all schemas in the specific {data-partition-Id} and the list of available shared schemas in chronological order based on \"dateCreated\". If filter criteria is specific then the schemas matching the criteria will be returned. If \"latestestVersion=true\", then result will only contain the latest version of the schema for a given Authority, Source & Entity. **Required roles** 'users.datalake.viewers' or 'users.datalake.editors' or 'users.datalake.admins'",
"operationId": "searchSchemaInfoRepository",
"parameters": [
{
"$ref": "#/components/parameters/data-partition-id"
},
{
"in": "query",
"name": "authority",
"description": "pass an optional string to search for a specific authority",
"required": false,
"schema": {
"type": "string",
"default": "*",
"example": "osdu"
}
},
{
"in": "query",
"name": "source",
"description": "pass an optional string to search for a specific source",
"required": false,
"schema": {
"type": "string",
"default": "*",
"example": "wks"
}
},
{
"in": "query",
"name": "entityType",
"description": "pass an optional string to search for a specific entityType",
"required": false,
"schema": {
"type": "string",
"default": "*",
"example": "wellbore"
}
},
{
"in": "query",
"name": "schemaVersionMajor",
"description": "pass an optional string to search for a specific schemaVersionMajor",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "schemaVersionMinor",
"description": "pass an optional string to search for a specific schemaVersionMinor",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "schemaVersionPatch",
"description": "pass an optional string to search for a specific schemaVersionPatch",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "status",
"description": "The schema status specification",
"schema": {
"type": "string",
"title": "Schema Status",
"enum": [
"PUBLISHED",
"DEVELOPMENT",
"OBSOLETE"
]
}
},
{
"in": "query",
"name": "scope",
"description": "The scope or schema visibility specification",
"schema": {
"type": "string",
"title": "Scope",
"enum": [
"SHARED",
"INTERNAL"
]
}
},
{
"in": "query",
"name": "latestVersion",
"description": "if True, only return the latest version",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"example": true
}
},
{
"in": "query",
"name": "limit",
"description": "maximum number of schema records to return",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"example": 10
}
},
{
"in": "query",
"name": "offset",
"description": "number of records to skip for pagination",
"schema": {
"type": "integer",
"minimum": 0,
"example": 0
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SchemaInfoResponse"
}
}
}
},
"400": {
"description": "Bad user input. Mandatory fields missing or unacceptable value passed to API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"401": {
"description": "Unknown or invalid user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"403": {
"description": "User not authorised to access the API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"deprecated": false
}
},
"/schema/{id}": {
"get": {
"tags": [
"Schema"
],
"summary": "Gets schema from the schema repository.",
"description": "Retrieve a schema using its system defined id. Required roles 'users.datalake.viewers' or 'users.datalake.editors' or 'users.datalake.admins' groups to get the schema.",
"operationId": "Get Schema",
"parameters": [
{
"$ref": "#/components/parameters/data-partition-id"
},
{
"name": "id",
"in": "path",
"description": "the system id of the schema",
"required": true,
"example": "osdu:wks:wellbore:1.0.0",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "search results matching criteria",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "The entity shapefile.",
"title": "ShapeFile",
"type": "object",
"definitions": {},
"properties": {}
}
}
}
},
"400": {
"description": "Bad user input. Mandatory fields missing or unacceptable value passed to API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"401": {
"description": "Unknown or invalid user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"403": {
"description": "User not authorised to access the API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
},
"404": {
"description": "Requested Schema not found in repository",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseFormat"
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"deprecated": false
}
},
"/info": {
"get": {
"tags": [
"Info"
],
"summary": "Version info",
"description": "For deployment available public `/info` endpoint, which provides build and git related information.",
"operationId": "Version info",
"responses": {
"200": {
"description": "Version info.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VersionInfo"
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"data-partition-id": {
"name": "data-partition-id",
"in": "header",
"description": "desired data partition id",
"required": true,
"schema": {
"type": "string"
}
}
},
"securitySchemes": {
"bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "User Token from SLB Authenticator Service"
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"reason": {
"type": "string"
},
"domain": {
"type": "string"
}
}
},
"ErrorModel": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
},
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
},
"ErrorResponseFormat": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorModel"
}
},
"description": "An error that occurs during normal application logic"
},
"SchemaInfoResponse": {
"description": "The response for a GET schema request",
"title": "SchemaInfo Response",
"properties": {
"schemaInfos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SchemaInfo"
}
},
"offset": {
"type": "integer",
"description": "The offset for the next query",
"title": "Offset",
"minimum": 0
},
"count": {
"type": "integer",
"description": "The number of schema versions in this response",
"title": "Count",
"minimum": 0
},
"totalCount": {
"type": "integer",
"description": "The total number of entity type codes in the repositories",
"title": "Count",
"minimum": 0
}
}
},
"SchemaInfo": {
"type": "object",
"required": [
"schemaIdentity",
"status"
],
"properties": {
"createdBy": {
"type": "string",
"example": "user@opendes.com",
"description": "The user who created the schema. This value is taken from API caller token."
},
"dateCreated": {
"type": "string",
"format": "date-time",
"example": "2019-05-23 11:16:03+00:00",
"description": "The UTC date time of the entity creation"
},
"schemaIdentity": {
"$ref": "#/components/schemas/SchemaIdentity"
},
"scope": {
"type": "string",
"example": "INTERNAL",
"description": "Schema Scope - is it internal or shared. This is a system defined attribute based on partition-id passed.",
"enum": [
"INTERNAL",
"SHARED"
]
},
"status": {
"type": "string",
"description": "Schema lifecycle status",
"enum": [
"PUBLISHED",
"OBSOLETE",
"DEVELOPMENT"
]
},
"supersededBy": {
"$ref": "#/components/schemas/SchemaIdentity"
}
},
"title": "Schema Info",
"description": "Schema info including status, creation and schemaIdentity"
},
"SchemaIdentity": {
"type": "object",
"required": [
"authority",
"entityType",
"source",
"schemaVersionMajor",
"schemaVersionMinor",
"schemaVersionPatch"
],
"properties": {
"authority": {
"type": "string",
"example": "osdu",
"description": "Entity authority"
},
"entityType": {
"type": "string",
"example": "wellbore",
"description": "EntityType Code"
},
"id": {
"type": "string",
"example": "osdu:wks:wellbore:1.0.0",
"description": "A read-only system defined id used for referencing of a schema."
},
"schemaVersionMajor": {
"type": "integer",
"example": 1,
"description": "Major Schema Version Number"
},
"schemaVersionMinor": {
"type": "integer",
"example": 1,
"description": "Minor Schema Version Number"
},
"schemaVersionPatch": {
"type": "integer",
"example": 0,
"description": "Patch Schema Version Number"
},
"source": {
"type": "string",
"example": "wks",
"description": "Entity source"
}
},
"title": "SchemaIdentity",
"description": "Schema authority source and type description"
},
"SchemaRequest": {
"type": "object",
"required": [
"schema",
"schemaInfo"
],
"properties": {
"schema": {
"type": "object"
},
"schemaInfo": {
"$ref": "#/components/schemas/SchemaInfo"
}
},
"title": "SchemaRequest",
"example": {
"schemaInfo": {
"schemaIdentity": {
"authority": "osdu",
"source": "wks",
"entityType": "wellbore",
"schemaVersionMajor": 1,
"schemaVersionMinor": 0,
"schemaVersionPatch": 0
},
"status": "DEVELOPMENT"
},
"schema": {}
}
},
"VersionInfo": {
"type": "object",
"properties": {
"groupId": {
"type": "string",
"description": "Maven artifact group ID."
},
"actifactId": {
"type": "string",
"description": "Maven artifact ID."
},
"version": {
"type": "string",
"description": "Maven artifact version"
},
"buildTime": {
"type": "string",
"description": "Maven artifact build time"
},
"branch": {
"type": "string",
"description": "Current git branch"
},
"commitId": {
"type": "string",
"description": "Latest commit hash"
},
"commitMessage": {
"type": "string",
"description": "Latest commit message"
},
"connectedOuterServices": {
"type": "array",
"description": "Connected outer services information",
"items": {
"$ref": "#/components/schemas/ConnectedOuterService"
}
}
},
"description": "Version info."
},
"ConnectedOuterService": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Connected outer service name."
},
"version": {
"type": "string",
"description": "Connected outer service version."
}
},
"description": "Connected outer service information."
}
}
}
}