16 PROPERTY RESOURCE & REPRESENTATION
The (domain object) property resource can be used to obtain the detailed domain object property representation §C16.4 for a particular domain object instance. It also allows the value of that property to be modified (or to validate a proposed new value for a property).
The endpoint URL for this resource is:
/objects/{domainType}/{instanceId}/properties/{propertyId}
where:
-
{domainType}uniquely identifies the object’s type, and -
{instanceId}uniquely identifies an object instance of that type -
{propertyId}is the property identifier
16.1 HTTP GET
Obtain a detailed representation of a property §C16.4.
This resource is typically requested as a result of following a link from the domain object representation §C14.4.
16.1.1 Request (any property type)
To return a representation §C16.4 of the property; if a non-blobClob then this will include the property’s current value, if a blob/clob then will include a link rel="…/attachment" by which the blob/clob can be retrieved, §C16.1.2.
16.1.1.1 Query String
-
x-ro-domain-model (optional, §A3.1)
-
"simple"
-
"formal"
-
16.1.2 Request (for blobClob attachment)
If the property is a blob/clob, then getting the property with an "application/json" Content-Type §C16.1.1 will return a representation of the property §C16.4 that include an rel="…/attachment" link. This link refers back to the same resource URL, but indicates the media type [1] for the Accept header in order to obtain the actual blob/clob.
16.2 HTTP PUT
Update property value of an object, or check that the proposed new value for the property would be valid without making the change. The PUT method may be used to clear the property by passing in a null value, but the recommended practice is to use DELETE §C16.3 for that purpose.
Properties that are blob/clobs support two different request formats. Non blob/clobs support only a single request format.
16.2.1 Request (for non-blobClobs)
Updating non-blobClob properties is performed by PUTting the value in-lined within a JSON map §A2.9.2.2.
16.2.2 Request (if blobClobs)
Updating blobClob properties is performed by PUTting the actual value (e.g. image), with appropriate content type.
Note that optional validation (x-ro-validate-only) and domain type metadata preferences (x-ro-domain-model) are not supported for blobClobs.
16.3 HTTP DELETE
This is the recommended resource for clearing a property value, or for validating that a property can be cleared but without making the change.
Strictly speaking the DELETE Object Property resource is redundant because it is also possible to clear a property using the PUT method, passing in a null value. However, the DELETE Object Property resource has been included in the spec because it offers a simpler syntax (no body to pass in) and because it is more ‘intentional’ (the intent of calling the resource is clearer to anyone reading the code).
16.4 Representation
The domain object property representation provides full details about a property of a domain object instance, and provides links to resources to allow the property to be modified (if it is not disabled).
The Content-Type for the representation is:
application/json;profile=".../object-property"
The links from the object property representation to other resources are as shown in the diagram below:
For example, the representation of an Order’s deliveryOption property might be:
"deliveryOption": {
"disabledReason": ...,
"value": ...,
"choices": [ ... ],
"links": [ {
"rel": "self",
"href": "http://~/objects/ORD/123/properties/deliveryOption",
"type": "application/json;profile=\".../object-property\"",
"method": "GET"
}, {
"rel": ".../modify;property=\"deliveryOption\"",
...
}, {
"rel": ".../clear;property=\"deliveryOption\"",
...
}, {
"rel": "up", ...
...
}
],
"extensions": { ... }
}where:
| JSON-Property | Description |
|---|---|
links |
list of links to resources. |
links[rel=self] |
link to a resource that can obtain this representation |
id |
property ID, to use when building templated URIs |
value |
(optional) the current value of the (non blob/clob) property, §C16.4.1 |
choices |
(optional) list of suggested/recommended choices for the (non blob/clob) property, §C16.4.1. |
disabledReason |
(optional) if populated then indicates the reason why the property cannot be modified. |
links[rel=…/modify] |
(optional) link back to self to modify property value; discussed below, §C16.4.2 |
links[rel=…/clear] |
(optional) link back to self to clear property value; discussed below, §C16.4.2. |
links[rel=up] |
link to the object that is the owner of this property. |
links[rel=…/attachment] |
(optional) link to resource returning property if a blob/clob, §C16.4.1. |
extensions |
additional information about the resource. |
"choices"
The "choices" json-property lists a set of values which are valid for the property. (It is up to the implementation to determine whether this set of choices is exclusive ( i.e. whether other values may also be valid) or not.
"links" and "extensions"
Both the "links" and the "extensions" json-properties may contain domain model information; this is discussed in §C16.4.3.
Restful Objects defines no further standard child properties for the "extensions" json-property. Implementations are free to add further links/json-properties to "links" and "extensions" as they require.
16.4.1 Property values and choices
For value properties (other than blobs/clobs), the "value" and "choices" json-properties are directly parseable strings:
{
"id": "deliveryOptions",
...
"value": "PRIORITY",
"choices": ["PRIORITY", "STANDARD", "PARCEL"], ...
}For reference properties, the "value" and "choices" json-properties hold links to other object resources:
{
"id": "paymentMethod",
...,
"value": {
"rel": ".../value;property=\"paymentMethod\"",
"href": "http://~/objects/PMT/VISA",
"type": "application/json;profile=\".../object\"",
"method":
"GET",
"title": "Visa"
},
"choices": [ {
"rel": ".../choice;property=\"paymentMethod\"",
"href": "http://~/objects/PMT/VISA",
"type": "application/json;profile=\".../object\"",
"method": "GET",
"title": "Visa"
}, {
"rel": ".../choice;property=\"paymentMethod\"",
"href": "http://~/objects/PMT/AMEX",
"type": "application/json;profile=\".../object\"",
"method": "GET",
"title": "American Express"
}, {
"rel": ".../choice;property=\"paymentMethod\"",
"href": "http://~/objects/PMT/MCRD",
"type": "application/json;profile=\".../object\"",
"method": "GET",
"title": "Mastercard"
}
]
}For blob/clob value properties, the "value" json-property is omitted. Instead a link[rel="…/attachment"] json-property provides a link that can be followed, with the appropriate Accept header, to obtain the blob/clob:
{
"id": "scannedSignature",
...,
"links": [ {
"rel": ".../attachment;property=\"scannedSignature\"",
"href": "http://~/objects/CUS/123/property/scannedSignature",
"type": "image/jpeg",
"method": "GET"
}
]
}If the property is null, then there will be neither a "value" nor a "links[rel=…/attachment]" json-property.
16.4.2 Property modification
If the property is modifiable, then the "modify" and "clear" json-properties provide links to the resources used to change the property’s state.
For example:
{
"id": "deliveryTime",
...
"links": [ {
"rel": ".../modify;property=\"deliveryTime\"",
"href": "http://~/objects/ORD/123/properties/deliveryTime",
"type": "application/json;profile=\".../object-property\"",
"method": "PUT",
"arguments": {
"value": null
}
}, {
"rel": ".../clear;property="\deliveryTime\"",
"href": "http://~/objects/ORD/123/properties/deliveryTime",
"type": "application/json;profile=\".../object-property\"",
"method": "DELETE"
}, ...
]
}where:
| JSON-Property | Description |
|---|---|
links[rel=…/modify] |
link back to self to modify property value; not included if the property is disabled |
links[rel=…/clear] |
link back to self to clear property value; not included if the property is disabled |
The new value (for the "modify") is sent in the body request via HTTP PUT. Validation of properties occurs when the modify is made. If only validation is of a property is required, then specify the x ro-validate only request parameter §A3.2.
If the domain object property is NOT modifiable, then the representation will include a "disabledReason" json-property that indicates the reason (or just the literal "disabled") why the value of the property cannot be modified:
{
...
"disabledReason": "Cannot add items to order that has already shipped",
...
}where:
| JSON-Property | Description |
|---|---|
disabledReason |
indicates the reason why the property cannot be modified/cleared; only included if the property is disabled. |
16.4.3 Domain model information
Domain model information is available through either the "links" or the "extensions" json-properties.
16.4.3.1 Simple scheme
Implementations that support the simple scheme provide extra data in the "extensions" json-property.
For example:
"extensions": {
"friendlyName": "Delivery Time",
"description": "Time that the order will be delivered",
"returnType": ...,
"optional": false,
"format": ..., // for string properties only
"maxLength": ..., // for string properties only
"pattern": ..., // for string properties only
"memberOrder": 3
}See §A3.1.1 for the full definitions of these json-properties.
16.4.3.2 Formal scheme
Implementations that support the formal scheme §A3.1.2 provide an additional link only in the "links" json-property:
"links": [ {
"rel": "describedby",
"href": "http://~/domain-types/ORD/properties/deliveryTime",
"type": "application/json;profile=\".../ property-description\"",
"method": "GET"
}
]which links to the domain property description resource §D22.2 corresponding to this domain object property.