Examples are usually better than most other documentations. This page will provide many hands-on examples. In order to have it easier to understand, all examples are written in JSON - but work likewise as XML.

The xml syntax is identical to the JSON one. Please have also a look at the attached Article_00.xml file which contains a full example of a write payload in the XML format. See also section Full Example.

Create or Update

The payload for create and update is essentially the same. The only difference is how an already existing item is handled. In case of a create call, existing items will return a corresponding error, in case of an update they will be updated.
There are query parameters to change this behavior for update and create. Please see the request definitions on REST Object API Write.

General Examples

This section shows some general examples which basically work for all entities which are defined in the repository. For ease of understanding the examples are also made with the "Item" entity, but as mentioned, a generic by nature.

Simple fields on the root level of the entity

This example has no identifier, so the identifier will be generated in case it's used for create. In case it's used for update, the identifier needs to be provided in the request URL anyway.

{
  "catalog": {
    "_key": {
      "_externalId": "'ObjectApiWriterTest'"
    }
  },
  "gtin": "123456789",
  "orderUnit": {
    "_code": "C62"
  },
  "deliveryTime": 42.42
}

Remove a sub-entity record

This example will remove the english language sub-entity record

{
  "lang": [
    {
      "_changeType": "remove",
      "_qualification": {
        "language": {
          "_code": "en"
        }
      }
    }
  ]
}

Item, Product, Variants

Create prices for an item

The prices sub-entity has a small specialty. Contrary to the repository/meta definition, the object api does not have the "validAt" qualification. The object api used the validFrom and validTo qualifications instead.

This example creates an item with three purchase price records

{
  "pricePurchase": [
    {
      "_qualification": {
        "supplier": {
          "_code": "MAIN_SUPPLIER"
        },
        "type": {
          "_code": "net_list"
        },
        "currency": {
          "_code": "EUR"
        },
        "territory": {
          "_code": "DE"
        },
        "validFrom": "2021-01-01",
        "validTo": "2021-05-28"
      },
      "value": [
        {
          "_qualification": {
            "lowerBound": 1.0
          },
          "amount": 11.11
        }
      ]
    },
    {
      "_qualification": {
        "supplier": {
          "_code": "MAIN_SUPPLIER"
        },
        "type": {
          "_code": "net_list"
        },
        "currency": {
          "_code": "EUR"
        },
        "territory": {
          "_code": "DE"
        },
        "validFrom": "2021-05-29",
        "validTo": "2021-09-30"
      },
      "value": [
        {
          "_qualification": {
            "lowerBound": 1.0
          },
          "amount": 22.22
        }
      ]
    },
    {
      "_qualification": {
        "supplier": {
          "_code": "MAIN_SUPPLIER"
        },
        "type": {
          "_code": "net_list"
        },
        "currency": {
          "_code": "EUR"
        },
        "territory": {
          "_code": "DE"
        },
        "validFrom": "2021-10-01",
        "validTo": "2021-12-31"
      },
      "value": [
        {
          "_qualification": {
            "lowerBound": 1.0
          },
          "amount": 33.33
        }
      ]
    }
  ]
}

Update a single price

To update the amount of a single price, you need to specify the full list of qualifications in order to uniquely identify the record to update.

{
  "pricePurchase": [
    {
      "_qualification": {
        "supplier": {
          "_code": "MAIN_SUPPLIER"
        },
        "type": {
          "_code": "net_list"
        },
        "currency": {
          "_code": "EUR"
        },
        "territory": {
          "_code": "DE"
        },
        "validFrom": "2021-05-29",
        "validTo": "2021-09-30"
      },
      "value": [
        {
          "_qualification": {
            "lowerBound": 1.0
          },
          "amount": 44.44
        }
      ]
    }
  ]
}

Assign an item to a structure group

The ArticleStructureMap sub-entity is not available in the object api. It's successor, the ArticleStructureGroupMap is. To make it easier for everyone, we omit the Structure as a qualification field. It would have redundant since the StructureGroup is already a qualification field.

This element assigns the item, product or variant to "MyNode" within the "MyStructure" structure system. Please note that the StructureGroup field has no enumeration, therefor we can not use the code syntax for it but must use the entity_items

{
  "structureGroupMap": [
    {
      "_qualification": {
        "structureGroup": {
          "_externalId": "'MyNode'@'MyStructure'"
        }
      }
    }
  ]
}

You can also combine this with "_changeType"="remove" which would remove the assignment.

Set Attribute Values (based on Structure Attributes)

In case the structure is a maintenance structure, the structure can define attributes which then can have actual values on the item level. Here is an example how to set the Attribute value with a mapping to the structure feature.

{
   "attribute": [
	{
		"_qualification": {
			"nameInKeyLang": "Product name"
		},
		"identifier": "BAA316003",
		"datatype": {
			"_code": "String"
		},
		"value": [
			{
				"_qualification": {
					"language": {
						"_code": "eng"
					},
					"identifier": "DEFAULT"
				},
				"value": "spirits. Mrs. Bennet invited him to dine with them; but, with many expres"
			}
		],
		"structureGroupAttributeMap": [
			{
				"_qualification": {
					"structureGroup": {
						"_entity": "StructureGroup",
						"_externalId": "'AKL837004'@'ECLASS-6.1'"
					}
				},
				"structureAttribute": {
					"_key": {
						"_entity": "StructureFeature",
						"_externalId": "'BAA316003'@'ECLASS-6.1'"
					}
				}
			}
		]
	}
}

Add characteristic records with child records

This example creates/updates an item's characteristic values.

The characteristic model which has been used looks roughly like this:
AnimalIngredients (Characteristic, Root)
|
|-- CertificateDown (1:1 for AnimalIngredient: DOWN)
| |-- CertDownZert (1:1 for CertificateDown: OTHER)
| |-- CertDownDesc (1:1 for CertificateDown: OTHER)
| |-- CertDownExpDate (1:1 for CertificateDown: OTHER)

Characteristic values are hierarchical by nature, but the repository model for them is different. The normal generic logic can not be used here as it would be way too complicated.

The recordKey qualification can be omitted in case there is only one record for this characteristic. In this case the default (0000.0000.RK) is used.
The parentRecordKey can always be omitted as the parent is defined by the hierarchical structure itself
The language qualification can be omitted in case the value is not language dependent. (In case you want to provide it anyway, please use zxx as language code (this means "language independent")
All validations which are defined in the validation expressions are executed and will be reported in the result object!

{
  "_characteristicRecords": [
    {
      "_qualification": {
        "characteristic": {
          "_code": "AnimalIngredient"
        }
      },
      "_recordLang": [
        {
          "values": [
            {
              "_code": "Down"
            }
          ]
        }
      ],
      "_children": [
        {
          "_qualification": {
            "characteristic": {
              "_code": "CertDown"
            }
          },
          "_recordLang": [
            {
              "values": [
                {
                  "_code": "Other"
                }
              ]
            }
          ],
          "_children": [
            {
              "_qualification": {
                "characteristic": {
                  "_code": "CertDownExpDate"
                }
              },
              "_recordLang": [
                {
                  "values": [
                    "1977-05-28"
                  ]
                }
              ]
            },
            {
              "_qualification": {
                "characteristic": {
                  "_code": "CertDownZert"
                }
              },
              "_recordLang": [
                {
                  "values": [
                    {
                      "_path": "archiveSubFolder/testMimeValue.jpg"
                    }
                  ]
                }
              ]
            },
            {
              "_qualification": {
                "characteristic": {
                  "_code": "CertDownDesc"
                }
              },
              "_recordLang": [
                {
                  "values": [
                    "Language Independent Description"
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Remove a root characteristic record

To remove a characteristic record of an item, use the _changeType attribute. It will remove also all children of this record.

{
  "catalog": {
    "_code": "ObjectApiWriterTest"
  },
  "_characteristicRecords": [
    {
      "_changeType" : "remove",
      "_qualification": {
        "characteristic": {
          "_code": "AnimalIngredient"
        },
        "recordKey": "0000.0000.RK"
      }
    }
  ]
}

Structures

Create a new child node below the "MyParent" node.

The structure for groups is the same as the catalog for items. Their container object. It can be omitted depending on how the object api is called. We left it in this example for educational purposes.

{
  "structure": {
    "_entity": "Structure",
    "_externalId": "'MyStructure'"
  },
  "parent": {
    "_entity": "StructureGroup",
    "_externalId": "'MyParent'@'MyStructure'"
  }
}

Full Example

This example contains a value for pretty much all fields which we have defined in the repository, this includes GDSN fields. However, as the values are artificially generated, they do not make too much sense, but at least persisting this object will not lead to an error (assuming all dependencies are met).

It's merely here to give a big example as how the object api looks like. We have the same data created once as JSON document, and once as XML document. The xml document has a root element named <_data>, json obviously has no name of the root object.

Full Example in XML: Article_00.xml

Full Example in JSON: Article_00.json