X.commerce catalog capability

catalog.avdl

@namespace("com.x.service.catalog")

/**
 * Protocol for the Catalog Service
 * ================================
 */
protocol CatalogService {

	//-----------------------------------------------------------------------------------------------------
	// Request & Response: Product Types
	//
	// 	- GetProductTypesMessage : Request product types by locale.
	// 	- ProductTypesMessage : Return a collection of product type records.
	//-----------------------------------------------------------------------------------------------------

	/*
	   Get Product Types Message.
		- Catalog message request for all known product types by locale.
	*/
	@topic("/productType/find") 
	record GetProductTypesMessage {
		// The locale is used to request Country/Language specific product types.
		//    - The locale EN_US will be the default if no locale is supplied in the message.
		union { null, string } locale;
	}

	/*
	   Product Type Information
		- Structure that contains a sub-set of product type metadata information.
	*/
	record ProductType {
		// Contains the product type ID
		string productTypeId;
		// Contains the well know product type name.
		string producTypeName;
		// categorization data, e.g., /Cameras & Photo/Flashes & Flash Accessories/Flashes
		string categorization;
		// Contains a brief description of the product type.
		string description;
	}

	/*
	   Product Types Message
		- Catalog message response that contains a collection of product types by locale.
	*/
	@topic("/productType/find/success") 
	record ProductTypesMessage {
		// Message creation time stamp.
		string timeStamp;
		// The product types collection locale.
		union {null, string} locale;
		array<ProductType> ProductTypes;
	}

	/*
	  Error Message
	      - Catalog error message for GetProductTypesMessage
	*/
	@topic("/productType/find/fail") 
	record GetProductTypesErrorMessage {
		// time stamp.
		string timeStamp;
		// The locale specified in request.
		union {null, string} locale;
		// error code
		int errorCode;
		// error message
		string errorMessage;
	}

	//-----------------------------------------------------------------------------------------------------
	// Request & Response: Product Type Metadata Message
	//
	// 	- GetProductTypeMetadataMessage : Request for metadata for a single product type.
	// 	- ProductTypeMetadataMessage - Return metadata for a single product type.
	//-----------------------------------------------------------------------------------------------------

	/*
	   Get Product Type Metadata Message.
		- Catalog message request for product type metadata.
	*/
	@topic("/productType/attributeMetadata/get") 
	record GetProductTypeMetadataMessage {
		// Product type ID.
		string productTypeId;
	}

	/*
	   Attribute data type
		- defines well known data types.
	*/
	enum AttributeDataType {
		NUMERIC,
		CURRENCY,
		STRING,
		BOOLEAN,
		DATE
	}

	/*
	   Pre-Defined Values
	*/
	record Token {
		// Indicates if the attribute is restricted to only use predefined values.
		boolean restricted;
		// Collection of pre-defined attribute values.
		array<string> predefinedValues;
	}

	/*
	   Numeric Type Specific Attribute Information
	*/
	record NumericTypeDetails {
		// Validation - Maximum allowed value.
		union { null, int } maxValueAllowed;
		// Unit of measure pre-defined values.
		union { null, Token } unitOfMeasure;
	}

	/*
	   String Type Specific Attribute Information
	*/
	record StringTypeDetails {
		// Validation - Contains validation rules.
		union { null, string } regularExpression;
		// Description of attribute restrictions.
		union { null, string } descriptionOfRestriction;
		// Pre-defined attribute values.
		union { null, Token } predefinedValues;
		// Indicates if multiple values are allowed.
		boolean allowMultiValue;
	}

	/*
	   Type Specific Information
	*/
	record TypeSpecificDetails {
		// Contains numeric type attribute information
		union { null, NumericTypeDetails } numericTypeDetails;
		// Contains string type attribute information
		union { null, StringTypeDetails } stringTypeDetails;
	}

	/*
	   Attribute Metadata Information
	*/
	record AttributeMetadata {
		// Attribute name.
		string attributeName;
		// Well known attribute data type.
		AttributeDataType attributeDataType;
		// Indicates if the attribute is required.
		boolean required;
		// Attribute type specific information.
		union { null, TypeSpecificDetails} typeSpecificDetails;
		// Descriptive comments regarding the attribute.
		union { null, string } attributeDescription;
	}

	/*
	   Product Type Metadata Message
		- Catalog message response that contains attribute metadata for a product type.
	*/
	@topic("/productType/attributeMetadata/get/success") 
	record ProductTypeMetadataMessage {
		// Message creation time stamp
		string timeStamp;
		// Product type Id
		string productTypeId;
		array<AttributeMetadata> attributeMetadata;
	}

	/*
	   Error Message
	       - error message for GetProductTypeMetadataMessage
	*/
	@topic("/productType/attributeMetadata/get/fail") 
	record GetProductTypeMetadataErrorMessage {
	       // time stamp.
	       string timeStamp;
	       // productTypeId, which uniquely identify the request
	       string productTypeId;
	       // error code
	       int errorCode;
	       // error message
	       string errorMessage;
	}

	//-----------------------------------------------------------------------------------------------------
	// AVRO Generated Catalog Service Interface
	//
	// Define all of the request method signatures required in the CatalogServiceImpl source code.
	//-----------------------------------------------------------------------------------------------------
	ProductTypesMessage getProductTypes(GetProductTypesMessage message);
	ProductTypeMetadataMessage getProductTypeMetadata(GetProductTypeMetadataMessage message);

}