Child pages
  • Defining API Descriptors

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated link to CREST API Descriptor Specification


This wiki page contains resources and tips & tricks related to defining API Descriptors.

CREST API Descriptor Specification


  • API Descriptor annotations
  • JSON Schema from flat files
  • Single "action"
  • API Descriptor annotations
  • JSON Schema from annotated POJO classes
  • Multiple "actions"
  • Resource schema and "read" endpoint
  • API Descriptor from Describable interface
  • JSON Schema read from managed.json
Example in forgerock-commons


Two sets of annotations can often be used to describe portions of an API Descriptor. There are a set of CREST related annotations, that define the actual API endpoints, and another set of annotations that extend Jackson support for JSON Schema v4 generation.

CREST API Descriptor annotations

Java AnnotationNotes



In OpenIDM, use,

final Router router = new DescribableRouter();

for the parent class that adds RequestHandler instances onto the router.





Defines error responses that the user of the API needs to be aware of.


Points to a JSON example text-file. This is not JSON Schema, but an actual example of the resource / payload.


Defines a parameter either as URL path-template (ParameterSource.PATH) or as a query-parameter (ParameterSource.ADDITIONAL).


Points to a JSON Schema v4 text-file or POJO class (see annotations below).






Action / Actions

Actions are unique, because custom request / response payload schemas can be defined, whereas the other CRUDPAQ operations are assumed to use one resource-schema for the endpoint.

Use the "Actions" annotation when an endpoint supports multiple actions.


Annotations that generate JSON Schema,


Please also refer to the Jackson Annotations documentation (examples), which are often necessary when field names need to be renamed or hidden/ignored, for example.

JSON Schema FieldJava AnnotationNotes
typeprovided by JacksonJackson determines the correct JSON type for the POJO class and nested fields.
propertiesprovided by JacksonFields on an object correspond to getter/setters on your POJO.
enumprovided by JacksonA Java "enum" will be converted into a JSON Schema "enum".
options/enum_titleorg.forgerock.api.annotations.EnumTitleProvide titles for enum items.
descriptionorg.forgerock.api.annotations.DescriptionDescription of class or field.
titleorg.forgerock.api.annotations.TitleShort title for class or field.
itemsprovided by Jackson

A List<String> or String[] field on the POJO will define itself as a JSON Schema "type":"array" and the "items" will have "type":"string".

Warning: might be restricted to one array-item type (not multiple)

uniqueItemsorg.forgerock.api.annotations.UniqueItems"uniqueItems":true means that all array/collection items must be unique

returnOnDemandorg.forgerock.api.annotations.PropertyPoliciesWhether or not a field is always returned or if it must be requested via "_fields".


propertyOrderorg.forgerock.api.annotations.PropertyOrderJackson normally orders properties (fields) in the order they are defined in the POJO class, so this annotation makes the ordering more specific if that is necessary.
minLengthjavax.validation.constraints.SizeMinimum string length. Can be used to allow "empty string".
maxLengthjavax.validation.constraints.SizeMaximum string length.
minItemsjavax.validation.constraints.SizeMinimum items in an array/set.
maxItemsjavax.validation.constraints.SizeMaximum items in an array/set.
minimum (for int/long)javax.validation.constraints.MinMinimum value (inclusive) for an int/long.
maximum (for int/long)javax.validation.constraints.MaxMaximum value (inclusive) for an int/long.
minimum (for any? number)javax.validation.constraints.DecimalMinMinimum value (inclusive) for any Java number.
maximum (for any? number)javax.validation.constraints.DecimalMaxMaximum value (inclusive) for any Java number.
exclusiveMinimumjavax.validation.constraints.DecimalMinMinimum value (exclusive) for any Java number.
multipleOforg.forgerock.api.annotations.MultipleOf"multipleOf":2.0 means that the number is a multiple of 2 (e.g., 2, 4, 6...)
exclusiveMaximumjavax.validation.constraints.DecimalMinMaximum value (exclusive) for any Java number.
requiredjavax.validation.constraints.NotNullSpecify field as "non-null", which translates to "required":true in JSON Schema.
readOnlyorg.forgerock.api.annotations.ReadOnlyField is read-only.
patternjavax.validation.constraints.PatternRegex that a "string" field should match.

Supported "format" values by JSON type,

  • integer
    • int32 (default)
    • int64
  • number
    • double (default)
    • float
    • int32
    • int64
  • string
    • byte (base64)
    • binary (base64)
    • full-date (RFC 3339)
    • date-time (RFC 3339)
    • password
    • uuid

The "default" value, represented as a string.

NOTE: all JSON types are supported when defining a "default" field using a JSON Schema text-file (non-annotation)

additionalPropertiesorg.forgerock.api.annotations.AdditionalPropertiesUseful when the JSON object is a "map" of "string" keys and values of the given type, but the keys might be only known at runtime.

JSON Schema Text Files

JSON Schema's for API Descriptor resources and request / response payloads can be defined in text files, using JSON Schema v4 syntax. For most common use-cases annotations on a POJO can generate the appropriate schema, but there are times when the annotations fall short. For example, the @Default annotation currently only supports string representations of simple default-values (e.g., "text", "1.0", "true"), so if you want to define a default  JSON object or array value, you will need to use a raw JSON Schema text-file.