Update assets - Precisely Data Integrity Suite

Data Integrity Suite APIs

Product

Data_Integrity

Spatial_Analytics

Data_Enrichment

geo_addressing_1

Services

Spatial Analytics

Data Enrichment

Geo Addressing

ft:title

Data Integrity Suite APIs

ft:locale

en-US

PublicationType

pt_developer

copyrightfirst

2023

copyrightlast

2026

Updates existing assets in the Data Catalog.

The PATCH Assets method allows you to update existing assets in the Data Catalog. This method follows the JSON Patch standard (RFC 6902), which provides a structured way to describe changes to a JSON document.

Warning: This method uses JSON Patch operations, not a simple merge operation. Understanding the difference is essential to avoid unintended data loss.

HTTP

PATCH https://hostname/v2/catalog/assets

Understanding JSON Patch

JSON Patch is a format for describing changes to a JSON document. It consists of an array of operation objects, where each operation has:

op: The operation type (add, remove, replace, copy, move, or test)
path: A JSON Pointer that indicates where to apply the operation
value: The value to use (for add, replace operations)
from: Source path (for copy, move operation)

Key Difference from Regular PATCH

A regular patch is a simple merge operation. This is not supported by the PATCH Assets method. The PATCH Assets method implements the JSON patch standard.

The first example illustrates a simple merge operation. The method does not support the simple marge operation.

Simple merge operation (not supported)

This example illustrates a simple merge operation, which is not supported by the method.

{
  "id": "65f00e903d974a9332140bf1",
  "properties": [
    {"name": "Name", "value": "New Name"}
  ]
}

JSON patch standard (supported)

This example illustrates implementation of the JSON patch standard operation, which is supported by the method.

{
  "id": "65f00e903d974a9332140bf1",
  "patch": [
    {
      "op": "replace",
      "path": "/properties/0/value",
      "value": "New Name"
    }
  ]
}

Request

Header keys

Key	Required	Type	Description
x-batch	No	boolean	Enable asynchronous batch processing for large asset update operations. When true, returns HTTP 202 (Accepted) with execution tracking ID instead of HTTP 200 (OK) with updated assets. Use for more than 100 assets or when updates trigger expensive recalculations (display values, calculated fields, lineage aggregation). Batch mode processes updates in chunks of optimal size based on payload.

Request body

The request body contains an array of contains an array of objects that update one or more assets. Each array item corresponds to an asset and that contains from the following properties.

Ancestors	Property	Required	Type	Description
	id	Yes	string	Object ID for asset (`ObjectId` format, matches `^[a-fA-F\d]{24}$`).
	patch	Yes	array(object)	Array of JSON Patch operations.
patch	op	Yes	string	Designates the update operation: `add` `remove` `replace` `copy` `move` `test`
patch	path	Yes	string	JSON Pointer path to the field.
patch	value	Yes	any	Value for `add` and `replace` operations.
patch	from	Yes	string	Source path for `copy` and `move` operations.
	triggerWorkflow	No	boolean	Default is true. Set to false to skip workflow triggers.

Request body example

{
   "id": "65f00e903d974a9332140bf1",
   "patch": [
     {
       "op": "replace",
       "path": "/properties",
       "value":{
         "name": "Name",
         "value": "Sherlock_Mssql-08March2024"
       }
       "value":{
         "name": "Description",
         "value": "Test Description"
       }
     }
   ]
}

Response

Response body

Example status code responses for this method are shown here. To view the response schemas, you can download the Data Catalog APIs Open API Specification from the Precisely Developer Portal..

Response body properties

Ancestors	Property	Required	Type	Description
	data		array(object)	Data envelope for response.
data	id	No	string	Format: `objectId` Pattern: `^[a-fA-F\d]{24}$`
data	parentId	No	string	Format: `objectId` Pattern: `^[a-fA-F\d]{24}$`
data	assetTypeId	No	string	Format: `objectId` Pattern: `^[a-fA-F\d]{24}$`
data	xref	No	array
data	scoresValues	No
data	scoresUpdated	No
data	counter	No	object
data/counter	value	Yes	number
data/counter	valueWithPrefix	No	string
data	color	No	string
data	class	No	string	This property is an enumerated string type (enum) set to one of these values: `Business` `Model` `Policy` `Reference` `Technical` `Rule` `Diagram` `Generic` `Configuration` `Domain` `Internal`
data	properties	No	array
data	tags	No	array
data	displayValue	No	string	Maximum length: 100 characters
data	assetTypeName	No	string
data	path	No	array
data	assetGroups	No	array
data	semanticType	No	object
data/semanticType	qualifier	Yes	string
data/semanticType	overridden	No	boolean	This property may be set to `true` or `false`.
data/semanticType	updatedAt	No	string	Format: `date-time`
data	createdBy	No	string
data	createdAt	No	string	Format: `date-time`
data	updatedBy	No	string
data	updatedAt	No	string	Format: `date-time`
data	metrics	No	array
data	assetTypeXrefs	No	array
data	isPlaceholder	No	boolean	This property may be set to `true` or `false`.
data	keyPath	No	string
data	level	No	number
data	displayPath	No	string
data	location	No	string
data	isLeaf	No	boolean	This property may be set to `true` or `false`.

Response examples

Examples

{
      "data": [
            {
                  "id": "fEdE078426900844f0944Ecc",
                  "assetTypeId": "d3AbCeBE2a1F760f22FCc78F",
                  "class": "Technical",
                  "createdBy": "Sample User",
                  "createdAt": "2024-10-01T07:51:41.666Z",
                  "updatedBy": "Sample User",
                  "updatedAt": "2004-10-06T08:44:23.634Z",
                  "xref": [
                        "Sample xref"
                  ],
                  "color": "Sample color"
            }
      ],
      "links": {
            "self": "https://api.cloud.precisely.com/assets"
      }
}

{
  "links": {
    "self": "https://example.com/",
    "next": "https://example.com/",
    "prev": "https://example.com/"
  },
  "errors": [
    {
      "id": "string",
      "status": 0,
      "code": "string",
      "detail": "string",
      "source": {
        "additionalProp1": {}
      }
    }
  ],
  "data": {}
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Bad Request"
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable"
}

{
  "statusCode": 504,
  "error": "Gateway Timeout",
  "message": "Request timeout"
}

Using this method

Common operations

Replaces an existing value at the specified path.

{
  "op": "replace",
  "path": "/fieldName",
  "value": "new value"
}

Adds a new value. For arrays, you can specify an index or use - to append.

{
  "op": "add",
  "path": "/xref",
  "value": "new-xref-value"\
}

Removes a value at the specified path.

{
  "op": "remove",
  "path": "/fieldName"
}

Tests that a value at the path is equal to the specified value. Useful for conditional updates.

{
  "op": "test",
  "path": "/properties/0/name",
  "value": "Name"
}

Risky method: Delete unspecified properties

This example replaces the properties array and deletes all field values that are not explicitly specified. This is considered risky because it deletes all properties except those specified.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "replace",
        "path": "/properties",
        "value": [
          {
            "name": "Name",
            "value": "New Name"
          },
          {
            "name": "Description",
            "value": "New Description"
          }
        ]
      }
    ]
  }
]

After the completion this operation completes, the updated asset will have only the Name and Description properties. All other properties (such as Owner, Status, CreateDate will be deleted. The next section describes a safer method.

Recommended method: Update properties by index

To update a single property without affecting others, use an indexed path, as described in these examples.

Examples

This example updates only the value of the property at index 0. All other properties remain unchanged.

[
  {
    {
      "id": "65f00e903d974a9332140bf1",
      "patch": [
        {
          op": "replace",
          "path": "/properties/0/value",
          "value": "Updated First Property Value"
        }
    ]
  }
]

This example updates the values at indices 0, 1, and 3. Properties at indices 2, 4, 5, etc. remain unchanged

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "replace",
        "path": "/properties/0/value",
        "value": "Updated Name"
      },
      {
        "op": "replace",
        "path": "/properties/1/value",
        "value": "Updated Description"
      },
      {
        "op": "replace",
        "path": "/properties/3/value",
        "value": "Updated Owner"
      }
    ]
  }
]

How to find property indices

To update a property by index, you need to know its position in the properties array. To do this, first use GET /v2/catalog/assets/{id} to fetch the assets, then inspect the properties area to find the index of the property that you want to update.

Say you want to update owner and you get the following response:

{
  "id": "65f00e903d974a9332140bf1",
  "properties": [
    { "name": "Name", "value": "Current Name" }, // Index 0
    { "name": "Description", "value": "Current Desc" }, // Index 1
    { "name": "Status", "value": "Active" }, // Index 2
    { "name": "Owner", "value": "John Doe" } // Index 3
  ]
}

Owner is the third index, so you would use the path /properties/3/value.

Adding new properties

Appends a new property to the properties array by not specifying an index.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "add",
        "path": "/properties",
        "value": {
          "name": "NewField",
          "value": "New Field Value"
        }
      }
    ]
  }
]

Inserts a new property at index 2, shifting existing properties at indices to the right.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
     {
       "op": "add",
       "path": "/properties/2",
       "value": {
       "name": "MiddleField",
       "value": "Inserted at index 2"
       }
     }
   ]
  }
]

Removing properties

Removes the property at index 2. Properties after index 2 shift left.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "remove",
        "path": "/properties/2"
      }
    ]
  }
}

Removes all properties from the asset.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
     {
       "op": "remove",
       "path": "/properties"
     }
    ]
  }
]

Tag updates

Replaces all tags with the new set. Previous tags are deleted.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
       "op": "replace",
       "path": "/tags",
       "value": [
         {
           "tagTypeId": "64c5be29903737baddf16f8c",
           "value": "production"
         },
         {
           "tagTypeId": "64c5be29903737baddf16f8d",
           "value": "critical"
         }
       ]
      }
    ]
  }
]

Appends a new tag to the existing tags array.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "add",
        "path": "/tags",
        "value": {
          "tagTypeId": "64c5be29903737baddf16f8c",
          "value": "new-tag"
        }
      }
    ]
  }
]

Updates the value of the tag at index 0.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
     {
      "op": "replace",
      "path": "/tags/0/value",
      "value": "updated-tag-value"
     }
    ]
  }
]

Removes the tag at index 1.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "remove",
        "path": "/tags/1"
      }
    ]
  }
]

Advanced examples

Updates the first property value.
Adds a new xref.
Changes the asset color.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "replace",
        "path": "/properties/0/value",
        "value": "Updated Name"
      },
      {
        "op": "add",
        "path": "/xref",
        "value": "additional-xref"
      },
      {
        "op": "replace",
        "path": "/color",
        "value": "#FF5733"
      }
    ]
  }
]

Updates three different assets in a single API call. Each asset gets its own set of patch operations.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "replace",
        "path": "/properties/0/value",
        "value": "Asset 1 Updated"
      }
    ]
  },
  {
    "id": "65f00e903d974a9332140bf2",
    "patch": [
      {
        "op": "replace",
        "path": "/properties/0/value",
        "value": "Asset 2 Updated"
      }
    ]
  },
  {
    "id": "65f00e903d974a9332140bf3",
    "patch": [
      {
        "op": "replace",
        "path": "/properties/1/value",
        "value": "Asset 3 Description Updated"
      }
    ]
  }
]

Tests if the property at index 2 has value "Draft", and if so, replaces it with "Published". If the test fails, the entire patch operation fails.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
       "op": "test",
       "path": "/properties/2/value",
       "value": "Draft"
      },
      {
       "op": "replace",
       "path": "/properties/2/value",
       "value": "Published"
      }
    ]
  }
]

Updates the semantic type qualifier and marks it as manually overridden.

[
  {
     "id": "65f00e903d974a9332140bf1",
     "patch": [
      {
       "op": "replace",
       "path": "/semanticType/qualifier",
       "value": "PII.EMAIL"
      },
      {
        "op": "replace",
        "path": "/semanticType/overridden",
        "value": true
      }
    ]
  }
]

Updates the counter value for the asset.

[
  {
     "id": "65f00e903d974a9332140bf1",
     "patch": [
      {
       "op": "replace",
       "path": "/semanticType/qualifier",
       "value": "PII.EMAIL"
      },
      {
        "op": "replace",
        "path": "/semanticType/overridden",
        "value": true
      }
    ]
  }
]

Note: You cannot update /counter/valueWithPrefix directly. It is computed from the value.

Update xref array

These examples demonstrate various ways to manage the xref (external reference) array.

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "add",
        "path": "/xref",
        "value": "new-external-reference"
      }
    ]
  }
]

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "replace",
        "path": "/xref/0",
        "value": "updated-external-reference"
      }
    ]
  }
]

[
  {
    "id": "65f00e903d974a9332140bf1",
    "patch": [
      {
        "op": "remove",
        "path": "/xref/1"
      }
    ]
  }
]

Common issues

Using /properties path instead of /properties/0/value deletes all other properties.

DANGER

This deletes ALL other properties.

{
  "op": "replace",
  "path": "/properties",
  "value": [
    {
      "name": "Name",
      "value": "New Name"
    }
  ]
}

Correct: This updates only the first property.

{
  "op": "replace",
  "path": "/properties/0/value",
  "value": "New Name"
}

Problem: Properties array indices can shift after add/remove operations.

Solution: Always fetch fresh data before patching, or apply all operations in the same request.

When replacing entire objects, you must include all required fields.

Wrong: Missing required 'name' field.

{
 "op": "add",
 "path": "/properties",
 "value": { "value": "Some Value" }
}

Problem: Some fields are computed and cannot be updated.

Fields you cannot update:

/counter/valueWithPrefix (computed from /counter/value)
/createdBy
/createdAt
/id
/assetTypeId