Skip to main content

JSON Instructions Schema


The pdf.instructions schema contains everything you need to create instructions using the pdf endpoint.


Using the pdf endpoint requires you understand the pdf.instructions.schema.json JSON schema. You use this schema to create an instructions document that you then use to call the pdf endpoint.

Review the schema online or a graphical depiction of the schema.

tip

It is much easier to use one of the provided client libraries than creating a JSON instructions document from scratch.

PDFDocument#

Your pdf endpoint instructions JSON document begins with a single object representing the JSON document (the instructions). The instructions JSON can have any of the following elements as properties of the instructions document. Only the inputs element is required.

ElementRequired
authorMetadata Elements
titleMetadata Elements
subjectMetadata Elements
creatorMetadata Elements
keywordsMetadata Elements
fontsMetadata Elements
inputsInputs✔️
outlinesOutlines
templatestemplates
securitysecurity
formFieldsformFields
flattenAllFormFieldsMetadata Elements
retainSignatureFormFieldsMetadata Elements

Top-Level Instructions#

You can use the following top-level metadata elements in a instructions document to create a PDF. These elements either specify a PDF metadata value or it specifies if all form fields can be flattened or if signature form fields are retained.

Metadata Elements #

Every instruction JSON document you create can have one instance of one or more of the following elements.

ElementTypeRequiredDescription
authorstringThe PDF's author property. The author in the generated PDF's metadata.
titlestringThe PDF's title property. The title in the generated PDF's metadata.
subjectstringThe PDF's subject property. The subject in the generated PDF's metadata.
creatorstringThe PDF's creator property. The creator name in the generated PDF's metadata.
keywordsstringThe PDF's keywords property. This is a comma-separated list of keywords in the generated PDF's metadata.
flattenAllFormFieldsbooleanFlatten all form fields.
retainSignatureFormFieldsbooleanRetain signature fields.

The top-level instruction elements are optional and are used in generating the PDF returned by the pdf endpoint. For example, the following JSON snippet illustrates the top-level elements of an instructions document.

{  "$ref": "https://www.dynamicpdf.com/schemas/pdf.instructions.scheme.json",  "author": "John Doe",  "title": "Arabica Coffee Flavors",  "creator": "Jane Doe",  "keywords": "coffee,beverages,arabica,espresso"  ...}

Fonts#

You can also specify the fonts the generated PDF is to create using the font's array element. The fonts array is an array of JSON objects with the following child elements.

ElementTypeDescriptionRequired
namestringThe font name.✔️
resourceNamestringThe resource file name or path of Font. Resides in your cloud environment or uploaded as resource.✔️

Inputs #

The inputs array specifies the type of asset being manipulated. Every instructions document must contain one or more inputs elements.

ElementTypeDescriptionRequired
inputsarrayThe type of assets being manipulated to create a PDF.✔️

Every element in the inputs array must be of type: pdf, page, dlex, or image.

Input TypeDescription
pageCreate a blank PDF that can have more elements added to it.
pdfA pre-existing PDF in your CloudAPI resources that is merged with other inputs.
dlexA dlex file in your CloudAPI resources that is used to create a PDF report.
imageAn image file in your CloudAPI resources that is used to convert into a PDF.

There can be more than one input to an inputs array. Each input instruction is evaluated in the order your instructions document lists its elements.

Inputs Processing#

An instructions document processes each input differently. An instructions document can have one or more inputs and each input is merged to produce a final PDF in the order specified in the instructions document. The processing rules are as follows.

  • A page input is processed and generates a PDF.
  • A dlex input is processed into report and generates a PDF
  • An image input is converted to a PDF
  • A pdf input indicates a PDF document in resources.
  • If multiple inputs, the individual inputs are merged to create a final PDF.

The following figures illustrate several processing scenarios.

Figure 1. A page input creates a PDF.

Figure 2. A dlex input creates a PDF.

Figure 3. An image is converted into a PDF.

Figure 4. Two pdf inputs are merged to create a PDF.

Figure 5. A dlex input, a pdf input, and an image input are processed and then merged to create a PDF.

Inputs Types#

Depending upon the input's type, an input can have different child elements.

page#

A page input instructs the pdf endpoint to generate a PDF from the page. The page input creates a blank page or cover page.

tip

Use DynamicPDF Designer combined with the dlex input to create PDF content such as reports.

A page has the following elements.

ElementTypeDescriptionRequired
typeenumerationValue is page.✔️
idstringThe id to assign to the input.
templateIDstringThe id to assign to any included templates. Refers to an id in the template element. See below for more information on template element.
pageWidthnumberThe page width of the PDF to create.
pageHeightnumberThe page height of the PDF to create.
elementsarrayOne or more elements items. (elements).
Example#

For example, the following JSON instructions would result in a blank PDF with the number 1 printed in the top left corner.

{  "$ref": "https://www.dynamicpdf.com/schemas/pdf.instructions.schema.json",  "author": "John Doe",  "title": "My Blank PDF page",  "inputs": [    {      "type": "page",      "pageWidth": 792,      "pageHeight": 612,      "elements":[        {          "type":"pageNumbering",          "anchor":"topCenter",          "text":"1"        }        ]    }  ]}

dlex#

The dlex element specifies that an instructions document creates a PDF report using a DLEX file. A dlex element takes the following elements.

ElementTypeDescriptionRequired
typeenumerationValue is dlex.✔️
idstringThe id to assign to the input.
resourceNamestringThe resource file name or path of the DLEX. Resides in your cloud environment or uploaded as resource.✔️
layoutDataResourceNamestringThe layout data resource file name or path of the JSON data. Resides in your cloud environment or uploaded as resource.✔️
templateIDstringThe ID of the template to apply to all pages of the DLEX layout.

The resourceName is the path to the DLEX file on either your local system or in your CloudAPI resources. The following illustrates processing instructions that uses a DLEX file in your CloudAPI resources folder and the JSON data file name.

{  "$ref": "https://www.dynamicpdf.com/schemas/pdf.instructions.schema.json",  "author": "John Doe",  "title": "My PDF From REST API Using DLEX",  "inputs": [    {      "type": "dlex",      "resourceName": "simple-dlex-layout/SimpleReportWithCoverPage.dlex",      "layoutDataResourceName": "SimpleReportData.json"    }  ]}
tip

The layoutDataResourceName element specifies the JSON data document's file name. You specify the file's actual location as a form field parameter.

curl https://aeus2.dynamicpdf.com/api/v1.0/pdf -H "Authorization:Bearer DP.V9xxxxxxxxxxxxxxx" -F "Instructions=@C:/instructions-simplereport.json"-F "layoutDataResourceName=@C:/simple-dlex-data.json"-o combined.pdf

pdf#

The pdf element specifies a pre-existing PDF. Use a pdf input with other input types to merge the inputs into a finished PDF.

tip

Be certain to distinguish between the pdf endpoint and the pdf input type. The pdf input type specifies an input that represents a PDF document.

ElementTypeDescriptionRequired
typeenumerationValue is pdf.✔️
idstringThe id used to refer to the input.
resourceNamestringThe resource file name or path of PDF. Resides in your cloud environment or uploaded as resource.
mergeOptionsobjectThe options used to merge pdf.
pageCountintegerThe number of pages to include.
templateIdstringThe ID of the template to apply to all pages of PDF.
{  "author": "John Doe",  "title": "Getting Started - Merge Two PDFs",  "inputs": [    {      "type": "pdf",      "resourceName": "getting-started/DocumentA.pdf"    },    {      "type": "pdf",      "resourceName": "getting-started/DocumentB.pdf"    }  ]}

image#

An image input specifies that the input is from an image. The image is converted to a PDF and then merged with any other inputs in the instructions document.

ElementTypeDescriptionRequired
typeenumerationValue is image.✔️
idstringThe id used to refer to the input.
resourceNamestringThe resource file name or path of the image. Resides in your cloud environment or uploaded as resource.✔️
startPageintegerThe starting page of a multipage TIFF to include (1s based).
pageCountintegerThe number of pages from a multipage TIFF to include.
templateIDstringThe id of the template to apply to all pages of the image.
scaleXnumberThe x scale of image.
scaleYnumberThe y scale of image.
topMarginnumberImage top margin in points.
leftMarginnumberImage left margin in points.
bottomMarginnumberImage bottom margin in points.
rightMarginnumberImage right margin in points.
pageWidthnumberWidth of page containing image.
pageHeightnumberHeight of page containing image.
expandToFitbooleanExpand image to fit page?
shrinkToFitbooleanShrink image to fit page?
alignenumHorizontal alignment of image on page. Values: left, center, right
vAlignenumVertical alignment of image on page. Values: top, middle, bottom
{  "$ref": "https://www.dynamicpdf.com/schemas/pdf.instructions.schema.json",  "author": "John Doe",  "title": "My Multipage Tiff Converted to PDF",  "inputs": [    {      "type": "image",      "resourceName":"pdf-endpoint/image/multipage.tiff"    }  ]}

Templates #

ElementTypeRequiredDescription
idstringThe id used to refer to input.
elementsarray✔️ (name)(elements)

Security #

Security Types#

ElementsElementTypeDescription
AES 128 bit or 256 bit encryptiontypestringaes128, aes256
RC4, 128 bit encryptiontypestringrc4128

Security Elements#

ElementTypeRequiredDescription
typeenum✔️Encryption. Values: aes128, aes256
documentComponentsenumDocument components to encrypt. Values: all, allExceptMetadata
allowaccessibilitybooleanEnable accessibility features.
allowCopybooleanText can be copied from the PDF.
allowDocumentAssemblybooleanDocument pages can be added or removed.
allowEditbooleanPDF can be edited.
allowFormFillingbooleanAllow form filling.
allowHighResolutionPrintingbooleanPDF can be printed at a high resolution.
allowPrintbooleanPDF can be printed at high resolution.
allowUpdateAnnotsAndFieldsbooleanAllow updates to annotations and form fields.
ownerPasswordstringPDF owner password.
userPasswordstringPDF user password.

FormFields #

Acro form field values are set as they are merged into a new PDF document. Use the formFields array to provide the values to merge into the generated PDF.

ElementTypeRequiredDescription
namestring✔️Full name of form field.
valuestringForm field's value.
flattenbooleanFlatten form field.
removebooleanRemove form field.
{  "$ref": "https://www.dynamicpdf.com/schemas/pdf.instructions.schema.json",  "author": "John Doe",  "title": "My PDF From REST API",  "inputs": [    {      "type": "pdf",      "resourceName": "pdf-endpoint/form-fields/simple-form-fill.pdf",      "startPage": 1,      "pageCount": 1    }  ],  "formFields": [    {      "name": "company_name",      "value": "DynamicPDF"    },    {      "name": "description",      "value": "DynamicPDF CloudAPI. RealTime PDFs, Real FAST!"    }  ]}

Definitions#

The JSON schema defines the following schema definitions. These definitions are used in other JSON elements.

DefinitionDescription
colorDefines a color.
rgbColorDefines an rgb color.
outlinesAn array that defines elements in a PDF's outline.
elementsAn array that defines elements in a PDF

color #

Color can be one of the following types:

  • CMYK - Specified with C, M, Y, and K color values,
  • RGB - Specified with R, G, and B color values,
  • Web - Specified with the Web color format (i.e. "#FF0080" or "aqua"),
  • Grayscale - Specified as a level of gray,
  • Gradient - Specified with two colors of the same type,
  • Auto Gradient - Specified with two colors of the same type or,
  • Spot Color - Specifies a tint (shading) of a spot color ink.

You can also use one of the predefined colors listed below.

"color": {  "type": "string",  "pattern":"^(aliceBlue|antiqueWhite|aqua|aquamarine|azure|beige|bisque|black|blanchedAlmond|blue|blueViolet|brown|burlyWood|cadetBlue|chartreuse|chocolate|coral|cornflowerBlue|cornsilk|crimson|cyan|darkBlue|darkCyan|darkGoldenRod|darkGray|darkGreen|darkKhaki|darkMagenta|darkOliveGreen|darkorange|darkOrchid|darkRed|darkSalmon|darkSeaGreen|darkSlateBlue|darkSlateGray|darkTurquoise|darkViolet|deepPink|deepSkyBlue|dimGray|dodgerBlue|feldspar|fireBrick|floralWhite|forestGreen|fuchsia|gainsboro|ghostWhite|gold|goldenRod|gray|green|greenYellow|honeyDew|hotPink|indianRed|indigo|ivory|khaki|lavender|lavenderBlush|lawnGreen|lemonChiffon|lightBlue|lightCoral|lightCyan|lightGoldenRodYellow|lightGrey|lightGreen|lightPink|lightSalmon|lightSeaGreen|lightSkyBlue|lightSlateBlue|lightSlateGray|lightSteelBlue|lightYellow|lime|limeGreen|linen|magenta|maroon|mediumAquaMarine|mediumBlue|mediumOrchid|mediumPurple|mediumSeaGreen|mediumSlateBlue|mediumSpringGreen|mediumTurquoise|mediumVioletRed|midnightBlue|mintCream|mistyRose|moccasin|navajoWhite|navy|oldLace|olive|oliveDrab|orange|orangeRed|orchid|paleGoldenRod|paleGreen|paleTurquoise|paleVioletRed|papayaWhip|peachPuff|peru|pink|plum|powderBlue|purple|red|rosyBrown|royalBlue|saddleBrown|salmon|sandyBrown|seaGreen|seaShell|sienna|silver|skyBlue|slateBlue|slateGray|snow|springGreen|steelBlue|tan|teal|thistle|tomato|turquoise|violet|violetRed|wheat|white|whiteSmoke|yellow|yellowGreen|(#)?[A-F,a-f,0-9]{6}|gray\\(((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)\\)|rgb\\(((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)(,((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)){2}\\)|cmyk\\(((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)(,((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)){3}\\))$"}

rgbColor #

An rgbColor specifies an RGB color and is used in the outlines element. An rgb color can have one of the following values.

"rgbColor": {  "type": "string",  "pattern":"^(aliceBlue|antiqueWhite|aqua|aquamarine|azure|beige|bisque|black|blanchedAlmond|blue|blueViolet|brown|burlyWood|cadetBlue|chartreuse|chocolate|coral|cornflowerBlue|cornsilk|crimson|cyan|darkBlue|darkCyan|darkGoldenRod|darkGray|darkGreen|darkKhaki|darkMagenta|darkOliveGreen|darkorange|darkOrchid|darkRed|darkSalmon|darkSeaGreen|darkSlateBlue|darkSlateGray|darkTurquoise|darkViolet|deepPink|deepSkyBlue|dimGray|dodgerBlue|feldspar|fireBrick|floralWhite|forestGreen|fuchsia|gainsboro|ghostWhite|gold|goldenRod|gray|green|greenYellow|honeyDew|hotPink|indianRed|indigo|ivory|khaki|lavender|lavenderBlush|lawnGreen|lemonChiffon|lightBlue|lightCoral|lightCyan|lightGoldenRodYellow|lightGrey|lightGreen|lightPink|lightSalmon|lightSeaGreen|lightSkyBlue|lightSlateBlue|lightSlateGray|lightSteelBlue|lightYellow|lime|limeGreen|linen|magenta|maroon|mediumAquaMarine|mediumBlue|mediumOrchid|mediumPurple|mediumSeaGreen|mediumSlateBlue|mediumSpringGreen|mediumTurquoise|mediumVioletRed|midnightBlue|mintCream|mistyRose|moccasin|navajoWhite|navy|oldLace|olive|oliveDrab|orange|orangeRed|orchid|paleGoldenRod|paleGreen|paleTurquoise|paleVioletRed|papayaWhip|peachPuff|peru|pink|plum|powderBlue|purple|red|rosyBrown|royalBlue|saddleBrown|salmon|sandyBrown|seaGreen|seaShell|sienna|silver|skyBlue|slateBlue|slateGray|snow|springGreen|steelBlue|tan|teal|thistle|tomato|turquoise|violet|violetRed|wheat|white|whiteSmoke|yellow|yellowGreen|(#)?[A-F,a-f,0-9]{6}|gray\\(((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)\\)|rgb\\(((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)(,((0+)?1((\\.0+)?)?|(0+)?((\\.[0-9]+)?)?)){2}\\))$"}

lineStyle #

The lineStyle refers to the style of a line and can have one of the following values or a numeric value.

Property ValueDescription
DashGets a dashed line.
DashLargeGets a line with large dashes.
DashSmallGets a line with small dashes.
DotsGets a dotted line.
NoneGets a invisible line.
SolidGets a solid line.
"lineStyle": {  "type": "string",  "pattern": "^(dash|dashLarge|dashSmall|dots|solid|\\[(([0-9]+((\\.[0-9]+)?)?)|(\\.[0-9]+))((,(([0-9]+((\\.[0-9]+)?)?)|(\\.[0-9]+)))+)?\\](([0-9]+((\\.[0-9]+)?)?)|(\\.[0-9]+))?)$"  }

Outlines #

ElementsTypeRequiredDescription
colorSee color definition.The outline color.
expandedbooleanExpand outline by default.
styleenumThe outline's style. Values: bold, boldItalic, italic, regular.
textstringThe outline's text.
linkToSee linkTo definition.The link to link to in the outline.
childrenarrayAn array of outlines that are the child outlines to the outline.

linkTo #

The linkTo element can be a URL or another input. If the linkTo refers to a URL then it consists of the following element. Otherwise the linkTo element refers to an input that is the ID of another input element.

url#
ElementTypeRequiredDescription
url✔️The URL to link to.
{     "url":"http://www.mynowhere.com"}
input#
ElementTypeRequiredDescription
inputIDstring✔️
pageOffsetintegerThe page offset from the first page to link to.
pageZoomenumThe page zoom of the target page when opened. Values: retain, fitPage, fitWidth, fitHeight, fitBox
{     "inputID":"12345A",     "pageOffset":12}

Elements #

The elements array is an array of elements that are added to the page to construct a PDF. The elements array allows one instance of each of the following elements. These are properties that are unique to the items in the elements array.

ElementTypeRequiredDescription
typeenumCurrently one value: pageNumbering.
anchorenumPosition of element on the page. The anchor element can have the following values: topLeft, topCenter, topRight, bottomLeft, bottomCenter, bottomRight.
xOffsetnumberElement x offset from anchor point.
yOffsetnumberSee common element table (yOffset).
colorstringSee colors.
fontstringThe font name.
fontSizenumberThe font size.
textstringText containing page numbering tokens of element.
tip

Be certain to distinguish between the element named "element" and the term element. Element in the general sense is an object or field, it is an element in JSON. The element element specifies the name of a particular JSON element.

Examples#

The instructions schema can be tricky to decipher. In this section several JSON snippets illustrating how to use the schema are provided.

page with title and image

{  "$ref": "https://www.dynamicpdf.com/schemas/pdf.instructions.schema.json",  "author": "John Doe",  "title": "Page with Title and Image",  "inputs": [    {      "type": "page",      "id":"pdf1",      "templateID":"template123",      "pageWidth": 612,      "pageHeight": 792,      "elements":[         {            "type":"text",            "anchor":"topCenter",            "yOffset":100,            "text":"My Document Title"         },         {            "type":"image",            "anchor":"bottomCenter",            "resourceName":"dynamicpdf-logo.png"         }        ]    }  ]}

pdf with merge options

{  "author":"CeteSoftware",  "creator":"DynmaicPDF Cloud Api",  "flattenAllFormFields":false,  "retainSignatureFormFields":false,  "inputs":[    {      "resourceName":"samples/shared/pdf/merge-options.pdf",      "id":"fdb5620e-2435-4951-bc1d-2ddcf247e64a",      "mergeOptions":{        "documentInfo":false,        "pageAnnotations":false      },      "type":"pdf"    },    {      "resourceName":"samples/shared/pdf/merge-options.pdf",      "id":"8e5f391b-b423-43d5-b05e-a039ca543b20",      "type":"pdf"    }  ]}

image with outline

{  "author": "John Doe",  "title": "PDF - Image with Outline",  "inputs": [    {      "type": "pdf",      "id": "invoice",      "resourceName": "Invoice.pdf"    },    {      "type": "image",      "id": "picture",      "resourceName": "myTiff.tif"    },    {      "type": "pdf",      "id": "docA100",      "resourceName": "DocumentA100.pdf"    }  ],  "outlines": [    {      "text": "Invoice",      "linkTo": {        "inputID": "invoice"      }    },    {      "text": "Picture",      "linkTo": {        "inputID": "picture"      }    },    {      "text": "Outlines in Doc A 100",      "children": [        {          "fromInputID": "docA100"        }      ]    },    {      "text": "DynamicPDF is Cool!",      "linkTo": {        "url": "https://www.dynamicpdf.com"      }    }  ]}

Font Names#

  • times - Times (Times New Roman)
  • timesBold - Times (Times New Roman) Bold
  • timesItalic - Times (Times New Roman) Italic
  • timesBoldItalic - Times (Times New Roman) Bold Italic
  • helvetica - Helvetica (Arial)
  • helveticaBold - Helvetica (Arial) Bold
  • helveticaOblique - Helvetica (Arial) Oblique
  • helveticaBoldOblique - Helvetica (Arial) Bold Oblique
  • courier - Courier
  • courierBold - Courier Bold
  • courierOblique - Courier Oblique
  • courierBoldOblique - Courier Bold Oblique
  • symbol - Symbol
  • zapfDingbats - Zapf Dingbats