In stage 2 specifications a scope construct is often used for selecting multiple managed object instances. The scope construct, together with a so called base managed object instance, selects a set of object instances from the name-containment tree starting at the document root. This set contains some or all object instances name-contained by the base object instance. It may contain the base object itself. In operations, the base object instance and the scope construct are specified as an input parameter. In NRM control fragments, the base object instance is the object instance that name-contains the control object instance of the NRM control fragment, and the scope construct is an attribute of the control object instance. A filter construct is also often used in stage 2 specifications to select a subset of the managed object instances selected by the base managed object instance and scope construct. The filter is specified in operations as input parameter and in NRM control fragments as an attribute of a control object. When scoping and filtering is specified using NRM control fragments, no special considerations are required for the REST SS, since the scope construct and the filter are normal attributes of a managed object. When scoping and filtering is specified as part of the input parameters of an operation, however, it is necessary to define how to map these parameters in the REST SS.

Scoping may be supported by the HTTP GET method. It is not supported by any other method. The URI path component identifies the base resource. The URI query component shall be used for carrying the scope construct. Multiple query parameters shall be separated by an ampersand character ("&"). With one query parameter the base resource and all resources until the level indicated by the query parameter can be selected. When the value of the query parameter is set to infinite, the complete subtree starting at the base resource is selected. Two query parameters for scoping allow for more sophisticated selection methods. An example scoping method uses a "scopeType" and a "scopeLevel" query parameter. The allowed values are defined in Table 6.1.2-1.

Filtering may be supported by the HTTP GET method. It is not supported by any other method. The URI query component shall be used for carrying the filter expression. The name of the query parameter is "filter". Jex [21] shall be used for specifying the filter expression. The Jex expression is applied to a JSON document document constructed based on the following rules:

• The document element is the object identified by the path component of the target URI. If the path component of the target URI identifies the NRM root (see clause 4.4.4), then the element name of the document element shall be "nrmRoot". The "nrmRoot" element contains the element nodes coming from the top-level objects as its children.
• The document includes scoped objects only.
• The document is constructed with the scoped objects using the hierarchical response construction method defined in clause 6.1.4.

A valid XPath expression returns a flat list of selected resources. Name-contained resources included in the selected resources shall be removed before constructing the final response message according to clause 6.1.4. The Jex expression needs to be percent-encoded as described in Section 2 of RFC 3986 and Section 3.4 of RFC 3986. Note that NRM objects and NRM attributes are both mapped to element nodes. The children of an element node representing a NRM object are hence the NRM attributes of that NRM object or the name-contained NRM objects. This needs to be taken into account when constructing a location path for selecting element nodes representing NRM objects or NRM attributes.

When multiple resources are selected for retrieval by HTTP GET, the response message body with the selected resource set shall be constructed according to one of the following rules. Flat response construction method: The resources are returned as a flat list of JSON objects. Their location in the hierarchical containment tree shall be specified by, e.g. , their URI or Distinguished Name (DN) which needs to be returned for each resource. The object class name of each resource should be returned as well. Hierarchical response construction method: The resources are returned inside the containment tree as specified by the JSON schema definition of the information model. For the resources that are not selected, the following applies:

• A resource is not returned at all if it is not an ancestor of any of the selected resources.
• A resource is returned empty, except for the resource identifiers, if it is a descendant of the base resource and an ancestor of any of the selected resources

The containment tree present in the response message shall always start with the base resource. If no resource is identified in the retrieval request the MnS Producer shall return a "204 No Content" response. The following media types shall be used to distinguish the flat and the hierarchical response representation:

• application/vnd.3gpp.object-tree-flat+json,
• application/vnd.3gpp.object-tree-hierarchical+json.

The "application/json" media type may be used alternatively and defaults to the hierarchical representation format. The MnS Consumer shall indicate the acceptable representations in the "Accept" header, as described in clause 4.3.2. One or multiple media types may be specified. If the MnS Producer cannot provide an acceptable representation, a "406 Not Acceptable" error response shall be returned. The MnS Consumer may send a second request with another media type specified in the "Accept" header.

This design pattern allows to specify attributes of resources selected by the target URI. Often attributes have no scalar values but are complex structured data types with an own hierarchy and many attribute fields. In this case it may be desirable to identify not only the complete attribute but also individual attribute fields. The attributes or attribute fields to be returned shall be specified in the query part of the URI. Attribute selection or attribute field selection may be supported by the HTTP GET method. It is not applicable to any other method.

In case one or more attributes (with all attribute fields) are to be retrieved, the name of the query parameter shall be "attributes". The value of "attributes" shall be a list with the names of the attributes to be selected. Attribute names are separated by a comma (","). An empty "attributes" query parameter is allowed and has the special meaning that no attributes shall be returned.The naming attribute "id" shall always be returned. In case one or more fields of one or more attributes are to be retrieved, the name of the query parameter shall be "fields". The value of "fields" shall be a comma (",") separated list of entries that follow the syntax of JSON Pointer in JSON String Representation [14]. The context resource for the construction of the JSON Pointer is the resource identified by the target URI. Note that for multi-valued attributes the selection of one or multiple attribute elements is not supported with this pattern. Furthermore, conditional attribute or attribute field selection is not supported.

In a first step the resource identified by the target URI, or the set of resources identified by the target URI and the scope and filter parmeters, is determined. Then, in a second step, resources that do not contain at least one attribute identified by the "attributes" parameter or one attribute field identified by the "fields" parameter shall be removed from the output set of the first step. In the last step all attributes and attribute fields not identified by "attributes" and "fields" shall be removed from the remaining resource representations. This result set is then used to construct the final response using either the hierarchical or the flat construction method, both defined in clause 6.1.4. If no resource is identified in the retrieval request the MnS producer shall return an error response with "404 Not Found" in the status line.

HTTP PUT allows to replace (overwrite) a complete resource on the MnS Producer with the new representation in the request body. It cannot be used for partial updates of a resource. For partial updates of a single resource HTTP PATCH (RFC 5789) shall be used. With PATCH, a set of changes to be applied to the target resource is described in the request message body. The set of changes carried in the message body is called patch document. The format of the patch document is identified by its media type. RFC 5789 does not define any patch format, only the PATCH method. The HTTP PATCH method is atomic, as per RFC 5789. The MnS Producer shall apply the entire set of changes atomically and never provide (e.g., in response to a GET during this operation) a partially modified representation. If the entire patch document cannot be successfully applied, then the MnS Producer shall not apply any of the changes. PATCH thus has transaction semantics. For JSON, IETF has defined two patch formats for the use with the HTTP PATCH method: JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902). The usage of these patch formats is described in the following clauses.

RFC 7396 specifies a simple patch format for JSON documents called JSON Merge Patch. It allows to describe a set of modifications to be applied to the target resource representation. The JSON Merge Patch document is a partial representation of the resource to be patched. JSON Merge Patch works at the level of name/value pairs. The received patch document is merged into the target resource representation. The media type of the patch document is "application/merge-patch+json". Three types of patches are described in RFC 7396:

1. Replacing the value of an already existing name/value pair by a new value.
2. Adding a new name/value pair.
3. Removing an existing name/value pair.

The target resource is identified by the target URI. The target URI shall have no query and no fragment component. The target resource needs to exist, otherwise the error status code "404 Not Found" shall be returned. The "id" of the resource shall be present in the patch document and shall be identical to the "id" of the patched resource in the request URI. This ensures uniformity of resource representations in message bodies, though, strictly speaking, the presence of the "id" in the patch document is redundant. JSON Merge Patch does not allow manipulation of arrays other than replacing the complete array value (an array with all present items) with a new value (an array with all new items). It is not possible to change individual items in an array or to add/delete individual items.

The procedure flow is as follows:

1. The MnS Consumer sends an HTTP PATCH request to the MnS Producer. The resource to be updated is identified with the target URI. The message body shall carry the JSON Merge Patch document describing a set of modifications to be applied to the target resource.
2. The MnS Producer returns the HTTP PATCH response to the MnS Consumer. On success, "200 OK" together with the complete representation of the updated resource in the message body or "204 No Content" shall be returned. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

JSON Merge Patch shall be used for patching the target resource only. The patch format shall not be used for creating, modifying or deleting child resources of the target resource in the same request, even if the child resources are included in the schema definition of the target resource. This limitation is introduced, because child resources (of one object class) are represented as items of an array that is a property of the target resource (alongside with the attributes of the target resource), and JSON Merge Patch does not allow to modify individual array items. With JSON Merge Patch, only the complete array value with the representations of all child resources (of one class) could be replaced. Note that child resources can have child resources as well. The patch document would hence need to include the representations of all descendant resources. This is very inefficient and against the principle of PATCH to provide the changes only. The following examples demonstrate the usage of JSON Merge Patch. Assume an "XyzFunction" resource has no attribute "attrA" yet, then the following PATCH request creates it. The following subsequently executed PATCH request replaces its value with "def". This PATCH request deletes the attribute.

The JSON Patch format is specified in RFC 6902. The patch document is a JSON array. Each array item is a JSON object describing a modification to be applied to the target resource. The modifications shall be applied to the target resource sequentially in the order they appear in the array. The media type of JSON Patch is "application/json-patch+json". Each modification is defined by three properties: The operation ("op"), the identification of the secondary resource within the target resource to be manipulated ("path") and a value ("value"). When removing a secondary resource, the "value" property is absent. When moving or copying an existing value, the "value" property is absent, too, and the "from" property is present instead. The "from" property identifies the secondary resource, whose value is moved or copied to the location specified by the "path" property. The value of the "from" and "path" property is a JSON Pointer in string representation as defined in Section 5 of RFC 6901. In contrast to JSON Merge Patch, JSON Patch allows to modify individual items of an array. Array items are identified based on their position (index) in an array. The first item has the index "0". The "-" character is used by the operations "add" and "move" to index the end of the array for appending a new array item. Its use in any other operation is forbidden. The target URI identifies the resource to be modified. As for JSON Merge Patch, the target URI shall have no query and no fragment component. The target resource needs to exist, otherwise the error status code "404 Not Found " shall be returned.

The procedure flow is as follows:

1. The MnS Consumer sends an HTTP PATCH request to the MnS Producer. The resource to be updated is identified with the target URI. The message body shall carry a JSON Patch document describing a set of modification instructions to be applied to the target resource.
2. The MnS Producer returns the HTTP PATCH response to the MnS Consumer. On success, "200 OK" together with the representation of the updated resource in the message body or "204 No Content" shall be returned. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

As JSON Merge Patch, also JSON Patch shall be used for patching the target resource only. The patch format shall not be used for creating, modifying or deleting child resources of the target resource in the same request, even if the child resources are included in the schema definition of the target resource. This is because JSON Patch can address items in an array only based on the position of the item in the array, and not based on an identifier independent from the position of the item in the array. A patch document could hence not address descendant resources of the target resource based on their "id". This is prone to conflicts in multi-client scenarios, where the position of resource items in an array can change due to the concurrent creation or deletion of resource items in the same array. Risk mitigation would require complex ETag calculations in the resource hierarchy. The JSON Patch document is described by the folloing JSON schema fragment. The schema for the "value" property is the list (constructed with "anyOf") of the NRM schema fragments for all resource representations, and the NRM schema fragments for the values of all attributes and attribute fields. The NRM schema normally contains many NRM schema fragments of these kinds. For that reason it is normally not practicable to list all NRM schema fragments defining the allowed values of the "value" property. In addition, the resource, attribute or attribute field identified in the "path" property cannt be related by the schema itself to its value schema. For these reasons, the schema "{}" is normally used, which is the shorthand syntax for a schema without any type. The following example adds a new attribute "attrA" to an "XyzFunction" (assuming "attrA" does not exist yet). The following example replaces the value of "attrA" with "def". It is not an error if the "path" property of an "add" operation specifies an object member that exists already. In this case the value of the specified object member is replaced. The following patch request has hence the same effect as the patch request in the example above. In both cases the value of "attrA" is replaced with "def". The following patch document has not the same effect as both examples above. It does not replace the value of "attrA" with a new value. Instead, it replaces the value of the "attributes" object with a value that is an object and has a single member, the "attrA" property (attribute), thereby deleting all other attributes, that may exist when the patch request is received. To remove the attribute "attrA" the MnS Consumer may send. When the attribute to be added is a JSON array, the "value" property contains an array. In the following example the array has two items of type string. To add a new item to an existing array, the "path" property needs to specify the array index where the item is to be added. For example, the following PATCH request adds the array item "xyz" after the first array item.

Clause 6.1 discusses a method for retrieving multiple resources with a single HTTP GET request. This clause specifies methods allowing to manipulate (create, update, delete) multiple resources with a single request. The specified methods use the HTTP PATCH method and provide extensions to the JSON Merge Patch and JSON Patch formats. As described in clause 6.3, JSON Merge Patch and JSON Patch are used for partial updates of a single resource. The extensions specified in the following clauses are designed to allow for efficient manipulation of multiple resources with a single HTTP PATCH request. The target resource and all its descendant resources are ascessible with a single request. The extended patch formats are called 3GPP JSON Merge Patch and 3GPP JSON Patch. Note that the HTTP PATCH method is atomic as explained in clause 6.3.1.

3GPP JSON Merge Patch is a 3GPP defined extension to JSON Merge Patch (RFC 7396). It allows, using a single patch document, to update the target resource (as does JSON Merge Patch) and to update, create or delete descendant resources, which JSON Merge Patch does not allow, at least not in an efficient manner. This is achieved by relaxing for arrays that contain resources (of a single object class) as array items the constraint that the complete updated array value needs to be provided in the merge document. Instead, only resources to be manipulated are present in the patch document. These resources are identified with their "id". Resources that are not manipulated are either absent or present with their "id" only, when this is required to navigate along the containment tree to the resource to be patched. In other words, the rules of the hierarchical response construction method (clause 6.1.4) apply also when constructing the 3GPP JSON Merge Patch document. The merge semantic of JSON Merge Patch is hence extended to descendant resources of the target resource. Note that the behaviour of patching attributes of type array does not change in 3GPP JSON Merge Patch compared to JSON Merge Patch. The complete updated array value needs to be provided for attributes of type array also in a 3GPP JSON Merge Patch document. It is not possible to patch individual array items only. As for JSON Merge Patch, the target URI shall have no query and no fragment component. The target resource needs to exist, otherwise the error status code 404 (Not Found) shall be returned. The target URI shall identify a resource that is a common ancestor of the resources to be patched. The patch document itself shall start with the resource identified by the target URI. A resource is deleted by setting the "attributes" property of the resource to "null". In case a complete subtree is deleted, all resources from the base resource of the subtree down to the leaf resources shall be marked for deletion. When creating new resources, the object class name of the resource to be created shall be contained in the patch document for the resources to be created. The media type of 3GPP JSON Merge Patch is "vnd.3gpp.merge-patch+json". This media type is defined by 3GPP. It is not registered with IANA. Patch documents using this media type need to conform to the "application/json" media type. The procedure is as follows:

1. The MnS Consumer sends an HTTP PATCH request to the MnS Producer. The message body shall carry a 3GPP JSON Merge Patch document describing a set of modification instructions to be applied to the identified resources.
2. The MnS Producer returns the HTTP PATCH response to the MnS Consumer. On success, "200 OK" together with the representation of the updated and created resources, constructed according to the hierarchical response construction method described in clause 6.1.4, in the message body or "204 No Content" shall be returned. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

3GPP JSON Patch is a 3GPP defined extension to JSON Merge Patch (RFC 6902). Like 3GPP JSON Merge Patch, it allows, using a single patch document, to update the target resource (as does JSON Patch) and to update, create or delete descendant resources, which JSON Patch does not allow, at least not based on resource identifiers. This extension is that the "path" and "from" properties of a patch operation define an offset to the target resource as specified by the request URI. This offset is relative to the target URI. It has a first component pointing to a resource below the target resource, and a second component pointing to a secondary resource within the resource identified by the first component. The first component of "path" or "from" is built from URI path components. It follows the same syntax as the path components of the target URI. The second component is a URI fragment with a JSON pointer in the URI fragment identifier representation as defined in Section 6 of RFC 6901, i.e. the second component starts with the "#" character. Both components are concatenated without a delimiter. For example, assume the target URI is "/SubNetwork=SN1" and the "userLabel" attribute of a child of class "ManagedElement" with the id "ME1" is to be patched, then the first path component is "/ManagedElement=ME1/" and the second path component is "#attributes/userLabel". This results in the following path: The target URI shall identify a common ancestor resource of the resources to be patched, or the NRM root. Note that when one or more root resources are patched, the target URI identifies always the NRM root. When no root resources are patched, the MnS producer has a choice as to the target resource. For example, assume the resource with the URI is patched. Then the target resource is either the parent resource of the patched resource, in this case the root resource, or the NRM root. Setting the target resource always to the NRM root is hence a possible implementation option for MnS Consumers. When creating new resources ("op"="add"), the object class name of the resource to be created shall be included in the "value" property of the operation. The "replace" operation is not applicable when the "path" identifies a resource. The media type of 3GPP JSON Merge Patch is "3gpp-patch+json". This media type is defined by 3GPP and is not registered with IANA. Patch documents using this media type need to conform to the "application/json" media type. The procedure is as follows:

1. The MnS Consumer sends a HTTP PATCH request to the MnS Producer. The message body carries a 3GPP JSON Patch document describing a set of modification instructions (patch items) to be applied to the identified resources. The "Accept" header shall be included in the request and specify the media types acceptable to the MnS Consumer for "200 OK" or "204 No Content" responses.
2. The MnS Producer returns the HTTP PATCH response to the MnS Consumer. On success, "200 OK" together with the representation of the updated and created resources, constructed according to either the flat or hierarchical response construction method described in clause 6.1.1, in the message body or "204 No Content" shall be returned. On failure, the appropriate error code shall be returned. The response message body may provide additional error information.

A single operation in a 3GPP JSON Patch document shall patch a single (primary) resource only. Different operations in a patch document can patch different resources though. The consequence of this restriction is for example that subtrees with multiple resources cannot be created or deleted with a single patch operation. Each resource needs to be created or deleted with an own patch operation in the patch document. This behaviour is aligned with those of the PUT and DELETE methods. Note that the "replace" operation of (3GPP) JSON Patch has replace semantics like PUT and not merge semantics like JSON Merge Patch. When multiple attributes or attribute fields of a resource are patched, then a patch operation for each update is required, for example: To streamline partial updates of single resources, 3GPP JSON Patch introduces a new patch operation named "merge". For that operation, the JSON object contained in the "value" property shall be merged into the target resource referenced by "path" using the rules of JSON Merge Patch (RFC 7396). An MnS Producer shall verify if a "merge" operation is for a single resource by checking if the "path" property contains the string "#/attributes" and shall reject the request with "422 Unprocessable Entity" if it doesn't. The following example is invalid. It attempts to patch, besides the target resource, which is allowed, the contained "ManagedElement" resources, which is not allowed. In the same way as JSON Patch allows to construct conditional patch requests using the "test" operation, 3GPP JSON Patch can be used to construct condititional patch requests where the condition is expressed with the "test" operation. In contrast to JSON Patch, however, the condition may be based on attribute values outside of the patched resource. For example, the following patch document replaces the value of "attrA", which is an attribute of a "XyzFunction" resource whereas the condition relates to an attribute in the "SubNetwork" resource.