4.3 Property Definition

Here is a typical property definition extracted from our example schema:

      <xs:element name="orderDate" type="xs:date" minOccurs="0"
        sme:label="Date" sme:canSort="true" sme:canFilter="true" sme:precedence="2" />

This definition contains a mix of standard XSD attributes and SData extensions. The following table describes the attributes that can be applied to property definitions:

Attribute	Value	Description	Compliance
name	string	Name of the property.	MUST
type	data type	Data type for property values. This type must be one of the standard XSD types. For example, `xs:date.` Or a reference to a `simpleType` or `complexType` defined in the schema. For example, `tns:civility--type.`	MUST
nillable	true false (default)	Does the property accept `null` as a valid value?	MUST (if true)
minOccurs	0 or 1	Minimium number of occurences of the element in the payload. 0 is recommended value. See Update Payloads section for an explanation.	SHOULD
sme:label	string	A friendly name for the property (localized). Used as column title when the data is displayed in a grid.	SHOULD
sme:canSort	true false (default)	Can the feed be sorted by this property? If this attribute is set to true, the feed should contain an `<sle:sort>` element. See Simple List Extensions section for details.	SHOULD (if true)
sme:canFilter	true false (default)	Can the feed be filtered by the property?	SHOULD (if true)
sme:canGroup	true false (default)	Can feed entries be grouped by values of this property? If this attribute is set to true, the feed should contain an `<sle:group>` element. See Simple List Extensions section for details.	SHOULD (if true)
sme:precedence	integer	Integer that controls the visibility of properties on small screens. 1 = always visible. 2 and above = visible if enough space (the higher the value, the lower the priority). 0 = the default value and means no priority. This attribute has a counterpart in the SData query parameters. The `precedence` query parameter allows a service consumer to control which properties are returned in the payload, based on the precedence values that have been set in the schema. See Controlling Payload section for details.	SHOULD
sme:groupName	string	A group (category) name to group related properties.	MAY
sme:isMandatory	true false (default)	Is the property value mandatory or not when creating a new resource?	MUST (if true)
sme:isUniqueKey	true false (default)	Is the property a key that identifies a unique resource?	SHOULD (if true)
sme:isGlobalId	true false (default)	Is the property a global identifier for the resource? Only one property can have this attribute set to true. This property must be of string type (in the absence of a standard XML UUID type) and its value must be formatted as _`XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`_ in XML payloads. When `isGlobalId` is set to true, `isUniqueKey` should also be set to true. This attribute is deprecated as UUIDs should be passed via the sdata:uuid attribute rather than as element values.	deprecated
sme:isLocalized	true false (default)	Should the property contain localized text?	SHOULD (if true)
sme:isIdentifier	true false (default)	Is the property the identifier for the resource? This attribute is used by generic UI consumers, in conjunction with `sme:isDescriptor`, typically to fill combo boxes. The UI consumer displays the descriptor property to the user but will use the identifier property as entry key. This attribute is deprecated as primary key values should be passed via the sdata:key attribute rather than as element values.	deprecated
sme:isDescriptor	true false (default)	Is the property the descriptor for the resource? See `sme:isIdentifier` above.	deprecated
sme:isReadOnly	true false (default)	Is the property read-only? For example, an ID set by the provider or a calculated property.	MUST (if true)
sme:relationship	parent child reference association	Reserved for properties that define relationships. See Relationship Definition section for details.	MUST for relationship properties
sme:isCollection	true false (default)	Reserved for properties that define relationships. See Relationship Definition section for details. Does the property refer to a collection of resources or a single resource?	MUST (if true)
sme:copiedFrom	xpath expression	Should the property be updated when the subresource changes? This attribute applies to properties that are involved in relationships. See Relationship Definition section for details.	deprecated
sme:canGet sme:canPost sme:canPut sme:canDelete	true false (default)	Reserved for properties that define relationships. See Relationship Definition section for details. Indicates the HTTP methods supported on the property.	MUST (if true)
sme:unsupported	true false (default)	Is property part of a global contract that is not supported by this specific provider?	SHOULD (if true)
sme:tags	comma separated string	List of tags that apply to the property. SData does not impose any predefined list of tags. Instead, each contract is free to define its own list of tags. This feature is an extensibility mechanism. It should be used when the information cannot be captured by one of the other SME attributes, not as a replacement for existing SME attributes.	MAY (1.1)

Let’s see how how these attributes have been used in our sales order definition example:

  <xs:complexType name="salesOrder--type">
    <xs:all>
      <xs:element name="orderNumber" type="xs:string" minOccurs="0"
                  sme:label="#" sme:canSort="true" sme:canFilter="true" sme:precedence="1" 
                  sme:isUnique="true" sme:isReadOnly="true"/>
      <xs:element name="orderDate" type="xs:date" minOccurs="0"
                  sme:label="Date" sme:canSort="true" sme:canFilter="true" sme:precedence="2" />
      <xs:element name="shipDate" type="xs:date" minOccurs="0" nillable="true"
                  sme:label="Shipping Date" sme:canSort="true" sme:canFilter="true" sme:precedence="3" />
      <xs:element name="subTotal" type="xs:decimal" minOccurs="0"
                  sme:label="Sub-total" sme:canSort="true" sme:canFilter="true" sme:precedence="2"
                  sme:isReadOnly="true" />
      <xs:element name="billAddress" type="tns:address--type" minOccurs="0"
                  sme:relationship="child" sme:isCollection="false" sme:label="Billing Address"
                  sme:canGet="true" sme:canPut="true" />
      <xs:element name="shipAddress" type="tns:address--type" minOccurs="0"
                  sme:relationship="child" sme:isCollection="false" sme:label="Shipping Address"
                  sme:canGet="true" sme:canPut="true" />
      <xs:element name="orderLines" type="tns:salesOrderLine--list" minOccurs="0"
                  sme:relationship="child" sme:isCollection="true" sme:label="Order Lines"
                  sme:canGet="true" sme:canPost="true" />
      <xs:element name="contact" type="tns:contact--type" minOccurs="0"
                  sme:relationship="reference" sme:label="Contact"
                  sme:canGet="true" sme:isMandatory="true" />
    </xs:all>
  </xs:complexType>

In this complexType definition, the SME attributes are used as follows:

canFilter is set to true on the orderNumber, orderDate and subTotal properties. This means the feed consumer can set up filters on these properties.
canSort is set to true on the orderNumber, orderDate and subTotal properties. This means the feed consumer can enable sorting on these columns when displaying the data in a grid.
isUniqueKey is set to true on orderNumber as this property uniquely idenfies a sales order resource.
precedence is set to 1 on the orderNumber property. This property must always be displayed. It is set to 2 on the orderDate and subTotal properties, and to 3 on shipDate. These properties should be displayed next if there is enough space on the screen (shipDate having lower priority). Precedence is not set on the other properties. So, they should only be displayed if there is enough space left on the screen.
The relationship attribute is set on the orderLines, billAddress, shipAddress and contact properties. The orderLines, billAddress and shipAddress relationships are child relationships while the contact relationship is a reference relationship (see Relationship Definition section for details). The isCollection attribute is true for the orderLines property and false for the other relationship properties.
The isReadonly attribute is set to true on the orderNumber and subTotal properties. These property values are set/worked out on the provider side and cannot be modified directly by the consumer.
The isMandatory attribute is set on the contact property because we assume that this information must be provided at the time the order is created. The orderNumber property is not mandatory because we assume that it is generated on the service provider side in this example. Similarly, the orderDate property is not mandatory because we assume that the service provider defaults it to the current date.