Plastic Best Practices

Jan 17, 2020

  • Your input schema only needs to reflect the portion of the payload you are interested in; any extra structure/data in the payload is ignored. So don’t over-specify your input schemas: it slows down the translation and makes it harder to see what is important.

  • Always use a unique name for each morpher. They are all in the same namespace and will collide if they have the same name. Ideally the morpher class name will include trailing numbers to account for versioning. There is no error check for this yet.

  • In general, input and output variable names should be the same to use the built-in mapping, to avoid writing a morpher, and to make it easier to follow.

  • If you write a morpher and deal with conditional output, it is better to populate the full output in the output schema and delete portions in the morpher.

  • Never use periods as part of your variable names because Plastic uses these internally as path separators. There is no error check for this condition yet.

  • Treat the parsed payload as read-only; don’t modify it in your morpher. Input maps, output maps, and the output tree are fully modifiable.

  • Classes in the lib area are for importing and should have their names match their file name (just like Java). You can use an aribtrary directory heirarchy if you avoid using packages for your classes (recommended). If you insist on using packages, then the directory structure must match the package names.

  • Classifiers and morphers should never die - they should gracefully degrade. This means they should not abort, throw, or return null. Doing otherwise will make the individual translation fail, or if being used in a batching context, the whole batch will fail translation.

Appendix

This document can be converted to PDF using rst2pdf

RST syntax reference