Schema Upgrade
Schema upgrade service assists in updating the records of the OSDU platform to align with newer versions of the schema. All records within the OSDU platform are designed to conform to a particular schema type. Whenever this schema undergoes updates to incorporate additional features or attributes, the schema version is incremented. In order to accommodate this modification, the records on the OSDU platform need to be upgraded to comply with the updated schema version.
Endpoints Available
schema upgrade, reference value upgrade and rollback endpoints are available
1. Schema upgrade
Schema upgrade: This endpoint upgrades the records that conform to a specific kind. Both the kind and target version must be provided as parameters to the service. Please note that only for the pilot implementation, this service accepts the Record ID as a parameter.
Response is an Activity record that captures the outcome of the upgrade process.
Configuration :
SchemaUpgradeSpecification file containing Instructions for upgrade has to be updated in OSDU . For example Schema upgrade instructions for Storage records from kind osdu:wks:master-data--SeismicAcquisitionSurvey:1.0.0 to osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0" would be the folllowing.
These instructions are JOLT configurations to transform JSON. Link to SchemaUpgradeSpecification.1.0.0.json - https://community.opengroup.org/osdu/data/data-definitions/-/blob/master/SchemaRegistrationResources/shared-schemas/osdu/reference-data/SchemaUpgradeSpecification.1.0.0.json
{
"id": "{{NAMESPACE}}:reference-data--SchemaUpgradeSpecification:osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0",
"kind": "osdu:wks:reference-data--SchemaUpgradeSpecification:1.0.0",
"acl": {
"owners": [
"{{DATA_OWNERS_GROUP}}"
],
"viewers": [
"{{DATA_VIEWERS_GROUP}}"
]
},
"legal": {
"legaltags": [
"{{LEGAL_TAG}}"
],
"otherRelevantDataCountries": [
"{{ISO_3166_ALPHA_2_CODE}}"
]
},
"data": {
"Name": "osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0",
"Description": "Schema upgrade instructions for Storage records from kind osdu:wks:master-data--SeismicAcquisitionSurvey:1.0.0 to osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0",
"Code": "osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0",
"ExpectedResults": {
"kind": "osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0"
},
"JoltConfigurations": [
{
"operation": "shift",
"spec": {
"acl": "acl",
"data": {
"ResourceHomeRegionID": "data.ResourceHomeRegionID",
"ResourceHostRegionIDs": "data.ResourceHostRegionIDs",
"ResourceCurationStatus": "data.ResourceCurationStatus",
"ResourceLifecycleStatus": "data.ResourceLifecycleStatus",
"ResourceSecurityClassification": "data.ResourceSecurityClassification",
"Source": "data.Source",
"ExistenceKind": "data.ExistenceKind",
"NameAliases": "data.NameAliases",
"GeoContexts": "data.GeoContexts",
"SpatialLocation": "data.SpatialLocation",
"VersionCreationReason": "data.VersionCreationReason",
"TechnicalAssuranceTypeID": "data.TechnicalAssuranceTypeID",
"ProjectID": "data.ProjectID",
"ProjectName": "data.ProjectName",
"Purpose": "data.Purpose",
"ProjectBeginDate": "data.ProjectBeginDate",
"ProjectEndDate": "data.ProjectEndDate",
"FundsAuthorizations": "data.FundsAuthorizations",
"ContractIDs": "data.ContractIDs",
"Operator": "data.Operator",
"Contractors": "data.Contractors",
"Personnel": "data.Personnel",
"ProjectSpecifications": "data.ProjectSpecifications",
"ProjectStates": "data.ProjectStates",
"ActivityTemplateID": "data.ActivityTemplateID",
"ParentProjectID": "data.ParentProjectID",
"Parameters": "data.Parameters",
"SeismicGeometryTypeID": "data.SeismicGeometryTypeID",
"AcquisitionTypeID": "data.AcquisitionTypeID",
"OperatingEnvironmentID": "data.OperatingEnvironmentID",
"AreaCalculated": "data.AreaCalculated",
"AreaNominal": "data.AreaNominal",
"SampleInterval": "data.SampleInterval",
"RecordLength": "data.RecordLength",
"ShootingAzimuthAngle": "data.ShootingAzimuthAngle",
"MinOffsetDistance": "data.MinOffsetDistance",
"FoldCount": "data.FoldCount",
"ExtensionProperties": "data.ExtensionProperties",
"ShotpointIncrementDistance": "data.SourceConfigurations[0].ShotpointSpacing",
"EnergySourceTypeID": "data.SourceConfigurations[0].EnergySourceTypeID",
"SourceArrayCount": "data.SourceConfigurations[0].SourceArrayCount",
"SourceArraySeparationDistance": "data.SourceConfigurations[0].SourceArraySpacing",
"CableCount": "data.ReceiverConfigurations[0].CableCount",
"CableLength": "data.ReceiverConfigurations[0].CableLength",
"CableSpacingDistance": "data.ReceiverConfigurations[0].CableSpacing",
"VesselNames": {
"0": [
"data.ReceiverConfigurations[0].VesselName",
"data.SourceConfigurations[0].VesselName"
]
}
},
"ancestry": "ancestry",
"createTime": "createTime",
"createUser": "createUser",
"id": "id",
"kind": {
"osdu:wks:master-data--SeismicAcquisitionSurvey:1.0.0": {
"#osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0": "kind"
}
},
"legal": "legal",
"modifyTime": "modifyTime",
"modifyUser": "modifyUser",
"tags": "tags",
"version": "version",
"meta": "meta"
}
}
],
"SourceKind": "osdu:wks:master-data--SeismicAcquisitionSurvey:1.0.0",
"TargetKind": "osdu:wks:master-data--SeismicAcquisitionSurvey:1.1.0",
"Source": "Workbook Authoring/SchemaUpgradeSpecification.1.0.0.xlsx; commit SHA 91ef01e9.",
"CommitDate": "2022-10-10T12:47:10+02:00"
}
}
Header :
| Attribute | Value |
|---|---|
| data-partition-id | Example - opendes |
Request :
| Attribute | Value |
|---|---|
| Kind | The schema kind that needs to be upgraded. |
| Target | The version to which the schema kind is being upgraded. |
| id | Specifies the records that need to be upgraded. This attribute will be deprecated in the future. |
Sample Request :
{
"kind":"osdu:wks:master-data--Wellbore:1.0.0",
"target":"osdu:wks:master-data--Wellbore:1.1.0",
"id":["opendes:master-data--Wellbore:5171"]
}
Response :
| Attribute | Value |
|---|---|
| Activity:1.1.0 | The response is an Activity record that contains the dataObjectParameter specifying the upgraded kind and the record version before the upgrade. |
Sample Response :
{
"id": "opendes:work-product--Activity:SchemaUpgrade-28821",
"kind": "osdu:wks:work-product-component--Activity:1.1.0",
"acl": {
"viewers": [
"data.default.viewers@opendes.contoso.com"
],
"owners": [
"data.default.viewers@opendes.contoso.com"
]
},
"legal": {
"legaltags": [
"opendes-public-usa-dataset-open-test-data"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"data": {
"Parameters": [
{
"index": 0.0,
"dataObjectParameter": "opendes:master-data--Wellbore:5171:1682356584489954",
"parameterKindID": "osdu:wks:master-data--Wellbore:1.0.0",
"title": "SchemaUpgradeSource"
}
]
},
"tags": {}
}
For detailed documentation on crafting JOLT configurations refer to the OSDU JOLT CheatSheet
Exceptions : TBD
2. Rollback
The rollback service allows you to undo the upgrade of a record. By using the version number in the activity record, you can revert a record back to its previous state. Activity record id is the only parameter to this service.
Header :
| Attribute | Value |
|---|---|
| data-partition-id | Example - opendes |
Request :
| Attribute | Value |
|---|---|
| id | Activity record id that needs to be reverted |
Sample Request :
{
"id":"opendes:work-product--Activity:SchemaUpgrade-28821"
}
Response :
Indicated by string Success
3. Reference value upgrade
This service enables the upgrading of a particular reference value in the data platform. Note : List of record id's to be provided only for initial version of this service.
Configuration :
Configuration file provides information on refrence value type, lookup values that have to be replaced, instructions to find the reference value in OSDU records.
Configuration file of type ReferenceValueUpgradeLookUp.1.0.0.json has to be updated for each reference value upgrade. For example VerticalMeasurementPath upgrade would require the following.
https://community.opengroup.org/osdu/data/data-definitions/-/blob/v0.18.1/ReferenceValues/Manifests/reference-data/LOCAL/ReferenceValueUpgradeLookUp.1.0.0.json
{
"kind": "osdu:wks:Manifest:1.0.0",
"ReferenceData": [
{
"id": "{{NAMESPACE}}:reference-data--ReferenceValueUpgradeLookUp:VerticalMeasurementPath",
"kind": "osdu:wks:reference-data--ReferenceValueUpgradeLookUp:1.0.0",
"acl": {
"owners": [
"{{DATA_OWNERS_GROUP}}"
],
"viewers": [
"{{DATA_VIEWERS_GROUP}}"
]
},
"legal": {
"legaltags": [
"{{LEGAL_TAG}}"
],
"otherRelevantDataCountries": [
"{{ISO_3166_ALPHA_2_CODE}}"
]
},
"data": {
"Name": "VerticalMeasurementPath",
"Description": "Reference value upgrade look-up table and usage references for VerticalMeasurementPath.",
"Code": "VerticalMeasurementPath",
"LookUp": {
"{{NAMESPACE}}:reference-data--VerticalMeasurementPath:ELEV:": {
"SupersededBy": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:TrueVerticalHeight:"
},
"{{NAMESPACE}}:reference-data--VerticalMeasurementPath:MD:": {
"SupersededBy": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:MeasuredDepth:"
},
"{{NAMESPACE}}:reference-data--VerticalMeasurementPath:TVD:": {
"SupersededBy": "{{NAMESPACE}}:reference-data--VerticalMeasurementPath:TrueVerticalDepth:"
}
},
"UsingKinds": {
"osdu:wks:master-data--Coring:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--HoleSection:1.1.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--IsolatedInterval:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--PerforationInterval:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--PerforationJob:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--ReferenceLevel:1.0.0": [
{
"Path": "data.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--RockSample:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--SeismicAcquisitionSurvey:1.2.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--Well:1.0.0": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--Well:1.1.0": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--Well:1.2.0": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--WellPlanningWellbore:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:master-data--Wellbore:1.0.0": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--Wellbore:1.1.0": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--Wellbore:1.1.1": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--Wellbore:1.2.0": [
{
"Path": "data.VerticalMeasurements[].VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QueryNested:"
}
],
"osdu:wks:master-data--WellboreOpening:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--GeoReferencedImage:1.0.0": [
{
"Path": "data.EmbeddedReferenceLevel.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--GeoReferencedImage:1.1.0": [
{
"Path": "data.EmbeddedReferenceLevel.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--PPFGDataset:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--RockSampleAnalysis:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--RockSampleAnalysis:1.1.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellLog:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellLog:1.1.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
},
{
"Path": "data.SeismicReferenceElevation.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellLog:1.2.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
},
{
"Path": "data.SeismicReferenceElevation.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreIntervalSet:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreMarkerSet:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreMarkerSet:1.1.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreMarkerSet:1.2.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreMarkerSet:1.2.1": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreTrajectory:1.0.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
],
"osdu:wks:work-product-component--WellboreTrajectory:1.1.0": [
{
"Path": "data.VerticalMeasurement.VerticalMeasurementPathID",
"SearchModeID": "{{NAMESPACE}}:reference-data--DiscoverabilityBySearch:QuerySimple:"
}
]
},
"Source": "Workbook Authoring/ReferenceValueUpgradeLookUp.1.0.0.xlsx; commit SHA be89c03a.",
"CommitDate": "2022-11-09T11:59:41+01:00"
}
}
Header :
| Attribute | Value |
|---|---|
| data-partition-id | Example - opendes |
Request :
| Attribute | Value |
|---|---|
| id | Specifies the reference value to be upgraded |
| KindList | List of kinds that contains the specified reference value and record id's of these kind. field to be deprecated |
Sample Request :
{
"id":"opendes:reference-data--ReferenceValueUpgradeLookUp:VerticalMeasurementPath",
"kindlist":[{
"kind": "osdu:wks:master-data--WellPlanningWellbore:1.0.0",
"id": [
"opendes:master-data--WellPlanningWellbore:wellplaningwellboreWD_autotest5439222"
]
}, {
"kind": "osdu:wks:master-data--Wellbore:1.0.0",
"id": [
"opendes:master-data--Wellbore:5218"
]
}]
}
Response :
| Attribute | Value |
|---|---|
| Activity:1.1.0 | The response consists of an Activity record that includes the record IDs that were upgraded and the version number of each record before the upgrade. |
Sample Response :
{
"id": "opendes:work-product--Activity:SchemaUpgrade-68974",
"kind": "osdu:wks:work-product-component--Activity:1.1.0",
"acl": {
"viewers": [
"data.default.viewers@opendes.contoso.com"
],
"owners": [
"data.default.viewers@opendes.contoso.com"
]
},
"legal": {
"legaltags": [
"opendes-public-usa-dataset-open-test-data"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"data": {
"Parameters": [
{
"index": 0.0,
"dataObjectParameter": "opendes:master-data--WellPlanningWellbore:wellplaningwellboreWD_autotest5439222:1684760345614614",
"parameterKindID": "osdu:wks:master-data--WellPlanningWellbore:1.0.0",
"title": "SchemaUpgradeSource"
},
{
"index": 1.0,
"dataObjectParameter": "opendes:master-data--Wellbore:5218:1684760346591707",
"parameterKindID": "osdu:wks:master-data--Wellbore:1.0.0",
"title": "SchemaUpgradeSource"
}
]
},
"tags": {}
}