Nouns

A logical model definition is required for services that are fronted by an XML schema. In WebSphere Commerce, the logical model definition is represented as a noun. WebSphere Commerce uses its own simplified nouns, defined types, and primitive XML schema types. WebSphere Commerce does not use nouns and base types provided by OAGIS.

Nouns define the name of each data element in the logical model, and assign that name to a data type. The data type can be a primitive XML schema type such as boolean, or a complex type. A complex type is a construct of data elements such as CurrencyType which contains price (represented by a double type) and currency (represented as a string). A noun can contain one or more noun parts (sometimes referred to as noun elements). A Noun part is a complex XML type within a noun that can be acted upon independently. Noun parts represent parts of a logical noun. Separating a noun into parts simplifies coding by reducing the scope of commands and mediators. Instead of handling the entire noun, code is limited to only processing the noun part. When a request arrives, it is broken into its different parts and the appropriate command for each part is run. For example, the CatalogEntry noun contains a list of descriptions. A catalogEntry description is considered a noun part and is processed using the ChangeCatalogEntryDescriptionCmdImpl and ChangeCatalogEntryDescriptionMediator.

The mapping between a noun, noun part, and command is done in the CMDREG table, and the mapping between a noun, noun part, and mediator is done in the wc-business-object-mediator.xml file.

Nouns do not have to be broken up into different parts. That is, if a noun is relatively simple, the entire contents, including complex XML types, can be processed by the same command and mediator.

WebSphere Commerce provides some predefined complex type constructs which are shared among all nouns. You can use these types in your custom nouns.

Identifier types

Identify and distinguish uniquely, one instance of an object in an identification scheme from all other objects in the same scheme. For example, PersonIdentifierType, OrganizationIdentifierType, CatalogExternalIdentifierType

IBM/Commerce/Resources/ComponentsIdentifierTypes.xsd
Base types

Types that are not domain specific. For example, DescriptionType, LanguageType, CurrencyType, CharType, and UserDataType.

IBM/Commerce/Resources/ComponentsBaseTypes.xsd
Component common types

Domain specific types that are shared across components. Include CommonTypes.xsd if you want to use the types defined in IdentifierTypes.xsd and BaseTypes.xsd.

IBM/Commerce/Resources/ComponentsCommonTypes.xsd

Includes IdentifierTypes.xsd and BaseTypes.xsd

Types that are used inside one service module only, but shared between nouns are defined in a common XSD file, such as CatalogCommon.xsd

The following table provides general guidelines to follow when creating nouns.

Conventions
General
  • Model nouns so that many services can interact with a single noun. A business object that resembles a list of WebSphere Commerce controller command parameters for is not well defined.
  • Optimize business objects as a logical view of your business. A well-designed logical model is understandable by business users, whereas a database schema is optimized for data storage and retrieval.
  • Do not use abbreviations, except for well known short forms and industry-standard acronyms. For example, ID and SKU are acceptable acronyms, but Grp is not.
  • Use explicit names. Do not use symbols or numbers.
  • Add annotation to the schema to describe elements. In particular, annotate elements where the values have a specific meaning. For example, add annotations to the ProcessNoun schema to describe the possible actions of the process verb.
  • Include store-specific information in the noun, or noun part, when the business object has a context specific to the store. Consider the following example, a site contains several stores which sell the same merchandise. In this case, a catalog entry is not store-specific. Each store has its own catalog; therefore, the catalog is store-specific.
  • Model the business object so that it can include data from other nouns when appropriate. For example, a catalog entry price varies depending on the customer, discounts, customer segment and so on, for simplicity the CatalogEntry noun does not include price information. Price information is in a PriceList noun.
  • Create custom nouns that refer to WebSphere Commerce nouns. For example, to create a noun that refers to a catalog entry, include CatalogEntryIdentifierType the catalog entry identifier type in your noun. This association enables the service to request more information. The Order noun refers to the StoreIdentifier type by using this method.
Types
  • Begin with an uppercase letter; then use camel case.
  • End the name with Type. This distinguishes the defined type objects and the elements that are of that type.
  • Include a UserData element in all complex types. The UserData element enables customization.
  • Define enumerated types in the schema. Begin with an uppercase letter; then use camel case. For example, define enumerated type for address values as Home, Office, and Cottage. Do not use internal bit values to define enumerated types; ensure that values are meaningful to the user.
  • Use normalizedString for enumeration. Enumeration values begin with an uppercase letter; then use camel case.
  • Use union with EnumerationExtensionType (defined in IdentifierTypes.xsd) to support extension. EnumerationExtensionType has a pattern value of x[0-9A-Za-z][0-9A-Za-z_.]*.
    
     <simpleType name="AddressUsageEnumerationType">
          <annotation>
              <documentation>Indicates how usage of the address:
         Shipping:  Shipping address
         Billing:  Billing address
         ShippingAndBilling: Shipping and Billing address
       </documentation>
      </annotation>
      <restriction base="normalizedString">
                 <enumeration value="Shipping"/>
                 <enumeration value="Billing"/>
                 <enumeration value="ShippingAndBilling"/>
      </restriction>
     </simpleType>
     
     <simpleType name="AddressUsageType">
          <annotation>
              <documentation>Allows extension to the default address usage types.
       </documentation>
      </annotation>
      <union memberTypes="wcf:AddressUsageEnumerationType
                          wcf:EnumerationExtensionType"/>
     </simpleType>
    
  • Include an identifier complex type, this consists of an internal key (primary key) and external identifier. This identifier type is used by other types to refer to this object. The IdentifierType contains:
    UniqueID
    A required string, UniqueID, that typically maps to the primary key. To identify an object itself, an internal key or external identifier can be used, however, the internal key is always returned in the response.
    External identifiers
    External identifiers are optional. To refer to another object (foreign key), use an internal key or external identifier. If an external identifier is used, the identifier cannot be changed after the object is saved.
    <complexType name="PersonIdentifierType">
         <sequence>
             <element maxOccurs="1" minOccurs="0" name="UniqueID" type="string"></element>
             <element maxOccurs="1" minOccurs="0" name="DistinguishedName" type="string"></element>
        </sequence>
    </complexType>
    
Elements
  • Begin with an uppercase letter; then use camel case.
  • Do not use underscores in element names.
  • Use a name consistent with the corresponding type, but do not append Type.
  • If the element is a simple type identifier, append ID to the end. For example, SomeObjectNameID.
Attributes
  • Begin with a lowercase letter; then use camel case.
  • Do not use underscores in attribute names.
  • Attributes should be used for scoping element values, elements for main content. Complex types must have at least one element.
Namespace There is a one-to-one mapping between namespace and service modules. Many business objects can share the same namespace.

A namespace consists of three parts:

domain name
Your company's domain name.
/xmlns/prod/commerce/9
Indicates a WebSphere Commerce related object based on the OAGIS 9 processing envelop.
business-service identifier
Classifies a group of nouns.
For example: http://www.mycompany.com/xmlns/prod/commerce/9/order

The default values for namespace attributes are elementFormDefault="qualified" and attributeFormDefault="unqualified".