Edit in GitHubLog an issue

Implemented Validations

This document catalogues what validation rules are in place for element creation payloads. We assume general familiarity with Libraries, and the element creation process.

Definitions#

TermDefinition
property path (column heading)Path to property in JSON document.
condition (column heading)The condition that must be fulfilled for a validation to execute.
type (column heading)The JSON type expected for some property value, or the Java type that the JSON value will be coerced into if it is more restrictive then the JSON type and is a primitive type or the boxed equivalent. Additionally, some properties are polymorphous, and may have different validation rules associated with different types.
empty (string)A string containing no characters, e.g., "".
blank (string)A string containing only whitespace, e.g., " ".
always (execution condition)Indicates that a validation will always be performed, regardless of property value.
when present (execution condition)Indicates that a validation will only be performed if the property value is non-null.
well-known (element or representation type)An element or representation type for which we have implemented bespoke validation logic.
well-known (property in paragraph or character style)A style for which we have implemented bespoke validation logic.
supported (element or representation type)An element or representation type that can be used in requests.
user-uploaded assetBinary data uploaded before a library element is created referring to the uploaded data.
concrete MIME typeA MIME type that is both valid, and does not contain wildcards, e.g., "image/*" is a valid MIME type, but is not concrete, but "image/png" is valid and concrete.

JSON Property Path Legend#

SymbolDescription
$contextual document root, will refer to the last object level named in a heading
.aPropertyproperty access
[1]array index
.*all properties in object
[*]all indexes in array
.{a, b, c, d}a specific set of possible properties
[*](property=value)a selector; all objects in the array where property=value

Validation and Type Coercion#

There are effectively two layers of processes that sanitize service input. The first is the process that maps input to models with strongly-typed properties. The second is explicit validation logic that interrogates payload content after it has been mapped. A payload may be rejected within either layer, but, these errors will appear differently to the service consumer. For example, if a property value should be coerced into an integer in the mapping layer, but the JSON type of the value supplied was string, and, that string contained non-numeric characters, then the service consumer may get a 500 in response as the type coercion would fail. However, if we had implemented validation that enforces a range for this property, the consumer supplied a valid number that could be coerced into an integer, and this number fell outside of the allowed range, we would return a 400. Since, in effect, both processes sanitize input, both are accounted for in this document.

A couple examples\:

Property PathConditionTypeValidation
$.adbeDesiredLetterSpacingwhen presentnumbermust be between -100 and 500, inclusive

In this example, if the supplied value was not coercible into a number, the payload would be rejected. If the supplied value was coercible, then the validation rule "must be between -100 and 500, inclusive" would apply.

Property PathConditionTypeValidation
$.vectorColorwhen presentbooleannone (coercion only)

In this example, if the supplied value was not coercible into a boolean, the payload would be rejected. If the supplied value was coercible, no other validation would occur.

MIME Types Associated With User-Uploaded Assets#

Copied to your clipboard
1 private static final String[] assetMimeTypes = {
2 "image/*",
3 "video/*",
4 "text/*",
5 "audio/*",
6 "application/photoshop",
7 "application/ai",
8 "application/pdf",
9 "application/zip",
10 "application/postscript",
11 "application/vnd.adobe.indesign-idms",
12 "application/x-indesign",
13 "application/vnd.adobe.muse-collection",
14 "application/vnd.adobe.pstouch",
15 "application/vnd.adobe.psremix",
16 "application/vnd.adobe.ideas",
17 "application/vnd.adobe.ase",
18 "application/mxf",
19 "application/x-shockwave-flash",
20 "application/msword",
21 "application/msexcel",
22 "application/mspowerpoint",
23 "application/vnd.ms-publisher",
24 "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
25 "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
26 "application/vnd.openxmlformats-officedocument.presentationml.presentation"
27 };

Valid CSS Units#

Copied to your clipboard
1 public static final Set<String> cssUnits = Set.of(
2 "%",
3
4 // relative units
5 "em",
6 "ex",
7 "cap",
8 "ch",
9 "ic",
10 "rem",
11 "lh",
12 "rlh",
13 "vw",
14 "vh",
15 "vi",
16 "vb",
17 "vmin",
18 "vmax",
19
20 // absolute lengths
21 "cm",
22 "mm",
23 "q",
24 "in",
25 "pt",
26 "pc",
27 "px",
28
29 // angles
30 "deg",
31 "grad",
32 "rad",
33 "turn",
34
35 // duration
36 "s",
37 "ms",
38
39 // frequency
40 "hz",
41 "khz",
42
43 // resolution
44 "dpi",
45 "dpcm",
46 "dppx"
47 );

Supported Audio Types#

audio/mpeg\ audio/x-mpeg\ audio/mpeg3\ audio/x-mpeg-3\ audio/mp3\ audio/m4a\ audio/wav\ audio/x-wav\ audio/vnd.wave\ audio/wave\ audio/aac\ audio/aacp\ audio/aif\ audio/x-aiff

Validation Rules#

Reference Structures#

The following models are used in specific contexts, and are not used in representation payloads outside of those contexts.

Unit#

Property PathConditionTypeValidation
$.typewhen presentstringmust be a valid CSS measurement, case-insensitive; c.f. "Valid CSS Measurements"
$.valuewhen presentnumbernone (coercion only)

postLibraryElementPayload#

Property PathConditionTypeValidation
$.typealwaysstringmust have a valid MIME type that is also concrete (no wildcards)
$.clientalwaysobjectmust not be null
$.client.{app, deviceId, device}alwaysstringmust not be blank
$.representationswhen presentarraynone (coercion)
$.representationswhen presentarraycannot contain more then one representation with the 'primary' relationship
$.representations[*]when presentobjecteach representation must be valid according to rules associated with representation type
$.namewhen presentstringnone (coercion only)
$.sourcewhen presentstringnone (coercion only)

postLibraryElementPayload.representations[*]#

Property PathConditionTypeValidation
$.typealwaysstringmust be a valid MIME type that is also concrete (no wildcards)
$.typethe representation type is well-knownstringrepresentation type must belong to the set of types associated with the element type
$.{storage_href, path}type matches one of the items in "MIME Types Associated With User-Uploaded Assets" list above.stringstorage_href and/or path must not be blank
$.linktype$.type is "application/vnd.adobe.library.link+dcx"stringmust be a valid MIME type that is also concrete (no wildcards)
$.linkurl$.type is "application/vnd.adobe.library.link+dcx"stringmust not be a blank string
$.adobestock#trackingdatatype is "application/vnd.adobe.library.link+dcx"objectmust not be null
$.color#data$.type is "application/vnd.adobe.library.color+dcx"objectmust not be null
$.colortheme#data$.type is "application/vnd.adobe.library.colortheme+dcx"objectmust not be null
$.gradient#data$.type is "application/vnd.adobe.library.gradient+dcx"objectmust not be null
$.gradient#data$.type is "application/vnd.adobe.library.gradient.noise+dcx"objectmust not be null
$.audio#data$.type is a supported audio type; c.f. "Supported Audio Types" aboveobjectmust not be null
$.font#data$.type is "application/vnd.adobe.library.font+dcx"objectmust not be null
$.characterstyle#data$.type is "application/vnd.adobe.library.characterstyle+dcx"objectmust not be null
$.paragraphstyle#data$.type is "application/vnd.adobe.library.paragraphstyle+dcx"objectmust not be null
$.relationshipwhen presentstringnone (coercion only)
$.md5when presentstringnone (coercion only)
$.etagwhen presentstringnone (coercion only)
$.is_full_sizewhen presentbooleannone (coercion only)
$.is_external_linkwhen presentbooleannone (coercion only)
$.widthwhen presentlongnone (coercion only)
$.heightwhen presentlongnone (coercion only)
$.content_lengthwhen presentLongnone (coercion only)
$.representation_orderwhen presentIntegernone (coercion only)
$.is_preferred_thumbnailwhen presentbooleannone (coercion only)
$.is_componentwhen presentbooleannone (coercion only)

Representation Type Validations#

application/vnd.adobe.color+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.color+json).color#data)#

Property PathConditionTypeValidation
$.modealwaysstringmust be in set {"RGB", "CMYK", "Lab", "Gray", "HSB", "RGB.tint", "CMYK.tint", "Lab.tint"}
$.valuealwaysobjectmust be non-null
$.valuewhen mode is "RGB" or "RGB.tint"objectmust have keys "r", "g", and "b"
$.value.{r, g, b}when mode is "RGB" or "RGB.tint"Doublevalues must be between 0 and 255, inclusive
$.valuewhen mode is "CMYK" or "CMYK.tint"objectmust have keys "c", "m", "y", and "k'
$.value.{c, m, y, k}when mode is "CMYK" or "CMYK.tint"Doublevalues must be between 0 and 100, inclusive
$.valuewhen mode is "Lab" or "Lab.tint"Doublemust have keys "l", "a", and "b"
$.value.lwhen mode is "Lab" or "Lab.tint"Doublemust be between 0 and 100, inclusive
$.value.awhen mode is "Lab" or "Lab.tint"Doublemust be between -128 and 127, inclusive
$.value.bwhen mode is "Lab" or "Lab.tint"Doublemust be between -128 and 127, inclusive
$.valuewhen mode is "HSB"objectmust have keys "h", "s", and "b"
$.value.hwhen mode is "HSB"Doublemust be between 0 and 360, inclusive
$.value.swhen mode is "HSB"Doublemust be between 0 and 100, inclusive
$.value.bwhen mode is "HSB"Doublemust be between 0 and 100, inclusive
$.valuewhen mode is "Gray"Doublemust be between 0 and 100, inclusive
$.profileNamewhen presentstringmust be non-null
$.alphawhen presentDoublemust be between 0 and 1, inclusive
$.typewhen presentstringmust be in set {"process", "spot", "registration", "none"}
$.spotColorNamewhen type is "spot"stringmust be non-empty string
$.tintwhen mode is one of {"RGB.tint", "CMYK.tint", "Lab.tint"}stringmust be between 0 and 100, inclusive

application/vnd.adobe.colortheme+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.colortheme+json).colortheme#data)#

Property PathConditionTypeValidation
$.swatchesalwaysarraymust contain 5 things
$.swatches[*]alwaysarraymust be an array
$.swatches[*]alwaysarraymust contain one application/vnd.adobe.color+json where mode is "RGB"
$.swatches[*][*]alwaysobjectapply application/vnd.adobe.color+json validations
$.themeIdwhen presentstringnone (coercion only)
$.baseSwatchIndexwhen presentintegernone (coercion only)
$.tagswhen presentarray of stringsnone (coercion only)
$.rulewhen presentstringnone (coercion only)
$.moodwhen presentstringnone (coercion only)

application/vnd.adobe.gradient+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.gradient+json).gradient#data)#

Property PathConditionTypeValidation
$.typealwaysstringvalue one of {"linear", "radial"}
$.stopsalwaysarraymust not be null
$.stops[*].coloralwaysarraymust be an array
$.stops[*].coloralwaysarraymust contain at least one color where mode is "RGB"
$.stops[*].color[*]alwaysarraymust be a valid application/vnd.adobe.color+json
$.stops[*].phxsInheritwhen presentstringmust be one of {"foreground", "background"}
$.stops[*].offsetwhen presentDoublemust be between 0 and 1, inclusive
$.stops[*].midpointalwaysDoublenone (coercion only)
$.anglewhen presentIntegermust be between 0 and 360, inclusive
$.scalewhen presentDoublemust be greater than 0
$.centerPointwhen presentobjectmust contain the keys "x", and "y"
$.centerPoint.{x, y}alwaysDoublevalues must be between -1 and 1, inclusive
$.interpolationalwaysstringmust be one of {"linear", "euclidean", "spline"}
$.opacitieswhen presentarraymust be an array
$.opacities[*].{opacity, midpoint, offset}when presentDoublemust be between 0 and 1, inclusive
$.orientationwhen presentobjectmust contain the keys "x1", "x2", "y1", "y2"
$.orientation.{x1, x2, y1, y2}when presentobjectvalues must be between 0 and 1
$.directionwhen presentstringmust be one of {"horizontal", "vertical" }
$.smoothnesswhen presentIntegermust be between 0 and 4096, inclusive

application/vnd.adobe.gradient.noise+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.gradient.noise+json).gradient#data)#

Property PathConditionTypeValidation
$.maximumColoralwaysarrayis not null, is an array
$.minimumColoralwaysarraymust contain at least one color where mode is "RGB"
$.minimumColor[*]alwaysobjectis a valid application/vnd.adobe.color+json
$.maximumColoralwaysarrayis not null, is an array
$.maximumColoralwaysarraymust contain at least one color where mode is "RGB"
$.maximumColor[*]alwaysobjectis a valid application/vnd.adobe.color+json
$.randomSeedalwaysDoubleis not null
$.smoothnesswhen presentIntegermust be between 0 and 4096, inclusive
$.typewhen presentstringnone (coercion only)
$.namewhen presentstringnone (coercion only)
$.vectorColorwhen presentbooleannone (coercion only)
$.showTransparencywhen presentbooleannone (coercion only)

application/vnd.adobe.font+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.font+json).font#data)#

Property PathConditionTypeValidation
$.namewhen presentstringmust not be blank
$.familywhen presentstringmust not be blank
$.postScriptNamewhen presentstringmust not be blank
$.stylewhen presentstringmust not be blank
$.typekitFontIdwhen presentstringmust not be blank
$.foundrywhen presentstringmust not be blank

application/vnd.adobe.element.characterstyle+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.characterstyle+json).characterstyle#data)#

Property PathConditionTypeValidation
$alwaysanymust contain at least one property
$alwaysanycannot contain any properties from application/vnd.adobe.element.paragraphstyle+json that are type coerced 🚩
$.*when presentanymust not be null
$.*when present, if stringstringmust not be blank
$.color[*]when presentobjectmust be a valid application/vnd.adobe.color+json
$.fontSizewhen presentobjectmust be a valid Unit
$.fontFamilywhen presentstringmust not be blank
$.fontStylewhen presentstringmust not be blank
$.fontWeightwhen presentstringmust not be blank
$.fontWeightwhen presentIntegermust be between 1 and 1000, inclusive
$.lineHeightwhen presentobjectmust be a valid Unit
$.baselineShiftwhen presentobjectmust be a valid Unit
$.letterSpacingwhen presentobjectmust be a valid Unit
$.adbeFontwhen presentobjectmust be a valid application/vnd.adobe.font+json, except, all properties are optional

application/vnd.adobe.element.paragraphstyle+json (postLibraryElementPayload.representations[*](type=application/vnd.adobe.paragraphstyle+json).paragraphstyle#data)#

Property PathConditionTypeValidation
$alwaysanyall validations from application/vnd.adobe.element.characterstyle+json, except where marked 🚩
$.adbeParaAlignmentwhen presentstringmust be one of {"Alignment.LEFT_ALIGN", "Alignment.CENTER_ALIGN", "Alignment.RIGHT_ALIGN", "Alignment.LEFT_JUSTIFIED", "Alignment.CENTER_JUSTIFIED", "Alignment.RIGHT_JUSTIFIED", "Alignment.FULLY_JUSTIFIED"}
$.adbeLeftIndentwhen presentobjectmust be a valid Unit
$.adbeFirstLineIndentwhen presentobjectmust be a valid Unit
$.adbeRightIndentwhen presentobjectmust be a valid Unit
$.adbeSpaceBeforewhen presentobjectmust be a valid Unit
$.adbeSpaceAfterwhen presentobjectmust be a valid Unit
$.adbeMinimumWordSpacingwhen presentnumbermust be between 0 and 1000, inclusive
$.adbeDesiredWordSpacingwhen presentnumbermust be between 0 and 1000, inclusive
$.adbeMaximumWordSpacingwhen presentnumbermust be between 0 and 1000, inclusive
$.adbeMinimumLetterSpacingwhen presentnumbermust be between -100 and 500, inclusive
$.adbeDesiredLetterSpacingwhen presentnumbermust be between -100 and 500, inclusive
$.adbeMaximumLetterSpacingwhen presentnumbermust be between -100 and 500, inclusive
$.adbeMinimumGlyphScalingwhen presentnumbermust be between 50 and 200, inclusive
$.adbeDesiredGlyphScalingwhen presentnumbermust be between 50 and 200, inclusive
$.adbeMaximumGlyphScalingwhen presentnumbermust be between 50 and 200, inclusive
$.adbeParaAutoLeadingwhen presentnumbermust be between 0 and 500, inclusive
$.adbeSingleWordJustificationwhen presentstringmust be one of {"Justification.FULLY_JUSTIFIED", "Justification.LEFT_ALIGN", "Justification.CENTER_ALIGN", "Justification.RIGHT_ALIGN"}

audio/ (see Supported Audio Types) postLibraryElementPayload.representations[](type=application/vnd.adobe.audio+json).audio#data#

Property PathConditionTypeValidation
$.durationwhen presentDoublemust be greater than 0
$.bitratewhen presentIntegermust be greater than 0
$.channelswhen presentIntegermust be greater than 0
$.tempowhen presentIntegermust be greater than 0
Copyright © 2021 Adobe. All rights reserved.