Appendix A: SerializationModifier Examples

Description

SerializationModifiers are only allowed for GET and PATCH operations.

GET operations can use any combination of SerializationModifiers.

POST operations create new resources using the input content.

PUT operations replace existing resources using the input content.

POST and PUT use the regular serialization. The client creates the input content as needed, so that no further SerializationModifiers need to be used.

PATCH operations may use the regular serialization, the metadata serialization, or the ValueOnly- serialization. The SerializationModifier Core is not used. The resources in the input content must already exist on the server and are replaced one by one accordingly. If one of the resources in the input content does not exist, no changes will be made on the server. “Resource exists” means, that the type of a SubmodelElement is the same in the input content and on the server. For example, a property may only be replaced by a property; elements of a SubmodelElementCollection or SubmodelElementList can only be replaced if they already exist on the server. A SubmodelElementList with five elements cannot be patched with a SubmodelElementList with more than five elements. A SubmodelElementList with five elements can be patched with a SubmodelElementList with less than five elements since all required elements starting from index 0 already exist.

Note: values remain unchanged with content=metadata.

Examples for GET Operations

Deep (default) Core

Normal
(default)

If applied to the Submodel:

{
  "modelType": "Submodel",
  "id": "http://i40.customer.com/type/1/1/7A7104BDAB57E184",
  "idShort": "TechnicalData",
  "semanticId": {
    "keys": [ {
        "type": "GlobalReference",
        "value": "0173-1#01-AFZ615#016"
    } ],
    "type": "ExternalReference"
  },
  "submodelElements": [ {
    "modelType":  "SubmodelElementCollection",
    "idShort": "RotationSpeed",
    "semanticId": {
      "keys": [ {
          "type": "GlobalReference",
          "value": "http://purl.org/iot/vocab/iot-taxonomy-lite#RotationalSpeed"
      } ],
      "type": "ExternalReference"
    },
    "value": [ {
        "modelType": "Property",
        "idShort": "MaxRotationSpeed",
        "category": "PARAMETER",
        "semanticId": {
          "keys": [ {
              "type": "ConceptDescription",
              "value": "0173-1#02-BAA120#008"
          } ],
          "type": "ExternalReference"
        },
        "valueType": "xs:int",
        "value": "5000"
      } ]
  } ]
}

If applied to the Submodel:

{
  "modelType": "Submodel",
  "id": "http://i40.customer.com/type/1/1/7A7104BDAB57E184",
  "idShort": "TechnicalData",
  "semanticId": {
    "keys": [ {
        "type": "GlobalReference",
        "value": "0173-1#01-AFZ615#016"
    } ],
    "type": "ExternalReference"
  },
  "submodelElements": [ {
    "modelType":  "SubmodelElementCollection",
    "idShort": "RotationSpeed",
    "semanticId": {
      "keys": [ {
          "type": "GlobalReference",
          "value": "http://purl.org/iot/vocab/iot-taxonomy-lite#RotationalSpeed"
      } ],
      "type": "ExternalReference"
    }
  } ]
}

Metadata

If applied to the Submodel (no “Level” modifier for “Metadata”):

{
  "modelType": "Submodel",
  "id": "http://i40.customer.com/type/1/1/7A7104BDAB57E184",
  "idShort": "TechnicalData",
  "semanticId": {
    "keys": [ {
        "type": "GlobalReference",
        "value": "0173-1#01-AFZ615#016"
    } ],
    "type": "ExternalReference"
  }
}

If applied to the SubmodelElementCollection, i.e., idShortPath “RotationSpeed”:

{
    "modelType":  "SubmodelElementCollection",
    "idShort": "RotationSpeed",
    "semanticId": {
      "keys": [ {
          "type": "GlobalReference",
          "value": "http://purl.org/iot/vocab/iot-taxonomy-lite#RotationalSpeed"
      } ],
      "type": "ExternalReference"
    }
}

If applied to the Property, i.e. idShortPath “RotationSpeed.MaxRotationSpeed”:

{
   "modelType": "Property",
   "idShort": "DocumentId",
   "category": "PARAMETER",
   "semanticId": {
       "keys": [ {
           "type": "GlobalReference",
           "value": "0173-1#02-BAA120#008"
       } ] ,
       "type": "ExternalReference"
   },
   "valueType": "xs:int"
}

Value

If applied to the Submodel:

{
  "RotationSpeed": {
    "MaxRotationSpeed": 5000
  }
}

If applied to the SubmodelElementCollection, i.e., idShortPath “RotationSpeed”:

{
  "MaxRotationSpeed": 5000
}

If applied to the Property, i.e. idShortPath “RotationSpeed.MaxRotationSpeed”:

5000

If applied to the Submodel:

{
  "RotationSpeed": {}
}

If applied to the SubmodelElementCollection, i.e., idShortPath “RotationSpeed”:

{
  "MaxRotationSpeed": 5000
}

If applied to the Property, i.e. idShortPath “RotationSpeed.MaxRotationSpeed”:

5000

Reference

Not allowed, see Modifier Constraints:

“The combination of Level=Deep and Content=Reference is not allowed.”

If applied to the Submodel:

{
  "keys": [ {
     "type": "Submodel",
     "value": "http://i40.customer.com/type/1/1/7A7104BDAB57E184"
  } ],
  "type": "ModelReference"
}

If applied to the SubmodelElementCollection, i.e. idShortPath "RotationSpeed":

{
  "keys": [ {
     "type": "Submodel",
     "value": "http://i40.customer.com/type/1/1/7A7104BDAB57E184"
  }, {
     "type": "SubmodelElementCollection",
     "value": "RotationSpeed"
  } ],
  "type": "ModelReference"
}

If applied to the Property inside the SubmodelElementCollection, i.e. idShortPath “RotationSpeed.MaxRotationSpeed”:

{
  "keys": [ {
     "type": "Submodel",
     "value": "http://i40.customer.com/type/1/1/7A7104BDAB57E184"
  }, {
     "type": "SubmodelElementCollection",
     "value": "RotationSpeed"
  }, {
     "type": "Property",
     "value": "MaxRotationSpeed"
  }],
  "type": "ModelReference"
}

Path

If applied to the Submodel:

Note: IdShortPaths always start at the first SubmodelElement.

[
  "RotationSpeed",
  "RotationSpeed.MaxRotationSpeed"
]

If applied to the SubmodelElementCollection:

[
  "RotationSpeed",
  "RotationSpeed.MaxRotationSpeed"
]

If applied to the Property inside the SubmodelElementCollection:

[
  "RotationSpeed.MaxRotationSpeed"
]

If applied to the Submodel:

Note: The SubmodelElementCollection “RotationSpeed” is the only direct child of the Submodel, therefore, it’s the only entry.

[
  "RotationSpeed"
]

If applied to the SubmodelElementCollection:

[
  "RotationSpeed",
  "RotationSpeed.MaxRotationSpeed"
]

If applied to the Property inside the SubmodelElementCollection:

[
  "RotationSpeed.MaxRotationSpeed"
]

Examples for PATCH Operations

Deep (default)

Normal (default)

If applied to the Submodel:

{
  "modelType": "Submodel",
  "id": "http://i40.customer.com/type/1/1/7A7104BDAB57E184",
  "idShort": "TechnicalData",
  "semanticId": {
    "keys": [ {
        "type": "GlobalReference",
        "value": "0173-1#01-AFZ615#016"
    } ],
    "type": "ExternalReference"
  },
  "submodelElements": [ {
    "modelType":  "SubmodelElementCollection",
    "idShort": "RotationSpeed",
        "semanticId": {
      "keys": [ {
          "type": "GlobalReference",
          "value": "http://purl.org/iot/vocab/iot-taxonomy-lite#RotationalSpeed"
      } ],
      "type": "ExternalReference"
    },
    "value": [ {
        "modelType": "Property",
        "idShort": "MaxRotationSpeed",
        "category": "PARAMETER",
        "semanticId": {
          "keys": [ {
              "type": "ConceptDescription",
              "value": "0173-1#02-BAA120#008"
          } ],
          "type": "ExternalReference"
        },
        "valueType": "xs:int",
        "value": "5000"
      } ]
  } ]
}

If applied to the SubmodelElementCollection, i.e. idShortPath RotationSpeed:

{
    "modelType":  "SubmodelElementCollection",
    "idShort": "RotationSpeed",
    "semanticId": {
      "keys": [ {
          "type": "GlobalReference",
          "value": "http://purl.org/iot/vocab/iot-taxonomy-lite#RotationalSpeed"
      } ],
      "type": "ExternalReference"
    },
    "value": [ {
        "modelType": "Property",
        "idShort": "MaxRotationSpeed",
        "category": "PARAMETER",
        "semanticId": {
          "keys": [ {
              "type": "ConceptDescription",
              "value": "0173-1#02-BAA120#008"
          } ],
          "type": "ExternalReference"
        },
        "valueType": "xs:int",
        "value": "5000"
   } ]
}

If applied to the Property, i.e. idShortPath RotationSpeed.MaxRotationSpeed:

{
  "modelType": "Property",
  "idShort": "MaxRotationSpeed",
  "category": "PARAMETER",
  "semanticId": {
    "keys": [ {
      "type": "ConceptDescription",
      "value": "0173-1#02-BAA120#008"
    } ],
    "type": "ExternalReference"
  },
  "valueType": "xs:int",
  "value": "5000"
}

Metadata

If applied to the Submodel:

{
  "modelType": "Submodel",
  "id": "http://i40.customer.com/type/1/1/7A7104BDAB57E184",
  "idShort": "TechnicalData"
}

If applied to the SubmodelElementCollection, i.e. idShortPath “RotationSpeed”:

{
    "modelType":  "SubmodelElementCollection",
    "idShort": "RotationSpeed",
    "semanticId": {
      "keys": [ {
          "type": "GlobalReference",
          "value": "http://purl.org/iot/vocab/iot-taxonomy-lite#RotationalSpeed"
      } ],
      "type": "ExternalReference"
    }
}

If applied to the Property, i.e. idShortPath “RotationSpeed.MaxRotationSpeed”:

{
  "modelType": "Property",
  "idShort": "MaxRotationSpeed",
  "category": "PARAMETER",
  "semanticId": {
    "keys": [ {
        "type": "ConceptDescription",
        "value": "0173-1#02-BAA120#008"
    } ],
    "type": "ExternalReference"
  }
}

Value

If applied to the Submodel:

{
  "RotationSpeed": {
    "MaxRotationSpeed": 5000
  }
}

If applied to the SubmodelElementCollection, i.e. idShortPath “RotationSpeed”:

{
  "MaxRotationSpeed": 5000
}

If applied to the Property, i.e. idShortPath “RotationSpeed.MaxRotationSpeed”:

5000