Nouns

+

Search Tips   |   Advanced Search

 

Overview

Any service that is fronted by an XML schema requires a logical model definition. For WebSphere Commerce, the logical model will be represented as a noun. To reduce complexity, WebSphere Commerce uses its own...

• simplified nouns
• defined types
• primitive XML schema types

...rather than using the 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. This data type may be a primitive XML schema type like boolean, or you can define a complex type. A complex type is a construct of data elements like CurrencyType which contains price (represented by a double type) and currency (represented as a string). WebSphere Commerce provides some predefined complex type constructs which are shared among all of the nouns.

 

WebSphere Commerce common types

WebSphere Commerce common types can be found in one of the following files:

IBM/Commerce/Resources/ComponentsIdentifierTypes.xsd	Contains the identifier types. Identifier types are types that 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/ComponentsBaseTypes.xsd	Contains the types that are not domain specific, such as DescriptionType, LanguageType, CurrencyType, CharType, UserDataType, etc.
IBM/Commerce/Resources/ComponentsCommonTypes.xsd	Contains the domain specific types that are shared across components. CommonTypes.xsd includes IdentifierTypes.xsd and BaseTypes.xsd. You only need to include CommonTypes.xsd if you want to use the types defined in above files.

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

 

Naming conventions

• Abbreviations should not be used in naming, except for well known short forms (like ID instead of identifier) or industry standard acronyms (for example, SKU). Otherwise, spell out the full name (write Group instead of Grp).

• Element names should be consistent with their corresponding type name where appropriate, but without the "Type".

• Types must end with "Type" to indicate it is a type. This is a good practice to distinguish the defined type objects and the elements that are of that type.

• All attributes should start with lowercase, then use camelcase.

• All elements should start with uppercase, and use camelcase.

• All types should start with uppercase, and use camelcase.

• Do not use underscores in attribute or element names.

• When specifying an element as an identifier, use a capital "ID" on the end, like "SomeObjectNameID".

• Use explicit names rather than confusing symbols or number.

• Enumerated types should be properly specified in the schema, with values in camelcase starting with an uppercase letter. For example, if you need an enumerated type for the type of address, you could define an enumerated type with values "Home", "Office", and "Cottage". Do not use internal bit values to define enumerated types; ensure that the type values are meaningful to the user of the schema.

• When creating a namespace, its name should reflect the following criteria:

  1. Your company's domain name.

  2. Add /xmlns/prod/commerce/9, as it is a commerce related object based on the OAGIS 9 processing envelop.

  3. Add a business-service identifier, which would classify a grouping of nouns.

  When creating and naming a namespace using the steps above, an example could be:

  http://www.mycompany.com/xmlns/prod/commerce/9/order Which would represent Order related business objects and services developed by MyCompany, following the OAGIS 9 processing envelop for the purpose of Commerce.

 

Schema structure

• If your business object looks like your database schema then most likely one of the two is poorly defined. The business object should be a logical view of your business and should not be influenced by the schema.

• If your business object looks like the list of parameters for a WebSphere Commerce controller command, it is probably not well defined. The noun should be multi-purpose, allowing for many services to be performed against it. It should be self-documenting.

• It is important to add annotation to the schema to describe elements; especially those elements that has values which have specific meaning. For example, it is always important to add annotations to the ProcessNoun schema to describe the possible actions of the process verb.

• Do not expose internal flags. If a flag should be set by the business logic then let the business logic set it. Do not expose it to the consumer of the service and make them worry about the semantics.

• All complex types should have an UserData element if you expect customization.

• Attributes should be used for scoping element values, elements for main content. Complex types must have at least one element.

• Internal key (primary key) and external identifier:

  • To identify an object itself, an internal key or external identifier can be used, however, the internal key will always be returned in the response.

  • To reference another object (foreign key), an internal key or external identifier can be used. However, if external identifier is used, the identifier can not be changed once the object is published..

  .

• The default values for namespace attributes should be elementFormDefault="qualified" and attributeFormDefault="unqualified".

• Enumeration should use normalizedString, and the values of enumeration should start with uppercase, and use camelcase..

• To support extension of the enumeration, use union with EnumerationExtensionType (defined in BaseTypes.xsd). EnumerationExtensionType has a pattern starting with "x". For example:

   <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>

  .

• Each business object should have an identifier complex type. The IdentifierType should contain following:

  • UniqueID (string) (mandatory) UniqueID is normally mapped to the primary key.

  • External identifiers (optional).

  <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>

  This identifier type should be used by other types that need to reference this object.

• There is a one-to-one mapping between namespace and service modules. Therefore, there can be many business objects sharing the same namespace.

Related concepts

WebSphere Commerce use of Open Applications Group (OAGIS) messaging