{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Table of Contents","description":"Accelerate E&P application development and protect your innovation by consuming our Data and Domain APIs / Platform APIs.","lang":"en-US","meta":[{"name":"robots","content":"noindex"}],"llmstxt":{"hide":true,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"table-of-contents","__idx":0},"children":["Table of Contents ",{"$$mdtype":"Tag","name":"a","attributes":{"name":"TOC"},"children":[]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#introduction"},"children":["Introduction"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#concepts"},"children":["Concepts"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#usage_guide"},"children":["Usage Guide"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#rdv_bootstraping"},"children":["Bootstrapping of RDV"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction ",{"$$mdtype":"Tag","name":"a","attributes":{"name":"introduction"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reference Data Management Service enables a centralized governance and management of reference data values. It provides all necessary APIs to fetch, create, update and search reference data values."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"concept","__idx":2},"children":["Concept ",{"$$mdtype":"Tag","name":"a","attributes":{"name":"concepts"},"children":[]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reference Data"]},": Reference data refers to the information about business objects managed in the OSDU Record catalog. These objects tend to be real-world things with natural identifiers.  They provide context to digital objects to identify and standardize their names, as in a controlled value list. They tend to refer to concepts that"," ","exist outside a company’s business processes."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reference Data Type"]},":  Some reference data values are supplied with the OSDU Data Platform. These are controlled for each reference data type by the level of governance established by the OSDU Forum. The level for a particular entity is defined in the schema definition for that entity using the custom property x-osdu-governance-model."," ","For example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json \"x-osdu-governance-model\": \"FIXED\" "]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The levels are defined as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["FIXED"]},": The values are pre-determined by agreement in the OSDU Forum"," ","This level of governance is usually used for reference data types that have short well-known lists and are highly"," ","benefited by interoperability between companies, or are required for the proper operation of the system. The list of reference values cannot be extended or changed, except by the governing authority/authorities itself."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OPEN"]},": A set of values agreed by the OSDU Forum, but companies may extend the list with custom values."," ","Custom values should not conflict with Forum values. This level of governance is used for reference data types that will benefit from some amount of interoperability but also are uncontrolled enough that companies can add their own values."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LOCAL"]},": The OSDU Forum makes no declaration about the values, though it may provide a starter list of reference data values to provide different entities for example."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Companies need to create their own value list. These reference data types have little benefit apart from interoperability, and agreed-upon values are hard to come by."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While creating bootstrapped RDVs following ACLs are used:-"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"#"},"children":["#"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"LOCAL"},"children":["LOCAL"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"FIXED/OPEN"},"children":["FIXED/OPEN"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Viewer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["data.referencedata-local.viewers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["data.referencedata.viewers"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Owner"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["data.referencedata-local.owners"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["data.referencedata.owners"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage-guide","__idx":3},"children":["Usage Guide ",{"$$mdtype":"Tag","name":"a","attributes":{"name":"usage_guide"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This service provides different APIs to create, update, search and retrieve reference data values. Additionally, this service puts a governance on the create and update operations on reference data values. For example, only below operations are possible:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create"]},":",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference data values of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]}," can only be created, using POST endpoint and using bootstrapped ACLs and legal tags as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#rdv_bootstraping"},"children":["Bootstrapping of RDV"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Users should be part of non-bootstrapped ACLs ie data.referencedata-local.owners to be able to create reference data values."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the record id is not supplied, service will create an id and use that for ingesting the record. For a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FIXED"]}," type, bootstrapping option is available."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update"]},":",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference data values of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]}," can only be updated using PUT endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference data of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," can only be updated using non-bootstrapped ACLs ie data.referencedata-local.owners/viewers and users should be part of non-bootstrapped ACLs ie data.referencedata-local.owners to be able to update reference data values."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Service also adds a tag 'rdvLocallyUpdated' and sets it's value as true for the records which are modified."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Name Alias"]},":",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Name alias can be added using PATCH endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/reference-data/v1/{id}/namealias"]}," for reference data values of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FIXED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["This API is meant for assigning Name alias to a given RDV. It will append the provided NameAlias object only if it's unique, in the already existing list."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Service also adds a tag 'nameAliasUpdated' and sets it's value as true for the records where name alias list is modified. Update of the existing AliasName will be done by this API."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retrieve reference data"]},": Reference data value can be retrieved using the reference data id."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Active/Inactive reference data"]},": A reference data record is an active record by default. It can be marked INACTIVE using PATCH endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/reference-data/v1/record/{id}/inactive"]}," for reference data values of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN(non-bootstrapped)"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]},". This API is meant for updating a reference data record with InactiveIndicator attribute, given a reference data value is no longer required. However, the user can reactivate the record, if required, by setting the value back to false using the same endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Search"]},": Reference data values can be searched using different query parameters such as Code/Name/AliasName/InactiveIndicator etc. User can supply multiple values for any of these filter attributes, and service will return OR-based search result for those values. Wild card search is also supported on the attribute values and on the kind value.This endpoint restricts the search to the records with AbstractReferenceType schema only."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": The CRS catalog extension needs to take care of below recommendation:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The data.id attribute should be  of the pattern ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{data.Kind}:{data.CodeSpace}::{data.Code}"]},"."," ","For example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/id-recommendation.d7a3d8e541ee355c20eb82cf947eb4c5e7830ec0cb5b434b4de4b815b799341a.cff9a875.jpg","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"bootstrapping-of-rdv","__idx":4},"children":["Bootstrapping of RDV ",{"$$mdtype":"Tag","name":"a","attributes":{"name":"rdv_bootstraping"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is a Reference Data bootstrap script which bootstraps all the RDVs present at this ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.opengroup.org/osdu/data/data-definitions/-/tree/master/ReferenceValues/Manifests/reference-data"},"children":["repository"]}," to all the available data partitions. However, for the RDV records whose name alias list was updated locally using the RDMS patch API, the name alias list pulled from community will be merged to the existing list (It will not overwrite the existing list). All the necessary ACLs and Legal tags required to create the reference data are also created using this script."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bootstrap Legal tag"]}," RDVs bootstrapping script also bootstrapping the legal tag would be used to create RDVs records. The Legal tag is created by using Compliance Service API, below is the payload to create a legal tag."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["URL:  <HOST>/api/legal/v1/legaltags"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"referencedata-legal\",\n  \"description\": \"Legal tag for reference data values\",\n  \"properties\": {\n    \"countryOfOrigin\": [\n      \"US\"\n    ],\n    \"contractId\": \"Unknown\",\n    \"originator\": \"OSDU\",\n    \"dataType\": \"Public Domain Data\",\n    \"securityClassification\": \"Public\",\n    \"personalData\": \"No Personal Data\",\n    \"exportClassification\": \"No License Required\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It will create legal tag with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name <tenant-name>-referencedata-legal"]}," in a given partition."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bootstrap ACL Groups"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Owner Group"]},": The RDV bootstrapping script bootstraps the Owner ACL group \"data.referencedata.owners\" which would be used to create ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FIXED"]}," and OPEN RDV records. The bootstrapping user (azure service principle) is the only member assigned to this group so that records can be created and updated by the script only."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Script also creates \"data.referencedata-local.owners\" which would be used to create ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]}," RDV records and update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]}," RDV records. The bootstrapping user and datalake.admins would be members assigned to this group, so that it would allow all datalake admin users to a specific partition to update their copy of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCAL"]}," values"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["URL: <HOST>/api/entitlements/v2/groups"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\"name\": \"data.referencedata.owners\",\n\"description\": \"Owners group for reference data values of FIXED and OPEN type\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Viewer Group"]},": The RDV bootstrapping scripts also bootstrap the Viewer ACL group \"data.referencedata.viewers\" which would be used to view RDVs records. The script also bootstraps the local viewer ACL group  \"data.referencedata-local.viewers\"  which would be used to view local RDVs records. The script also adds the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["users@{data-partition-id}.{domain}"]}," group as a member to this viewer group, so that all the users of that partition by default get the access to the \"data.referencedata.viewers\" group."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bootstrap RDVs"]},": After successful bootstrapping of Legal and ACL, the script will bootstrap the reference data values into all the partitions of a given environment. The RDVs records are created by using Storage API."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]}]},"headings":[{"value":"Table of Contents","id":"table-of-contents","depth":2},{"value":"Introduction","id":"introduction","depth":2},{"value":"Concept","id":"concept","depth":2},{"value":"Usage Guide","id":"usage-guide","depth":2},{"value":"Bootstrapping of RDV","id":"bootstrapping-of-rdv","depth":2}],"frontmatter":{"seo":{"title":"Table of Contents"}},"lastModified":"2025-12-09T04:18:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/solutions/data-workspace/tutorial/reference-data-service","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}