MOO API /

Documentation

Pack Validation

Validation flow

Every request that sends a Pack object to the MOO API is strongly validated in a few ways. The basic steps taken are:

  • Check that the JSON is well-formed. If not, report an Exception.
  • Check that the request is semantically value (i.e. all the JSON properties and values are correctly named, and of the right type). If not report an Exception.
  • If the request includes a Pack object, send for validation.
  • If the Pack references a productCode which cannot be loaded, report an Exception.
  • Report any other validation failures as response warnings.

See the Error Handling page for more details on what happens if an Exception is reported - but in these cases the request will fail. If it's only validation warnings, these will be reported in the response object to the call.

Data structure

The validation warnings from a successful request are all listed in the "warnings" property of the response object, which is an array of ValidationFailure objects, each of which has the following properties:

  • element - string - where in the semantic pack structure the failure was reported. This should help you identify precisely where the problem is in your pack. It follows the dot notation, so a failure in a image side #1's "variable_image_front" datum will be tagged with pack.sides.image.1.variable_image_front
  • code - string - the validation failure code. These can be considered unique, and won't change meaning over time. MOO reserves the right to add more validation failure messages from time to time.
  • message - string - a message to explain why the element wasn't valid. The meaning of the message is tied to the code, but may be a string specific to the element (i.e. these are not 1-1 mapped with the code property values)

Example warnings structure:

{
    "warnings":[
        {
            "element":"pack.sides.image.1.variable_image_front",
            "code":"PVI002",
            "message":"You must define neither or both of imageBox and resourceUri on an Image",
        }
    ]
}

Recovery

Validation failures merely suggest that more data is required for the Pack. In this way (assuming you have the relevant permissions) you can build a Pack through multiple API calls, each one of which adds more information (and hopefully reduces the number of validation warnings!). They will often prevent the user being dropped back into the MOO website to finish making their order.

In the case of the moo.pack.addToCart method call, any validation failures will cause that call to fail.

Codes

Code Message Further description
PV001 numCards is not valid for
Each product requires the Pack to specify the same numCards as are found in the product. This ensures there are no mismatches in expectation of how large the printed pack will be.
PV002 Only X cards are defined when Y are required
The pack.cards array is optional, but if you provide a pack.cards array, it must have the correct number of Card objects defined.
PV003 Side - is not unique
You have created 2 Side objects in the pack.sides which have the same type and sideNum. This means that we cannot be sure which one should be used if the Side is referenced from a CardSide object, and therefore produces a warning.
PVD001 Pack.sides needs to define at least one of the following side: image
For all products, there MUST be at least 1 "image" Side defined. If you want to create a Pack with a blank "image" side, then simply create one Side with a relevant full image template code, and no image data defined.
PVD002
Pack.sides needs to define at least one of the following side: details For all products except stickers, there MUST be at least 1 "details" Side defined. If you want to create a Pack with a blank "details" side, then simply create one Side with a relevant details side template, and no user data defined.
PVD003
Pack.sides needs to define at least one of the following side: middle For holiday cards, there MUST be at least 1 "middle" Side defined. If you want to create a Pack with with a blank "middle" side, then simply create one Side with a relevant middle side, leaving the user data empty.
PV005 Card has duplicate CardSide for the following type:
If manually constructing the pack.cards array, then within each Card, there must be exactly one CardSide for each side type. This message indicates that there are 2 CardSide objects defined for the same side type. We therefore cannot know which one we should actually print on that side type.
PV006 Card references non-existant Side: NULL
You have provided a CardSide object but without having specified the sideType and sideNum information. We need to know which Side should be used, and this information must be provided.
PV006
Card references non-existant Side: -
You have provided a CardSide object with populated sideType and sideNum, but we cannot find the Side for this type and number. Check that the distribution is still valid.
PV007 Card is missing CardSide instances for the following types:
You have provided a Card object which is missing CardSide objects for the listed Side types. Each Card MUST define exactly one CardSide for each side type on the product
PV008 linkId is not unique within Side You have provided a Side object with a user data array that contains elements referencing the same linkId from the Template. This is invalid - each Side must only reference a specific linkId once (or not at all)
PV009 is an invalid template You have provided a Side object that references a template not valid for this pack or side type.
PVB001 Datum is not a Box type You have provided a user data object in a Side whose linkId references a Box item from the Template, but which is not a "boxData" type in the JSON.
PVB002 Box must define a colour This means that for the given linkId, neither the Template object, nor your user data item (if specified) has provided a Colour object for the box to be rendered. Once the user data and template data are merged, all properties must be fully specified.
PVI001 Datum is not an Image type You have provided a user data object in a Side whose linkId references an Image item from the Template, but which is not a "imageData" type in the JSON.
PVI002 You must define neither or both of imageBox and resourceUri on an Image If your user data seeks to place an image in the Template's image content element, then you MUST specify BOTH of the imageBox and resourceUri. If you do not want the image to display, then you must provide NONE of the imageBox or resourceUri. Supplying one without the other is invalid (as we cannot know whether you meant for the image to display or not)
PVFI001 Datum is not a FixedImage type You have provided a user data object in a Side whose linkId references an FixedImage item from the Template, but which is not a "fixedimageData" type in the JSON.
PVFI002 FixedImage must define a resourceUri This means that for the given linkId, neither the Template object, nor your user data item (if specified) has provided a resourceUri for the fixed image to be rendered. Once the user data and template data are merged, all properties must be fully specified. In this case, the Template item should have provided a choice list from which the user data needs to select one image
PVFI003 FixedImage resourceUri must be from approved choice list in template Your user data item has provided resourceUri which is NOT in the choice list allowed by the Template content element. Please use a resourceUri in the choices supplied by the template.
PVT001 Datum is not a Text type You have provided a user data object in a Side whose linkId references an Text item from the Template, but which is not a "textData" type in the JSON.
PVT002 Illegal attempt to override text property The Template has enabled the textFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "text" property.
PVT003 Illegal attempt to override alignment property The Template has enabled the alignmentFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "alignment" property.
PVT004 Illegal attempt to override pointSize property The Template has enabled the pointSizeFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "pointSize" property.
PVT005 Illegal attempt to override colour property The Template has enabled the colourFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "colour" property.
PVT006 Illegal attempt to override font property The Template has enabled the fontFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "font" property.
PVT007 Text must define text property The Template item did not specify a default text property, and so you MUST provide one in the user data object for the relevant linkId
PVT008 Text must define font property The Template item did not specify a default font property, and so you MUST provide one in the user data object for the relevant linkId
PVT009 Text must define pointSize property The Template item did not specify a default pointSize property, and so you MUST provide one in the user data object for the relevant linkId
PVT010 Text must define colour property The Template item did not specify a default colour property, and so you MUST provide one in the user data object for the relevant linkId
PVT011 Text must define alignment property The Template item did not specify a default alignment property, and so you MUST provide one in the user data object for the relevant linkId
PVMT001 Datum is not a MultiLineText type You have provided a user data object in a Side whose linkId references an Text item from the Template, but which is not a "multiLineTextData" type in the JSON.
PVMT002 Illegal attempt to override text property The Template has enabled the textFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "text" property.
PVMT003 Illegal attempt to override alignment property The Template has enabled the alignmentFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "alignment" property.
PVMT004 Illegal attempt to override pointSize property The Template has enabled the pointSizeFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "pointSize" property.
PVMT005 Illegal attempt to override colour property The Template has enabled the colourFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "colour" property.
PVMT006 Illegal attempt to override font property The Template has enabled the fontFixed constraint, but your user data has attempted to override the setting. Your user data must not provide a "font" property.
PVMT007 MultiLineText must define text property The Template item did not specify a default text property, and so you MUST provide one in the user data object for the relevant linkId
PVMT008 MultiLineText must define font property The Template item did not specify a default font property, and so you MUST provide one in the user data object for the relevant linkId
PVMT009 MultiLineText must define pointSize property The Template item did not specify a default pointSize property, and so you MUST provide one in the user data object for the relevant linkId
PVMT010 MultiLineText must define colour property The Template item did not specify a default colour property, and so you MUST provide one in the user data object for the relevant linkId
PVMT011 MultiLineText must define alignment property The Template item did not specify a default alignment property, and so you MUST provide one in the user data object for the relevant linkId
  Oh hi, nice to see you! Fonts Terms & conditions Privacy policy © MOO Inc., 985 Waterman Avenue, East Providence, RI 02914, USA - Registered in the United States of America.